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:

Salzburg ID: 5526b96f556275312a040000
Attendorn ID: 55f262a5c32dab4b930056f0
Dortmund ID: 5720933dc32dab4f5f0521f2
Sarstedt ID: 5d7b62afeb9a037825013f44
kaufinBW - Blatt & Blüte ID: 5e621711cc57b7008c000029
Monheim - Bäckerei Eilers ID: 5ea834dcbe5b6e02660032f4
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
Berlin - Reinickendorf ID: 58f9fb89c32dab4605000000
Bonn ID: 597ad9a6c32dab5c270000de
Schweiz ID: 59a578f5c32dab43a0000188
Zürich-Pickup ID: 59e862cac32dab77f50001f0
Alfeld ID: 59e4cef5c32dab44b400011b
Monheim ID: 59c0d106c32dab1d4d000170
Homburg ID: 5a023a3dc32dab63070003f7
Braunau-Simbach ID: 5a97d689c32dab2a7f000b93
Bern-Pickup ID: 59e86284c32dab77f50001ef
Luxembourg (SAME DAY) ID: 5a1e83f0c32dab307c00125a
Erding ID: 5afc6fe5c32dab042b001b97
Eisleben ID: 5b44787522df7f008b009d27
Luxembourg (NEXT DAY) ID: 5b7d74e881ad59008c000003
Ettlingen ID: 5b90fa22152eb6008c000cac
Lux Batiself Foetz ID: 5bc7396eedb5e40034002241
Bitterfeld ID: 5b44a64622df7f008b009d60
Gmunden ID: 5b17c50a00372f0038001056
kaufinBW ID: 5c77f5a2edb5e4638b0034ce
Pfungstadt ID: 5e785d70cc57b7008c000b12
Monheim - Eiscafé art & wEISe ID: 5e79fad4cc57b7008c001067
Pfaffenhofen-Primo-Pizza ID: 5e81e213cc57b7008c003c17
Monheim - Einkaufsliste ID: 5e8224e3cc57b7008c004072
Nordfriesland ID: 5e4bdb69301e3a008c0016a6
Luxembourg De Coursier ID: 5e8c2afdbe5b6e0266000563
Bochum ID: 5a5f2143c32dab738700000e
kaufinBW - Fil & Chris ID: 5e8f1a70be5b6e026600195a
Ettlingen - Uhren Dotter ID: 5e9955aebe5b6e02660023c6
Ludwigsburg ID: 5fa43f5f2491d2005fc9c19e
Monheim - Hilgers ID: 5fce2a862491d2005fc9f560
Neuruppin ID: 602bb7eb2491d224964d7651
Kirn ID: 6040e51c2491d2005f9e9e13
kaufinbw - Blumen Bertsch ID: 6092933c2491d251535c93c3
Rahlstedt ID: 60a38fb12491d200784dbf2d
Grossenhain ID: 60a38b612491d200784dbf05
Hildburghausen ID: 60b639d92491d200784dc23e
Hamburg - NOMIS ID: 61110b7d2491d20078783123
Günzburg ID: 58ca74ffc32dab265100001f
Dessau ID: 60ebe4692491d200784dd0de
Dormagen ID: 619f7b912491d23ca2f46b88
Meckpom ID: 61a7360b2491d20079bf9ad0
Frankreich ID: 642f3685eacfdf007899f723
Altmühlfranken ID: 5dcbdbce0696c3008c000767
Halle (Saale) ID: 5e8f005ebe5b6e026600191e
Altmühlfranken - Bäckerei Herzog ID: 5e8318cccc57b7008c004100
Hamburg - Salima ID: 5eb93de8be5b6e008c000543
Regensburg ID: 5eccc44b3a4e96008c0000b1
Murrhardt ID: 5cb83818eb9a03008e007cb9
Wuppertal ID: 552cf4e55562752ea1160000
atalanda ID: 5e7b7172cc57b7008c001722
Modehaus ID: 5fa3c38c2491d2005fc9c0de
Sabu ID: 62627f9d2491d20078108a2d
Leipzig ID: 5a86f352c32dab6ff600049b
Schuhe.de ID: 62e0f63e2491d200788880e7
Altmühlfranken - HeimaTeil ID: 62ea73bf2491d200788880ed
Sabu - Winkler (4399901939851) ID: 639b18632491d20077bc6fb3
Leipzig (self_collect) ID: 63a414522491d217d44ec681
Bochum - Ruhrprojekt ID: 5f8983952491d2005fc9b19a
Wällermarkt ID: 61a7364a2491d20079bf9adb
Südpfalz - Natursteine Kohler ID: 62ce84642491d277a7c808dd
Berlin ID: 62d8fb182491d200788880de

curl -i -H "Authorization: bearer XXXXXXXXXXXXXXXXXXXXXXXX" "https://sandbox.atalogics.com/api/v2/cities/5526b96f556275312a040000/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.