Suorigo Konfigurátor

Vrátí katalog triček/mikin Suorigo (barvy, velikosti, ceny vč. množstevních slev) nebo jeden produkt podle id/slug.

{
  "type": "object",
  "properties": {
    "product": {
      "type": "string",
      "description": "id nebo slug konkrétního produktu (volitelné)"
    }
  },
  "required": []
}

Rychlý odhad ceny JEDNOHO produktu (vč. DPH) podle množství/velikostí a počtu potištěných stran. Přesnou cenu celé objednávky (doprava, kupón, termín) vrací quote_order.

{
  "type": "object",
  "properties": {
    "product": {
      "type": "string"
    },
    "quantity": {
      "type": "number"
    },
    "sizes": {
      "type": "object",
      "description": "mapování velikost→počet, např. {\"M\":10,\"L\":5}"
    },
    "printedSides": {
      "type": "number",
      "description": "počet potištěných stran 0–4"
    },
    "printSideHeightsCm": {
      "type": "array",
      "items": {
        "type": "number"
      },
      "description": "výška motivu v cm na každé potištěné straně"
    },
    "promoCode": {
      "type": "string"
    }
  },
  "required": [
    "product"
  ]
}

Zvaliduje a uloží design (logo/text na stranách trička): vrátí vrstvy s nahranými URL pro create_order, orientační příplatek za potisk a previewUrl — odkaz, kde zákazník uvidí návrh na tričku v konfigurátoru (a může ho tam i sám objednat).

{
  "type": "object",
  "properties": {
    "product": {
      "type": "string"
    },
    "colorId": {
      "type": "string"
    },
    "layers": {
      "type": "array",
      "items": {
        "type": "object"
      },
      "description": "vrstvy: {type:'image'|'text', side:'front'|'back'|'sideLeft'|'sideRight', x,y,width,height v % 0–100, rotation?, src? (https URL nebo data:URL obrázku), text?, fontFamily?, fontSize?, fill?}"
    },
    "previewFrontDataUrl": {
      "type": "string"
    },
    "previewBackDataUrl": {
      "type": "string"
    }
  },
  "required": [
    "product",
    "layers"
  ]
}

Přesná cena celé objednávky PŘED založením — stejný výpočet jako create_order (položky, doprava vč. dopravy zdarma od 1 500 Kč, kupón, termín výroby). Vrací totalVat, rozpis, dostupné termíny (deliverySpeeds), ceny dopravy a v `requirements` co ještě chybí k objednání. Nic neukládá.

{
  "type": "object",
  "properties": {
    "items": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "product": {
            "type": "string",
            "description": "id nebo slug produktu z list_products"
          },
          "colorId": {
            "type": "string"
          },
          "colorName": {
            "type": "string",
            "description": "název barvy (rozhoduje i o expresu: jen černá/bílá)"
          },
          "size": {
            "type": "string",
            "description": "velikost z katalogu, např. M"
          },
          "quantity": {
            "type": "integer",
            "minimum": 1
          },
          "printMethod": {
            "type": "string"
          },
          "layers": {
            "type": "array",
            "items": {
              "type": "object"
            },
            "description": "vrstvy z create_design (určují příplatek za potisk)"
          }
        },
        "required": [
          "product",
          "size",
          "quantity"
        ]
      },
      "description": "položky objednávky (každá velikost/barva zvlášť)"
    },
    "shippingId": {
      "type": "string",
      "enum": [
        "zasilkovna",
        "balikovna",
        "ppl-vydejni",
        "dpd-vydejni",
        "ppl",
        "dpd",
        "osobni"
      ],
      "description": "doprava: zasilkovna (výdejní místo / Z-BOX, 89 Kč), balikovna (69 Kč), ppl-vydejni (79 Kč), dpd-vydejni (89 Kč), ppl / dpd (na adresu, 129 Kč); od 1 500 Kč zdarma; osobni (Šitbořice) jen se slevovým kódem, který ho odemyká"
    },
    "pickupPointId": {
      "type": "string",
      "description": "id výdejního místa z find_pickup_points (povinné u dopravy na výdejní místo)"
    },
    "pickupPointName": {
      "type": "string",
      "description": "název výdejního místa (volitelné, doplní se samo)"
    },
    "deliverySpeedId": {
      "type": "string",
      "enum": [
        "rush3",
        "d7",
        "d14",
        "d30"
      ],
      "description": "termín: d14 = do 14 prac. dní (výchozí, bez příplatku), d7 = do 7 dní +30 % (jen trička Standard), rush3 = expres do 3 prac. dnů +100 % (jen černá/bílá trička Standart, objednávka 1 500–5 000 Kč, podání do 12:00), d30 = do měsíce −10 %; nedostupný termín = 400 s důvodem (quote_order ukáže dostupnost)"
    },
    "promoCode": {
      "type": "string",
      "description": "slevový kód; neplatný kód = chyba (nikdy tiše plná cena)"
    },
    "customer": {
      "type": "object",
      "description": "volitelné: email (kvůli limitu kupónu), name, ico, adresy — jen pro kontrolu requirements"
    }
  },
  "required": [
    "items"
  ]
}

Vyhledá výdejní místa dopravce podle města, PSČ, ulice nebo názvu (Zásilkovna vč. Z-BOXů, Balíkovna, PPL ParcelShop, DPD Pickup). Vrácené `id` patří do create_order.pickupPointId.

{
  "type": "object",
  "properties": {
    "shippingId": {
      "type": "string",
      "enum": [
        "zasilkovna",
        "balikovna",
        "ppl-vydejni",
        "dpd-vydejni"
      ]
    },
    "query": {
      "type": "string",
      "description": "město, PSČ, ulice nebo název (min. 2 znaky), např. „Brno Lidická“ nebo „60200“"
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 25,
      "description": "počet výsledků (výchozí 10)"
    }
  },
  "required": [
    "shippingId",
    "query"
  ]
}

Dohledá firmu podle IČO v ARES (název, DIČ, sídlo) — pro nákup na firmu. Vrací pole ve tvaru create_order.customer (companyName, ico, dic, billingStreet…).

{
  "type": "object",
  "properties": {
    "ico": {
      "type": "string",
      "description": "IČO (7–8 číslic)"
    }
  },
  "required": [
    "ico"
  ]
}

Založí ZÁVAZNOU objednávku (čeká na platbu). paymentMethod 'bank_transfer' (výchozí) vrátí číslo účtu, variabilní symbol a QR; 'card' vrátí paymentUrl — zabezpečenou stránku Stripe pro tuto objednávku, kde zákazník sám zadá kartu (agent kartu nikdy nezadává ani nevidí; po zaplacení jede faktura a výroba stejně jako u objednávky z webu). Vždy vrátí statusUrl a statusToken (pro get_order_status, get_payment_link, cancel_order) a zákazníkovi pošle e-mail. Volej až po výslovném souhlasu zákazníka s položkami a cenou z quote_order. Povinné: skutečný e-mail (doména musí přijímat poštu, jinak 422), jméno a příjmení, shippingId (+ pickupPointId u výdejního místa, jinak adresa), consent:true; nad 10 000 Kč bez IČO fakturační adresa. Kartou nejméně 15 Kč. Nezaplacená karta propadne po 48 h, převod po 7 dnech. Limity: 3 objednávky / IP / den, 2 nezaplacené a 3 objednávky za 24 h na e-mail (429). Při opakování po timeoutu pošli stejný idempotencyKey.

{
  "type": "object",
  "properties": {
    "items": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "product": {
            "type": "string",
            "description": "id nebo slug produktu z list_products"
          },
          "colorId": {
            "type": "string"
          },
          "colorName": {
            "type": "string",
            "description": "název barvy (rozhoduje i o expresu: jen černá/bílá)"
          },
          "size": {
            "type": "string",
            "description": "velikost z katalogu, např. M"
          },
          "quantity": {
            "type": "integer",
            "minimum": 1
          },
          "printMethod": {
            "type": "string"
          },
          "layers": {
            "type": "array",
            "items": {
              "type": "object"
            },
            "description": "vrstvy z create_design (určují příplatek za potisk)"
          }
        },
        "required": [
          "product",
          "size",
          "quantity"
        ]
      },
      "description": "položky objednávky (každá velikost/barva zvlášť)"
    },
    "shippingId": {
      "type": "string",
      "enum": [
        "zasilkovna",
        "balikovna",
        "ppl-vydejni",
        "dpd-vydejni",
        "ppl",
        "dpd",
        "osobni"
      ],
      "description": "doprava: zasilkovna (výdejní místo / Z-BOX, 89 Kč), balikovna (69 Kč), ppl-vydejni (79 Kč), dpd-vydejni (89 Kč), ppl / dpd (na adresu, 129 Kč); od 1 500 Kč zdarma; osobni (Šitbořice) jen se slevovým kódem, který ho odemyká"
    },
    "pickupPointId": {
      "type": "string",
      "description": "id výdejního místa z find_pickup_points (povinné u dopravy na výdejní místo)"
    },
    "pickupPointName": {
      "type": "string",
      "description": "název výdejního místa (volitelné, doplní se samo)"
    },
    "deliverySpeedId": {
      "type": "string",
      "enum": [
        "rush3",
        "d7",
        "d14",
        "d30"
      ],
      "description": "termín: d14 = do 14 prac. dní (výchozí, bez příplatku), d7 = do 7 dní +30 % (jen trička Standard), rush3 = expres do 3 prac. dnů +100 % (jen černá/bílá trička Standart, objednávka 1 500–5 000 Kč, podání do 12:00), d30 = do měsíce −10 %; nedostupný termín = 400 s důvodem (quote_order ukáže dostupnost)"
    },
    "promoCode": {
      "type": "string",
      "description": "slevový kód; neplatný kód = chyba (nikdy tiše plná cena)"
    },
    "customer": {
      "type": "object",
      "description": "zákazník: email (povinné, skutečná doména s poštou), name (povinné — jméno A příjmení, jde na daňový doklad), phone?, address? (doručovací adresa jedním řádkem u doručení na adresu) nebo deliveryStreet/deliveryCity/deliveryZip, firma: companyName?, ico? (doplní se z ARES), dic?, fakturační adresa billingStreet/billingCity/billingZip/billingCountry (nad 10 000 Kč bez IČO povinná)",
      "properties": {
        "email": {
          "type": "string"
        },
        "name": {
          "type": "string"
        },
        "phone": {
          "type": "string"
        },
        "address": {
          "type": "string"
        },
        "deliveryStreet": {
          "type": "string"
        },
        "deliveryCity": {
          "type": "string"
        },
        "deliveryZip": {
          "type": "string"
        },
        "companyName": {
          "type": "string"
        },
        "ico": {
          "type": "string"
        },
        "dic": {
          "type": "string"
        },
        "billingStreet": {
          "type": "string"
        },
        "billingCity": {
          "type": "string"
        },
        "billingZip": {
          "type": "string"
        },
        "billingCountry": {
          "type": "string"
        }
      },
      "required": [
        "email",
        "name"
      ]
    },
    "paymentMethod": {
      "type": "string",
      "enum": [
        "bank_transfer",
        "card"
      ],
      "description": "bank_transfer = převod + QR (výchozí); card = odkaz na platbu kartou (Stripe Checkout, Apple/Google Pay podle prohlížeče)"
    },
    "consent": {
      "type": "boolean",
      "description": "souhlas zákazníka s obchodními podmínkami (https://suorigo.cz/obchodni-podminky), musí být true"
    },
    "notes": {
      "type": "string",
      "maxLength": 1000,
      "description": "vzkaz zákazníka k objednávce (co má dílna vědět); uloží se k zakázce jako poznámka od zákazníka, delší text se ořízne"
    },
    "idempotencyKey": {
      "type": "string",
      "maxLength": 128,
      "description": "libovolný unikátní klíč této objednávky (např. UUID); opakované volání se stejným klíčem a obsahem vrátí stejnou objednávku (replayed:true, u karty tentýž platební odkaz), stejný klíč s jiným obsahem = 409"
    }
  },
  "required": [
    "items",
    "customer",
    "shippingId",
    "consent"
  ]
}

Vrátí odkaz na zaplacení existující objednávky kartou (paymentUrl na Stripe) — když zákazník odkaz ztratil nebo vypršel (platí ~24 h). Stejná cesta jako tlačítko „Dokončit platbu kartou“ na webu: otevřenou platbu znovu použije, zaplacenou jen potvrdí, rozpracované ověření v bance nechá doběhnout. Jen pro objednávky kartou (převod má platební údaje v create_order). Autorizace: statusToken → vrátí paymentUrl; orderNumber + email → odkaz NEvrací, pošle ho zákazníkovi na e-mail z objednávky (max 1× / 15 min, 3× / den).

{
  "type": "object",
  "properties": {
    "statusToken": {
      "type": "string",
      "description": "statusToken z create_order (poslední část statusUrl) — plný přístup"
    },
    "orderNumber": {
      "type": "string",
      "description": "číslo objednávky (9 číslic) — jen spolu s e-mailem"
    },
    "email": {
      "type": "string",
      "description": "e-mail zákazníka z objednávky — jen spolu s orderNumber"
    }
  },
  "required": []
}

Stav objednávky: platba (pending/paid/failed/refunded), výroba (new → shipped/delivered, cancelled), očekávaný termín. Se statusToken navíc statusUrl, faktura (PDF po zaplacení) a sledování zásilky. S orderNumber + email jen základní stav (čísla objednávek jsou předvídatelná). Neshoda = found:false.

{
  "type": "object",
  "properties": {
    "statusToken": {
      "type": "string",
      "description": "statusToken z create_order (poslední část statusUrl) — plný přístup"
    },
    "orderNumber": {
      "type": "string",
      "description": "číslo objednávky (9 číslic) — jen spolu s e-mailem"
    },
    "email": {
      "type": "string",
      "description": "e-mail zákazníka z objednávky — jen spolu s orderNumber"
    }
  },
  "required": []
}

Stornuje NEZAPLACENOU objednávku, která ještě není ve výrobě — stejně jako tlačítko na stránce stavu (zákazník dostane e-mail o stornu, otevřená platba kartou se zavře). Zaplacenou objednávku stornovat nejde (napiš na [email protected]). Jen se statusToken a jen na výslovný pokyn zákazníka.

{
  "type": "object",
  "properties": {
    "statusToken": {
      "type": "string",
      "description": "statusToken z create_order (poslední část statusUrl) — plný přístup"
    }
  },
  "required": [
    "statusToken"
  ]
}