---
title: "Založit objednávku (závazná, čeká na platbu)"
method: POST
path: "/api/order/agent"
tags: ["objednávka"]
---

# Založit objednávku (závazná, čeká na platbu)

`POST /api/order/agent`

## Request

- Base URL: `https://konfigurator.suorigo.cz`
- URL: `https://konfigurator.suorigo.cz/api/order/agent`
- Auth: none declared

Založí ostrou objednávku (stejná pravidla jako pokladna). `paymentMethod: "bank_transfer"` (výchozí, zpětně kompatibilní) vrátí částku, IBAN, variabilní symbol a QR kód SPAYD. `paymentMethod: "card"` vrátí `paymentUrl` — odkaz na zabezpečenou stránku Stripe Checkout PRO TUTO OBJEDNÁVKU, kde kartu (nebo Apple/Google Pay) zadá sám zákazník; agent kartu nikdy nezadává ani nevidí. Po zaplacení jede stejný webhook, faktura a výroba jako u objednávky z webu.
Vždy vrátí `statusUrl` a `statusToken` (autorizace pro GET /api/order/agent?statusToken, POST /payment-link a POST /cancel) a zákazníkovi odejde e-mail se stejnými údaji. Volej až po výslovném souhlasu zákazníka s položkami, dopravou a cenou z POST /api/order/agent/quote.

Ceny se počítají na serveru; při nesmyslné konfiguraci dostaneš 400/409 s vysvětlením a strojovým `code`. Při opakování po timeoutu pošli stejný `idempotencyKey` — vrátí se tatáž objednávka (`replayed: true`, u karty tentýž platební odkaz), nevznikne duplicita.
Nezaplacená objednávka se ruší po 7 dnech (převod) nebo 48 hodinách (karta); zákazník dostane nejvýš jednu připomínku. Objednávky od 10 000 Kč nebo s IČO se automaticky neruší (řeší je člověk).

## Request body

- OrderInput
  - `items` OrderItem[], required
    - `product` string, required: id nebo slug produktu z GET /api/products
    - `colorId` string: id barvy z katalogu (colors[].id)
    - `colorName` string
    - `size` string, required: velikost z katalogu (sizes[]), např. "M"
    - `quantity` integer, required
    - `printMethod` string: z printMethods[] produktu; výchozí první
    - `layers` DesignLayer[]: vrstvy potisku — nejlépe výstup POST /api/design (už s nahranými URL)
      - `type` 'image' | 'text', required
      - `side` 'front' | 'back' | 'sideLeft' | 'sideRight', required
      - `x` number, required: % tiskové plochy zleva (0–100)
      - `y` number, required: % tiskové plochy shora (0–100)
      - `width` number, required: % šířky plochy
      - `height` number, required: % výšky plochy
      - `rotation` number
      - `src` string: image: data URL nebo veřejná https URL; po /api/design trvalá URL
      - `text` string
      - `fontFamily` string
      - `fontSize` number
      - `fill` string: barva textu, hex
  - `customer` Customer, required
    - `email` string, email, required: SKUTEČNÝ e-mail zákazníka. Doména musí přijímat poštu (MX/A záznam); example.com, .test apod. → 422. Zákazník sem dostane platební údaje.
    - `name` string, required: Jméno A příjmení (aspoň dvě slova) — POVINNÉ, jde na daňový doklad, stejně jako v pokladně. Chybí/jedno slovo → 400 full_name_required.
    - `phone` string: formát +420 …
    - `address` string: doručovací adresa jedním textem (ulice č., PSČ město) — u dopravy na adresu
    - `deliveryStreet` string: alternativa k address: ulice a číslo
    - `deliveryCity` string
    - `deliveryZip` string
    - `companyName` string
    - `ico` string: doplní/ověří se v ARES při založení objednávky
    - `dic` string
    - `billingStreet` string: nad 10 000 Kč bez IČO povinné (nebo deliveryStreet)
    - `billingCity` string
    - `billingZip` string
    - `billingCountry` string
  - `shippingId` 'zasilkovna' | 'balikovna' | 'ppl-vydejni' | 'dpd-vydejni' | 'ppl' | 'dpd', required: způsob dopravy (POVINNÉ). zasilkovna/balikovna/ppl-vydejni/dpd-vydejni = výdejní místo (vyžaduje pickupPointId), ppl/dpd = na adresu (vyžaduje customer.address nebo deliveryStreet/deliveryCity/deliveryZip)
  - `pickupPointId` string: kód výdejního místa z GET /api/shipping/pickup-points — povinné u dopravy na výdejní místo, jinak 400 pickup_point_required
  - `pickupPointName` string: název výdejního místa (volitelné, doplní se samo)
  - `deliverySpeedId` 'd7' | 'd14' | 'd30': termín výroby; d14 = výchozí bez příplatku; nedostupný termín → 400 delivery_speed_unavailable (dostupnost všech termínů vrací quote_order)
  - `promoCode` string
  - `paymentMethod` 'bank_transfer' | 'card': bank_transfer (výchozí, zpětně kompatibilní) = převod + QR; card = paymentUrl na Stripe Checkout, kartu zadává zákazník sám
  - `consent` true, required: zákazník souhlasí s obchodními podmínkami (https://suorigo.cz/obchodni-podminky)
  - `notes` string: vzkaz zákazníka dílně
  - `idempotencyKey` string: unikátní klíč objednávky; stejný klíč + stejný obsah = stejná objednávka

## Response `200`

Objednávka založena (nebo vrácena existující při stejném idempotencyKey)

- OrderResult
  - `ok` boolean
  - `status` integer
  - `error` string
  - `code` string: jen při chybě — viz components.schemas.Error
  - `orderNumber` string: 9 číslic, zároveň variabilní symbol
  - `currency` 'CZK'
  - `amount` number: celkem k úhradě s DPH včetně dopravy
  - `paymentMethod` 'bank_transfer' | 'card'
  - `variableSymbol` string: jen paymentMethod bank_transfer
  - `bank` object: jen paymentMethod bank_transfer
    - `account` string
    - `iban` string
  - `spaydString` string: jen paymentMethod bank_transfer — SPAYD řetězec (QR platba)
  - `spaydQr` string, nullable: jen paymentMethod bank_transfer — data:image/png;base64 QR kód
  - `paymentUrl` string: jen paymentMethod card — Stripe Checkout pro TUTO objednávku; kartu zadá zákazník sám
  - `paymentUrlExpiresAt` string, date-time, nullable: jen paymentMethod card — do kdy odkaz platí (~24 h); pak nový přes POST /api/order/agent/payment-link
  - `paymentState` 'pending' | 'paid' | 'processing' | 'requires_action': jen paymentMethod card — stav platby kartou
  - `status_` 'pending' | 'paid'
  - `statusUrl` string: veřejná stránka stavu objednávky — předej zákazníkovi
  - `statusToken` string: poslední část statusUrl — autorizace pro GET /api/order/agent?statusToken, /payment-link a /cancel
  - `paymentDueDate` string, date-time: do kdy musí dorazit platba (karta 48 h, převod 3 dny; nezaplacený převod se ruší po 5 dnech); pak se nezaplacená objednávka ruší
  - `expectedDeliveryDate` string, date-time: očekávaný termín doručení podle zvoleného termínu výroby
  - `emailSent` boolean: false = e-mail neodešel, předej údaje z odpovědi
  - `replayed` boolean: true = odpověď na dřívější objednávku se stejným idempotencyKey
  - `paymentInstructions` string: hotový text pro zákazníka

## Other responses

- `400`: Chybí e-mail / položky / consent, neplatná položka, chybějící nebo neznámá doprava (`shipping_required`, `unknown_shipping`), chybějící výdejní místo (`pickup_point_required`) nebo adresa (`address_required`), chybějící jméno a příjmení (`full_name_required`), chybějící fakturační adresa nad 10 000 Kč (`billing_address_required`), neplatný slevový kód (`coupon_invalid`), neznámý nebo nedostupný termín výroby (`unknown_delivery_speed`, `delivery_speed_unavailable`)
- `409`: Cena nesouhlasí se serverem (`price_changed`), idempotencyKey už použit s jiným obsahem (`idempotency_mismatch`) nebo právě probíhá (`idempotency_in_progress`), zvolené výdejní místo teď nepřijímá zásilky (`pickup_unavailable`)
- `422`: E-mail zákazníka není doručitelný (placeholder doména nebo doména bez poštovního serveru)
- `429`: Překročen limit (per IP, per e-mail, globální nebo denní). Text v `error` říká, co se stalo a co dělat; typicky počkej nebo odkaž zákazníka na https://konfigurator.suorigo.cz.
- `500`: Objednávku se nepodařilo vytvořit — zopakuj se stejným idempotencyKey (`try_again`)
- `502`: Objednávka kartou je založená, ale Stripe teď nevydal odkaz (`payment_link_unavailable`) — v odpovědi je orderNumber a statusToken; NEzakládej znovu, zavolej za chvíli /api/order/agent/payment-link
- `503`: Platba kartou teď není nakonfigurovaná (`card_unavailable`), nebo databáze momentálně nedostupná — zopakuj se stejným idempotencyKey (`try_again`)

---

[API](https://skmtc.dev/suorigo/apis/suorigo-api-pro-ai-agenty.md) · [All operations](https://skmtc.dev/suorigo/apis/suorigo-api-pro-ai-agenty/llms.txt) · [OpenAPI document](https://skmtc.dev/suorigo/apis/suorigo-api-pro-ai-agenty/revisions/08c6a3ef2349?raw)