This is the atalogics APIv2. If you are searching for atalogics APIv3, please refer to APIv3
We provide two separate environments, for production and testing:
Important:
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.
atalogics uses the OAuth2 standard for authentication and authorization users and applications. For now, we only support the client_credentials flow.
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
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"
}
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 '{}'
The way of booking shipments is a 2-phase:
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
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"]
}
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
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
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 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 companyassigned: Shipment is assigned to a courierin_progress: Courier currently carries the shipment (fulfilled catched at customer)delivered: Shipment is successfully deliveredreturning: Shipment is currently returned from the customerfailed: Shipment has failedcanceled: Shipment was canceled by a customer, dispatcher or adminThe backslash \ at the end of the cURL examples is only used, so you can copy and paste the examples into the terminal.