Dokumentacja REST API systemu Imker

Wprowadzenie

API Imker SalesCRM umożliwia integrację Twojego systemu ze sklepem. Możesz zarządzać produktami i kodami rabatowymi (tworzenie, edycja, usuwanie) oraz przeglądać i aktualizować zamówienia.

Base URL

https://{your-subdomain}.salescrm.pl/api/v1/

Właściciel sklepu może w dowolnym momencie wyłączyć dostęp do API w panelu administracyjnym (Integracje → API). Po wyłączeniu wszystkie żądania będą zwracać błąd 401 Unauthorized.

Autoryzacja

Wszystkie żądania wymagają nagłówka X-API-KEY. Klucz API wygenerujesz w panelu admina: Integracje → API.

Przykład

curl -H "X-API-KEY: your-api-key" \
  https://your-shop.salescrm.pl/api/v1/products

Format odpowiedzi

Wszystkie odpowiedzi są w formacie JSON. Pomyślne odpowiedzi zawierają pole data, listy dodatkowo meta z paginacją.

Lista (sukces)

{
  "data": [...],
  "meta": {
    "page": 1,
    "per_page": 25,
    "total": 100,
    "total_pages": 4
  }
}

Błąd walidacji

{
  "error": "Unprocessable Entity",
  "errors": {
    "name": ["can't be blank"]
  }
}

Paginacja

Parameter	Type	Opis
`page`	integer	Numer strony (domyślnie 1)
`per_page`	integer	Elementów na stronę (domyślnie 25, max 100)

Rate Limiting

Typ	Limit	Opis
Ogólny	100 req/min	Wszystkie endpointy
Mutacje	30 req/min	POST, PATCH, DELETE

Po przekroczeniu limitu otrzymasz odpowiedź 429 Too Many Requests z nagłówkiem Retry-After.

Produkty

GET /api/v1/products

Lista produktów z paginacją.

Parametry

Parameter	Type	Wymagany	Opis
`active`	string	Nie	"true" / "false"
`category_id`	integer	Nie	ID kategorii produktu
`search`	string	Nie	Szukaj po nazwie lub SKU
`page`	integer	Nie	Numer strony
`per_page`	integer	Nie	Elementów na stronę (max 100)

Przykład odpowiedzi

{
  "data": [
    {
      "id": 1,
      "name": "E-book: Marketing",
      "sku": "EBOOK1",
      "price": "49.99",
      "vat_rate": 23,
      "active": true,
      "electronic": true,
      "distribution": "normal",
      "description": "<p>Opis produktu...</p>",
      "description_for_cart": "Krótki opis w koszyku",
      "category": "E-booki",
      "category_id": 5,
      "ean": null,
      "producer": "Imker",
      "invoice_item_name": "E-book Marketing",
      "pkwiu": null,
      "product_link": "https://example.com/product",
      "gtu_code": null,
      "regular_price_displayed": "69.99",
      "allow_price_change": false,
      "minimal_price": null,
      "allow_zero_minimal_price": false,
      "delivery_type_ids": [1, 3],
      "payment_type_ids": [2, 5],
      "cart_quantity_limit": null,
      "hide_in_xmls": false,
      "no_invoice": false,
      "hide_invoice_address_fields": false,
      "payment_return_url": null,
      "created_at": "2026-01-15T10:30:00Z",
      "updated_at": "2026-02-20T14:15:00Z"
    }
  ],
  "meta": { "page": 1, "per_page": 25, "total": 1, "total_pages": 1 }
}

GET /api/v1/products/:id

Szczegóły pojedynczego produktu.

curl

curl -H "X-API-KEY: your-key" \
  https://your-shop.salescrm.pl/api/v1/products/1

POST /api/v1/products

Tworzenie nowego produktu.

Parametry

Parameter	Type	Wymagany	Opis
`name`	string	Tak	Nazwa produktu
`price`	string	Tak	Cena brutto
`sku`	string	Nie	SKU
`vat_rate`	string	Nie	Stawka VAT (np. "23")
`active`	boolean	Nie	Czy aktywny
`description`	string	Nie	Opis produktu (HTML)
`description_for_cart`	string	Nie	Opis wyświetlany w koszyku
`electronic_product`	boolean	Nie	Produkt elektroniczny
`distribution`	string	Nie	normal, audio, video, webinar, course
`producer`	string	Nie	Producent
`ean`	string	Nie	Kod EAN (13 cyfr)
`invoice_item_name`	string	Nie	Nazwa na fakturze
`pkwiu`	string	Nie	PKWiU
`product_link`	string	Nie	Link do produktu (URL)
`gtu_code`	string	Nie	Kod GTU (GTU_01-GTU_13)
`regular_price_displayed`	string	Nie	Cena regularna (przekreślona)
`allow_price_change`	boolean	Nie	Klient może zmienić cenę
`minimal_price`	string	Nie	Minimalna cena (gdy allow_price_change)
`allow_zero_minimal_price`	boolean	Nie	Czy cena minimalna może być 0
`delivery_type_ids`	array	Nie	ID metod dostawy
`payment_type_ids`	array	Nie	ID metod płatności
`product_category_id`	integer	Nie	ID kategorii produktu
`cart_quantity_limit`	integer	Nie	Limit ilości w koszyku
`hide_in_xmls`	boolean	Nie	Ukryj w plikach XML
`no_invoice`	boolean	Nie	Nie generuj faktury
`hide_invoice_address_fields`	boolean	Nie	Ukryj pola adresu na fakturze
`payment_return_url`	string	Nie	URL powrotu po płatności

curl

curl -X POST \
  -H "X-API-KEY: your-key" \
  -H "Content-Type: application/json" \
  -d '{"name":"New Product","price":"49.99","vat_rate":"23","active":true}' \
  https://your-shop.salescrm.pl/api/v1/products

PATCH /api/v1/products/:id

Aktualizacja produktu. Wysyłasz tylko zmienione pola.

curl

curl -X PATCH \
  -H "X-API-KEY: your-key" \
  -H "Content-Type: application/json" \
  -d '{"price":"59.99","active":false}' \
  https://your-shop.salescrm.pl/api/v1/products/1

DELETE /api/v1/products/:id

Usunięcie produktu. Jeśli produkt ma zamówienia, zostanie ukryty zamiast usunięty.

Przykład odpowiedzi (ukryty)

{
  "data": {
    "id": 1,
    "deleted": false,
    "hidden": true,
    "message": "Product has orders and was hidden instead of deleted"
  }
}

Kody rabatowe

GET /api/v1/discount_codes

Lista kodów rabatowych z paginacją i filtrami.

Parametry

Parameter	Type	Wymagany	Opis
`discount_type`	string	Nie	Typ rabatu (percentage_discount, value_discount, free_delivery_discount, free_contents, value_and_free_delivery_discount, percentage_and_free_delivery_discount, value_per_product_discount, value_per_product_and_free_delivery_discount)
`active`	string	Nie	"true" / "false"
`search`	string	Nie	Szukaj po kodzie lub nazwie
`page`	integer	Nie	Numer strony
`per_page`	integer	Nie	Elementów na stronę (max 100)

Przykład odpowiedzi

{
  "data": [
    {
      "id": 1,
      "code": "LATO20",
      "name": "Letnia promocja",
      "discount_type": "percentage_discount",
      "value": "20.0",
      "case_sensitive": false,
      "minimum_amount": "50.0",
      "usages_limit": 100,
      "usages_per_customer_limit": 1,
      "usages": 42,
      "active": true,
      "start_date": "2026-06-01T00:00:00Z",
      "end_date": "2026-08-31T23:59:59Z",
      "combine_with_other_discount": true,
      "relation_with_products": "all_products",
      "product_ids": [],
      "product_category_ids": [],
      "relation_with_delivery_types": "all_delivery_types",
      "delivery_type_ids": [],
      "created_at": "2026-05-15T10:00:00Z",
      "updated_at": "2026-05-15T10:00:00Z"
    }
  ],
  "meta": { "page": 1, "per_page": 25, "total": 1, "total_pages": 1 }
}

GET /api/v1/discount_codes/:id

Szczegóły pojedynczego kodu rabatowego.

curl

curl -H "X-API-KEY: your-key" \
  https://your-shop.salescrm.pl/api/v1/discount_codes/1

POST /api/v1/discount_codes

Tworzenie nowego kodu rabatowego.

Parametry

Parameter	Type	Wymagany	Opis
`code`	string	Tak	Kod rabatowy (unikalny)
`discount_type`	string	Tak	percentage_discount, value_discount, free_delivery_discount, free_contents, value_and_free_delivery_discount, percentage_and_free_delivery_discount, value_per_product_discount, value_per_product_and_free_delivery_discount
`value`	string	Tak*	Wartość rabatu (% lub kwota). *Wymagana dla percentage i value discount
`name`	string	Nie	Nazwa (widoczna tylko w panelu)
`case_sensitive`	boolean	Nie	Wielkość liter ma znaczenie (domyślnie true)
`minimum_amount`	string	Nie	Minimalna kwota zamówienia
`usages_limit`	integer	Nie	Maksymalna liczba użyć
`usages_per_customer_limit`	integer	Nie	Maksymalna liczba użyć na klienta
`start_date`	string	Nie	Data rozpoczęcia (ISO 8601)
`end_date`	string	Nie	Data zakończenia (ISO 8601)
`combine_with_other_discount`	boolean	Nie	Łącz z innymi rabatami (domyślnie true)
`relation_with_products`	string	Nie	all_products, selected_products, products_except, selected_categories, categories_except
`product_ids`	array	Nie	ID produktów
`product_category_ids`	array	Nie	ID kategorii
`relation_with_delivery_types`	string	Nie	domestic_delivery_types_only, all_delivery_types, selected_delivery_types
`delivery_type_ids`	array	Nie	ID metod dostawy

curl

curl -X POST \
  -H "X-API-KEY: your-key" \
  -H "Content-Type: application/json" \
  -d '{"code":"LATO20","discount_type":"percentage_discount","value":"20","usages_limit":100}' \
  https://your-shop.salescrm.pl/api/v1/discount_codes

PATCH /api/v1/discount_codes/:id

Aktualizacja kodu rabatowego. Wysyłasz tylko zmienione pola.

curl

curl -X PATCH \
  -H "X-API-KEY: your-key" \
  -H "Content-Type: application/json" \
  -d '{"value":"25","usages_limit":200}' \
  https://your-shop.salescrm.pl/api/v1/discount_codes/1

DELETE /api/v1/discount_codes/:id

Usunięcie kodu rabatowego.

Zamówienia powiązane z tym kodem zachowują informację o rabacie, ale powiązanie z kodem zostaje usunięte.

Przykład odpowiedzi

{
  "data": {
    "id": 1,
    "deleted": true
  }
}

Zamówienia

GET /api/v1/orders

Lista zamówień z paginacją i filtrami.

Parametry

Parameter	Type	Opis
`status`	integer	ID statusu zamówienia (order_status_id)
`internal_status`	string	placed, canceled, returned
`payment_status`	string	paid / unpaid
`date_from`	string	YYYY-MM-DD
`date_to`	string	YYYY-MM-DD
`customer_email`	string	Email klienta
`search`	string	Szukaj po numerze zamówienia
`product_id`	integer / lista	ID produktu - zwraca tylko zamówienia zawierające ten produkt. Możesz podać kilka ID po przecinku, np. `product_id=12,17,33`.
`sku`	string / lista	SKU produktu - zwraca zamówienia zawierające produkt o tym SKU. Możesz podać kilka SKU po przecinku.

Przykład odpowiedzi

{
  "data": [
    {
      "id": 42,
      "ordinal_number": "2026/03/001",
      "internal_status": "placed",
      "order_status": "Nowe",
      "order_status_id": 1,
      "email": "jan@example.com",
      "total": "149.99",
      "currency": "PLN",
      "paid": true,
      "delivery_method": "Kurier DPD",
      "placed_at": "2026-03-01T14:30:00Z",
      "created_at": "2026-03-01T14:25:00Z",
      "updated_at": "2026-03-01T14:30:00Z"
    }
  ],
  "meta": { "page": 1, "per_page": 25, "total": 1, "total_pages": 1 }
}

GET /api/v1/orders/:id

Szczegóły zamówienia z pozycjami, adresami, kosztami, atrybutami i notatkami.

Pola w odpowiedzi

Pole	Typ	Opis
`order_status_id`	integer	Numeryczny ID statusu zamówienia (użyj do zmiany statusu przez PATCH /orders/:id/status)
`invoice_recipient_name`	string	Dodatkowe informacje na fakturze (np. nazwa odbiorcy, jeśli inny niż nabywca)
`notes`	array	Notatki admina - tablica obiektów z polami `content` (treść) i `created_at` (data dodania)

Przykład odpowiedzi

{
  "data": {
    "id": 42,
    "ordinal_number": "2026/03/001",
    "internal_status": "placed",
    "order_status": "Nowe",
    "order_status_id": 1,
    "email": "jan@example.com",
    "total": "149.99",
    "currency": "PLN",
    "paid": true,
    "delivery_method": "Kurier DPD",
    "placed_at": "2026-03-01T14:30:00Z",
    "products_cost": "129.99",
    "delivery_cost": "15.00",
    "delivery_vat_rate": 23,
    "payment_cost": "5.00",
    "payment_vat_rate": 23,
    "gift_packing_cost": "0.0",
    "total_discount": "0.0",
    "discount_code": "",
    "cash_on_delivery": false,
    "comment": "Proszę o szybką wysyłkę",
    "delivery_point_code": null,
    "tracking_number": "DPD123456",
    "tracking_url": "https://tracktrace.dpd.com.pl/parcelDetails?p1=DPD123456",
    "items": [
      {
        "id": 101,
        "product_id": 1,
        "name": "E-book: Marketing",
        "sku": "EBOOK1",
        "quantity": 1,
        "unit_price": "49.99",
        "vat_rate": 23,
        "price": "49.99",
        "discount": "0.0",
        "final_price": "49.99"
      }
    ],
    "delivery_address": {
      "first_name": "Jan",
      "last_name": "Kowalski",
      "company": null,
      "nip": null,
      "address": "ul. Główna 1",
      "postcode": "00-001",
      "city": "Warszawa",
      "country": "PL",
      "phone": "+48123456789",
      "email": "jan@example.com"
    },
    "invoice_address": {
      "first_name": "Jan",
      "last_name": "Kowalski",
      "company": "Firma Sp. z o.o.",
      "nip": "1234567890",
      "address": "ul. Firmowa 10",
      "postcode": "00-002",
      "city": "Warszawa",
      "country": "PL",
      "phone": "+48123456789",
      "email": "jan@example.com"
    },
    "invoice_recipient_name": "Szkoła Podstawowa nr 1",
    "order_attributes": [
      { "name": "Dedykacja", "value": "Dla Ani" }
    ],
    "notes": [
      { "content": "Klient prosił o fakturę z innym adresem", "created_at": "2026-03-01T15:00:00Z" },
      { "content": "Faktura wysłana mailem", "created_at": "2026-03-02T09:30:00Z" }
    ]
  }
}

PATCH /api/v1/orders/:id/status

Zmiana statusu zamówienia.

Parametry

Parameter	Type	Wymagany	Opis
`order_status_id`	integer	Tak	ID nowego statusu

Uwaga: Zmiana statusu wywołuje te same efekty uboczne co w panelu admina (eventy, emaile, webhooki).

curl

curl -X PATCH \
  -H "X-API-KEY: your-key" \
  -H "Content-Type: application/json" \
  -d '{"order_status_id": 5}' \
  https://your-shop.salescrm.pl/api/v1/orders/42/status

PATCH /api/v1/orders/:id/clear

Rozliczenie zamówienia - odpowiednik przycisku "Rozlicz zamówienie" w panelu administracyjnym. Oznacza zamówienie jako opłacone ręcznie i uruchamia cały pipeline automatyzacji.

Co się dzieje po rozliczeniu

Rozliczenie zamówienia to nie tylko zmiana flagi "opłacone". System automatycznie uruchamia następujące procesy (identycznie jak przy kliknięciu "Rozlicz zamówienie" w panelu):

Generowanie faktury - jeśli automatyczne fakturowanie jest włączone, faktura zostanie wygenerowana w podłączonym programie (wFirma, Fakturownia, iFirma, InFakt)
Webhooki - wszystkie skonfigurowane webhooki otrzymają event o rozliczeniu zamówienia
Sekwencje e-mail - automatyczne sekwencje wiadomości powiązane ze statusem "opłacone" zostaną uruchomione
Tagi w narzędziach marketingowych - tagi produktów i zamówienia opłaconego zostaną przypisane w ConvertKit, ActiveCampaign lub MailerLite (jeśli integracja jest aktywna)
Subskrypcje - jeśli zamówienie zawiera produkty subskrypcyjne, subskrypcja zostanie aktywowana
Google Analytics - event purchase zostanie wysłany do GA4

Warunki

Warunek	Odpowiedź
Zamówienie nieopłacone	`200 OK` - zamówienie zostaje rozliczone
Zamówienie już opłacone (automatycznie lub ręcznie)	`422` - "Zamówienie jest już rozliczone"
Zamówienie na kwotę 0 zł	`422` - "Zamówienie na kwotę 0 zł nie wymaga rozliczenia"

Uwaga: Rozliczenie zamówienia jest operacją nieodwracalną przez API. Cofnięcie rozliczenia jest możliwe tylko z poziomu panelu administracyjnego. Upewnij się, że zamówienie faktycznie zostało opłacone zanim wywołasz ten endpoint.

curl

curl -X PATCH \
  -H "X-API-KEY: your-key" \
  https://your-shop.salescrm.pl/api/v1/orders/42/clear

Przykład odpowiedzi (sukces)

{
  "data": {
    "id": 42,
    "ordinal_number": "2026/04/001",
    "internal_status": "placed",
    "order_status": "Nowe",
    "email": "jan@example.com",
    "total": "149.99",
    "currency": "PLN",
    "paid": true,
    "cleared_at": "2026-04-22T10:30:00Z",
    "delivery_method": "Kurier DPD",
    "placed_at": "2026-04-20T14:30:00Z",
    "created_at": "2026-04-20T14:25:00Z",
    "updated_at": "2026-04-22T10:30:00Z"
  }
}

Przykład błędu (już rozliczone)

{
  "error": "Already Cleared",
  "message": "Zamówienie jest już rozliczone."
}

Dane referencyjne

Endpointy referencyjne zwracają listy dostępnych opcji (metody dostawy, płatności, statusy, kategorie). Używaj ich do poznania dostępnych ID przy tworzeniu/aktualizacji produktów i zamówień.

GET /api/v1/reports/sales

Raport sprzedaży: liczba i suma zamówień złożonych w wybranym okresie. Tylko zamówienia ze statusem placed - anulowane (canceled) i zwrócone (returned) są pomijane. Pozwala filtrować po produktach, kliencie i statusie płatności, oraz grupować dane po dniu, tygodniu lub miesiącu (do rysowania wykresów).

Parametry

Parameter	Type	Wymagany	Opis
`date_from`	string	Tak	Data początkowa, YYYY-MM-DD (włącznie)
`date_to`	string	Tak	Data końcowa, YYYY-MM-DD (włącznie). Maksymalny zakres: 1830 dni (~5 lat).
`group_by`	string	Nie	`total` (domyślnie - jedna agregacja), `day`, `week` lub `month`
`product_id`	integer / lista	Nie	ID produktu - filtr po liniach zamówienia. Lista po przecinku.
`sku`	string / lista	Nie	SKU produktu - filtr po liniach zamówienia. Lista po przecinku.
`status`	integer	Nie	ID statusu zamówienia (order_status_id)
`payment_status`	string	Nie	`paid` / `unpaid`
`customer_email`	string	Nie	Email klienta

Przykład: total w miesiącu

GET /api/v1/reports/sales?date_from=2026-04-01&date_to=2026-04-30

{
  "data": {
    "date_from": "2026-04-01",
    "date_to": "2026-04-30",
    "currency": "PLN",
    "total_revenue": "12450.00",
    "orders_count": 187,
    "paid_revenue": "10300.00",
    "paid_orders_count": 154,
    "avg_order_value": "66.58"
  }
}

Przykład: dziennie + filtr po produkcie

GET /api/v1/reports/sales?date_from=2026-04-01&date_to=2026-04-30&group_by=day&product_id=42

{
  "data": {
    "date_from": "2026-04-01",
    "date_to": "2026-04-30",
    "currency": "PLN",
    "total_revenue": "3200.00",
    "orders_count": 64,
    "paid_revenue": "2950.00",
    "paid_orders_count": 59,
    "avg_order_value": "50.00",
    "buckets": [
      { "date": "2026-04-01", "orders_count": 3, "total_revenue": "150.00" },
      { "date": "2026-04-02", "orders_count": 5, "total_revenue": "275.00" }
    ]
  }
}

GET /api/v1/reports/payments

Raport płatności: liczba i suma zamówień opłaconych w wybranym okresie z rozbiciem na metody płatności. Akceptuje te same filtry co /reports/sales.

Parametry

Parameter	Type	Wymagany	Opis
`date_from`	string	Tak	Data początkowa, YYYY-MM-DD
`date_to`	string	Tak	Data końcowa, YYYY-MM-DD. Maks. zakres 1830 dni (~5 lat).
`group_by`	string	Nie	`total`, `day`, `week` lub `month`
`product_id` / `sku`	integer / string	Nie	Filtr po linii zamówienia (lista po przecinku)
`customer_email`	string	Nie	Email klienta

Przykład odpowiedzi

{
  "data": {
    "date_from": "2026-04-01",
    "date_to": "2026-04-30",
    "currency": "PLN",
    "total_paid": "10300.00",
    "count": 154,
    "by_payment_type": [
      { "payment_type": "Tpay - BLIK", "count": 92, "amount": "5800.00" },
      { "payment_type": "Tpay - karta", "count": 41, "amount": "3200.00" },
      { "payment_type": "Pobranie", "count": 21, "amount": "1300.00" }
    ]
  }
}

GET /api/v1/delivery_types

Lista aktywnych metod dostawy.

Przykład odpowiedzi

{
  "data": [
    {
      "id": 1,
      "name": "InPost Kurier",
      "name_displayed": "Kurier InPost",
      "default_price": "14.99",
      "vat_rate": 23
    }
  ]
}

GET /api/v1/payment_types

Lista aktywnych metod płatności.

Przykład odpowiedzi

{
  "data": [
    {
      "id": 3,
      "name": "Tpay",
      "name_displayed": "Przelew online",
      "default_price": "0.0",
      "vat_rate": 23,
      "cash_on_delivery": false
    }
  ]
}

GET /api/v1/order_statuses

Lista widocznych statusów zamówień. Użyj ID przy zmianie statusu zamówienia.

Przykład odpowiedzi

{
  "data": [
    { "id": 1, "name": "Nowe" },
    { "id": 2, "name": "W realizacji" },
    { "id": 3, "name": "Wysłane" }
  ]
}

GET /api/v1/product_categories

Lista kategorii produktów. Struktura drzewiasta - parent_id wskazuje na kategorię nadrzędną.

Przykład odpowiedzi

{
  "data": [
    { "id": 5, "name": "Elektronika", "parent_id": null },
    { "id": 12, "name": "Smartfony", "parent_id": 5 }
  ]
}

Referencja

Kody błędów

Kod	Opis
`400`	Brak wymaganych parametrów
`401`	Brak lub nieprawidłowy klucz API
`404`	Zasób nie znaleziony
`415`	Content-Type musi być application/json
`422`	Błąd walidacji (szczegóły w polu errors)
`429`	Przekroczono limit requestów
`500`	Wewnętrzny błąd serwera

Dokumentacja REST API systemu Imker

Wprowadzenie

Autoryzacja

Format odpowiedzi

Rate Limiting

Parametry

Parametry

Parametry

Parametry

Parametry

Pola w odpowiedzi

Parametry

Co się dzieje po rozliczeniu

Warunki

Parametry

Parametry

Kody błędów

Twoi klienci czekają.
Zacznij sprzedawać już teraz!

Co chcesz sprzedawać?

Nasze rozwiązania

Materiały

Akademie

Narzędzia

Firma

Dokumentacja REST API systemu Imker

Wprowadzenie

Autoryzacja

Format odpowiedzi

Paginacja

Rate Limiting

Parametry

Parametry

Parametry

Parametry

Parametry

Pola w odpowiedzi

Parametry

Co się dzieje po rozliczeniu

Warunki

Parametry

Parametry

Kody błędów

Twoi klienci czekają.Zacznij sprzedawać już teraz!

Co chcesz sprzedawać?

Nasze rozwiązania

Materiały

Akademie

Narzędzia

Firma

Twoi klienci czekają.
Zacznij sprzedawać już teraz!