Overview
Introduction
Your integration is going to be linked with an Organization, and that Organization has a list of Locations.
Please contact with our support team at [email protected] to receive a token.
Authentication
For both the Rest API and the webhooks we use the same authentication method. We will share with you a secret token, and in all the requests it has to be included as a header.
Header
Authorization: TOKEN
Rest API
GET Location List
[
{
"id": "0e53f16f-88f5-4379-ab6d-b21213968d5c",
"name": "T8 Tea Bar",
"address": "Pl. de España, 18, 28008 Madrid, España",
"organizationId": "4de9cd38-17ee-457c-9fff-bf4884a1a767",
"deleted": 0,
"countryCode": "ES",
"latitude": 40.42326736,
"longitude": -3.71103597
},
{
"id": "0e75756b-bf8b-41e0-9162-a87e3f19e771",
"name": "JOVELLANOS",
"address": "C. de Jovellanos, 6, 28014 Madrid",
"organizationId": "1321a1e9-e310-488a-9c6c-ed8203053bb7",
"deleted": 0,
"countryCode": "ES",
"latitude": 40.42326736,
"longitude": -3.71103597
}
]
HTTP Request
GET https://api.comeback.es/v1/locations
Location
| Field name | Description |
|---|---|
| id (String) | Unique identifier for the location |
| name (String) | Name of the location |
| address (String) | Address of the location |
| organizationId (String) | Unique identifier for the organization |
| deleted (Integer) | Deletion status of the location (0 or 1) |
| countryCode (String) | Country code of the location |
| latitude (Float) | Latitude of the location |
| longitude (Float) | Longitude of the location |
POST Create Order
{
"externalId": "h230he02",
"amount": 2950,
"products": [
{
"name": "Burger",
"quantity": 1,
"organizationProductExternalId": "eygh2hgnd",
"orderProductExternalId": "023hhe203h",
"price": 3000
}
],
"locationId": "0e75756b-bf8b-41e0-9162-a87e3f19e771",
"customerId": "33f9dc36-5e99-4044-8e2e-9b22c403c5f7",
"promotionsApplied": [
{
"id": "28afe959-6204-4169-b5ba-fc90f15aad43",
}
]
"discountAmount": 50
}
HTTP Request
POST https://api.comeback.es/v1/orders
Order
| Field name | Description |
|---|---|
| externalId (String) | Identifier of the order on your system |
| amount (Integer) | Total amount of the order in cents |
| products (Array) | List of products included in the order |
| locationId (String) | Unique identifier of the location where the order was placed |
| customerId (String) | Unique identifier of the customer who placed the order |
| promotionsApplied (Array) | List of promotions applied to the order |
| discountAmount (Integer) | Total discount amount applied to the order in cents |
Product
| Field name | Description |
|---|---|
| name (String) | Name of the product |
| quantity (Integer) | Quantity of the product |
| organizationProductExternalId (String) | Unique identifier of the product in the organization |
| orderProductExternalId (String) | Unique identifier of the product in the order |
| price (Integer) | Price of the product in cents, with the quantity already multiplied |
GET Promotion List
{
"promotions": [
{
"id": "28afe959-6204-4169-b5ba-fc90f15aad43",
"name": "El tenedor",
"description": "el tenedor",
"pointsExpense": 3,
"discountType": "percentage",
"discountAmount": 10,
}
]
}
HTTP Request
GET https://api.comeback.es/v1/promotions
Promotion
| Field name | Description |
|---|---|
| id (String) | Unique identifier of the promotion in Last |
| name (String) | Name of the promotion |
| description (String) | Description of the promotion |
| pointsRequired (Integer) | Amount of points that are needed and will be consumed when the promotion is used |
| discountType (String) | Type of the promotion. One of products, 2x1, percentage, currency |
| discountAmount (Integer) | Amount to be discounted by the promotion, can be a percentage or currency amount depending on the type |
POST Create Promotion
Request
{
"name": "50% off all products",
"description": "Get 50% off on all products on your 10th visit",
"pointTypeId": "0e53f16f-88f5-4379-ab6d-b21213968d5c",
"pointsExpense": 9,
"discountType": "percentage",
"discountAmount": 50
}
HTTP Request
POST https://api.comeback.es/v1/promotions
| Field name | Description |
|---|---|
| name (String) | Name of the promotion |
| description (String) | Description of the promotion |
| pointTypeId (String) | ID of the point type |
| pointsExpense (Integer) | Amount of points that will be consumed when the promotion is used |
| code (String) | Code that represents the promotion in the POS system |
| discountType (String) | Type of the promotion (don't needed if code is provided) |
| discountAmount (Integer) | Amount to be discounted by the promotion (don't needed if code is provided) |
GET Customer
Response
{
"id": "33f9dc36-5e99-4044-8e2e-9b22c403c5f7",
"name": "Bruce",
"surname": "Wayne",
"phoneNumber": "+34666666666",
"email": "[email protected]",
"creationTime": "2020-10-06T18:32:04.000Z",
"source": "SignUp",
"marketingCommunication": true,
"birthDate": "1990-01-01",
"externalId": "h230he02",
"appleDownloaded": true,
"androidDownloaded": false,
"points": [
{
"amount": 50,
"pointTypeId": "0e53f16f-88f5-4379-ab6d-b21213968d5c",
"pointTypeName": "Burgers"
}
],
"level": "Gold",
"availablePromotions": [
{
"id": "0hgfd0928ge32ge",
"name": "Descuento 10%",
"description": "Obtén un descuento por valor del 10%",
"discountType": "percentage",
"discountAmount": 10,
"pointsExpense": 0,
"availableOnline": true
},
{
"id": "9hsab0efasf8312",
"name": "Café gratis",
"description": "Obtén un café gratis en tu próxima visita",
"discountType": "currency",
"discountAmount": 250,
"pointsExpense": 10,
"availableOnline": false
}
]
}
HTTP Request
GET https://api.comeback.es/v1/customers/:customerId
Customer
| Field name | Description |
|---|---|
| id (String) | Unique identifier of the customer in Comeback |
| name (String) | Name of the customer |
| surname (String) | Surname of the customer |
| phoneNumber (String) | Full phone number with country code |
| email (String) | Email of the customer |
| creationTime (DateTime) | The time the customer was created (ISO-8601 UTC) |
| source (String) | Source of the customer |
| marketingCommunication | Whether the customer agreed to marketing |
| birthDate (Date) | Birth date of the customer |
| externalId (String) | External identifier of the customer |
| appleDownloaded (Boolean) | Whether the pass was downloaded on Apple devices |
| androidDownloaded (Boolean) | Whether the pass was downloaded on Android devices |
| points (Array) | List of customer current points |
| level (String) | Level of the customer |
| availablePromotions (Array) | List of promotions available to the customer |
Promotion
| Field name | Description |
|---|---|
| id (String) | Unique identifier of the promotion in Comeback |
| name (String) | Name of the promotion |
| description (String) | Description of the promotion |
| discountType (String) | Type of the promotion. One of: percentage, currency |
| discountAmount (Integer) | Amount to be discounted by the promotion, can be a percentage or currency amount in cents, depending on the type |
| pointsExpense (Integer) | Amount of points that are needed and will be consumed when the promotion is used |
| code (String) | Code that represents the promotion in the POS system |
| availableOnline (Boolean) | Whether the promotion should be available in the online shop |
Point
| Field name | Description |
|---|---|
| amount (Integer) | Amount of points |
| pointTypeId (String) | Unique identifier of the point type |
| pointTypeName (String) | Name of the point type |
GET Scanned customer in location
Response
{
"id": "33f9dc36-5e99-4044-8e2e-9b22c403c5f7",
"name": "Bruce",
"surname": "Wayne",
"phoneNumber": "+34666666666",
"email": "[email protected]",
"creationTime": "2020-10-06T18:32:04.000Z",
"source": "SignUp",
"marketingCommunication": true,
"birthDate": "1990-01-01",
"externalId": "h230he02",
"appleDownloaded": true,
"androidDownloaded": false,
"points": [
{
"amount": 50,
"pointTypeId": "0e53f16f-88f5-4379-ab6d-b21213968d5c",
"pointTypeName": "Burgers"
}
],
"level": "Gold",
"availablePromotions": [
{
"id": "0hgfd0928ge32ge",
"name": "Descuento 10%",
"description": "Obtén un descuento por valor del 10%",
"discountType": "percentage",
"discountAmount": 10,
"pointsExpense": 0,
"availableOnline": true
},
{
"id": "9hsab0efasf8312",
"name": "Café gratis",
"description": "Obtén un café gratis en tu próxima visita",
"discountType": "currency",
"discountAmount": 250,
"pointsExpense": 10,
"availableOnline": false
}
]
}
HTTP Request
GET https://api.comeback.es/v1/location/:locationId/customer/:identifier
Use this endpoint to get the relevant customer information for a location. The available promotions will take into account the location where the customer is scanned.
The identifier can be either the phone number or the email of the customer.
Customer
| Field name | Description |
|---|---|
| id (String) | Unique identifier of the customer in Comeback |
| name (String) | Name of the customer |
| surname (String) | Surname of the customer |
| phoneNumber (String) | Full phone number with country code |
| email (String) | Email of the customer |
| creationTime (DateTime) | The time the customer was created (ISO-8601 UTC) |
| source (String) | Source of the customer |
| marketingCommunication | Whether the customer agreed to marketing |
| birthDate (Date) | Birth date of the customer |
| externalId (String) | External identifier of the customer |
| appleDownloaded (Boolean) | Whether the pass was downloaded on Apple devices |
| androidDownloaded (Boolean) | Whether the pass was downloaded on Android devices |
| points (Array) | List of customer current points |
| level (String) | Level of the customer |
| availablePromotions (Array) | List of promotions available to the customer |
Promotion
| Field name | Description |
|---|---|
| id (String) | Unique identifier of the promotion in Comeback |
| name (String) | Name of the promotion |
| description (String) | Description of the promotion |
| discountType (String) | Type of the promotion. One of: percentage, currency |
| discountAmount (Integer) | Amount to be discounted by the promotion, can be a percentage or currency amount in cents, depending on the type |
| pointsExpense (Integer) | Amount of points that are needed and will be consumed when the promotion is used |
| code (String) | Code that represents the promotion in the POS system |
| availableOnline (Boolean) | Whether the promotion should be available in the online shop |
Point
| Field name | Description |
|---|---|
| amount (Integer) | Amount of points |
| pointTypeId (String) | Unique identifier of the point type |
| pointTypeName (String) | Name of the point type |
GET Download customer pass for Android
{
"downloadUrl": "https://testurl.com/gp/v/save/xyz123abc456"
}
HTTP Request
GET https://api.comeback.es/v1/customers/:customerId/androidDownloadUrl?passId={passId}
| Query parameter | Description |
|---|---|
| passId (String) | ID of the pass to download. If not provided, the first customer pass will be obtained. |
| Field name | Description |
|---|---|
| downloadUrl (String) | URL to download the customer pass for Android devices |
GET Download customer pass for Apple
{
"downloadUrl": "https://testurl.com/gp/v/save/xyz123abc456"
}
HTTP Request
GET https://api.comeback.es/v1/customers/:customerId/appleDownloadUrl?passId={passId}
| Query parameter | Description |
|---|---|
| passId (String) | ID of the pass to download. If not provided, the first customer pass will be obtained. |
| Field name | Description |
|---|---|
| downloadUrl (String) | URL to download the customer pass for Android devices |
GET Applied Promotions
{
"appliedPromotions": [
{
"promotionId": "28afe959-6204-4169-b5ba-fc90f15aad43",
"customerId": "33f9dc36-5e99-4044-8e2e-9b22c403c5f7",
"creationTime": "2020-03-12T18:32:04.000Z",
"locationId": "0e75756b-bf8b-41e0-9162-a87e3f19e771",
"orderId": "b2c8bc3-4601-47d1-8a11-26935d57222f"
},
{
"promotionId": "39bfaca0-9920-4224-9762-0cbc8d61dbcf",
"customerId": "33f9dc36-5e99-4044-8e2e-9b22c403c5f7",
"creationTime": "2020-10-06T18:32:04.000Z",
"locationId": "0e75756b-bf8b-41e0-9162-a87e3f19e771",
"orderId": "b2c8bc3-4601-47d1-8a11-26935d57222f"
}
]
}
HTTP Request
GET https://api.comeback.es/v1/customers/:customerId/appliedPromotions
Applied Promotion
| Field name | Description |
|---|---|
| promotionId (String) | Unique identifier of the promotion |
| customerId (String) | Name of the promotion |
| creationTime (Datetime) | Time when the promotion was applied |
| locationId (String) | Unique identifier of the location where the promotion was used |
| orderId (String) | Unique identifier of the order where promotion was applied |
GET Customers list
{
"customers": [
{ /* customer object */ },
{ /* customer object */ },
...
],
"page": 0,
"lastPage": 0
}
HTTP Request
GET https://api.comeback.es/v1/customers
| Query parameter | Description |
|---|---|
| page (Integer) | Result page to show |
* This request is paginated in groups of 100
POST Create Customer
Request
{
"name": "Bruce",
"surname": "Wayne",
"phoneNumber": "+34666666666",
"email": "[email protected]",
"source": "MyWebsite",
"marketingCommunication": true,
"birthDate": "1990-01-01"
}
HTTP Request
POST https://api.comeback.es/v1/customers
| Field name | Description |
|---|---|
| name (String) | Name of the customer |
| surname (String) | Surname of the customer |
| phoneNumber (String) | Full phone number with country code |
| email (String) | |
| source (String) | Source of the customer |
| marketingCommunication (Boolean) | Whether the customer agreed to marketing |
| birthDate (Date) | Birth date of the customer |
DELETE Delete Customer
Deletes a customer from the organization. The customer can be identified by their ID, phone number, or email.
HTTP Request
DELETE https://api.comeback.es/v1/customers/:identifier
URL Parameters
| Parameter | Description |
|---|---|
| identifier | Customer ID, phone number (with country code), or email address |
Response Codes
| Code | Description |
|---|---|
| 200 | Customer deleted successfully |
| 401 | Unauthorized - Invalid or missing token |
| 404 | Customer not found |
GET Point types list
{
"pointTypes": [
{
"id": "0e53f16f-88f5-4379-ab6d-b21213968d5c",
"name": "Points",
"expirationDays": 365,
"allowedPassIds": ["0e53f16f-88f5-4379-ab6d-b21213968d5c"]
},
...
]
}
HTTP Request
GET https://api.comeback.es/v1/pointTypes
Point Type
| Field name | Description |
|---|---|
| id (String) | Unique identifier of the point type |
| name (String) | Name of the point type |
| expirationDays (Integer) | Number of days before points expire |
| allowedPassIds (Array) | List of pass IDs allowed for this point type |
PUT Add Points to Customer
HTTP Request
POST https://api.comeback.es/v1/customers/${customerId}/addPoints
Request
{
"addedPoints": 10,
"pointTypeId": "0e53f16f-88f5-4379-ab6d-b21213968d5c"
}
Webhooks
Whenever there is a content change in our side that may be relevant for an integration we trigger webhook updates.
The request will be made via POST to your chosen webhook enpoint, which on success should return an empty response with status 200.
The update will come in json format in the body of the request, wrapped in an event object, with a corresponding payload (data) with the relevant resource or information.
| Field name | Description |
|---|---|
| type (String) | Type of event |
| eventTime (DateTime) | The time the event was created at (ISO-8601 UTC) |
| data (Object) | The data associated with the particular event |
Customer
{
"type": "customer:created",
"created": "2020-10-06T18:32:04.000Z",
"data": {
/* customer object */
}
}
Types
customer:createdcustomer:updated
Points
{
"type": "customer-points:updated",
"created": "2020-10-06T18:32:04.000Z",
"data": {
"customerId": "072c8bc3-4601-47d1-8a11-26935d57222f",
"locationId": "0e75756b-bf8b-41e0-9162-a87e3f19e771",
"addedPoints": 10,
"newPointsValue": 50,
"pointTypeId": "0e53f16f-88f5-4379-ab6d-b21213968d5c"
}
}
Types
customer-points:updated
Promotions
{
"type": "promotion:applied",
"created": "2020-10-06T18:32:04.000Z",
"data": {
"customerId": "072c8bc3-4601-47d1-8a11-26935d57222f",
"promotionId": "3e75756b-bf8b-41e0-9162-a87e3f19e771"
}
}
Types
promotion:applied
We'll sent this webhook when a promotion is applied for a customer.
FAQ
How can I get a testing account and a testing auth token?
At the moment, you'll need to send an email to our support team at [email protected].
We're currently working on adding the possibility to obtain testing credentials directly through API.
Once I have finished the integration with a testing account, how can I obtain the restaurants production token?
The restaurant manager should send an email to our support team at [email protected] asking for the token. If you are a third party, you can also ask for the token, only if you have the permission from the restaurant.
How can I get the ID of each location?
You can get all the locations related info making a request to GET Location List.
How can I add a webhook URL or suscribe to a webhook event?
At the moment, you'll need to send an email to our support team at [email protected].
We're currently working on adding the possibility to handle webhook management directly through API.
How many tokens I need for all my integrated locations?
You'll need one token for each Organization that you are managing. In our system, an Organization is a set of locations from the same franchise. For example, if you are managing three locations from the same franchise, you only need one token.
I have an API question, who can I ask about it?
You can send an email to [email protected], where we will be pleased to help you as mush as we can.