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 -> Obtained from the API access credentials mentioned in the prerequisites.
• SECRET -> Obtained from the API access credentials mentioned in the prerequisites.
• BASE_ENV_URL -> With the values cabify.com or cabify-sandbox.com, depending on the target environment.

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).