APIv3

This is the atalogics APIv3. If you are searching for atalogics APIv2, please refer to APIv2

APIv3 only provides endpoints for retrieving and booking an offer so far. In order to use all the other endpoints, please refer to APIv2.

Production & Sandbox environment

We provide two separate environments, for production and testing:

Important:

  • All the examples are written for the sandbox environment. To use it in production, simply replace sandbox.atalogics.com with atalogics.com
  • If you want to use our sandbox environment, you have to register yourself a test user, a test company... You can do this at https://sandbox.atalogics.com (without the need to confirm users or wait for permission confirmation of your company from our side).

Field definitions & playground

You can find all the field definitions and an interactive playground here:

Sandbox & Production: https://tryout.atalogics.com

Make sure to include your access_token at the top.

Authentication

atalogics uses the OAuth2 standard for authentication and authorization users and applications. For now, we only support the client_credentials flow.

1. Get your credentials

To use the atalogics API, you need a client_id and a client_secret. You can generate both, by going to https://sandbox.atalogics.com/companies -> Your Company > Generate API Application

2. Get an access token

Make a POST request to https://atalogics.com/oauth/token like this

cURL example:

curl -i https://sandbox.atalogics.com/oauth/token -H "Content-Type: application/json"\
--data '{ "client_id":"XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",\
"client_secret":"XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",\
"grant_type": "client_credentials" }'

When succesful, this returns an http status 200 with an access token, which is valid for a specific time:

{
  "access_token": "XXXXXXXXXXXXXXXXXXXXXXXX",
  "token_type": "bearer",
  "expires_in": 172800,
  "created_at": 1494322110
}

When something went wrong, you'll get a proper http error status, and a readable error descriptions like:

// http state 401, Unauthorized
{
  "error": "invalid_client",
  "error_description":"Client authentication failed due to unknown client, no client authentication included, or unsupported authentication method."
}

// http state 401, Unauthorized
{
  "error":"unsupported_grant_type",
  "error_description":"Unsupported grant_type. Valid values are client_credentials, authorization_code, password, refresh_token"
}

3. Include the access token in further requests

To authenticate and authorize your further requests, you have to include your access_token as a header:

Authorization: bearer XXXXXXXXXXXXXXXXXXXXXXXX

cURL example:

curl -i https://sandbox.atalogics.com/api/v2/shipments -H "Content-Type: application/json"\
-H "Authorization: bearer XXXXXXXXXXXXXXXXXXXXXXXX"\
--data '{}'

4. Get an offer

Make a POST request to https://sandbox.atalogics.com/api/v3/offers:

curl -i https://sandbox.atalogics.com/api/v3/offers -H "Content-Type: application/json"\
 -H "Authorization: bearer XXXXXXXXXXXXXXXXXXXXXXXX"\
 --data '{
  "catch_address": "Torstraße 102, 10119 Berlin," ,
  "drop_address": "Margaretenstr. 37, 12203 Berlin,"
}'

This returns an array of offers that include a key which is used in the next step to book a shipment. Furthermore catch_window and drop_window denote the possible timeslots.

{
  "offers": [
    {
      "city_key": "Berlin",
      "key": "XXX",
      "catch_window": {
        "from": "2017-05-09T08:00:00.000+02:00",
        "to": "2017-05-09T17:00:00.000+02:00",
        "bookable_till": "2017-05-09T16:00:00.000+02:00",
        "usable_till": "2017-05-09T16:00:00.000+02:00"
      },
      "drop_window": {
        "from": "2017-05-09T18:00:00.000+02:00",
        "to": "2017-05-09T21:00:00.000+02:00",
        "bookable_till": "2017-05-09T20:00:00.000+02:00",
        "usable_till": "2017-05-09T20:00:00.000+02:00"
      }
    }
  ]
}

5. Book an offer

To book an offer, do a POST request to https://sandbox.atalogics.com/api/v3/shipments (replace the offer_key with the value you got from the /api/v3/offers endpoint):

curl -i https://sandbox.atalogics.com/api/v3/shipments -H "Content-Type: application/json"\
  -H "Authorization: bearer XXXXXXXXXXXXXXXXXXXXXXXX"\
 --data '{
  "offer_key": "XXX",
  "catch_address": {
    "firstname": "Maria",
    "lastname": "Musterfrau",
    "street": "Torstraße",
    "number": "102",
    "postal_code": "10119",
    "city": "Berlin",
    "phone": "1234567890"
  },
  "drop_address": {
    "firstname": "Max",
    "lastname": "Mustermann",
    "street": "Margaretenstr",
    "number": "37",
    "postal_code": "12203",
    "city": "Berlin",
    "phone": "1234567890"
  }
}'

The response includes all information you need to continue processing a shipment in your application (tracking_id, state, catch_date, drop_date etc.).

{
  "tracking_id": "01XKLEIN07MM",
  "external_id": null,
  "state": "ordered",
  "ordered_at": "2017-05-09T12:57:59.899+02:00",
  "catch_date": "2017-05-09",
  "drop_date": "2017-05-09",
  "color_idx": 4,
  "webhook_url": null,
  "webhook_gps_url": null,
  "catch_address": {
    "firstname": "Maria",
    "lastname": "Musterfrau",
    "street": "Torstraße",
    "number": "102",
    "postal_code": "10119",
    "city": "Berlin",
    "phone": "1234567890",
    "email": null,
    "country": "Deutschland",
    "company_name": null,
    "additional_info": null,
    "lat": 53.57557,
    "lng": 9.93772
  },
  "drop_address": {
    "firstname": "Max",
    "lastname": "Mustermann",
    "street": "Margaretenstr",
    "number": "37",
    "postal_code": "12203",
    "city": "Berlin",
    "phone": "1234567890",
    "email": null
    "country": "Deutschland",
    "company_name": null,
    "additional_info": null,
    "lat": 53.5724295,
    "lng": 9.9343918
  },
  "extra_services": [],
  "id": "5911a0b7a1a22f0166000009",
  "cancelable?": true,
  "color": {
    "name": "deeppink",
    "value": "#FF1493"
  },
  "needs_a_courier": true,
  "catch_timeslot": {
    "id": "59118b2222946102d4000003",
    "window": {
      "from": "2017-05-09T08:00:00.000+02:00",
      "to": "2017-05-09T17:00:00.000+02:00",
      "bookable_till": "2017-05-09T16:00:00.000+02:00",
      "usable_till": "2017-05-09T16:00:00.000+02:00"
    },
    "type": "range"
  },
  "drop_timeslot": {
    "id": "59118b2222946102d4000004",
    "window": {
      "from": "2017-05-09T18:00:00.000+02:00",
      "to": "2017-05-09T21:00:00.000+02:00",
      "bookable_till": "2017-05-09T20:00:00.000+02:00",
      "usable_till": "2017-05-09T20:00:00.000+02:00"
    },
    "type": "range"
  },
  "zone": "Berlin",
  "couriers": []
}

# Reading Notes

The backslash `\` at the end of the cURL examples is only used, so you can copy and paste the examples into the terminal.

Quick Links