Integration API

REST do tworzenia i obsługi zamówień w Ecommigo. Integracja sklepu, ERP albo wtyczki WooCommerce czyta i zapisuje zamówienia na koncie powiązanym z kluczem.

Base URL https://integration-dev.ecommigo.com/v1

Autoryzacja

Każde żądanie wymaga nagłówka x-api-key. Klucz jest w panelu Ecommigo, w konfiguracji integracji.

x-api-key: <twój klucz>

Brak klucza → 401. Nieprawidłowy klucz → 403. API nie przyjmuje accountId w body — konto wynika z klucza.

Zamówienia

GET, PATCH i DELETE widzą wszystkie zamówienia konta (także te z panelu). POST tworzy nowe. Identyfikator w ścieżce to id, numer sklepu (externalNumber) albo numer dokumentu (np. ZK/2026/0001).

GET/orders

Lista zamówień konta, od najnowszych.

Query	Opis
`limit`	Domyślnie 50, max 200
`skip`	Offset
`scope`	`mine` — tylko zamówienia utworzone przez tę integrację

Odpowiedź 200

{
  "items": [
    {
      "id": "6a6da0cd0ceabb38f6cade11",
      "externalNumber": "SHOP-1001",
      "documentNumber": "ZK/2026/0001",
      "status": "new",
      "positions": []
    }
  ]
}

Przykład

curl -H "x-api-key: $API_KEY" \
  "https://integration-dev.ecommigo.com/v1/orders?limit=10"

GET/orders/{id}

Jedno zamówienie. {id} to identyfikator API, SHOP-1001 albo ZK/2026/0001.

Odpowiedź 200

{
  "id": "6adb5f26221a11a212042ad3",
  "externalNumber": "SHOP-1001",
  "documentNumber": "ZK/2026/0002",
  "status": "new",
  "customStatus": null,
  "contractor": { "name": "Acme Sp. z o.o.", "email": "ops@acme.test" },
  "payment": { "method": "bacs", "paid": false },
  "positions": [
    {
      "productId": "6a6b4776a2ca9b8864f7645d",
      "sku": "SHBZ18835239",
      "name": "Sneakersy Beżowe 39",
      "quantity": 1,
      "price": 19.99
    }
  ],
  "customFields": [],
  "createdAt": "2026-10-23T13:20:38.240Z",
  "updatedAt": "2026-10-23T13:20:38.240Z"
}

POST/orders

Tworzy zamówienie i nadaje documentNumber. Wymagane externalNumber. Ten sam numer przy ponownym POST zwraca istniejące zamówienie (200) zamiast tworzyć drugie.

Każda pozycja musi wskazywać produkt z katalogu: productId albo sku (ew. ean). Nieznany produkt → 400 unknown_product.

Request

{
  "externalNumber": "SHOP-1001",
  "status": "new",
  "contractor": {
    "name": "Acme Sp. z o.o.",
    "email": "ops@acme.test"
  },
  "payment": { "method": "bacs", "paid": false },
  "positions": [
    { "sku": "SHBZ18835239", "quantity": 2, "price": 19.99 }
  ],
  "customFields": [
    { "key": "source", "value": "shop" }
  ]
}

Odpowiedź 201

{
  "id": "6adb5f26…",
  "externalNumber": "SHOP-1001",
  "documentNumber": "ZK/2026/0002",
  "status": "new",
  "positions": [
    {
      "productId": "6a6b4776…",
      "sku": "SHBZ18835239",
      "name": "Sneakersy Beżowe 39",
      "quantity": 2,
      "price": 19.99
    }
  ]
}

PATCH/orders/{id}

Częściowa aktualizacja (status, płatność, pozycje, kontrahent, pola własne). Numer dokumentu i właściciel zamówienia się nie zmieniają.

Request

{
  "status": "paid",
  "payment": { "method": "bacs", "paid": true }
}

DELETE/orders/{id}

Usuwa zamówienie.

Odpowiedź 200

{ "deleted": true, "id": "SHOP-1001" }

Słowniki

Wartości do formularzy i mapowania. Wszystkie zwracają { "items": [ … ] }.

GET/payment-methods

Metody płatności konta. Pole payment.method na zamówieniu to key.

{
  "items": [
    {
      "id": "6a6b03e4…",
      "key": "bacs",
      "name": "Przelew tradycyjny",
      "isActive": true,
      "codAvailable": false
    }
  ]
}

GET/shipping-methods

Metody wysyłki. key wstawiasz jako metodę dostawy na zamówieniu.

{
  "items": [
    { "id": "…", "key": "inpost", "name": "InPost", "isActive": true, "iconUrl": null }
  ]
}

GET/order-statuses

Statusy zdefiniowane na koncie. id możesz podać jako customStatus przy tworzeniu / aktualizacji.

GET/custom-fields

Pola własne. Na zamówieniu: customFields: [{ "key", "value" }].

Kody błędów

Błędy aplikacji:

{ "error": { "code": "not_found", "message": "Order not found" } }

HTTP	code	Znaczenie
400	`bad_request`	Brak `externalNumber` albo niepoprawny JSON
400	`unknown_product`	Produkt spoza katalogu konta
401	—	Brak nagłówka `x-api-key`
403	—	Nieprawidłowy klucz
404	`not_found`	Nie ma takiego zamówienia na koncie
503	`numbering_unavailable`	Konto nie ma włączonej numeracji dokumentów