Dokumentacja API

Manifest ze spisem endpointów. Jedyny, który odpowiada 200 także bez klucza — użyj go jako health-checku. Pole authenticated mówi, czy Twój klucz jest poprawny.

{
  "ok": true,
  "shop": "Chrupkie",
  "api_version": 1,
  "currency": "PLN",
  "authenticated": true,        // false = zły albo brak klucza
  "counts": { "products": 12, "categories": 3, "deliveries": 1 },
  "endpoints": { "products": { "method": "GET", "path": "/api/shop/products" }, ... }
}

Nasze produkty. Każdy ma gotowe pole order_item — wklej je wprost do items przy zamówieniu, najwyżej zmieniając qty.

{
  "currency": "PLN",
  "products": [
    {
      "id": "flavor-pistacjowe",
      "category": "smaki",
      "type": "single",
      "name": "Pistacjowe",
      "unit_price_grosze": 1200,
      "quantity_tiers": [                        // rabat ilościowy
        { "min_qty": 1,  "unit_grosze": 1200 },
        { "min_qty": 12, "unit_grosze": 1100 },
        { "min_qty": 24, "unit_grosze": 1000 }
      ],
      "order_item": { "kind": "single", "flavor": "Pistacjowe", "qty": 1 }
    },
    {
      "id": "box-6", "category": "pudelka", "type": "box",
      "name": "Szóstka (6 ciastek)", "count": 6, "price_grosze": 6200,
      "order_item": { "kind": "box", "box": "6", "flavors": { "Pistacjowe": 6 } }
    },
    {
      "id": "set-prezent6", "category": "zestawy", "type": "set",
      "name": "Pudełko prezentowe", "count": 6, "price_grosze": 7400,
      "order_item": { "kind": "set", "id": "prezent6" }
    }
  ]
}

{ "categories": [
  { "id": "smaki",   "name": "Smaki (pojedyncze ciastka)",  "product_count": 4 },
  { "id": "pudelka", "name": "Pudełka (własna kompozycja)", "product_count": 3 },
  { "id": "zestawy", "name": "Zestawy gotowe",              "product_count": 5 }
] }

Na razie wozimy jedną metodą. Opłatę doliczamy sami do każdego zamówienia.

{ "currency": "PLN", "deliveries": [
  { "id": "standard", "name": "Dostawa pod drzwi", "fee_grosze": 999, "fee_pln": 9.99 }
] }

Wyceniamy koszyk, tworzymy zamówienie i zwracamy checkout_url — link do płatności, pod który przekierowujesz klienta.

curl -X POST https://chrupkie.vercel.app/api/shop/orders \
  -H "x-api-key: TWOJ_KLUCZ" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [{ "kind": "single", "flavor": "Pistacjowe", "qty": 6 }],
    "delivery": {
      "name":   "Jan Kowalski",       // te 5 pól jest wymagane
      "phone":  "600700800",
      "street": "Piotrkowska 100/5",
      "zip":    "90-001",
      "city":   "Łódź",
      "notes":  "kod do bramy 1234"    // opcjonalne
    },
    "code": "FRIENDSANDFAMILY",        // opcjonalne
    "dry_run": false,                  // opcjonalne
    "return_url": "https://twoj-system.pl/koszyk"  // opcjonalne
  }'

return_url — powrót kupującego do Ciebie

Domyślnie po płatności odsyłamy klienta na naszą stronę. Podaj return_url, a wrócimy go do Ciebie — doklejamy do niego parametry:

// po udanej płatności
https://twoj-system.pl/koszyk?status=sukces&session_id=cs_live_...

// po anulowaniu
https://twoj-system.pl/koszyk?status=anulowano&order_ref=ord_...

Odpowiedź 201

{
  "order_ref": "ord_d3830dbd996922b6",
  "order_id": null,
  "status": "oczekuje_na_platnosc",
  "currency": "PLN",
  "items_total_grosze": 7200,
  "delivery_grosze": 999,
  "subtotal_grosze": 8199,          // przed rabatem
  "promo_code": "FRIENDSANDFAMILY",
  "promo_label": "Darmowa dostawa",
  "discount_grosze": 999,
  "total_grosze": 7200,             // do zapłaty
  "total_pln": 72,
  "line_items": [
    { "name": "Pistacjowe", "qty": 6, "unit_grosze": 1200 },
    { "name": "Dostawa",    "qty": 1, "unit_grosze": 999 }
  ],
  "checkout_url": "https://checkout.stripe.com/c/pay/cs_live_...",
  "stripe_session_id": "cs_live_..."
}

dry_run — wycena bez zobowiązań

Z "dry_run": true dostajesz te same sumy i rabat, ale bez tworzenia płatności. Odpowiedź 200 z {"dry_run": true, ...}, bez checkout_url. Używaj do pokazania koszyka i sprawdzenia kodu rabatowego — nie zaśmiecasz wtedy Stripe'a sesjami, których nikt nie opłaci. Działa też na sandboxie, zanim wpniemy tam płatności.

Status bierzemy prosto ze Stripe'a, więc jest zawsze aktualny.

{
  "order_ref": "ord_fd2240feb5566f5a",
  "stripe_session_id": "cs_live_...",
  "status": "oczekuje_na_platnosc",
  "payment_status": "unpaid",
  "amount_total_grosze": 1099,
  "amount_total_pln": 10.99,
  "currency": "PLN",
  "delivery": { "name": "Jan Kowalski", "phone": "600700800", ... },
  "created": "2026-07-10T17:41:48.000Z"
}

Do wykrywania płatności lepszy jest webhook niż odpytywanie w pętli — ale ten endpoint zawsze zadziała jako zapasowy.