Spis treści

Dokumentacja API · v1

Cornvilla REST API

Zamówienia ze wszystkich kanałów, produkty, stany na lokacjach, przesyłki, zwroty i magazyn — przez zwykłe REST API z JSON-em. Kliknij adres, żeby zobaczyć parametry, treść żądania, odpowiedź i przykład wywołania.

Adres bazowy: https://api.cornvilla.com/v1
Token: POST https://api.cornvilla.com/v1/oauth/token
Format: JSON (UTF-8), daty ISO 8601, kwoty w groszach
Opis OpenAPI: openapi.json

Autoryzacja

OAuth2 client_credentials. Aplikację dodajesz w panelu: Ustawienia → API → Dodaj aplikację — dostajesz Client ID i Client Secret (secret widać tylko raz). Za ich pomocą pobierasz token ważny 1 godzinę i wysyłasz go w nagłówku Authorization: Bearer …. Nowy secret albo usunięcie aplikacji unieważnia tokeny od razu.

curl -X POST "https://api.cornvilla.com/v1/oauth/token" \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -d "grant_type=client_credentials"

{ "access_token": "cvat_…", "token_type": "Bearer", "expires_in": 3600, "scope": "orders:read stock:read" }

curl "https://api.cornvilla.com/v1/me" -H "Authorization: Bearer cvat_…"

Zasady wspólne

Stronicowanie: page (od 1) i pageSize (do 200); odpowiedź: items, page, pageSize, total.
Synchronizacja przyrostowa: GET /orders?updatedSince=2026-11-07T10:00:00Z zwraca tylko zamówienia zmienione po tej chwili.
Limity: liczba zapytań na minutę zależy od pakietu i liczy się na aplikację. Nagłówki X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset; po przekroczeniu 429 z Retry-After.
Wiele magazynów: domyślnie magazyn główny; inny wskazujesz nagłówkiem X-Warehouse: <id> (lista z GET /warehouses).
Wersje: w /v1 tylko dodajemy pola i adresy — nic nie usuwamy ani nie zmieniamy znaczenia.

Błędy

Każdy błąd to JSON { "code": "…", "message": "…" } — code jest stały (do obsługi w kodzie), message po polsku.

HTTP	code	Kiedy
401	UNAUTHORIZED / INVALID_TOKEN	Brak tokenu albo token nieprawidłowy, wygasły (po godzinie) lub unieważniony nowym sekretem — pobierz nowy.
401	invalid_client	Przy POST /oauth/token: zły Client ID albo Client Secret, aplikacja usunięta.
403	FORBIDDEN_SCOPE	Aplikacja nie ma uprawnienia wymaganego przez ten adres (np. orders:write).
400	VALIDATION_ERROR	Błędne dane w zapytaniu albo treści — komunikat wskazuje pole.
404	NOT_FOUND	Nie ma takiego zamówienia / produktu / adresu.
409	CONFLICT	Operacja niemożliwa w tym stanie (np. anulowanie wysłanego zamówienia).
402	TENANT_READONLY	Konto firmy tylko do odczytu (nieprzedłużone) — zapisy odrzucone.
429	RATE_LIMIT_EXCEEDED	Przekroczony limit zapytań na minutę — odczekaj tyle, ile mówi nagłówek Retry-After.

Autoryzacja

1Token dostępowy za Client ID i Client Secret (OAuth2 client_credentials).

post/v1/oauth/tokenPobierz token dostępowy (Client ID + Client Secret)

OAuth2 client_credentials. Wyślij grant_type=client_credentials i dane aplikacji z Ustawienia → API — w nagłówku Authorization: Basic base64(client_id:client_secret) albo w treści (client_id, client_secret; formularz albo JSON). Token jest ważny godzinę; nowy Client Secret albo usunięcie aplikacji unieważnia go od razu. Nie wymaga tokenu.

Treść żądania (JSON)

grant_typestring
Zawsze „client_credentials”.
client_idstring
Client ID z Ustawienia → API (albo w nagłówku Basic).
client_secretstring
Client Secret (albo w nagłówku Basic).

Przykładowe wywołanie

curl -X POST "https://api.cornvilla.com/v1/oauth/token" \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -d "grant_type=client_credentials"

Odpowiedź 200 — pola

access_tokenstring
Token do nagłówka „Authorization: Bearer …”.
token_type"Bearer"
expires_ininteger
Ważność w sekundach (3600). Po wygaśnięciu pobierz nowy token.
scopestring
Uprawnienia aplikacji, oddzielone spacją.

Odpowiedź 200 — przykład

{
  "access_token": "…",
  "token_type": "Bearer",
  "expires_in": 1,
  "scope": "…"
}

Konto

1Sprawdzenie tokenu: firma, aplikacja i jej uprawnienia, limit.

get/v1/meKim jestem: firma, aplikacja i jej uprawnienia, limit zapytań, bieżący magazyn

Najprostszy test tokenu. Nie wymaga żadnego uprawnienia.

Przykładowe wywołanie

curl "https://api.cornvilla.com/v1/me" \
  -H "Authorization: Bearer $TOKEN"

Odpowiedź 200 — pola

companyobject
- iduuid
- slugstring
- namestring
appobject
Aplikacja, której token użyto, i jej uprawnienia.
- namestring
- clientIdstring
- scopesstring[]
limitsobject
- requestsPerMinuteinteger
warehouseobject
Magazyn, w którym działa to żądanie (nagłówek X-Warehouse albo główny).
- iduuid
- codestring
- namestring
- isMainboolean
- activeboolean

Odpowiedź 200 — przykład

{
  "company": {
    "id": "3f2a9c1e-5b7d-4e8a-9c2b-1d4e6f8a0b2c",
    "slug": "…",
    "name": "…"
  },
  "app": {
    "name": "…",
    "clientId": "…",
    "scopes": [
      "…"
    ]
  },
  "limits": {
    "requestsPerMinute": 1
  },
  "warehouse": {
    "id": "3f2a9c1e-5b7d-4e8a-9c2b-1d4e6f8a0b2c",
    "code": "…",
    "name": "…",
    "isMain": true,
    "active": true
  }
}

Zamówienia

6Zamówienia ze wszystkich źródeł: lista, szczegóły z pozycjami, dodawanie, zmiany, anulowanie i wydanie.

get/v1/ordersLista zamówieńorders:read

Zamówienia bieżącego magazynu, najnowsze pierwsze. Filtry: status, źródło, zmienione od (updatedSince), szukanie (numer, klient, numer przesyłki).

Wymagane uprawnienie: orders:read

Parametry

pagew zapytaniu · integerdomyślnie 1
Numer strony (od 1).
pageSizew zapytaniu · integerdomyślnie 50
Pozycji na stronie (1–200).
statusw zapytaniu · "needs_linking" | "pending" | "picking" | "packed" | "shipped" | "cancelled" | "all"domyślnie "all"
sourcew zapytaniu · string
Nazwa połączenia (jak w polu `source`).
updatedSincew zapytaniu · data ISO 8601
Tylko zamówienia zmienione w Cornvilla po tej chwili (ISO 8601).
qw zapytaniu · stringdomyślnie ""
Szukanie: numer, numer ze sklepu, klient, numer przesyłki.
sortw zapytaniu · "orderedAt" | "createdAt"domyślnie "orderedAt"
orderw zapytaniu · "asc" | "desc"domyślnie "desc"

Przykładowe wywołanie

curl "https://api.cornvilla.com/v1/orders?page=1&pageSize=50" \
  -H "Authorization: Bearer $TOKEN"

Odpowiedź 200 — pola

itemsobject[]
- iduuid
- numberstring
  Numer w Cornvilla (unikalny).
- referencestring
  Numer ze sklepu / marketplace'u / ERP (unikalny w obrębie źródła).
- sourcestring
  Źródło zamówienia: nazwa połączenia (np. „Shoper”) albo „manual”.
- statusstring
  needs_linking (pozycja bez produktu) · pending (oczekujące) · picking (w realizacji) · packed (spakowane) · shipped (wysłane) · cancelled (anulowane).
- customerNamestring | null
- paidboolean | null
  null = źródło nie podaje.
- paymentMethodstring | null
- codAmountinteger | null
  Pobranie w groszach; null = bez pobrania.
- orderTotalinteger | null
  Wartość do zapłaty w groszach.
- currencystring | null
- deliveryMethodstring | null
- pickupPointstring | null
  Kod paczkomatu / punktu odbioru.
- orderedAtdata ISO 8601 | null
- shipBydata ISO 8601 | null
  Termin wysyłki.
- priorityinteger
  0 = normalny, wyżej = pilniejsze.
- lineCountinteger
- unitCountinteger
- trackingNumberstring | null
- labelStatusstring
  none · pending · generated · failed
- invoiceNumberstring | null
- invoiceStatusstring | null
  null = źródło bez fakturowania; pending · ready · failed.
- createdAtdata ISO 8601
pageinteger
pageSizeinteger
totalinteger
Łączna liczba pozycji spełniających filtry.

Odpowiedź 200 — przykład

{
  "items": [
    {
      "id": "3f2a9c1e-5b7d-4e8a-9c2b-1d4e6f8a0b2c",
      "number": "…",
      "reference": "…",
      "source": "…",
      "status": "…",
      "customerName": "…",
      "paid": true,
      "paymentMethod": "…",
      "codAmount": 1,
      "orderTotal": 1,
      "currency": "…",
      "deliveryMethod": "…",
      "pickupPoint": "…",
      "orderedAt": "2026-11-07T10:15:00.000Z",
      "shipBy": "2026-11-07T10:15:00.000Z",
      "priority": 1,
      "lineCount": 1,
      "unitCount": 1,
      "trackingNumber": "…",
      "labelStatus": "…",
      "invoiceNumber": "…",
      "invoiceStatus": "…",
      "createdAt": "2026-11-07T10:15:00.000Z"
    }
  ],
  "page": 1,
  "pageSize": 1,
  "total": 1
}

post/v1/ordersDodaj zamówienieorders:write

Zamówienie spoza podłączonych sklepów (telefon, B2B, własny system). Pozycje wskazują produkty Cornvilla (productId z GET /v1/products). Kwoty w groszach brutto. Numer nadaje Cornvilla (R-…).

Wymagane uprawnienie: orders:write

Treść żądania (JSON)

customerobjectwymagane
- namestring
- companystring | null
- phonestring | null
- emailstring | ""
addressobject | null
- streetstring | null
- houseNumberstring | null
- apartmentNumberstring | null
- postalCodestring | null
- citystring | null
- countrystring | null
deliveryMethodstring | null
pickupPointstring | null
deliveryCostinteger | null
payment"paid" | "unpaid" | "cod"wymagane
paymentMethodstring | null
invoiceobject | null
- companystring | null
- taxNostring | null
- streetstring | null
- postalCodestring | null
- citystring | null
- emailstring | null
linesobject[]wymagane
- productIduuid
- quantityinteger
- unitPriceinteger | null
notesstring | null
priorityintegerdomyślnie 0
shipBydata ISO 8601 | null

Przykładowe wywołanie

curl -X POST "https://api.cornvilla.com/v1/orders" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"customer":{"name":"…","company":"…","phone":"…","email":"…"},"address":{"street":"…","houseNumber":"…","apartmentNumber":"…","postalCode":"…","city":"…","country":"…"},"deliveryMethod":"…","pickupPoint":"…","deliveryCost":0,"payment":"paid","paymentMethod":"…","invoice":{"company":"…","taxNo":"…","street":"…","postalCode":"…","city":"…","email":"…"},"lines":[{"productId":"3f2a9c1e-5b7d-4e8a-9c2b-1d4e6f8a0b2c","quantity":1,"unitPrice":0}],"notes":"…","priority":0,"shipBy":"2026-11-07T10:15:00.000Z"}'

Odpowiedź 201 — pola

iduuid
numberstring

Odpowiedź 201 — przykład

{
  "id": "3f2a9c1e-5b7d-4e8a-9c2b-1d4e6f8a0b2c",
  "number": "…"
}

get/v1/orders/{id}Szczegóły zamówienia z pozycjamiorders:read

Wymagane uprawnienie: orders:read

Parametry

idw adresie · uuidwymagane

Przykładowe wywołanie

curl "https://api.cornvilla.com/v1/orders/<id>" \
  -H "Authorization: Bearer $TOKEN"

Odpowiedź 200 — pola

iduuid
numberstring
Numer w Cornvilla (unikalny).
referencestring
Numer ze sklepu / marketplace'u / ERP (unikalny w obrębie źródła).
sourcestring
Źródło zamówienia: nazwa połączenia (np. „Shoper”) albo „manual”.
statusstring
needs_linking (pozycja bez produktu) · pending (oczekujące) · picking (w realizacji) · packed (spakowane) · shipped (wysłane) · cancelled (anulowane).
customerNamestring | null
paidboolean | null
null = źródło nie podaje.
paymentMethodstring | null
codAmountinteger | null
Pobranie w groszach; null = bez pobrania.
orderTotalinteger | null
Wartość do zapłaty w groszach.
currencystring | null
deliveryMethodstring | null
pickupPointstring | null
Kod paczkomatu / punktu odbioru.
orderedAtdata ISO 8601 | null
shipBydata ISO 8601 | null
Termin wysyłki.
priorityinteger
0 = normalny, wyżej = pilniejsze.
lineCountinteger
unitCountinteger
trackingNumberstring | null
labelStatusstring
none · pending · generated · failed
invoiceNumberstring | null
invoiceStatusstring | null
null = źródło bez fakturowania; pending · ready · failed.
createdAtdata ISO 8601
notesstring | null
linesobject[]
- iduuid
- productIduuid | null
  null = pozycja czeka na powiązanie z produktem.
- skustring | null
- eanstring | null
- namestring
- quantityinteger
- sourceSkustring | null
  SKU / ID pozycji, jak podało źródło.
- sourceNamestring | null

Odpowiedź 200 — przykład

{
  "id": "3f2a9c1e-5b7d-4e8a-9c2b-1d4e6f8a0b2c",
  "number": "…",
  "reference": "…",
  "source": "…",
  "status": "…",
  "customerName": "…",
  "paid": true,
  "paymentMethod": "…",
  "codAmount": 1,
  "orderTotal": 1,
  "currency": "…",
  "deliveryMethod": "…",
  "pickupPoint": "…",
  "orderedAt": "2026-11-07T10:15:00.000Z",
  "shipBy": "2026-11-07T10:15:00.000Z",
  "priority": 1,
  "lineCount": 1,
  "unitCount": 1,
  "trackingNumber": "…",
  "labelStatus": "…",
  "invoiceNumber": "…",
  "invoiceStatus": "…",
  "createdAt": "2026-11-07T10:15:00.000Z",
  "notes": "…",
  "lines": [
    {
      "id": "3f2a9c1e-5b7d-4e8a-9c2b-1d4e6f8a0b2c",
      "productId": "3f2a9c1e-5b7d-4e8a-9c2b-1d4e6f8a0b2c",
      "sku": "…",
      "ean": "…",
      "name": "…",
      "quantity": 1,
      "sourceSku": "…",
      "sourceName": "…"
    }
  ]
}

patch/v1/orders/{id}Zmień opłacenie, formę płatności, dostawę, punkt odbioru albo statusorders:write

Wymagane uprawnienie: orders:write

Parametry

idw adresie · uuidwymagane

Treść żądania (JSON)

paidboolean | null
paymentMethodstring | null
deliveryMethodstring | null
Tylko dopóki nie ma etykiety i zamówienie nie jest wysłane.
pickupPointstring | null
status"pending" | "packed"
pending ← packed (cofnięcie) albo packed ← pending (spakowane poza Cornvilla). Wysyłkę oznacza POST …/release.

Przykładowe wywołanie

curl -X PATCH "https://api.cornvilla.com/v1/orders/<id>" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"paid":true,"paymentMethod":"…","deliveryMethod":"…","pickupPoint":"…","status":"pending"}'

Odpowiedź 200 — pola

iduuid
numberstring
Numer w Cornvilla (unikalny).
referencestring
Numer ze sklepu / marketplace'u / ERP (unikalny w obrębie źródła).
sourcestring
Źródło zamówienia: nazwa połączenia (np. „Shoper”) albo „manual”.
statusstring
needs_linking (pozycja bez produktu) · pending (oczekujące) · picking (w realizacji) · packed (spakowane) · shipped (wysłane) · cancelled (anulowane).
customerNamestring | null
paidboolean | null
null = źródło nie podaje.
paymentMethodstring | null
codAmountinteger | null
Pobranie w groszach; null = bez pobrania.
orderTotalinteger | null
Wartość do zapłaty w groszach.
currencystring | null
deliveryMethodstring | null
pickupPointstring | null
Kod paczkomatu / punktu odbioru.
orderedAtdata ISO 8601 | null
shipBydata ISO 8601 | null
Termin wysyłki.
priorityinteger
0 = normalny, wyżej = pilniejsze.
lineCountinteger
unitCountinteger
trackingNumberstring | null
labelStatusstring
none · pending · generated · failed
invoiceNumberstring | null
invoiceStatusstring | null
null = źródło bez fakturowania; pending · ready · failed.
createdAtdata ISO 8601
notesstring | null
linesobject[]
- iduuid
- productIduuid | null
  null = pozycja czeka na powiązanie z produktem.
- skustring | null
- eanstring | null
- namestring
- quantityinteger
- sourceSkustring | null
  SKU / ID pozycji, jak podało źródło.
- sourceNamestring | null

Odpowiedź 200 — przykład

{
  "id": "3f2a9c1e-5b7d-4e8a-9c2b-1d4e6f8a0b2c",
  "number": "…",
  "reference": "…",
  "source": "…",
  "status": "…",
  "customerName": "…",
  "paid": true,
  "paymentMethod": "…",
  "codAmount": 1,
  "orderTotal": 1,
  "currency": "…",
  "deliveryMethod": "…",
  "pickupPoint": "…",
  "orderedAt": "2026-11-07T10:15:00.000Z",
  "shipBy": "2026-11-07T10:15:00.000Z",
  "priority": 1,
  "lineCount": 1,
  "unitCount": 1,
  "trackingNumber": "…",
  "labelStatus": "…",
  "invoiceNumber": "…",
  "invoiceStatus": "…",
  "createdAt": "2026-11-07T10:15:00.000Z",
  "notes": "…",
  "lines": [
    {
      "id": "3f2a9c1e-5b7d-4e8a-9c2b-1d4e6f8a0b2c",
      "productId": "3f2a9c1e-5b7d-4e8a-9c2b-1d4e6f8a0b2c",
      "sku": "…",
      "ean": "…",
      "name": "…",
      "quantity": 1,
      "sourceSku": "…",
      "sourceName": "…"
    }
  ]
}

post/v1/orders/{id}/cancelAnuluj zamówienieorders:write

Zamówienie w realizacji albo spakowane wraca towarem na stan według reguł Cornvilla.

Wymagane uprawnienie: orders:write

Parametry

idw adresie · uuidwymagane

Przykładowe wywołanie

curl -X POST "https://api.cornvilla.com/v1/orders/<id>/cancel" \
  -H "Authorization: Bearer $TOKEN"

Odpowiedź 200 — pola

iduuid
numberstring
Numer w Cornvilla (unikalny).
referencestring
Numer ze sklepu / marketplace'u / ERP (unikalny w obrębie źródła).
sourcestring
Źródło zamówienia: nazwa połączenia (np. „Shoper”) albo „manual”.
statusstring
needs_linking (pozycja bez produktu) · pending (oczekujące) · picking (w realizacji) · packed (spakowane) · shipped (wysłane) · cancelled (anulowane).
customerNamestring | null
paidboolean | null
null = źródło nie podaje.
paymentMethodstring | null
codAmountinteger | null
Pobranie w groszach; null = bez pobrania.
orderTotalinteger | null
Wartość do zapłaty w groszach.
currencystring | null
deliveryMethodstring | null
pickupPointstring | null
Kod paczkomatu / punktu odbioru.
orderedAtdata ISO 8601 | null
shipBydata ISO 8601 | null
Termin wysyłki.
priorityinteger
0 = normalny, wyżej = pilniejsze.
lineCountinteger
unitCountinteger
trackingNumberstring | null
labelStatusstring
none · pending · generated · failed
invoiceNumberstring | null
invoiceStatusstring | null
null = źródło bez fakturowania; pending · ready · failed.
createdAtdata ISO 8601
notesstring | null
linesobject[]
- iduuid
- productIduuid | null
  null = pozycja czeka na powiązanie z produktem.
- skustring | null
- eanstring | null
- namestring
- quantityinteger
- sourceSkustring | null
  SKU / ID pozycji, jak podało źródło.
- sourceNamestring | null

Odpowiedź 200 — przykład

{
  "id": "3f2a9c1e-5b7d-4e8a-9c2b-1d4e6f8a0b2c",
  "number": "…",
  "reference": "…",
  "source": "…",
  "status": "…",
  "customerName": "…",
  "paid": true,
  "paymentMethod": "…",
  "codAmount": 1,
  "orderTotal": 1,
  "currency": "…",
  "deliveryMethod": "…",
  "pickupPoint": "…",
  "orderedAt": "2026-11-07T10:15:00.000Z",
  "shipBy": "2026-11-07T10:15:00.000Z",
  "priority": 1,
  "lineCount": 1,
  "unitCount": 1,
  "trackingNumber": "…",
  "labelStatus": "…",
  "invoiceNumber": "…",
  "invoiceStatus": "…",
  "createdAt": "2026-11-07T10:15:00.000Z",
  "notes": "…",
  "lines": [
    {
      "id": "3f2a9c1e-5b7d-4e8a-9c2b-1d4e6f8a0b2c",
      "productId": "3f2a9c1e-5b7d-4e8a-9c2b-1d4e6f8a0b2c",
      "sku": "…",
      "ean": "…",
      "name": "…",
      "quantity": 1,
      "sourceSku": "…",
      "sourceName": "…"
    }
  ]
}

post/v1/orders/{id}/releaseWydaj zamówienie („Wydano”)orders:write

Spakowane zamówienie przechodzi na „wysłane”: z etykietą — jak przekazanie kurierowi (status i numer przesyłki wracają do sklepu), bez etykiety — wydanie bez kuriera (odbiór osobisty, własny transport).

Wymagane uprawnienie: orders:write

Parametry

idw adresie · uuidwymagane

Przykładowe wywołanie

curl -X POST "https://api.cornvilla.com/v1/orders/<id>/release" \
  -H "Authorization: Bearer $TOKEN"

Odpowiedź 200 — pola

orderIduuid
orderNumberstring | null
outcome"requested" | "already" | "error"
messagestring | null
courierboolean

Odpowiedź 200 — przykład

{
  "orderId": "3f2a9c1e-5b7d-4e8a-9c2b-1d4e6f8a0b2c",
  "orderNumber": "…",
  "outcome": "requested",
  "message": "…",
  "courier": true
}

Produkty

4Katalog produktów: SKU, EAN, wymiary, stan i lokacje.

get/v1/productsLista produktówproducts:read

Szukanie fragmentem (SKU, nazwa, EAN, kategoria, marka, ID w sklepach) albo dokładne sku / ean.

Wymagane uprawnienie: products:read

Parametry

pagew zapytaniu · integerdomyślnie 1
Numer strony (od 1).
pageSizew zapytaniu · integerdomyślnie 50
Pozycji na stronie (1–200).
qw zapytaniu · stringdomyślnie ""
skuw zapytaniu · string
Dokładne SKU — zwraca najwyżej jeden produkt.
eanw zapytaniu · string
Dokładny EAN — zwraca najwyżej jeden produkt.
statusw zapytaniu · "active" | "inactive" | "all"domyślnie "active"
sortw zapytaniu · "sku" | "name" | "updatedAt" | "createdAt"domyślnie "sku"
orderw zapytaniu · "asc" | "desc"domyślnie "asc"

Przykładowe wywołanie

curl "https://api.cornvilla.com/v1/products?page=1&pageSize=50" \
  -H "Authorization: Bearer $TOKEN"

Odpowiedź 200 — pola

itemsobject[]
- iduuid
- skustring
- eanstring | null
- namestring
- unitstring
- activeboolean
- stocklessboolean
  Nie trzymany na magazynie (zamawiany pod zamówienie).
- kind"product" | "bundle"
- categorystring | null
- brandstring | null
- weightKgnumber | null
- lengthMminteger | null
- widthMminteger | null
- heightMminteger | null
- imageUrlstring | null
- vatRateinteger | null
  Stawka VAT w procentach; null = nie ustawiono.
- locationsstring[]
  Kody lokacji, w których produkt jest przypisany (główna pierwsza).
- stockinteger
  Łączny stan (sztuki).
- stockUnplacedinteger
  Część stanu w strefie przyjęć (do rozłożenia).
- externalRefsobject[]
  ID produktu w podłączonych sklepach.
  - sourceNamestring
  - externalIdstring
- createdAtdata ISO 8601
- updatedAtdata ISO 8601
pageinteger
pageSizeinteger
totalinteger
Łączna liczba pozycji spełniających filtry.

Odpowiedź 200 — przykład

{
  "items": [
    {
      "id": "3f2a9c1e-5b7d-4e8a-9c2b-1d4e6f8a0b2c",
      "sku": "…",
      "ean": "…",
      "name": "…",
      "unit": "…",
      "active": true,
      "stockless": true,
      "kind": "product",
      "category": "…",
      "brand": "…",
      "weightKg": 1,
      "lengthMm": 1,
      "widthMm": 1,
      "heightMm": 1,
      "imageUrl": "…",
      "vatRate": 1,
      "locations": [
        "…"
      ],
      "stock": 1,
      "stockUnplaced": 1,
      "externalRefs": [
        {
          "sourceName": null,
          "externalId": null
        }
      ],
      "createdAt": "2026-11-07T10:15:00.000Z",
      "updatedAt": "2026-11-07T10:15:00.000Z"
    }
  ],
  "page": 1,
  "pageSize": 1,
  "total": 1
}

post/v1/productsDodaj produktproducts:write

SKU musi być unikalne w firmie. Wymiary w mm, waga w kg — z nich Cornvilla liczy pojemność koszyków i dobór kartonu.

Wymagane uprawnienie: products:write

Treść żądania (JSON)

skustringwymagane
namestringwymagane
eanstring | null
unitstringdomyślnie "szt"
weightKgnumber | null
lengthMminteger | null
widthMminteger | null
heightMminteger | null
categorystring | null
brandstring | null
imageUrlstring | null
activebooleandomyślnie true
stocklessbooleandomyślnie false

Przykładowe wywołanie

curl -X POST "https://api.cornvilla.com/v1/products" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"sku":"…","name":"…","ean":"…","unit":"szt","weightKg":0,"lengthMm":1,"widthMm":1,"heightMm":1,"category":"…","brand":"…","imageUrl":"…","active":true,"stockless":false}'

Odpowiedź 201 — pola

iduuid
skustring
eanstring | null
namestring
unitstring
activeboolean
stocklessboolean
Nie trzymany na magazynie (zamawiany pod zamówienie).
kind"product" | "bundle"
categorystring | null
brandstring | null
weightKgnumber | null
lengthMminteger | null
widthMminteger | null
heightMminteger | null
imageUrlstring | null
vatRateinteger | null
Stawka VAT w procentach; null = nie ustawiono.
locationsstring[]
Kody lokacji, w których produkt jest przypisany (główna pierwsza).
stockinteger
Łączny stan (sztuki).
stockUnplacedinteger
Część stanu w strefie przyjęć (do rozłożenia).
externalRefsobject[]
ID produktu w podłączonych sklepach.
- sourceNamestring
- externalIdstring
createdAtdata ISO 8601
updatedAtdata ISO 8601

Odpowiedź 201 — przykład

{
  "id": "3f2a9c1e-5b7d-4e8a-9c2b-1d4e6f8a0b2c",
  "sku": "…",
  "ean": "…",
  "name": "…",
  "unit": "…",
  "active": true,
  "stockless": true,
  "kind": "product",
  "category": "…",
  "brand": "…",
  "weightKg": 1,
  "lengthMm": 1,
  "widthMm": 1,
  "heightMm": 1,
  "imageUrl": "…",
  "vatRate": 1,
  "locations": [
    "…"
  ],
  "stock": 1,
  "stockUnplaced": 1,
  "externalRefs": [
    {
      "sourceName": "…",
      "externalId": "…"
    }
  ],
  "createdAt": "2026-11-07T10:15:00.000Z",
  "updatedAt": "2026-11-07T10:15:00.000Z"
}

get/v1/products/{id}Szczegóły produktuproducts:read

Wymagane uprawnienie: products:read

Parametry

idw adresie · uuidwymagane

Przykładowe wywołanie

curl "https://api.cornvilla.com/v1/products/<id>" \
  -H "Authorization: Bearer $TOKEN"

Odpowiedź 200 — pola

iduuid
skustring
eanstring | null
namestring
unitstring
activeboolean
stocklessboolean
Nie trzymany na magazynie (zamawiany pod zamówienie).
kind"product" | "bundle"
categorystring | null
brandstring | null
weightKgnumber | null
lengthMminteger | null
widthMminteger | null
heightMminteger | null
imageUrlstring | null
vatRateinteger | null
Stawka VAT w procentach; null = nie ustawiono.
locationsstring[]
Kody lokacji, w których produkt jest przypisany (główna pierwsza).
stockinteger
Łączny stan (sztuki).
stockUnplacedinteger
Część stanu w strefie przyjęć (do rozłożenia).
externalRefsobject[]
ID produktu w podłączonych sklepach.
- sourceNamestring
- externalIdstring
createdAtdata ISO 8601
updatedAtdata ISO 8601

Odpowiedź 200 — przykład

{
  "id": "3f2a9c1e-5b7d-4e8a-9c2b-1d4e6f8a0b2c",
  "sku": "…",
  "ean": "…",
  "name": "…",
  "unit": "…",
  "active": true,
  "stockless": true,
  "kind": "product",
  "category": "…",
  "brand": "…",
  "weightKg": 1,
  "lengthMm": 1,
  "widthMm": 1,
  "heightMm": 1,
  "imageUrl": "…",
  "vatRate": 1,
  "locations": [
    "…"
  ],
  "stock": 1,
  "stockUnplaced": 1,
  "externalRefs": [
    {
      "sourceName": "…",
      "externalId": "…"
    }
  ],
  "createdAt": "2026-11-07T10:15:00.000Z",
  "updatedAt": "2026-11-07T10:15:00.000Z"
}

patch/v1/products/{id}Zmień produktproducts:write

Tylko przekazane pola; null czyści pole.

Wymagane uprawnienie: products:write

Parametry

idw adresie · uuidwymagane

Treść żądania (JSON)

skustring
namestring
eanstring | null
unitstring
weightKgnumber | null
lengthMminteger | null
widthMminteger | null
heightMminteger | null
categorystring | null
brandstring | null
imageUrlstring | null
activeboolean
stocklessboolean

Przykładowe wywołanie

curl -X PATCH "https://api.cornvilla.com/v1/products/<id>" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"sku":"…","name":"…","ean":"…","unit":"…","weightKg":0,"lengthMm":1,"widthMm":1,"heightMm":1,"category":"…","brand":"…","imageUrl":"…","active":true,"stockless":true}'

Odpowiedź 200 — pola

iduuid
skustring
eanstring | null
namestring
unitstring
activeboolean
stocklessboolean
Nie trzymany na magazynie (zamawiany pod zamówienie).
kind"product" | "bundle"
categorystring | null
brandstring | null
weightKgnumber | null
lengthMminteger | null
widthMminteger | null
heightMminteger | null
imageUrlstring | null
vatRateinteger | null
Stawka VAT w procentach; null = nie ustawiono.
locationsstring[]
Kody lokacji, w których produkt jest przypisany (główna pierwsza).
stockinteger
Łączny stan (sztuki).
stockUnplacedinteger
Część stanu w strefie przyjęć (do rozłożenia).
externalRefsobject[]
ID produktu w podłączonych sklepach.
- sourceNamestring
- externalIdstring
createdAtdata ISO 8601
updatedAtdata ISO 8601

Odpowiedź 200 — przykład

{
  "id": "3f2a9c1e-5b7d-4e8a-9c2b-1d4e6f8a0b2c",
  "sku": "…",
  "ean": "…",
  "name": "…",
  "unit": "…",
  "active": true,
  "stockless": true,
  "kind": "product",
  "category": "…",
  "brand": "…",
  "weightKg": 1,
  "lengthMm": 1,
  "widthMm": 1,
  "heightMm": 1,
  "imageUrl": "…",
  "vatRate": 1,
  "locations": [
    "…"
  ],
  "stock": 1,
  "stockUnplaced": 1,
  "externalRefs": [
    {
      "sourceName": "…",
      "externalId": "…"
    }
  ],
  "createdAt": "2026-11-07T10:15:00.000Z",
  "updatedAt": "2026-11-07T10:15:00.000Z"
}

Stany

2Stan produktów na lokacjach i korekty.

get/v1/stockStany na lokacjachstock:read

Produkt × lokacja (tylko niezerowe) w bieżącym magazynie. Bez filtrów — wszystko; productId/sku albo locationId zawężają.

Wymagane uprawnienie: stock:read

Parametry

productIdw zapytaniu · uuid
skuw zapytaniu · string
locationIdw zapytaniu · uuid

Przykładowe wywołanie

curl "https://api.cornvilla.com/v1/stock?productId=…&sku=…" \
  -H "Authorization: Bearer $TOKEN"

Odpowiedź 200 — pola

itemsobject[]
- productIduuid
- skustring
- eanstring | null
- namestring
- locationIduuid
- locationCodestring
- locationTypestring
  storage · receiving (strefa przyjęć) · quarantine · staging
- quantityinteger
- isPrimaryboolean
  Główne miejsce kompletacji produktu.

Odpowiedź 200 — przykład

{
  "items": [
    {
      "productId": "3f2a9c1e-5b7d-4e8a-9c2b-1d4e6f8a0b2c",
      "sku": "…",
      "ean": "…",
      "name": "…",
      "locationId": "3f2a9c1e-5b7d-4e8a-9c2b-1d4e6f8a0b2c",
      "locationCode": "…",
      "locationType": "…",
      "quantity": 1,
      "isPrimary": true
    }
  ]
}

post/v1/stock/adjustKorekta stanu na lokacjistock:write

Podajesz stan docelowy (policzoną ilość); Cornvilla zapisuje ruch „korekta” o różnicę. Pierwsze miejsce, na które trafi produkt, staje się jego głównym miejscem kompletacji.

Wymagane uprawnienie: stock:write

Treść żądania (JSON)

productIduuid
skustring
Zamiast productId.
locationIduuid
locationCodestring
Zamiast locationId, np. „A1B003”.
quantityintegerwymagane
Stan docelowy (policzona ilość) — Cornvilla sama wyliczy różnicę.
notestring

Przykładowe wywołanie

curl -X POST "https://api.cornvilla.com/v1/stock/adjust" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"productId":"3f2a9c1e-5b7d-4e8a-9c2b-1d4e6f8a0b2c","sku":"…","locationId":"3f2a9c1e-5b7d-4e8a-9c2b-1d4e6f8a0b2c","locationCode":"…","quantity":0,"note":"…"}'

Odpowiedź 200 — pola

locationCodestring
beforeinteger
afterinteger
deltainteger

Odpowiedź 200 — przykład

{
  "locationCode": "…",
  "before": 1,
  "after": 1,
  "delta": 1
}

Przesyłki

2Odbiorca, przewoźnik, numer przesyłki i plik etykiety.

get/v1/orders/{id}/shipmentWysyłka zamówienia: odbiorca, przewoźnik, etykieta i numer przesyłkishipments:read

Wymagane uprawnienie: shipments:read

Parametry

idw adresie · uuidwymagane

Przykładowe wywołanie

curl "https://api.cornvilla.com/v1/orders/<id>/shipment" \
  -H "Authorization: Bearer $TOKEN"

Odpowiedź 200 — pola

orderIduuid
orderNumberstring
orderStatusstring
carrierobject
Przewoźnik dobrany do sposobu dostawy.
- idstring
- namestring
pickupPointstring | null
recipientobject | null
null = zamówienie bez adresu dostawy (albo dane usunięte po okresie przechowywania).
- namestring
- companystring | null
- streetstring
- houseNumberstring | null
- apartmentNumberstring | null
- postalCodestring
- citystring
- countrystring
- phonestring | null
- emailstring | null
labelobject | null
- statusstring
  pending · generated · failed
- trackingNumberstring | null
- generatedAtdata ISO 8601 | null
- printedAtdata ISO 8601 | null
- errorstring | null
- hasFileboolean
  Plik etykiety do pobrania: GET /v1/orders/{id}/label

Odpowiedź 200 — przykład

{
  "orderId": "3f2a9c1e-5b7d-4e8a-9c2b-1d4e6f8a0b2c",
  "orderNumber": "…",
  "orderStatus": "…",
  "carrier": {
    "id": "…",
    "name": "…"
  },
  "pickupPoint": "…",
  "recipient": {
    "name": "…",
    "company": "…",
    "street": "…",
    "houseNumber": "…",
    "apartmentNumber": "…",
    "postalCode": "…",
    "city": "…",
    "country": "…",
    "phone": "…",
    "email": "…"
  },
  "label": {
    "status": "…",
    "trackingNumber": "…",
    "generatedAt": "2026-11-07T10:15:00.000Z",
    "printedAt": "2026-11-07T10:15:00.000Z",
    "error": "…",
    "hasFile": true
  }
}

get/v1/orders/{id}/labelPlik etykiety (PDF)shipments:read

Odpowiedź: plik application/pdf. Dostępny, gdy label.status = generated (inaczej 409). Przewoźnik testowy zwraca etykietę testową.

Wymagane uprawnienie: shipments:read

Parametry

idw adresie · uuidwymagane

Przykładowe wywołanie

curl "https://api.cornvilla.com/v1/orders/<id>/label" \
  -H "Authorization: Bearer $TOKEN"

Odpowiedź

Plik (np. PDF) albo pusta treść — zobacz opis.

Zwroty

1Zwroty zamówień.

get/v1/returnsLista zwrotów (otwarte pierwsze)returns:read

Wymagane uprawnienie: returns:read

Parametry

statusw zapytaniu · "open" | "done" | "cancelled" | "all"domyślnie "all"
orderIdw zapytaniu · uuid

Przykładowe wywołanie

curl "https://api.cornvilla.com/v1/returns?status=all&orderId=…" \
  -H "Authorization: Bearer $TOKEN"

Odpowiedź 200 — pola

itemsobject[]
- iduuid
- orderIduuid
- orderNumberstring
- statusstring
  open · done · cancelled
- reasonstring | null
- notestring | null
- createdAtdata ISO 8601
- finishedAtdata ISO 8601 | null
- lineCountinteger
  Ile pozycji już przyjęto.

Odpowiedź 200 — przykład

{
  "items": [
    {
      "id": "3f2a9c1e-5b7d-4e8a-9c2b-1d4e6f8a0b2c",
      "orderId": "3f2a9c1e-5b7d-4e8a-9c2b-1d4e6f8a0b2c",
      "orderNumber": "…",
      "status": "…",
      "reason": "…",
      "note": "…",
      "createdAt": "2026-11-07T10:15:00.000Z",
      "finishedAt": "2026-11-07T10:15:00.000Z",
      "lineCount": 1
    }
  ]
}

Magazyn

2Magazyny i lokacje.

get/v1/warehousesMagazyny firmy (główny pierwszy)warehouse:read

Id magazynu przekażesz w nagłówku X-Warehouse, żeby inne wywołania dotyczyły tego magazynu.

Wymagane uprawnienie: warehouse:read

Przykładowe wywołanie

curl "https://api.cornvilla.com/v1/warehouses" \
  -H "Authorization: Bearer $TOKEN"

Odpowiedź 200 — pola

itemsobject[]
- iduuid
- codestring
- namestring
- isMainboolean
- activeboolean

Odpowiedź 200 — przykład

{
  "items": [
    {
      "id": "3f2a9c1e-5b7d-4e8a-9c2b-1d4e6f8a0b2c",
      "code": "…",
      "name": "…",
      "isMain": true,
      "active": true
    }
  ]
}

get/v1/locationsLokacje bieżącego magazynu w kolejności trasy kompletacjiwarehouse:read

Wymagane uprawnienie: warehouse:read

Przykładowe wywołanie

curl "https://api.cornvilla.com/v1/locations" \
  -H "Authorization: Bearer $TOKEN"

Odpowiedź 200 — pola

itemsobject[]
- iduuid
- codestring
- typestring
  storage · receiving · quarantine · staging
- rackCodestring | null
- zonestring | null
- levelstring | null
- positionstring | null
- activeboolean
- productCountinteger
- unitsinteger

Odpowiedź 200 — przykład

{
  "items": [
    {
      "id": "3f2a9c1e-5b7d-4e8a-9c2b-1d4e6f8a0b2c",
      "code": "…",
      "type": "…",
      "rackCode": "…",
      "zone": "…",
      "level": "…",
      "position": "…",
      "active": true,
      "productCount": 1,
      "units": 1
    }
  ]
}