Dokumentacja API zamówień

Autoryzacja

Oba endpointy są przeznaczone dla integracji zewnętrznej i wymagają autoryzacji tokenem technicznym. Nie jest to token użytkownika JWT z panelu B2B, tylko stały token integracyjny przekazywany w nagłówku x-shadow-token.

x-shadow-token: <TOKEN>
Content-Type: application/json

Przykład użycia tokenu

curl -X POST "https://api.shadow.code-m.pl/orders/all" \
  -H "Content-Type: application/json" \
  -H "x-shadow-token: TOKEN_INTEGRACYJNY" \
  -d '{}'

Odpowiedzi błędów autoryzacji

Token powinien być przechowywany po stronie systemu integrującego w konfiguracji serwerowej lub zmiennej środowiskowej. Nie należy umieszczać go w kodzie frontendowym ani udostępniać użytkownikom końcowym.

1. Pobieranie zamówień

Endpoint zwraca listę zamówień z panelu B2B. Można pobrać wszystkie zamówienia albo zawęzić wynik filtrami przekazanymi w body. Każde zamówienie zawiera dane nagłówkowe, historię statusów, dane rozliczeniowe, dane dostawy oraz pozycje zamówienia.

Body requestu

{
  "d0": "2026-05-11",
  "status": 0,
  "gr_id_zam": 123,
  "gr_rok_zam": 2026,
  "gr_nr_zam": 45,
  "gr_id_kth": "1001",
  "order_id": 12,
  "sort_order": "DESC"
}

Parametry

Jeśli body jest puste, np. {}, endpoint zwraca wszystkie zamówienia.

Przykład requestu

curl -X POST "https://api.shadow.code-m.pl/orders/all" \
  -H "Content-Type: application/json" \
  -H "x-shadow-token: TOKEN" \
  -d '{
    "d0": "2026-05-11",
    "status": 0
  }'

Przykład odpowiedzi

[
  {
    "order_id": 34,
    "net_total": "560.00",
    "tax": "23.00",
    "total": "688.80",
    "currency": "pln",
    "payment_method": "direct_transfer",
    "status": 0,
    "created_at": "2026-05-11T11:29:34.000Z",
    "updated_at": "2026-05-11T11:31:01.000Z",
    "gr_id_kth": "1",
    "gr_id_zam": null,
    "gr_rok_zam": null,
    "gr_nr_zam": null,
    "custom_name": "Nazwa własna zamówienia",
    "shipping_tracking": [
      {
        "order_id": 34,
        "tracking_number": "88683524525",
        "carrier": "GLS",
        "tracking_url": "https://gls-group.eu/PL/pl/sledzenie-przesylek?match=88683524525"
      },
      {
        "order_id": 34,
        "tracking_number": "88683524526",
        "carrier": "GLS",
        "tracking_url": "https://gls-group.eu/PL/pl/sledzenie-przesylek?match=88683524526"
      }
    ],
    "order_history": [
      { "status": 0, "date": "2026-05-11" }
    ],
    "products": [
      {
        "order_item_id": 37,
        "name": "P1615 tłumaczenie PL nowe",
        "sku": "P1615",
        "price_group": "2",
        "retail_price": "560.00",
        "user_price": "560.00",
        "gr_id_indeksu": 8784,
        "discount": 0,
        "currency": "pln",
        "params": [
          {
            "lp_gr": "1000",
            "source_id": 45004,
            "value": 1650,
            "label": "1650",
            "name": "Szerokość [mm]"
          },
          {
            "lp_gr": "1001",
            "source_id": 45005,
            "value": 1520,
            "label": "1520",
            "name": "Wysokość [mm]"
          },
          {
            "lp_gr": "1010",
            "source_id": 45006,
            "value": "1870",
            "label": "0-0135 PL (SK) [gat. 0]",
            "name": "Tkanina",
            "gr_id_indeksu_mat": 1870,
            "fabricclass": "0"
          },
          {
            "lp_gr": "1015",
            "source_id": 45056,
            "value": "DB 703",
            "label": "DB703-ciemnoszary",
            "name": "Kolor systemu"
          },
          {
            "lp_gr": "1099",
            "source_id": 53478,
            "value": "UWAGI DO POZYCJI",
            "label": "UWAGI DO POZYCJI",
            "name": "Uwagi do pozycji"
          }
        ],
        "quantity": 1,
        "type": "custom",
        "notes": "Notatki do pozycji w sklepie"
      }
    ],
    "billing": {
      "company": "Firma ABC",
      "nip": "1234567890",
      "representative": "Jan Kowalski"
    },
    "shipping": {
      "first_name": "Jan",
      "last_name": "Kowalski",
      "company": "Firma ABC",
      "address": "Działkowa 9",
      "city": "Warszawa",
      "postcode": "00-001",
      "country": "Poland",
      "phone": "+48500000000",
      "custom_name": "Adres główny",
      "address_status": "domyslny",
      "erp_address_id": "GRAF-001"
    }
  }
]

Pola obiektu shipping

Kody odpowiedzi

2. Aktualizacja statusów zamówień

Endpoint aktualizuje statusy zamówień w panelu B2B. Przyjmuje pojedynczy obiekt albo tablicę obiektów. Dla każdego poprawnego obiektu:

• opcjonalnie aktualizuje orders.status,
• przy zmianie danych nagłówka aktualizuje orders.updated_at,
• opcjonalnie zapisuje dane ERP: gr_id_zam, gr_rok_zam, gr_nr_zam,
• opcjonalnie zapisuje dane wysyłkowe: tracking_number, carrier,
• jeśli dane wysyłkowe zostaną przekazane, dopisuje nowe rekordy do tabeli order_shipping_tracking,
• identyczny wpis order_id + tracking_number + carrier nie jest dublowany,
• dopisuje wpis do order_status_history,
• zwraca listę faktycznie zaktualizowanych zamówień.

Body requestu

{
  "order_id": 12,
  "status": 1,
  "date": "2026-05-11",
  "gr_id_zam": 123,
  "gr_rok_zam": 2026,
  "gr_nr_zam": 45,
  "tracking_number": "88683524525",
  "carrier": "GLS"
}

Parametry pojedynczego obiektu

Przykład requestu

curl -X POST "https://api.shadow.code-m.pl/orders/status-update" \
  -H "Content-Type: application/json" \
  -H "x-shadow-token: TOKEN" \
  -d '[
    {
      "order_id": 12,
      "gr_id_zam": 123
    },
    {
      "order_id": 12,
      "gr_nr_zam": 45,
      "gr_rok_zam": 2026,
      "tracking_number": "88683524525",
      "carrier": "GLS"
    },
    {
      "order_id": 13,
      "status": -1,
      "date": "2026-05-11",
      "tracking_number": "88683524526",
      "carrier": "GLS"
    }
  ]'

Przykład odpowiedzi

{
  "updated_ids": [12, 13]
}

Zasady działania

• Endpoint przyjmuje pojedynczy obiekt albo tablicę obiektów.
• Wymagane jest tylko pole order_id. Pozostałe pola są opcjonalne.
• Do updated_ids trafiają tylko zamówienia, które zostały znalezione i zaktualizowane.
• Pola tracking_number i carrier są opcjonalne i mogą być przekazywane niezależnie od zmiany statusu.
• Dane wysyłkowe są zapisywane w tabeli order_shipping_tracking z polami order_id, tracking_number, carrier.
• Nowe numery przesyłek dla tego samego zamówienia są dopisywane jako kolejne rekordy.
• Identyczny wpis order_id + tracking_number + carrier nie jest dublowany.
• Status -1 oznacza wpis informacyjny. Nie zmienia głównego statusu zamówienia, a jedynie dopisuje komunikat do historii statusów.
• Jeśli status nie zostanie przekazany, wpis historii statusów zapisze się jako informacyjny -1.
• Historia statusów jest dopisywana do tabeli order_status_history, a opis wykonanej akcji zapisywany jest w kolumnie message.

Kody odpowiedzi

3. Upload faktury PDF

Endpoint przyjmuje plik PDF faktury wraz z metadanymi zamówienia ERP. Format: multipart/form-data. Maksymalny rozmiar pliku: 10 MB.

Pola formularza

Przykład requestu (curl)

curl -X POST "https://api.shadow.code-m.pl/admin-tools/sync-import/invoice-upload" \
  -H "x-shadow-token: <TOKEN>" \
  -F "=@/path/to/Faktura_2026_31279.pdf" \
  -F "gr_id_inv=31279" \
  -F "gr_id_kth=128"

Przykład odpowiedzi

{
  "ok": true,
  "invoice_id": 12,
  "gr_id_inv": "31279"
}

Kody odpowiedzi

Statusy zamówień

W kodzie status jest przechowywany jako liczba typu int. Znaczenie statusów powinno być zgodne z mapą używaną w panelu B2B oraz ERP.