REST API: objednávky, vratky a zásilky

Pro účetnictví, ERP a expedici: kdo co objednal, v jakém je to stavu, kolik to stálo, co se vrací a kde je zásilka.

Cesty odpovídají na GET na doméně vašeho obchodu, například https://muj-eshop.cz/api/v1/…, a klíč se posílá v hlavičce Authorization: Bearer nebo x-api-key. Parametry, pole i chyby na téhle stránce se generují ze smlouvy, podle které API odpovídá, takže platí pro build, na kterém stránka běží. Každá cesta může navíc vrátit chyby společné všem cestám: invalid_api_key, missing_api_key, external_access_disabled, external_access_not_enabled, external_access_suspended, key_surface_mismatch, plan_required, shop_unavailable, shop_not_found, rate_limited a server_error. Co znamenají, popisuje článek Chybové odpovědi, klíč a oprávnění Autentizace a oprávnění a průchod výpisem Stránkování a filtry.

GET /api/v1/orders

Objednávky s částkami v haléřích, bez updated_since od nejnovější, s ním od nejstarší změny. Nákupní ceny, marže, interní poznámky ani identifikátory platby ven nejdou.

• Oprávnění: orders:read, u klíče „Objednávky (čtení)“.
• Odpověď: stránka výpisu, záznamy jsou v data a jak otevřít další stránku, říká seznam Obálka odpovědi.
• Synchronizace: s updated_since se výpis řadí podle pole updated_at od nejstarší změny, bez něj od nejnovějšího záznamu. Pole updated_at: Poslední změna záznamu objednávky. Podle něj stránkuje updated_since.

curl -s "https://muj-eshop.cz/api/v1/orders?limit=100" \
  -H "Authorization: Bearer $SHOPZI_API_KEY"

Parametry dotazu

• limit (celé číslo od 1 do 100, výchozí 25; nepovinný): Počet řádků na stránku, výchozí 25. Vyšší hodnota se ořízne na 100, nesmysl spadne na výchozí.
• cursor (text; nepovinný): Hodnota next_cursor z předchozí stránky, beze změny. Platí jen pro tentýž dotaz.
• updated_since (čas ISO 8601; nepovinný): ISO 8601 se zónou Z nebo s číselným posunem (+02:00). Vrátí záznamy změněné od té chvíle včetně, seřazené od nejstarší změny, a stránkuje stabilně: řádek změněný během průchodu se v něm neopakuje a přijde v příštím. Hodnota next_updated_since jde do adresy vložit bez kódování; + z nezakódované adresy se čte jako +.
• status (jedna z hodnot pending, received, confirmed, processing, shipped, delivered, completed, cancelled a rejected; nepovinný): Stav objednávky.
• payment_status (jedna z hodnot pending, authorized, paid, failed, refunded a partially_refunded; nepovinný): Stav platby.

Obálka odpovědi

• data (pole záznamů): Záznamy stránky, jejich pole popisuje seznam Pole záznamu.
• next_cursor (text nebo null): Kurzor další stránky, null = tohle je poslední stránka.
• next_updated_since (čas ISO 8601): Hodnota updated_since pro příští průchod: začátek tohoto průchodu mínus 5 minut. Na všech stránkách jednoho průchodu je stejná a do adresy jde vložit bez kódování.

Pole záznamu

• id (UUID)
• order_number (text): Číslo objednávky, jak ho vidí zákazník.
• status (jedna z hodnot pending, received, confirmed, processing, shipped, delivered, completed, cancelled a rejected)
• payment_status (jedna z hodnot pending, authorized, paid, failed, refunded a partially_refunded)
• payment_method (jedna z hodnot card_online, apple_pay, google_pay, bank_transfer, cod a invoice)
• fulfillment_status (jedna z hodnot pending, label_created, handed_over, in_transit, ready_for_pickup, delivered, returned, failed a cancelled, nebo null): Stav nejnovější zásilky, null bez zásilky. Vznik i posun zásilky posune updated_at objednávky; podrobnosti zásilky jsou v /shipments.
• currency_code (text se vzorem ^[A-Z]{3}$): Kód měny podle ISO 4217, dnes vždy CZK.
• subtotal_minor (celé číslo): Zboží celkem v haléřích, s DPH.
• discount_total_minor (celé číslo): Sleva celkem v haléřích.
• shipping_price_minor (celé číslo): Doprava v haléřích, s DPH.
• total_minor (celé číslo): K úhradě celkem v haléřích, s DPH.
• email (text)
• phone (text nebo null)
• is_quotation (true nebo false): true = velkoobchodní poptávka, ne závazná objednávka.
• placed_at (čas ISO 8601)
• created_at (čas ISO 8601)
• updated_at (čas ISO 8601): Poslední změna záznamu objednávky. Podle něj stránkuje updated_since.

Chyby této cesty

• 400 invalid_query: Parametr dotazu má neplatnou hodnotu: čas v updated_since bez časového posunu, nebo hodnota filtru, kterou výčet nezná. Zpráva jmenuje parametr, u filtru i povolené hodnoty.
• 400 invalid_cursor: Kurzor je poškozený, nebo patří k jinému dotazu (jiná cesta, jiný filtr nebo jiné updated_since). Začněte průchod znovu bez cursor.
• 403 insufficient_scope: Klíč je platný, ale nemá oprávnění, které cesta vyžaduje. Zpráva vypíše, co klíči chybí a co má.

GET /api/v1/orders/{id}

Jedna objednávka i s položkami, fakturační a doručovací adresou a variabilním symbolem.

• Oprávnění: orders:read, u klíče „Objednávky (čtení)“.
• Odpověď: jeden záznam v data.

curl -s "https://muj-eshop.cz/api/v1/orders/$ID" \
  -H "Authorization: Bearer $SHOPZI_API_KEY"

Parametry v cestě

• id (UUID; povinný): Identifikátor záznamu (UUID) z výpisu.

Obálka odpovědi

• data (záznam): Jeho pole popisuje seznam Pole záznamu.

Pole záznamu

• id (UUID)
• order_number (text): Číslo objednávky, jak ho vidí zákazník.
• status (jedna z hodnot pending, received, confirmed, processing, shipped, delivered, completed, cancelled a rejected)
• payment_status (jedna z hodnot pending, authorized, paid, failed, refunded a partially_refunded)
• payment_method (jedna z hodnot card_online, apple_pay, google_pay, bank_transfer, cod a invoice)
• fulfillment_status (jedna z hodnot pending, label_created, handed_over, in_transit, ready_for_pickup, delivered, returned, failed a cancelled, nebo null): Stav nejnovější zásilky, null bez zásilky. Vznik i posun zásilky posune updated_at objednávky; podrobnosti zásilky jsou v /shipments.
• currency_code (text se vzorem ^[A-Z]{3}$): Kód měny podle ISO 4217, dnes vždy CZK.
• subtotal_minor (celé číslo): Zboží celkem v haléřích, s DPH.
• discount_total_minor (celé číslo): Sleva celkem v haléřích.
• shipping_price_minor (celé číslo): Doprava v haléřích, s DPH.
• total_minor (celé číslo): K úhradě celkem v haléřích, s DPH.
• email (text)
• phone (text nebo null)
• is_quotation (true nebo false): true = velkoobchodní poptávka, ne závazná objednávka.
• placed_at (čas ISO 8601)
• created_at (čas ISO 8601)
• updated_at (čas ISO 8601): Poslední změna záznamu objednávky. Podle něj stránkuje updated_since.
• billing (objekt)
• billing.name (text)
• billing.company (text nebo null)
• billing.ico (text nebo null)
• billing.dic (text nebo null)
• billing.street (text)
• billing.city (text)
• billing.postal_code (text)
• billing.country (text)
• shipping (objekt)
• shipping.name (text nebo null)
• shipping.street (text nebo null)
• shipping.city (text nebo null)
• shipping.postal_code (text nebo null)
• shipping.country (text nebo null)
• shipping.pickup_point_label (text nebo null)
• shipping.carrier_code (jedna z hodnot packeta, personal, balikovna, cp, ppl, dpd, gls a printify, nebo null)
• variable_symbol (text nebo null)
• notes (text nebo null): Poznámka zákazníka k objednávce.
• lines (pole objektů)
• lines[].id (UUID)
• lines[].product_id (UUID nebo null)
• lines[].variant_id (UUID nebo null)
• lines[].sku (text nebo null)
• lines[].name (text): Název položky v okamžiku objednávky.
• lines[].quantity (celé číslo)
• lines[].unit_price_minor (celé číslo): Jednotková cena v haléřích, s DPH.
• lines[].line_discount_minor (celé číslo)
• lines[].line_total_minor (celé číslo)
• lines[].vat_rate (celé číslo od 0 do 100): Sazba DPH v celých procentech.

Chyby této cesty

• 403 insufficient_scope: Klíč je platný, ale nemá oprávnění, které cesta vyžaduje. Zpráva vypíše, co klíči chybí a co má.
• 404 not_found: Záznam s tímhle identifikátorem v obchodě není.

GET /api/v1/returns

Vratky a reklamace i s položkami, důvodem a stavem vrácení peněz v haléřích, s odkazem na objednávku a na vystavený dobropis.

• Oprávnění: orders:read, u klíče „Objednávky (čtení)“.
• Odpověď: stránka výpisu, záznamy jsou v data a jak otevřít další stránku, říká seznam Obálka odpovědi.
• Synchronizace: s updated_since se výpis řadí podle pole updated_at od nejstarší změny, bez něj od nejnovějšího záznamu.

curl -s "https://muj-eshop.cz/api/v1/returns?limit=100" \
  -H "Authorization: Bearer $SHOPZI_API_KEY"

Parametry dotazu

• limit (celé číslo od 1 do 100, výchozí 25; nepovinný): Počet řádků na stránku, výchozí 25. Vyšší hodnota se ořízne na 100, nesmysl spadne na výchozí.
• cursor (text; nepovinný): Hodnota next_cursor z předchozí stránky, beze změny. Platí jen pro tentýž dotaz.
• updated_since (čas ISO 8601; nepovinný): ISO 8601 se zónou Z nebo s číselným posunem (+02:00). Vrátí záznamy změněné od té chvíle včetně, seřazené od nejstarší změny, a stránkuje stabilně: řádek změněný během průchodu se v něm neopakuje a přijde v příštím. Hodnota next_updated_since jde do adresy vložit bez kódování; + z nezakódované adresy se čte jako +.
• status (jedna z hodnot requested, received, approved, partially_approved, rejected, refunded, closed a cancelled; nepovinný): Stav vratky.

Obálka odpovědi

• data (pole záznamů): Záznamy stránky, jejich pole popisuje seznam Pole záznamu.
• next_cursor (text nebo null): Kurzor další stránky, null = tohle je poslední stránka.
• next_updated_since (čas ISO 8601): Hodnota updated_since pro příští průchod: začátek tohoto průchodu mínus 5 minut. Na všech stránkách jednoho průchodu je stejná a do adresy jde vložit bez kódování.

Pole záznamu

• id (UUID)
• return_number (text)
• order_id (UUID)
• order_number (text)
• regime (jedna z hodnot withdrawal, reklamace a seller_cancel): withdrawal = odstoupení od smlouvy, reklamace = vada zboží, seller_cancel = zrušeno prodejcem (dodavatel zboží nemůže dodat, nejde o odstoupení zákazníka).
• status (jedna z hodnot requested, received, approved, partially_approved, rejected, refunded, closed a cancelled)
• reason (jedna z hodnot changed_mind, better_price, wrong_size, looks_different, arrived_late, no_longer_needed, defective, damaged_in_transit, wrong_item, missing_parts, not_as_described, quality_issue a other, nebo null)
• refund (objekt)
• refund.currency_code (text se vzorem ^[A-Z]{3}$): Kód měny podle ISO 4217, dnes vždy CZK.
• refund.requested_minor (celé číslo): Kolik zákazník požadoval.
• refund.approved_minor (celé číslo): Kolik obchod schválil, i s poštovným.
• refund.shipping_minor (celé číslo): Vrácené poštovné (§ 1832 OZ).
• refund.refunded_minor (celé číslo): Kolik se už opravdu vrátilo.
• credit_note_id (UUID nebo null): Vystavený dobropis k vratce, identifikátor pro /documents/{id}.
• credit_note_number (text nebo null)
• deadline_at (čas ISO 8601 nebo null): Lhůta vyřízení reklamace (zákonná, nebo dohodnutá delší).
• items (pole objektů)
• items[].id (UUID)
• items[].order_line_id (UUID)
• items[].variant_id (UUID nebo null)
• items[].sku (text nebo null)
• items[].name (text)
• items[].quantity_requested (celé číslo)
• items[].quantity_approved (celé číslo)
• items[].unit_price_gross_minor (celé číslo)
• items[].currency_code (text se vzorem ^[A-Z]{3}$): Kód měny podle ISO 4217, dnes vždy CZK.
• items[].vat_rate (celé číslo od 0 do 100)
• items[].reason (jedna z hodnot changed_mind, better_price, wrong_size, looks_different, arrived_late, no_longer_needed, defective, damaged_in_transit, wrong_item, missing_parts, not_as_described, quality_issue a other, nebo null)
• created_at (čas ISO 8601)
• updated_at (čas ISO 8601)

Chyby této cesty

• 400 invalid_query: Parametr dotazu má neplatnou hodnotu: čas v updated_since bez časového posunu, nebo hodnota filtru, kterou výčet nezná. Zpráva jmenuje parametr, u filtru i povolené hodnoty.
• 400 invalid_cursor: Kurzor je poškozený, nebo patří k jinému dotazu (jiná cesta, jiný filtr nebo jiné updated_since). Začněte průchod znovu bez cursor.
• 403 insufficient_scope: Klíč je platný, ale nemá oprávnění, které cesta vyžaduje. Zpráva vypíše, co klíči chybí a co má.

GET /api/v1/returns/{id}

Jedna vratka nebo reklamace, v témže tvaru jako ve výpisu.

• Oprávnění: orders:read, u klíče „Objednávky (čtení)“.
• Odpověď: jeden záznam v data.

curl -s "https://muj-eshop.cz/api/v1/returns/$ID" \
  -H "Authorization: Bearer $SHOPZI_API_KEY"

Parametry v cestě

• id (UUID; povinný): Identifikátor záznamu (UUID) z výpisu.

Obálka odpovědi

• data (záznam): Jeho pole popisuje seznam Pole záznamu.

Pole záznamu

• id (UUID)
• return_number (text)
• order_id (UUID)
• order_number (text)
• regime (jedna z hodnot withdrawal, reklamace a seller_cancel): withdrawal = odstoupení od smlouvy, reklamace = vada zboží, seller_cancel = zrušeno prodejcem (dodavatel zboží nemůže dodat, nejde o odstoupení zákazníka).
• status (jedna z hodnot requested, received, approved, partially_approved, rejected, refunded, closed a cancelled)
• reason (jedna z hodnot changed_mind, better_price, wrong_size, looks_different, arrived_late, no_longer_needed, defective, damaged_in_transit, wrong_item, missing_parts, not_as_described, quality_issue a other, nebo null)
• refund (objekt)
• refund.currency_code (text se vzorem ^[A-Z]{3}$): Kód měny podle ISO 4217, dnes vždy CZK.
• refund.requested_minor (celé číslo): Kolik zákazník požadoval.
• refund.approved_minor (celé číslo): Kolik obchod schválil, i s poštovným.
• refund.shipping_minor (celé číslo): Vrácené poštovné (§ 1832 OZ).
• refund.refunded_minor (celé číslo): Kolik se už opravdu vrátilo.
• credit_note_id (UUID nebo null): Vystavený dobropis k vratce, identifikátor pro /documents/{id}.
• credit_note_number (text nebo null)
• deadline_at (čas ISO 8601 nebo null): Lhůta vyřízení reklamace (zákonná, nebo dohodnutá delší).
• items (pole objektů)
• items[].id (UUID)
• items[].order_line_id (UUID)
• items[].variant_id (UUID nebo null)
• items[].sku (text nebo null)
• items[].name (text)
• items[].quantity_requested (celé číslo)
• items[].quantity_approved (celé číslo)
• items[].unit_price_gross_minor (celé číslo)
• items[].currency_code (text se vzorem ^[A-Z]{3}$): Kód měny podle ISO 4217, dnes vždy CZK.
• items[].vat_rate (celé číslo od 0 do 100)
• items[].reason (jedna z hodnot changed_mind, better_price, wrong_size, looks_different, arrived_late, no_longer_needed, defective, damaged_in_transit, wrong_item, missing_parts, not_as_described, quality_issue a other, nebo null)
• created_at (čas ISO 8601)
• updated_at (čas ISO 8601)

Chyby této cesty

• 403 insufficient_scope: Klíč je platný, ale nemá oprávnění, které cesta vyžaduje. Zpráva vypíše, co klíči chybí a co má.
• 404 not_found: Záznam s tímhle identifikátorem v obchodě není.

GET /api/v1/shipments

Zásilky objednávek: dopravce, způsob dopravy, číslo a odkaz pro sledování, stav a položky v zásilce. Štítek ani chybová hlášení dopravce ven nejdou.

• Oprávnění: orders:read, u klíče „Objednávky (čtení)“.
• Odpověď: stránka výpisu, záznamy jsou v data a jak otevřít další stránku, říká seznam Obálka odpovědi.
• Synchronizace: s updated_since se výpis řadí podle pole updated_at od nejstarší změny, bez něj od nejnovějšího záznamu.

curl -s "https://muj-eshop.cz/api/v1/shipments?limit=100" \
  -H "Authorization: Bearer $SHOPZI_API_KEY"

Parametry dotazu

• limit (celé číslo od 1 do 100, výchozí 25; nepovinný): Počet řádků na stránku, výchozí 25. Vyšší hodnota se ořízne na 100, nesmysl spadne na výchozí.
• cursor (text; nepovinný): Hodnota next_cursor z předchozí stránky, beze změny. Platí jen pro tentýž dotaz.
• updated_since (čas ISO 8601; nepovinný): ISO 8601 se zónou Z nebo s číselným posunem (+02:00). Vrátí záznamy změněné od té chvíle včetně, seřazené od nejstarší změny, a stránkuje stabilně: řádek změněný během průchodu se v něm neopakuje a přijde v příštím. Hodnota next_updated_since jde do adresy vložit bez kódování; + z nezakódované adresy se čte jako +.
• status (jedna z hodnot pending, label_created, handed_over, in_transit, ready_for_pickup, delivered, returned, failed a cancelled; nepovinný): Stav zásilky.

Obálka odpovědi

• data (pole záznamů): Záznamy stránky, jejich pole popisuje seznam Pole záznamu.
• next_cursor (text nebo null): Kurzor další stránky, null = tohle je poslední stránka.
• next_updated_since (čas ISO 8601): Hodnota updated_since pro příští průchod: začátek tohoto průchodu mínus 5 minut. Na všech stránkách jednoho průchodu je stejná a do adresy jde vložit bez kódování.

Pole záznamu

• id (UUID)
• order_id (UUID)
• order_number (text)
• carrier (jedna z hodnot packeta, personal, balikovna, cp, ppl, dpd, gls a printify)
• service (text nebo null): Způsob dopravy, jak ho zákazník vybral v pokladně.
• delivery_type (jedna z hodnot shipping, pickup_point a personal_pickup, nebo null)
• status (jedna z hodnot pending, label_created, handed_over, in_transit, ready_for_pickup, delivered, returned, failed a cancelled)
• tracking_number (text nebo null)
• tracking_url (text nebo null)
• pickup_point_id (text nebo null)
• parcel_count (celé číslo)
• weight_grams (celé číslo nebo null)
• currency_code (text se vzorem ^[A-Z]{3}$): Kód měny podle ISO 4217, dnes vždy CZK.
• cod_amount_minor (celé číslo nebo null): Dobírka v haléřích, null bez dobírky.
• handed_over_at (čas ISO 8601 nebo null)
• delivered_at (čas ISO 8601 nebo null)
• items (pole objektů): Položky přiřazené k zásilce. Prázdné pole = zásilka není rozepsaná po položkách.
• items[].order_line_id (UUID)
• items[].sku (text nebo null)
• items[].name (text)
• items[].quantity (celé číslo)
• created_at (čas ISO 8601)
• updated_at (čas ISO 8601)

Chyby této cesty

• 400 invalid_query: Parametr dotazu má neplatnou hodnotu: čas v updated_since bez časového posunu, nebo hodnota filtru, kterou výčet nezná. Zpráva jmenuje parametr, u filtru i povolené hodnoty.
• 400 invalid_cursor: Kurzor je poškozený, nebo patří k jinému dotazu (jiná cesta, jiný filtr nebo jiné updated_since). Začněte průchod znovu bez cursor.
• 403 insufficient_scope: Klíč je platný, ale nemá oprávnění, které cesta vyžaduje. Zpráva vypíše, co klíči chybí a co má.