Jak do Pohody naimportovat objednávku z e-shopu

Ruční přepisování objednávek z e-shopu do Pohody je nejčastější důvod, proč nás lidé kontaktují. Jedna objednávka zabere pár minut, sto objednávek týdně už je práce na půl úvazku — a každý překlep v kódu zboží znamená špatně vydaný sklad.

S apios pošle e-shop objednávku do Pohody ve chvíli, kdy ji zákazník dokončí. V Pohodě vznikne běžná přijatá objednávka, se kterou dál pracujete jako obvykle: vyřídíte ji výdejkou, vystavíte z ní fakturu a zásoby se odepíšou správně.

Jak objednávka vypadá

Objednávku vytvoříte voláním PUT /api/v1/order/received. Minimum je adresa zákazníka a položky:

curl -X PUT https://api.apios.cz/api/v1/order/received \
  -H "X-AUTH-TOKEN: VAS_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: eshop-objednavka-2026-1042" \
  -d '{
    "order_id": "2026-1042",
    "customer_company": "ABC s.r.o.",
    "customer_name": "Jan Novák",
    "customer_street": "Václavské nám. 109",
    "customer_city": "Praha",
    "customer_zip": "11000",
    "customer_company_id": "12345678",
    "customer_vat": "CZ12345678",
    "payment": "příkazem",
    "order_items": [
      { "ids": "STUL-01", "qty": 2 },
      { "ean": "8594012345678", "qty": 1 },
      { "name": "Doprava PPL", "qty": 1, "price": 99, "vat_rate": "high" }
    ]
  }'

Totéž volání najdete v dokumentaci se všemi parametry a můžete si ho tam rovnou vyzkoušet:

Co jednotlivá pole dělají:

• order_id je číslo objednávky z e-shopu. V Pohodě se uloží do pole Číslo objednávky, takže objednávku dohledáte podle čísla, které zná i zákazník.
• customer_* je fakturační adresa. Pokud se dodací adresa liší, přidejte pole shipping_company, shipping_name, shipping_street, shipping_city a shipping_zip.
• payment je forma úhrady. Musí odpovídat zkratce formy úhrady, kterou máte v Pohodě. Seznam zjistíte voláním GET /api/v1/payment-methods.
• order_items jsou položky. Rozlišují se dva druhy:
  • Skladová položka má alespoň jedno z polí id, ids (kód zásoby), ean nebo plu. Název, cenu a sazbu DPH doplní Pohoda sama ze skladu — e-shop posílá jen kód a množství.
  • Textová položka (doprava, balné, dárkové balení) nemá žádný z těchto identifikátorů a musí mít name, price a vat_rate (none, low nebo high). Cena textové položky je bez DPH.

Co se vrátí

{
  "success": true,
  "message": "Objednávka byla úspěšně vytvořena",
  "data": {
    "id": 23,
    "number": "252100012",
    "action_type": "add"
  }
}

Stálý zákazník z adresáře

Má-li zákazník v Pohodě záznam v adresáři, místo adresy pošlete jen jeho ID:

{
  "order_id": "2026-1043",
  "customer_id": 25,
  "order_items": [{ "ids": "STUL-01", "qty": 1 }]
}

Objednávka se pak správně naváže na adresář, což se vám hodí v přehledech podle odběratelů. Jak zákazníka najít nebo založit, popisuje návod Jak hledat a zakládat zákazníky v adresáři.

Jak sledovat stav objednávky

Zákazník se dřív nebo později zeptá, kde je jeho zásilka. Stav vyřízení zjistíte z ID, které jste si uložili:

curl https://api.apios.cz/api/v1/order/23/status \
  -H "X-AUTH-TOKEN: VAS_API_TOKEN"

{
  "id": 23,
  "number": "252100012",
  "external_number": "2026-1042",
  "status": "partially_delivered",
  "ordered_quantity": 3,
  "delivered_quantity": 2
}

Totéž volání najdete v dokumentaci se všemi parametry a můžete si ho tam rovnou vyzkoušet:

Stav může být received (přijato), partially_delivered (vydána část), delivered (vše vydáno), invoiced (vystavena faktura) nebo completed (vyřízeno). E-shop si ho může jednou za čas načíst a ukázat zákazníkovi v jeho účtu.

Na co si dát pozor

• Kód zásoby musí v Pohodě existovat. Když ids nebo ean Pohoda nenajde, položku se skladem nespáruje — v odpovědi pak uvidíte chybu nebo varování, takže ji vždy kontrolujte. Kódy produktů v e-shopu proto držte stejné jako v Pohodě — synchronizaci popisuje návod Jak držet stav skladu v e-shopu podle Pohody.
• Posílejte hlavičku Idempotency-Key. Když e-shop po výpadku sítě požadavek zopakuje, objednávka nevznikne dvakrát. Víc v návodu Jak zabránit dvojímu zápisu dokladu.
• Číselná řada. Bez parametru number_series se použije výchozí řada přijatých objednávek. Chcete-li mít objednávky z e-shopu ve vlastní řadě, zadejte její kód, např. "number_series": "ESHOP".

Co dál

Až bude objednávka vyřízená, můžete z ní jedním voláním vystavit fakturu.