Developers' resources

Quickly build your own, unique barcode soloution by integrating the existing infrastructure of validators, inspection devices and sales channels with TapCheck.

TapCheck Webshop API

TapCheck Webshop API (0.0.1)

Download OpenAPI specification:Download

This document describes the endpoints available for a webshop to communicate with the TapCheck Webshop API.

Product endpoints

Product related endpoints can be used to retrieve information about products that are available for your webshop at this moment in time.

List Products

Returns a list of products for the given salesChannelId.

path Parameters
salesChannelId
string (SalesChannelId) ^[1-9][0-9]{0,9}$
Example: 197492442

A unique identifier for this Sales Channel.

Responses

200

Returns a JSON array of products.

400

The request could not be validated. The request body or parameters contain incomplete or incorrect parameters. The body of the response will contain information about the problem.

404

The requested URL does not exist, or the requested object was not found.

406

The request was not accepted by the server. The body of the response will contain information about the problem.

500

The server encountered an internal error while processing your request. The body of the response will contain more information about the problem, and also a unique log entry id. Please keep this log entry id for future reference, as we might need it to analyze the problem.

get/channels/{salesChannelId}/products

Barcode issuing server endpoint

https://issuing.tapcheck.io/channels/{salesChannelId}/products

Response samples

Content type
application/json
Copy
Expand all Collapse all
[
  • {
    }
]

Product Details

Returns the details of the selected product.

path Parameters
salesChannelId
string (SalesChannelId) ^[1-9][0-9]{0,9}$
Example: 197492442

A unique identifier for this Sales Channel.

productCode
string (ProductCode) ^[A-Za-z0-9]{1,4}$
Example: A2B4

A unique identifier for this product type.

Responses

200
400

The request could not be validated. The request body or parameters contain incomplete or incorrect parameters. The body of the response will contain information about the problem.

404

The requested URL does not exist, or the requested object was not found.

406

The request was not accepted by the server. The body of the response will contain information about the problem.

500

The server encountered an internal error while processing your request. The body of the response will contain more information about the problem, and also a unique log entry id. Please keep this log entry id for future reference, as we might need it to analyze the problem.

get/channels/{salesChannelId}/products/{productCode}

Barcode issuing server endpoint

https://issuing.tapcheck.io/channels/{salesChannelId}/products/{productCode}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "salesChannelId": 197492442,
  • "productNameNL": "24 uurs dagkaart",
  • "productNameEN": "24 hour dayticket",
  • "productDescriptionNL": "Een kaart om 24 uur in Amsterdam mee te reizen",
  • "productDescriptionEN": "A ticket for traveling in Amsterdam for 24 hours",
  • "productCode": "A2B4",
  • "selectableUsageRangeStart": "2020-03-01",
  • "selectableUsageRangeEnd": "2020-03-28",
  • "usableAfter": "2020-03-02",
  • "usableBefore": "2020-03-20",
  • "validityDuration": 1440,
  • "validityUnit": "minutes",
  • "priceInCents": 750,
  • "modality": "BUS",
  • "termsAndConditionsNL": null,
  • "termsAndConditionsEN": null
}

Ticket endpoints

Create a ticket, activate a ticket, get barcodes and other information

Create ticket

Creates a ticket for traveling, based on the selected product.

Request Body schema: application/json
salesChannelId
string (SalesChannelId) ^[1-9][0-9]{0,9}$

A unique identifier for this Sales Channel.

ticketLanguage
string (Language)
Enum: "NL" "EN"

Language

productCode
string (ProductCode) ^[A-Za-z0-9]{1,4}$

A unique identifier for this product type.

validityStart
string <date>

For products that require the customer to pick a starting date for their ticket, this field needs to be filled. It is the date on which the validity of that ticket will start. For products that are activated on first use, this field can be omitted.

Responses

200

Returns a JSON array of products.

400

The request could not be validated. The request body or parameters contain incomplete or incorrect parameters. The body of the response will contain information about the problem.

404

The requested URL does not exist, or the requested object was not found.

406

The request was not accepted by the server. The body of the response will contain information about the problem.

500

The server encountered an internal error while processing your request. The body of the response will contain more information about the problem, and also a unique log entry id. Please keep this log entry id for future reference, as we might need it to analyze the problem.

post/tickets/create

Barcode issuing server endpoint

https://issuing.tapcheck.io/tickets/create

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "salesChannelId": 197492442,
  • "ticketLanguage": "NL",
  • "productCode": "A2B4",
  • "validityStart": "2020-03-03"
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "serviceId": "GVB-1234-7654-8945",
  • "ticketId": "KJj43nejhbTxhr897287",
  • "productName": "24 uurs dagkaart",
  • "soldAt": "2020-03-01T00:00:00+01:00",
  • "lifespanStart": "2020-03-01",
  • "lifespanEnd": "2020-03-28",
  • "validityStart": "2020-03-03",
  • "validityEnd": "2020-03-10",
  • "active": true
}

Get ticket info

Provides information and events related to a ticket

path Parameters
ticketId
string (TicketId) ^[A-Za-z0-9]{20}$
Example: KJj43nejhbTxhr897287

A unique 20-character alphanumeric id for a ticket.

Responses

200

Return information for the selected TicketId

400

The request could not be validated. The request body or parameters contain incomplete or incorrect parameters. The body of the response will contain information about the problem.

404

The requested URL does not exist, or the requested object was not found.

406

The request was not accepted by the server. The body of the response will contain information about the problem.

500

The server encountered an internal error while processing your request. The body of the response will contain more information about the problem, and also a unique log entry id. Please keep this log entry id for future reference, as we might need it to analyze the problem.

get/tickets/{ticketId}/info

Barcode issuing server endpoint

https://issuing.tapcheck.io/tickets/{ticketId}/info

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "ticket":
    {
    },
  • "events":
    [
    ]
}

Activate ticket

For tickets with a sliding validity, this endpoint can be used to indicate the activation (first use) of the ticket.

path Parameters
ticketId
string (TicketId) ^[A-Za-z0-9]{20}$
Example: KJj43nejhbTxhr897287

A unique 20-character alphanumeric id for a ticket.

Responses

200
400

The request could not be validated. The request body or parameters contain incomplete or incorrect parameters. The body of the response will contain information about the problem.

404

The requested URL does not exist, or the requested object was not found.

406

The request was not accepted by the server. The body of the response will contain information about the problem.

500

The server encountered an internal error while processing your request. The body of the response will contain more information about the problem, and also a unique log entry id. Please keep this log entry id for future reference, as we might need it to analyze the problem.

post/tickets/{ticketId}/activate

Barcode issuing server endpoint

https://issuing.tapcheck.io/tickets/{ticketId}/activate

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "serviceId": "GVB-1234-7654-8945",
  • "ticketId": "KJj43nejhbTxhr897287",
  • "productName": "24 uurs dagkaart",
  • "soldAt": "2020-03-01T00:00:00+01:00",
  • "lifespanStart": "2020-03-01",
  • "lifespanEnd": "2020-03-28",
  • "validityStart": "2020-03-03",
  • "validityEnd": "2020-03-10",
  • "active": true
}

Get barcode

Barcodes are not created by default for a ticket. This endpoint creates a barcode for the ticket, stores it with the ticket for future reference and returns it.

path Parameters
ticketId
string (TicketId) ^[A-Za-z0-9]{20}$
Example: KJj43nejhbTxhr897287

A unique 20-character alphanumeric id for a ticket.

Responses

200
400

The request could not be validated. The request body or parameters contain incomplete or incorrect parameters. The body of the response will contain information about the problem.

404

The requested URL does not exist, or the requested object was not found.

406

The request was not accepted by the server. The body of the response will contain information about the problem.

500

The server encountered an internal error while processing your request. The body of the response will contain more information about the problem, and also a unique log entry id. Please keep this log entry id for future reference, as we might need it to analyze the problem.

get/tickets/{ticketId}/barcode

Barcode issuing server endpoint

https://issuing.tapcheck.io/tickets/{ticketId}/barcode

Response samples

Content type
Copy
Expand all Collapse all
"string"

Cancel ticket

Cancels the ticket with the given id, with the given cancellation reason.

path Parameters
ticketId
string (TicketId) ^[A-Za-z0-9]{20}$
Example: KJj43nejhbTxhr897287

A unique 20-character alphanumeric id for a ticket.

Request Body schema: application/json
reason
string

free form text describing the reason of cancellation

Responses

200
400

The request could not be validated. The request body or parameters contain incomplete or incorrect parameters. The body of the response will contain information about the problem.

404

The requested URL does not exist, or the requested object was not found.

406

The request was not accepted by the server. The body of the response will contain information about the problem.

500

The server encountered an internal error while processing your request. The body of the response will contain more information about the problem, and also a unique log entry id. Please keep this log entry id for future reference, as we might need it to analyze the problem.

post/tickets/{ticketId}/cancel

Barcode issuing server endpoint

https://issuing.tapcheck.io/tickets/{ticketId}/cancel

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "reason": "Returned the ticket."
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "serviceId": "GVB-1234-7654-8945",
  • "ticketId": "KJj43nejhbTxhr897287",
  • "productName": "24 uurs dagkaart",
  • "soldAt": "2020-03-01T00:00:00+01:00",
  • "lifespanStart": "2020-03-01",
  • "lifespanEnd": "2020-03-28",
  • "validityStart": "2020-03-03",
  • "validityEnd": "2020-03-10",
  • "active": true
}