POST /v1/orders — złóż zamówienie w Polsce
Idempotentne składanie z X-Idempotency-Key. Zwraca 201 z order_id lub 409 przy duplikacie. VAT 23% liczony po stronie serwera.
Schemat zapytania
POST /v1/orders z body JSON: { idempotency_key, buyer:{vat_id, billing_address}, ship_to:{name, address (z kodem pocztowym Warszawa), contact}, lines:[{sku, qty, unit_price_cents, currency:'PLN'}], promised_date, po_number, tax_mode:'incl_vat' }. NIP walidowany via VIES w czasie rzeczywistym. Max 250 linii na zamówienie.
Odpowiedź i przepływ statusów
201 Created → { order_id, status:'accepted', estimated_vat_amount_cents, currency, fulfilment_hub:'Warszawa', invoice_channel:'KSeF' }. Przejścia jako webhooki: accepted → confirmed → in_production → shipped → delivered. Każde przejście zapisywane w GET /v1/orders/{id}/events.
Błędy walidacji
400 z RFC 7807 problem+json: invalid_vat (mismatch VIES), invalid_sku (poza katalogiem), min_qty_violation (poniżej MOQ), invalid_vat_rate (mismatch z 23%), idempotency_conflict. Wszystkie błędy zawierają czytelny detail i stabilne URI typu.
FAQ
Czy endpoint jest idempotentny?
Tak — przekaż X-Idempotency-Key (zalecane UUID v4). Ten sam klucz + to samo body zwraca istniejące zamówienie; ten sam klucz + różne body zwraca 409.
Jakie waluty są akceptowane?
PLN i EUR dla Polski. Ceny jednostkowe w jednostkach minimalnych (grosze/centy). Mieszane waluty odrzucane z 400 invalid_currency_mix.
Co z częściowym wysyłkiem?
Wyłączony domyślnie. Ustaw partial_ok:true, by zezwolić na dzielone wysyłki. Każda wysyłka generuje osobną fakturę przez KSeF.
Jak liczone są podatki?
Po stronie serwera na podstawie statusu VAT kupującego, kraju dostawy i klasy podatkowej SKU. VAT 23% krajowo; reverse-charge dla ważnego B2B UE (VIES OK).
Czy mogę anulować zamówienie przez API?
DELETE /v1/orders/{id} dozwolone w stanach accepted i confirmed. Po in_production koordynujemy mailem — skontaktuj się z AE.