Overview

This describes the resources that make up the official version 2.2 of the Centelar API. If you have any problems or requests please contact Support.

Current Version

All API access is done through the https://yourdomain/api/v2_2/ base url. If you are not sure about which domain you should use, please contact Support

All requests to the Centelar API receive the v2.2 version of the API. You must explicitly request this version via the /api/v2_2/ prefix in the url.

https://yourdomain/api/v2_2/

Changes from v2.1

Version 2.2 works exactly like version 2.1, except that order and delivery states use English names. This affects the state, shipping_state and shipping.state fields of orders, the response of Receive Item, and the state and previous_state parameters of Item Status Change, which no longer accept the v2.1 names.

To migrate from v2.1, change the /api/v2_1/ prefix to /api/v2_2/ and translate the states as follows.

Order states

v2.1 v2.2 Meaning
creando creating The order is being created and no stock has been reserved yet
reservado reserved The order was created as a reservation
seniado partially_paid Part of the order was paid (a deposit)
a_confirmar payment_unconfirmed The order was fully charged, but some payment is not confirmed yet
pagado paid The order was fully paid
anulado canceled The order was canceled
devuelto returned The order was returned

Delivery states

v2.1 v2.2 Meaning
creando creating How the item will be delivered is not defined yet
diferida deferred The item was sold and reserved at a location, but not checked yet
chequeada checked The item was checked and labeled, and is held until a release date
preparada prepared The item was checked, packed and labeled
lista_para_trasladar ready_for_transfer The item must be moved to another location, where the order is consolidated
en_viaje_de_traslado in_transfer The item is on a trip between locations
lista_para_entregar ready_for_delivery The item is ready to be shipped to the customer
en_viaje_de_entrega out_for_delivery The item is on a delivery trip to the customer
entregada delivered The customer received the item
inmediata immediate The item was bought and handed over at the counter
en_devolucion return_requested The customer asked for a credit note but has not returned the item yet
devuelta returned The returned item arrived at one of your locations
despreparar unpacking The item was canceled and must be unpacked and unlabeled
cancelada canceled The item’s delivery was canceled; the order continues without it
imposible needs_review There is a problem with the item that needs manual review

Schema

When invoking this API, all arguments should be passed as plain http parameters. The API will return all data in JSON format, in the body of the http response.

$ curl -i -X GET "https://yourdomain/api/v2_2/me"

HTTP/1.1 200 OK
Server: nginx/1.2.3
Date: Thu, 17 Jul 2023 15:36:17 GMT
Content-Type: application/json;charset=UTF-8
Transfer-Encoding: chunked
Connection: keep-alive

{
	"success": true,
	"statusMessage": "you are not logged in",
	"logged_in": false
}

All dates are specified in standard full date and time format: yyyy-MM-ddTHH:mm:ssZ using your domain’s configured timezone

...
"date" : "2023-02-20T16:32:51-0300",
 ...

Security

Every call to the api should include the access_token parameter, except for calls to the /authenticate endpoint, which is the one you must use to obtain a valid access_token.

$ curl -i -X GET https://yourdomain/api/v2_2/campaign/stats?access_token=77cd11b71335b73d9a518ec52ee4590fe88b6540

See the /authenticate api endpoint to learn how to obtaining a valid access token.

Client Errors

When calling this API, you must check the HTTP status code returned by Centelar in order to see if there was an error in your call. These are common error scenarios:

  1. Sending requests without an access token will result in a 401 response

     HTTP/1.1 401 Please include the access_token parameter in your requests. You can obtain one using the /api/v2/authenticate endpoint

  2. Sending requests with an invalid/expired access token will result in a 401 response

     HTTP/1.1 401 Please renew your access_token

  3. All other kind of invalid requests will return a 400 Bad Request or 404 Not Found response.

     HTTP/1.1 400 Bad Request
 HTTP/1.1 404 Not Found

Response Schema

All well-formatted and authenticated requests get a 200 OK response. That means that the request was processed by Centelar’s API. The response is sent back as a JSON structure in the body of the response. For simple GET request, normally you will get a JSON Object or Array with the requested data. For POST request, responses will be a JSON Object that always contain at least these two attributes: success and statusMessage. If success is false, then you can see the error message in the statusMessage attribute of the response.

$ curl -i -X GET "https://yourdomain/api/v2_2/me?access_token=ACCESS-TOKEN"

HTTP/1.1 200 OK
Server: nginx/1.2.3
Date: Thu, 17 Jul 2023 16:07:27 GMT
Content-Type: application/json;charset=UTF-8
Transfer-Encoding: chunked
Connection: keep-alive

{
    "success": true,
    "statusMessage": "you are logged in as 'api'",
    "logged_in": true
}

HTTP Verbs

Where possible, API v2.2 strives to use appropriate HTTP verbs for each action.

Verb Description
HEAD Can be issued against any resource to get just the HTTP header info.
GET Used for retrieving resources.
POST Used for creating or updating resources, or perform custom actions.
PUT Used for replacing resources or collections.
DELETE Used for deleting resources.

Authentication

Requests that require authentication will return 404 Not Found, instead of 403 Forbidden, in some places. This is to prevent the accidental leakage of private schemas to unauthorized users.

Obtaining an Access Token

To obtain an access token, you need to call the authenticate endpoint, as shown in the example below. For that call, you need a valid apiKey, userName and password. This information should be provided to you by your Centelar support representative or account manager.

$ curl -i -X POST -d 'userName=YOUR-USER-NAME&apiKey=YOUR-API-KEY&password=YOUR-PASSWORD'  https://yourdomain/api/v2_2/authenticate

HTTP/1.1 200 OK
Server: nginx/1.2.3
Date: Sat, 18 Jul 2023 00:19:29 GMT
Content-Type: application/json;charset=UTF-8
Transfer-Encoding: chunked
Connection: keep-alive
Expires: Thu, 01-Jan-1970 00:00:00 GMT

{
	"success": true,
	"access_token": "202060259b0df2b6d5b56a9b50a149e3270816f2",
	"expires": "2023-02-20T16:32:51-0300"
}

Using the Access Token

The call to the authenticate endpoint returns JSON object with a access_token attribute, which you can then use in subsequent calls to the API, by adding the access_token parameter to every call.

$ curl -i -X GET https://yourdomain/api/v2_2/me?access_token=ACCESS-TOKEN

Refreshing the Access Token

If at anytime you get a HTTP/1.1 401 Please renew your access_token response, you should renew your access token by calling the authenticate endpoint again.