Welcome to our API REST integration documentation! With this solution, you will have access to the entities and operations of our Cabify Logistics service. If you want to delve deeper into the functionality of this service, we invite you to visit our detailed documentation.

Prerequisites

• Follow these steps before starting to get your API key.

Environments

We provide a testing environment called "sandbox" and a production environment. The API specifications and functionality are identical in both environments, with only slight differences in the URL domain.

• Production -> cabify.com
• Sandbox -> cabify-sandbox.com

Everything, authentication included, is served from the logistics API
subdomain, logistics.api. There is one base URL to configure:

https://logistics.api.{{BASE_ENV_URL}}

Where BASE_ENV_URL can have two values depending on the environment you want to target: production or sandbox.

Written out, so you can copy it into your configuration:

The token endpoint also answers on the bare domain -- https://{{BASE_ENV_URL}}/auth/api/authorization -- so an
integration already pointing there keeps working. New ones should use the
single host above.

The environments are independent of each other. Credentials, parcels and
webhook subscriptions created in one do not exist in the other, so if nothing
you created seems to be there, check which environment you are talking to
before anything else.

Authentication

The Cabify Logistics API uses the OAuth 2.0 protocol for request authentication and authorization.

With the API access credentials, you need to generate an access token, which must be attached to all API requests.

Here is an example request:

# Get your Access Token
curl -X POST -d "grant_type=client_credentials&client_id={{OAUTH_ID}}&client_secret={{SECRET}}"
    --url https://logistics.api.{{BASE_ENV_URL}}/auth/api/authorization

Where:

• OAUTH_ID -> The value labeled UUID in your API keys. It goes in client_id.
• SECRET -> The value labeled Secreto in your API keys. It goes in client_secret.
• BASE_ENV_URL -> With the values cabify.com or cabify-sandbox.com, depending on the target environment.

Both values come from the Apps section of the Cabify Logistics portal, as explained in Get your Logistics API key. Credentials from anywhere else do not work with this API. The pair must also come from the same environment as BASE_ENV_URL. If a value is wrong or swapped, the request fails with a 422 error.

🚧

A token that works for nothing

If the token request succeeds but your first call with that fresh token returns
401 ("Provided token is invalid or expired"), the credentials exist but are not
enabled for the Logistics API in that environment. This is what happens with
credentials generated in Cabify Business instead of the Cabify Logistics portal,
or when the account has not been set up for Logistics. Retrying or refreshing the
token will not fix it: contact us with your client_id and the environment you
are calling.

Example response:

Get your Access Token Response

{
    "access_token": "alfanumeric_example_access_token",
    "refresh_token": "alfanumeric_example_refresh_token",
    "expires_in": 2591999,
    "token_type": "Bearer"
}

The access_token field is the one you must include in the authentication headers of your requests: Authorization: Bearer alfanumeric_example_access_token.

This token has an expiration time, which you can see in the token generation response under the expires_in field. You must refresh it before this time elapses, or your requests will return an error with HTTP status code 401.

To refresh the token, you need to make a call to the same endpoint used for token creation but with a different value in the grant_type parameter, in this case, refresh_token, and the value of the refresh_token parameter provided in the previous call. The request would look like this:

# Refresh your Access Token
curl -X POST -d "grant_type=refresh_token&client_id={{OAUTH_ID}}&client_secret={{SECRET}}&refresh_token=alfanumeric_example_refresh_token"
    --url https://logistics.api.{{BASE_ENV_URL}}/auth/api/authorization

This will return a payload with the same format as before:

Refresh your Access Token Response

{
    "access_token": "new_alfanumeric_example_access_token",
    "refresh_token": "new_alfanumeric_example_refresh_token",
    "expires_in": 2591999,
    "token_type": "Bearer"
}

Start using the API

Now that you have your access token, you can start using the API. To do so, you need to include the token in the Authorization header of your requests.

We recomend you to start testing the API with the sandbox environment, where you can simulate different scenarios and test the integration with your pre-production environment(s).