APIv2

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

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": 7200
}

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 like this:

Authorization: bearer XXXXXXXXXXXXXXXXXXXXXXXX

cURL example:

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

Book a shipment

The way of booking shipments is a 2-phase:

  1. Get a list of offers that are available for an address and a specific time.
  2. Add optional extra services
  3. Add optional catch and drop filters
  4. Book this shipment through an offer_id.

1. Get an offer

Make a POST request to https://sandbox.atalogics.com/api/v2/offers like this:

curl -i https://sandbox.atalogics.com/api/v2/offers -H "Content-Type: application/json"\
 -H "Authorization: bearer XXXXXXXXXXXXXXXXXXXXXXXX"\
 --data '{
  "catch_address": {
    "street": "Ignaz-Harrer-Str.",
    "number": "32",
    "postal_code": "5020",
    "city": "Salzburg"
  },
  "drop_address": {
    "street": "Maxglaner Hauptstrasse",
    "number": "12",
    "postal_code": "5020",
    "city": "Salzburg"
  }
}'

This returns an array of offers that include an offer_id which is used in the next step to purchase a shipment:

[{
  "offer_id":"eyJjYXRjaF90aW1lc2xvdF9pZCI6IjU0ODlmNzNhMzIzMzc0MWQwMDBjMDAwMCIsImRyb3BfdGltZXNsb3RfaWQiOiI1NDg5Zjc1MzMyMzM3NDFkMDAwZTAwMDAiLCJjYXRjaF9kYXRlIjoiMjAxNS0wMS0yNyIsImRyb3BfZGF0ZSI6IjIwMTUtMDEtMjciLCJleHRyYV9zZXJ2aWNlcyI6W10sInZhbGlkX2F0IjoiMjAxNS0wMS0yN1QxNzo1MDoxNi43ODUrMDE6MDAifQ==",
  "catch_date":"2015-01-27",
  "drop_date":"2015-01-27",
  "city_id":"53abd6dc636f6d71b0010000",
  "fee":{
    "currency":"eur",
    "amount":5.95
  },
  "catch_timeslot":{
    "window":{
      "from":"2015-01-27T08:00:00.000+01:00",
      "to":"2015-01-27T17:00:00.000+01:00"
    },
    "type":"range"
  },
  "drop_timeslot":{
    "window":{
      "from":"2015-01-27T18:00:00.000+01:00",
      "to":"2015-01-27T21:00:00.000+01:00"
    },
    "type":"range"
  }
}]

A list of all required and optional attributes is available here: https://tryout.atalogics.com/#!/offers/POST_offers_format

2. Extra Services

You can book extra services for every offer. To get a list of available extra services for a city, make a GET request to https://sandbox.atalogics.com/api/v2/cities/{city_id}/extra_services.

Available values for {city_id} inside the production environment are:

Wuppertal ID: 552cf4e55562752ea1160000
Attendorn ID: 55f262a5c32dab4b930056f0
Dortmund ID: 5720933dc32dab4f5f0521f2
Wien ID: 552e15be5562752ea1e30000
New York ID: 552e19725562752ea1e40000
Hamburg ID: 553fc1015562753d1e6e0100
Wolfenbüttel ID: 5620b64bc32dab0b0c0083a4
Göppingen ID: 55fbfb3bc32dab4bbf0076b1
Heilbronn ID: 5673ccbcc32dab579b074a39
Bern ID: 560be129c32dab306a000b85
Ravensburg ID: 57c7303bc32dab503908f52e
Bedburg ID: 57e40fe7c32dab7342091ca1
Freilassing ID: 58071d5bc32dab343004c342
Zürich ID: 583ebae3c32dab0cf102a088
Offenburg ID: 58733b63c32dab2110000003
Pfaffenhofen ID: 58ca6ed7c32dab2651000019
Speedy Zürich ID: 58de04c8c32dab5cbd000000
Berlin ID: 58f9fb89c32dab4605000000
Speedy Bern ID: 5936c4abc32dab13d7000007
Bonn ID: 597ad9a6c32dab5c270000de
Günzburg ID: 58ca74ffc32dab265100001f

curl -i -H "Authorization: bearer XXXXXXXXXXXXXXXXXXXXXXXX" "https://sandbox.atalogics.com/api/v2/cities/552cf4e55562752ea1160000/extra_services"

This will return a JSON array, which includes the identifier and the phases (if the extra service will be applied at catch, drop or at both phases of the shipment):

[{
    "identifier": "FSK18",
    "name": "Altersverifikation FSK18",
    "description": "Altersverifikation per Ausweis beim Abholen und Liefern.",
    "phases": [
      "catch",
      "drop"
    ],
    "fee": {
      "currency": "eur",
      "amount": 1.5
    }
}]

The identifiers are then included inside your offers POST request like this:

{
  "catch_address": { ... },
  "drop_address": { ... },
  "extra_services": ["FSK18"]
}

3 Exclude times and/or dates

For the case that your shop is closed for certain times or dates, we provide a catch_filter and drop_filter field. You can include offers for specific times at workdays, half holidays, holidays, specific week days and also exclude whole dates. To do so, include an additional catch_filters or drop_filters hash into your JSON POST request:

{
  "catch_address": { ... },
  "drop_address": { ... },
  "catch_filters": {
    "workday": "08:00-12:00,14:00-17:00",
    "exclude_dates": ["2015-01-09"]
  },
  "drop_filters": {
    "workday": "08:00-12:00,14:00-17:00",
    "exclude_dates": ["2015-01-09"]
  }
}

For this example, you would only get offers that can be delivered on workdays between 08:00 - 12:00 and 14:00 - 17:00 o'clock. It would also excludes offers for the 9th of January 2015 (e.g. your shop is closed at this day).

All available options can be found here: https://tryout.atalogics.com/#!/offers/POST_offers_format

4. Book an offer

To book an offer, you can do a POST request to https://sandbox.atalogics.com/api/v2/shipments like this (replace the offer_id with the values you got from the /api/v2/offers endpoint):

curl -i https://sandbox.atalogics.com/api/v2/shipments -H "Content-Type: application/json"\
 -H "Authorization: bearer XXXXXXXXXXXXXXXXXXXXXXXX"\
 --data '{
  "offer_id": "eyJjYXRjaF90aW1lc2xvdF9pZCI6IjU0ODlmNzNhMzIzMzc0MWQwMDBjMDAwMCIsImRyb3BfdGltZXNsb3RfaWQiOiI1NDg5Zjc1MzMyMzM3NDFkMDAwZTAwMDAiLCJjYXRjaF9kYXRlIjoiMjAxNS0wMS0yNyIsImRyb3BfZGF0ZSI6IjIwMTUtMDEtMjciLCJleHRyYV9zZXJ2aWNlcyI6W10sInZhbGlkX2F0IjoiMjAxNS0wMS0yN1QxNzo1MDoxNi43ODUrMDE6MDAifQ",
  "catch_address": {
    "firstname": "Maria",
    "lastname": "Musterfrau",
    "street": "Ignaz-Harrer-Str.",
    "number": "32",
    "postal_code": "5020",
    "city": "Salzburg",
    "phone": "1234567890"
  },
  "drop_address": {
    "firstname": "Max",
    "lastname": "Mustermann",
    "street": "Maxglaner Hauptstrasse",
    "number": "12",
    "postal_code": "5020",
    "city": "Salzburg",
    "phone": "1234567890"
  }
}'

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

{
  "tracking_id":"1#MAXGL12MM",
  "state":"ordered",
  "ordered_at":"2015-01-27T14:59:10.441Z",
  "catch_date":"2015-01-27",
  "drop_date":"2015-01-27",
  "color_idx":10,
  "catch_address":{
    "firstname":"Maria",
    "lastname":"Musterfrau",
    "email":null,
    "phone":"1234567890",
    "street":"Ignaz-Harrer-Str.",
    "number":"32",
    "city":"Salzburg",
    "postal_code":"5020",
    "country":"Österreich",
    "company_name":null,
    "additional_info":null,
    "lat":47.8114973,
    "lng":13.031406
  },
  "drop_address":{
    "firstname":"Max",
    "lastname":"Mustermann",
    "email":null,
    "phone":"1234567890",
    "street":"Maxglaner Hauptstrasse",
    "number":"12",
    "city":"Salzburg",
    "postal_code":"5020",
    "country":"Österreich",
    "company_name":null,
    "additional_info":null,
    "lat":47.7963949,
    "lng":13.0241833
  },
  "extra_services":[

  ],
  "id":"54c7c3de323374291c350000",
  "cancelable?":true,
  "catch_timeslot":{
    "window":{
      "from":"2015-01-27T08:00:00.000+01:00",
      "to":"2015-01-27T17:00:00.000+01:00"
    },
    "type":"range"
  },
  "drop_timeslot":{
    "window":{
      "from":"2015-01-27T18:00:00.000+01:00",
      "to":"2015-01-27T21:00:00.000+01:00"
    },
    "type":"range"
  }
}

A list of all required and optional attributes is available here: https://tryout.atalogics.com/#!/offers/POST_offers_format

Address check

Check if an address is inside our delivery area.

Make a GET request to https://sandbox.atalogics.com/api/v2/addresses/single/check and append street, postal_code and city as parameter to the url.

curl -i -H "Authorization: bearer XXXXXXXXXXXXXXXXXXXXXXXX" "https://sandbox.atalogics.com/api/v2/addresses/single/check?street=Maxglaner%20Hauptstrasse%2013&postal_code=5020&city=Salzburg"

Webhooks

Webhooks are used to, to inform your server about state changes of a shipment. When you provide the field webhook_url in your JSON data, a POST request will be send to this URL every time the state of a shipment changes. Have a look at https://tryout.atalogics.com where you can include the webhook url.

The JSON data, sent to your server, includes the following information about your shipment:

{
  "external_id": "EXT123",
  "tracking_id": "01XSTETT11MM",
  "state": "ordered",
  "gps_position": {},
  "catch_address": {
    "firstname": "Max",
    "lastname": "Müller",
    "email": "foo@bar.com",
    "phone": "12345",
    "street": "Jakob-Haringer-Straße",
    "number": "58",
    "city": "Salzburg",
    "postal_code": "5020",
    "country": "Österreich",
    "company_name": "Limited Ltd.",
    "additional_info": "1. Stock",
    "lat": 47.8226897,
    "lng": 13.0417092
  },
  "drop_address": {
    "firstname": "Maria",
    "lastname": "Musterfrau",
    "email": null,
    "phone": "12345",
    "street": "Schwedenstraße",
    "number": "8",
    "city": "Salzburg",
    "postal_code": "5020",
    "country": "Österreich",
    "company_name": "Firma XYZ",
    "additional_info": "Bitte hinterm Haus klingeln",
    "lat": 47.7984037,
    "lng": 13.0232296
  },
  "extra_services": [],
  "ordered_at": "2015-07-14T12:00:00+02:00"
}

"state" can be:

  • ordered: Initial state when the shipment is ordered.
  • reserved: Shipment is reserved for your company
  • assigned: Shipment is assigned to a courier
  • in_progress: Courier currently carries the shipment (fulfilled catched at customer)
  • delivered: Shipment is successfully delivered
  • returning: Shipment is currently returned from the customer
  • failed: Shipment has failed
  • canceled: Shipment was canceled by a customer, dispatcher or admin

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.