API Dokumentace Vyzvedni.to Dodame.to
Dokumentace je ve fázi přípravy!

Základní informace

  • Pro komuninaci s API budete potřebovat přístupové údaje, které Vám poskytneme.
  • API je na adrese: https://app.vyzvedni.to
  • Každý požadavek, který má v těle JSON, by měl mít hlavičku Content-Type: application/json.
  • V případě chyby vrací API JSON s textem zprávy a odpovídající kód chyby.
  • API pracuje v kódování UTF-8

Autentizace

Autentizace všech požadavků probíhá ověřením tokenu, který musí být součástí URL požadavku. Pro výpočet tokenu použijte následující konstrukci:

token = base64encode(hmac("sha1", "apisecret", "{partnerBranchId}+{httpMethod}+{timestamp}"))

Před použitím v URI použijte pro token funkci URL Encode.

  • apisecret: (string) Řetězec znaků, který Vám poskytneme (např. kjhJ5424siS!!POS)
  • partnerBranchId: (int) ID Vaší pobočky z našeho systému, které Vám poskytneme (např. 2)
  • httpMethod: Použitá metoda volání požadavku (GET / POST / PUT / DELETE)
  • timestamp: Časová známka požadavku (2021-04-04T12:45:32)

Kódy chyb

HTTP Stav Kód Význam
200 0 Success. No error.
200 -1 Authentication error.
200 -2 Invalid input data.
200 -99 System Error.
500 Unhandled System Error :-(.

Datová struktura

Všechny požadavky musí mít shodnou základní datovou strukturu:

  • timestamp: Časová známka požadavku (2021-04-04T12:45:32)
  • partnerId: (int) ID partnera, které Vám přidělíme (např. 1)
  • partnerBranchId: (int) ID Vaší pobočky z našeho systému, které Vám poskytneme (např. 2)
  • data: (object|null) Kontejner pro data specifická danému požadavku

Ukázka

{
    "partnerId": 1,
    "partnerBranchId": 2,
    "timestamp": "2021-04-02T15:19:23",
    "data": {
        "packetplace_id": 10
  }
}

Seznam výdejních míst

V této chvíli se ještě upřesňuje. Poskytuje seznam aktuálních výdejních míst.
  • URI: /api/packetplace?token={token}
  • HTTP metoda: POST
  • Hlavičky:
    • Content-Type: application/json
  • Parametry:
    • (string) token
  • Tělo požadavku:
    • (int) partnerId
    • (int) partnerBranchId
    • timestamp

Odpověd

Tělo:

  • errorCode: (int) číselný kód odpovědi
  • errorMsg: (string) text
  • data: (array) pole objektů jednotlivých poboček
    • (int) id
    • (string) name
    • (string) name_add
    • address: (object)
      • (string) city
      • (string) street
      • (string) postcode
      • (string) cordLtd
      • (string) cordLng
      • (string) country

Založení zásilky

Metoda pro založení nové zásilky do systému.
  • URI: /api/package?token={token}
  • HTTP metoda: POST
  • Hlavičky:
    • Content-Type: application/json
  • Parametry:
    • (string) token
  • Tělo požadavku:
    • (int) partnerId
    • (int) partnerBranchId
    • timestamp
    • data: (object)
      • (int) packetplace_id // ID výdejního místa
      • (int) partner_branch_id
      • (int) packet_count // Počet balíků
      • (float) weight // Celková hmotnost v kg
      • (float) package_length // Délka balíku v cm
      • (float) package_width // Šířka balíku v cm
      • (float) package_height // Výška balíku v cm
      • (float) price // Cena zásilky bez DPH
      • (int) dph // Procentní sazba DPH
      • (string|null) notes // Poznámka
      • customer: (object)
        • (string) firstname // Křesní jméno příjemce
        • (string) lastname // Přijmení příjemce
        • (string) phone // Telefon příjemce
        • (string) email // Email příjemce
        • (string) street // Ulice a č.p. doručení
        • (string) city // Město doručení
        • (string) postcode // PSČ doručení
        • (string) country // CZ
        • (string|null) company // Název společnosti
        • (string|null) ic // IČ společnosti
        • (string|null) dic // DIČ společnosti

Odpověd

Tělo:

  • errorCode: (int) číselný kód odpovědi
  • errorMsg: (string) text
  • data: (object)
    • (string) packageId // Track ID zásilky
    • (string) packageState // Stav zásilky
    • (datetime) dateCreate // Datum založení
    • (url) customerTrackUrl // Track URL zásilky
    • (url) shipmentPdf // URL pro stažení jízdenky

Zrušení (storno) zásilky

Metoda pro storno nové zásilky.
  • URI: /api/package/{packageId}?token={token}
  • HTTP metoda: DELETE
  • Hlavičky:
    • Content-Type: application/json
  • Parametry:
    • (string) packageId
    • (string) token
  • Tělo požadavku:
    • (int) partnerId
    • (int) partnerBranchId
    • timestamp

Odpověd

  • errorCode: (int) číselný kód odpovědi
  • errorMsg: (string) text

Označení zásilky jako Expedovaná

Po expedici zásilky volá partner tuto metodu. Takto označená zásilka musí být připravena k vyzvednutí našimi kurýry.
  • URI: /api/package/{packageId}?token={token}
  • HTTP metoda: PUT
  • Hlavičky:
    • Content-Type: application/json
  • Parametry:
    • (string) packageId
    • (string) token
  • Tělo požadavku:
    • (int) partnerId
    • (int) partnerBranchId
    • timestamp

Odpověd

  • errorCode: (int) číselný kód odpovědi
  • errorMsg: (string) text

Čtení stavu zásilky

Metoda vrací stav zásilky a URL pro track zásilky a stažení jízdenky.
  • URI: /api/package-status/{packageId}?token={token}
  • HTTP metoda: POST
  • Hlavičky:
    • Content-Type: application/json
  • Parametry:
    • (string) packageId
    • (string) token
  • Tělo požadavku:
    • (int) partnerId
    • (int) partnerBranchId
    • timestamp

Odpověd

Tělo:

  • errorCode: (int) číselný kód odpovědi
  • errorMsg: (string) text
  • data: (object)
    • (string) packageId // Track ID zásilky
    • (string) packageState // Stav zásilky
    • (datetime) dateCreate // Datum založení
    • (url) customerTrackUrl // Track URL zásilky
    • (url) shipmentPdf // URL pro stažení jízdenky

Stavy zásilek

STAV INFO
NEW Nová zásilka
EXPEDED Expedovaná partnerem
SHIPED Převzatá při svozu
PREPARED Doručená na výdejní místo
DELIVERED Doručená/Předána příjemci
NOTACCEPT Zamítnutá kurýrem
RETURNED Nepřevzatá/zamítnutá/vrácená zákazníkem
CANCELED Zrušená partnerem