Dokumentace API v3
Úvod
API (Application Programming Interface) slouží k tomu, aby aplikace mohly komunikovat mezi sebou a vyměňovat si data. Toto API je navrženo pro správu položek, šarží, výdejek a příjemek v rámci systému pro řízení skladového zásobování. Umožňuje vám jednoduše spravovat produkty na skladě, jejich pohyby a zásoby pomocí přehledného a standardizovaného rozhraní.
Swagger
Pro práci s API poskytujeme interaktivní dokumentaci přes Swagger a ReDoc:
- Swagger (produkce):
https://váš-server.cz/swagger
umožňuje přehledně procházet všechny endpointy a přímo je testovat.
- Swagger JSON:
https://váš-server.cz/swagger.json
poskytuje OpenAPI specifikaci v JSON formátu.
- ReDoc:
https://váš-server.cz/redoc
alternativní náhled dokumentace s důrazem na přehlednost.
Varování
Na produkční adrese pracujete s ostrými daty. Pokud si chcete API pouze vyzkoušet nebo testovat integrace, použijte demo prostředí: https://demo.stockisimo.cz/swagger.
Základní popis API
REST API je typ rozhraní, které pracuje s daty prostřednictvím standardních HTTP metod jako GET, POST, PUT a DELETE. Tyto metody umožňují číst data, vytvářet nové záznamy, aktualizovat existující data nebo je mazat.
Podporované metody:
GET: Používá se k načtení dat, například k získání seznamu položek nebo detailu konkrétního produktu.
POST: Používá se k odesílání dat na server a vytváření nových záznamů, jako například nového produktu nebo objednávky.
Autentizace
Pro přístup k API je nutná autentizace, která slouží k ověření identity uživatele, aby se zajistilo, že k API přistupuje oprávněná osoba.
Autentizace probíhá pomocí hlaviček HTTP:
X-ApiToken: Unikátní token pro přístup k API.
X-ApiSecret: Tajný klíč, který společně s tokenem slouží k zabezpečení přístupu.
Tyto hodnoty můžete zjistit v detailu klienta.
Hodnoty je možné přegenerovat pomocí endpointu secrets_keys. Tutéž akci je možné provést i v aplikaci v seznamu klientů. Po označení požadovaných klientů naleznete v sekci akcí tlačítko Generate API secrets.
Poznámka
Autentizace je vyžadována pro každý požadavek a není nutné udržovat spojení nebo dočasný token.
Příklad autentizace:
{
"client_id": 3,
"api_token": "fb70788d-70c2-49f7-99c3-143eba659985",
"api_secret": "7e44c09b-af24-4ed8-b843-7037b8424321"
}
JSON body
Při posílání POST nebo PUT dotazů je třeba poslat společně s dotazem i data ve formě JSON, a to v těle dotazu. V aplikaci Postman se to dělá v záložce Body. Z možností zvolte „raw“ a následně JSON (application/json).
Poznámka
Pro testování doporučuji používat program Postman, který je dostupný na všech běžných operačních systémech.
Stránkování (Pagination)
Při práci s větším datasetem (například při načítání seznamu všech položek ve skladu) se používá stránkování, které umožňuje načítat data postupně stránku po stránce. Výchozí počet záznamů na stránku je 50, toto množství lze jednorázově upravit.
Parametry pro stránkování:
page: Určuje číslo stránky, kterou chcete načíst.
page_size: Určuje počet záznamů na jedné stránce.
Poznámka
API automaticky vrací odkaz na další a předchozí stránku, pokud existují, spolu s celkovým počtem záznamů.
Příklad odpovědi:
{
"count": 182,
"displayed_count": 50,
"next": "https://www.[API_ADDRESS]/api/v3/sales_order/?page=2",
"previous": null,
"results": [
{
"id": 40518,
"number": "PROC20-00012",
"status": "Packaging",
"date": "2020-03-23 13:10:51",
"updated": "2021-08-25 11:51:57",
"shipping_type": "Schenker",
"cash_on_delivery": 0
}
]
}
Produkty (Items)
Produkty jsou základními jednotkami, které API spravuje. Může jít o jakýkoliv druh zboží, který je potřeba spravovat ve skladu.
Získání seznamu položek
URL: /item/
Metoda: GET
Popis: Získání seznamu všech položek ve skladu.
Příklad odpovědi:
{
"count": 19906,
"displayed_count": 50,
"next": "http://www.[API_URL]/api/v3/item/?page=2",
"previous": null,
"results": [
{
"id": 10798,
"ean_codes": ["3145891012705", ],
"ean": "3145891012705",
"code": "07101270",
"title": "EAU DE COLOGNE VAPO 75ML",
"brand": "CHANEL",
"amount": 15,
"created": "2019-06-28T17:09:29.424465",
"updated": "2020-02-20T14:24:38.093064"
}
]
}
Získání detailu položky
URL: /item/{identifier}/
Metoda: GET
Popis: Získání detailu položky podle identifikátoru (identifier), který může být buď ID nebo kód položky.
Příklad odpovědi:
{
"id": 10798,
"code": "07101270",
"ean_codes": ["3145891012705", ],
"ean": "3145891012705",
"title": "EAU DE COLOGNE VAPO 75ML",
"brand": "CHANEL",
"amount": 15,
"weight": 1.0,
"created": "2019-06-28T17:09:29.424465",
"updated": "2020-02-20T14:24:38.093064",
"positions": [
{
"code": "112002",
"quantity": 15,
"available": 5,
"reserved": 10,
"available_groups": [
{
"created": "2019-06-30T12:23:35.165",
"amount": 5,
"batch": "3101",
"hu": "XL06414",
"shipment_number": "",
"status": "ok",
"serial_numbers": ""
}
],
"reserved_groups": [
{
"created": "2024-08-23T15:09:32.913",
"amount": 10,
"batch": "3101",
"hu": "XL06414",
"shipment_number": "",
"status": "ok",
"serial_numbers": ""
}
],
"remaining_groups": []
}
]
}
Získání skladových zásob produktů
URL: /item/stock/
Metoda: GET
Popis: Získání skladových zásob pro položky.
Příklad odpovědi:
{
"count": 19907,
"displayed_count": 50,
"next": "http://www.localhost:8080/api/v3/item/stock?page=2",
"previous": null,
"results": [
{
"07101270": {
"amount": 205,
"available_amount": 50,
"reserved_amount": 155
}
},
{
"07101565": {
"amount": 17,
"available_amount": 17,
"reserved_amount": 0
}
},
]
}
Vytvoření položky
URL: /item/
Metoda: POST
Popis: Vytvoření nové položky.
Povinné atributy: code, title
Volitelné atributy: ean, brand, weight, usability, min_usability, box_amount, pallete_amount, sn, batch_required, stickering_code, insurance_price, extern_id
Příklad těla požadavku:
{
"ean": "test_ean",
"code": "test_code",
"title": "Test item"
}
Příklad odpovědi:
{
"result": "Success",
"msg": "The product has been successfully created",
"item": {
"title": "Test item",
"code": "test_code",
"ean": "test_ean",
"ean_codes": [
"test_ean"
]
}
}
Přidání eanu do položky
URL: /item/add-ean/
Metoda: POST
Popis: Přidání eanu do položky.
Povinné atributy: code, ean
Příklad těla požadavku:
{
"ean": "test_ean2",
"code": "test_code"
}
Příklad odpovědi:
{
"result": "Success",
"msg": "EAN code has been successfully added",
"item": {
"title": "Test item",
"code": "test_code",
"ean": "test_ean2",
"ean_codes": [
"test_ean",
"test_ean2"
]
}
}
Šarže (Batches)
Každý výrobek má šarži, která definuje jeho datum výroby, spotřeby atd.
Získání šarží
URL: /batch/{identifier}/
Metoda: GET
Popis: Získání seznamu šarží pro produkt podle identifikátoru produktu, tím může být ID nebo kód položky.
Příklad odpovědi:
{
"count": 9,
"displayed_count": 9,
"next": null,
"previous": null,
"results": [
{
"id": 41952,
"date": "2019-06-30",
"batch": "3101",
"made": "2018-07-01",
"amount": null,
"usability": 65,
"created": "2019-06-30T12:23:35.158138",
"updated": "2020-12-03T05:00:28.958264",
"out": false,
"expiration": "2025-06-29",
"expired": true
},
{
"id": 450898,
"date": "2024-08-27",
"batch": "test123",
"made": null,
"amount": null,
"usability": 0,
"created": "2024-08-27T10:55:57.154593",
"updated": "2024-08-27T10:55:57.154655",
"out": false,
"expiration": "2024-08-31",
"expired": true
}
]
}
Výdejka (Sales Order)
Výdejka neboli výdej slouží k evidenci a správě výdeje zboží ze skladu.
Získání seznamu výdejek
URL: /sales_order/
Metoda: GET
Popis: Získání seznamu všech výdejek.
Příklad odpovědi:
{
"count": 182,
"displayed_count": 50,
"next": "http://www.[API_URL]/api/v3/sales_order/?page=2",
"previous": null,
"results": [
{
"id": 40518,
"number": "PROC20-00012",
"status": "Packaging",
"date": "2020-03-23 13:10:51",
"updated": "2021-08-25 11:51:57",
"shipping_type": "Schenker",
"cash_on_delivery": 0
}
]
}
Získání detailu výdejky
URL: /sales_order/{number}/
Metoda: GET
Popis: Získání detailu výdejky podle čísla objednávky.
Příklad odpovědi:
{
"id": 40518,
"number": "PROC20-00012",
"extern_id": null,
"order_number": "",
"date": "2020-03-23 13:10:51",
"updated": "2021-08-25 11:51:57",
"scheduled": "2021-08-25 11:51:57",
"shipping_date": null,
"confirm_date": null,
"status": "Packaging",
"operator": "Jiri Novák",
"employee": "Jiri Novák",
"note": "",
"stock": "Sklad s.r.o.",
"items": [
{
"title": "BLEU DE CHANEL PARFUM 50 ML",
"code": "07107170",
"ean_codes": [
"839174001496"
],
"ean": "839174001496",
"brand": "CHANEL",
"amount": 2,
"batch": "5102",
"batch_expiration": "2027-02-28",
"hu_ean": null,
"specification": ""
}
],
"sell_carts": [],
"delivery": {
"shipping_type": "Schenker",
"cash_on_delivery": 0,
"delivery_date": null,
"delivery_name": "Test d.o.o.",
"delivery_street": "Koranska 16",
"delivery_city": "Zagreb",
"delivery_psc": "10 000",
"delivery_country": "HR",
"delivery_phone": null,
"delivery_email": null,
"delivery_note": null
},
"shipping_extern_id": "",
"invoice": {
"invoice_name": "Test d.o.o.",
"invoice_street": "Koranska 16",
"invoice_city": "Zagreb",
"invoice_psc": "10 000",
"invoice_country": "HR",
"invoice_phone": null,
"invoice_email": null,
"invoice_ico": null,
"invoice_vat": null,
"invoice_gln": "",
"invoice_delivery_places_gln": ""
}
}
Vytvoření výdejky
URL: /sales_order/
Metoda: POST
Popis: Vytvoření nové výdejky.
Povinné atributy: number, items, delivery, invoice, delivery_name, delivery_street, delivery_city, delivery_psc, delivery_country
Volitelné atributy: extern_id, note, shipping_type, cash_on_delivery, delivery_date, delivery_phone, delivery_email, delivery_note, invoice_name, invoice_street, invoice_city, invoice_psc, invoice_country, invoice_phone, invoice_email, invoice_ico, invoice_vat, invoice_gln, invoice_delivery_places_gln
Povinné atributy položky: code, amount
Příklad těla požadavku:
{
"number": "test-11111",
"items": [{
"code": "07101270",
"amount": 20
}],
"delivery": {
"shipping_type": "PPL",
"cash_on_delivery": 0,
"delivery_date": "2020-12-02T00:00:00",
"delivery_name": "Testovaci",
"delivery_street": "Test 21/831",
"delivery_city": "PRAHA 1",
"delivery_psc": "110 00",
"delivery_country": "CZ",
"delivery_phone": "",
"delivery_email": "",
"delivery_note": ""
},
"shipping_extern_id": "18410",
"invoice": {
"invoice_name": "Test s.r.o.",
"invoice_street": "Testovací 750/34",
"invoice_city": "PRAHA 1 STARÉ MĚSTO",
"invoice_psc": "110 00",
"invoice_country": "CZ",
"invoice_phone": null,
"invoice_email": null,
"invoice_ico": null,
"invoice_vat": null,
"invoice_gln": "",
"invoice_delivery_places_gln": ""
}
}
Příklad odpovědi:
{
"result": "Success",
"msg": "The operation has been successfully created.",
"number": "test-11111"
}
Typy dopravy (Shipping Type)
Získání seznamu typů dopravy
URL: /shipping_type/
Metoda: GET
Popis: Získání seznamu všech typů dopravy.
Příklad odpovědi:
{
"count": 1,
"displayed_count": 1,
"next": null,
"previous": null,
"results": [
{
"id": 1,
"name": "Zásilkovna",
"text": ""
}
]
}
Příjemka (Purchase Order)
Označuje příjem zboží.
Získání seznamu příjemek
URL: /purchase_order/
Metoda: GET
Popis: Získání seznamu všech příjemek.
Příklad odpovědi:
{
"count": 10,
"displayed_count": 10,
"next": null,
"previous": null,
"results": [
{
"id": 53314,
"number": "POC20-00418",
"status": "Done",
"date": "2020-11-30 16:15:04",
"updated": "2020-12-01 15:10:03"
}
]
}
Získání detailu příjemky
URL: /purchase_order/{number}/
Metoda: GET
Popis: Získání detailu příjemky podle identifikátoru, tím může být ID nebo číslo objednávky.
Příklad odpovědi:
{
"id": 53314,
"number": "POC20-00418",
"extern_id": null,
"order_number": "",
"date": "2020-11-30 16:15:04",
"updated": "2020-12-01 15:10:03",
"scheduled": "2020-12-01 14:49:46",
"confirm_date": null,
"status": "Done",
"shipping_type": null,
"operator": null,
"employee": "Jan Novák",
"note": null,
"stock": null,
"items": [
{
"title": "MAGNETIC LUMINOUS EYE ANGEL",
"code": "88F4005005",
"ean_codes": [
"839174005005"
],
"ean": "839174005005",
"brand": "NUDESTIX",
"amount": 6,
"batch_expiration": "2022-12-31",
"specification": ""
}
],
"delivery": {
"shipping_type": null,
"cash_on_delivery": 0,
"delivery_date": null,
"delivery_name": "Orbico Beauty d.o.o.",
"delivery_street": "Koranska 16",
"delivery_city": "Zagreb",
"delivery_psc": "10 000",
"delivery_country": "HR",
"delivery_phone": null,
"delivery_email": null,
"delivery_note": null
}
}
Vytvoření příjemky
URL: /purchase_order/
Metoda: POST
Popis: Vytvoření nové příjemky.
Povinné atributy: number, items, delivery
Volitelné atributy: extern_id, note, shipping_type, cash_on_delivery, delivery_date, delivery_name, delivery_street, delivery_city, delivery_psc, delivery_country, delivery_phone, delivery_email, delivery_note
Povinné atributy položky: code, amount
Volitelné atributy položky: batch, expiration
Příklad těla požadavku:
{
"number": "purchase_order",
"items": [{
"code": "07101270",
"amount": 20,
"batch": "test_batch",
"expiration": "2026-10-02"
}],
"delivery": {
"shipping_type": "PPL",
"delivery_date": "2020-12-02T00:00:00",
"delivery_name": "Testovaci",
"delivery_street": "Test 21/831",
"delivery_city": "PRAHA 1",
"delivery_psc": "110 00",
"delivery_country": "CZ",
"delivery_phone": "",
"delivery_email": "",
"delivery_note": ""
}
}
Příklad odpovědi:
{
"result": "Success",
"msg": "The operation has been successfully created.",
"number": "purchase_order"
}
Úprava příjemky
URL: /purchase_order/{number}/
Metoda: PUT
Popis: Úprava konkrétní příjemky (při podrobnější úpravě je tělo požadavku stejné jako u vytváření, nelze upravocat produkty)
Příklad těla požadavku:
{
"invoice": {
"invoice_name": "Test s.r.o.",
"invoice_street": "Testovací 750/34",
"invoice_city": "PRAHA 1 STARÉ MĚSTO",
"invoice_psc": "110 00",
"invoice_country": "CZ"
}
}
Příklad odpovědi:
{
"result": "Success",
"msg": "The operation has been successfully updated.",
"number": "purchase_order"
}
Operace podle sériového čísla produktů
Dalším endpointem v rámci operací je získání operací podle sériového čísla produktů.
URL: /operation/
Metoda: GET
Popis: Získání operace podle sériového čísla produktů.
Parametry: sn (např. /api/v3/operation?sn=11, 22, 33)
{
"count": 1,
"displayed_count": 1,
"next": null,
"previous": null,
"results": [
{
"id": 53732,
"number": "test-11111",
"status": "New",
"action": "Sales order",
"date": "2024-08-27T11:03:30.562386",
"updated": "2024-08-27T11:03:30.562439",
"shipping_type": "PPL",
"cash_on_delivery": 0
}
]
}
Atributy
V následující tabulce jsou uvedeny všechny atributy, které se v API používají.
Atribut |
Popis |
|---|---|
id |
Unikátní identifikátor (generován automaticky). |
number |
Číslo objednávky. |
extern_id |
Externí identifikátor pro integraci s jinými systémy. |
order_number |
Číslo původní objednávky, pokud existuje. |
date |
Datum vytvoření operace. Formát je obvykle YYYY-MM-DD HH:MM:SS. |
updated |
Datum a čas poslední aktualizace operace. Formát je obvykle YYYY-MM-DD HH:MM:SS. |
scheduled |
Datum a čas naplánování operace. Formát je YYYY-MM-DD HH:MM:SS. |
shipping_date |
Datum a čas plánované expedice. Formát je YYYY-MM-DD HH:MM:SS. |
confirm_date |
Datum a čas potvrzení objednávky. Formát je YYYY-MM-DD HH:MM:SS. |
status |
Stav operace (např. „pending“, „confirmed“). |
operator |
Jméno operátora, který operaci zpracovává. |
employee |
Jméno zaměstnance, který je za operaci zodpovědný. |
note |
Poznámka k operaci, např. speciální instrukce. |
stock |
Název skladu, kde je operace zpracovávána. |
items |
Seznam položek zahrnutých v objednávce. |
code |
Kód, vyplnění je povinné při vytváření. Musí být unikátní. |
ean |
EAN kód (string v případě vytváření, pole v případě výsledku). |
ean_codes |
List EAN kódů. |
amount |
Počet kusů položek v operaci. |
title |
Název. |
brand |
Značka produktu. |
weight |
Váha produktu. |
min_usability |
Doba použitelnosti v %. |
rule |
Typ vyskladnění [FIFO, FEFO, DEFAULT, LIFO]. |
box_amount |
Počet ks v kartonu. |
pallete_amount |
Počet ks na paletě. |
sn |
Vyžaduje scanovat seriové číslo. [True/False] |
batch_required |
Vyžaduje sbírat informace o šaržích. [True/False] |
stickering_code |
Štítkuje se - číslo štítku. |
insurance_price |
Cena pojištění. |
gtin |
Číslo položky Global Trade. |
batch |
Vlastní název šarže. |
expiration / batch_expiration |
Expirace danné šarže Formát je %Y-%m-%d. |
sell_carts |
Seznam handling units v operaci. |
positions |
Pozice na kterých se položka nachází. |
quantity |
Celkové množství vázané k pozici. |
available |
Dostupné množství na danné pozici. |
reserved |
Množství položek na pozici, které je již rezervované v jiné operaci nebo ještě nebylo naskladněno. |
available_groups |
Dostupné skupiny zboží. |
hu |
Manipulační jednotky, ve kterých se skupina zboží nachází. |
shipment_number |
Číslo balíku pro doručení. |
serial_numbers |
Sériová čísla položek ve skupině. |
reserved_groups |
Rezervované skupiny na pozici. |
remaining_groups |
Ostatní skupiny na pozici. Například skupiny které nejsou v pořádku (missing). |
made |
Datum výroby dané šarže. |
out |
Udává, zda je zboží nebo operace aktivní nebo archivovaná. |
expired |
Udává, zda je šarže již po expiraci. |
specification |
Specifikace dané položky. |
delivery |
Informace o dodání zboží. |
shipping_type |
Název typu dopravy (např. PPL, DPD). - vizte List Shipping Types. Lze dostat z metody /shiping_type/ |
shipping_extern_id |
Parcel shop ID |
cash_on_delivery |
Hodnota dobírky. |
delivery_date |
Datum dodání zboží. |
delivery_name |
Datum dodání zboží. |
delivery_street |
Jméno příjemce. |
delivery_city |
Ulice dodání. |
delivery_psc |
Město dodání. |
delivery_country |
PSČ dodání. |
delivery_phone |
Země dodání. |
delivery_email |
Telefon příjemce. |
delivery_note |
Email příjemce. |
invoice |
Informace o fakturaci. |
invoice_name |
Jméno na faktuře. |
invoice_street |
Ulice na faktuře. |
invoice_city |
Město na faktuře. |
invoice_psc |
PSČ na faktuře. |
invoice_country |
Země na faktuře. |
invoice_phone |
Telefon na faktuře. |
invoice_email |
Email na faktuře. |
invoice_ico |
IČO na faktuře. |
invoice_vat |
DIČ na faktuře. |
invoice_gln |
GLN kód na faktuře. |
invoice_delivery_places_gln |
Místo dodání GS1 Global Location Number |
Časové formáty
%Y-%m-%dT%H:%M:%SZ
%Y-%m-%dT%H:%M:%S
%Y-%m-%dT%H:%M:%S.%fZ
%Y-%m-%dT%H:%M
%Y-%m-%d %H:%M:%S
%Y-%m-%d %H:%M
%Y-%m-%d
%Y.%m.%d
%Y.%m.%d %H:%M:%S
%Y.%m.%d %H:%M
%d.%m.%Y
%d-%m-%Y
Statusy operací
wt: Waiting for delivery
new: New
pen: Pending
proc: In process
res: Rescan
box: Packaging
ok: Done
Status doručení
rpd: Received packet data
arr: Arrived
pfd: Prepared for departure
dep: Departed
rfp: Ready for pickup
del: Delivered
pb: Posted back
ret: Returned
can: Cancelled
rpa: Reverse packet arrived
rej: Rejected
att: Delivery attempt failed
cus: Customs declaration process
Chybové zprávy
400 Bad Request: Špatný požadavek, například chybí povinné parametry.
404 Not Found: Požadovaný zdroj nebyl nalezen.
409 Conflict: Konflikt při zpracování požadavku (např. duplicita).
500 Internal Server Error: Neočekávaná chyba na straně serveru.
{
"result": "Error",
"msg": "Detailní popis chyby"
}