Integracja

Dokumentacja API Firmatec v1.1

Integracja z systemem Faktura iBiznes. Każdy endpoint ma ten sam układ: opis, nagłówki, parametry, body, błędy i przykład.

X-FTToken F-service: firmatec_api

Wymagane nagłówki

Przy każdym wywołaniu potrzebne są te nagłówki:

NagłówekWymaganyDomyślneOpis
X-FTToken tak — Token firmy
F-service tak — firmatec_api
Accept nie application/json Format odpowiedzi. Dla faktury mogą być też zwrócone application/pdf albo text/html. Dla zamówienia może być też zwrócone application/xml.
Accept-Language nie — pl albo en - język komunikatów błędów
Content-Type zależnie od zapisu — Przy zapisie JSON: application/json. Przy wczytaniu XML: application/xml, text/xml albo multipart/form-data.

Błędy wracają jako JSON. W opisie każdego endpointu te same nagłówki są powtórzone w tabeli Nagłówki.

Wprowadzenie

Przez to API mogą być pobierane i zapisywane faktury, zamówienia, formy płatności i karty klientów firmy oraz stany magazynowe. Faktury i zamówienia mogą być wczytane z pliku XML programu Faktura iBiznes albo z JSON.

Adres bazowy API:

https://api.firmatec.pl/api/firmatec

Każdy endpoint ma ten sam układ: opis, nagłówki, parametry ścieżki, parametry query, body, kody błędów, przykład odpowiedzi i przykład cURL. Blok jest pomijany, gdy dany endpoint go nie ma.

Token i usługa

Token firmy (X-FTToken)

Token należy do jednej firmy i daje dostęp tylko do jej faktur, zamówień, form płatności, kartoteki klientów i stanów magazynowych.

Token generuje się i zmienia samodzielnie na stronie API w Centrum konfiguracji.

Usługa integracji

Do API potrzebna jest aktywna usługa Serwis integracji z oprogramowaniem Firmatec (firmatec_api).

Usługę można kupić i przedłużyć samodzielnie na tej samej stronie: https://wconfig.firmatec.pl/services/firmatec-api.

Pytania i zgłoszenia: www@firmatec.pl.

Faktury

GET /invoice

Lista faktur

X-FTToken + F-service

Zwraca listę dokumentów, które nie zostały anulowane.
Wynik jest podzielony na strony. Nieznany type jest traktowany jak VAT. Dla WZ, PW, RW i PZ lista pochodzi z tabeli dokumentów magazynowych (dok).

Nagłówki4
NagłówekWymaganyDomyślneOpis
X-FTToken tak — Token firmy
F-service tak — firmatec_api
Accept nie application/json Format odpowiedzi JSON.
Accept-Language nie — pl albo en - język komunikatów błędów
Parametry query7
ParametrTypWymaganyDomyślneOpis
type string nie VAT Rodzaj: VAT, PAR, WZ, PW, RW albo PZ.
perpage int nie 10 Liczba rekordów na stronę. Najwyżej 200.
page int nie 1 Numer strony.
date_from string nie — Data wystawienia od, np. 2026-01-01.
date_to string nie — Data wystawienia do, np. 2026-01-31.
sort_by string nie DWy Pole sortowania: id, DWy (data wystawienia) albo amount (kwota).
sort_direction string nie DESC ASC - rosnąco, DESC - malejąco.

Kody błędów

HTTPOpis
403 Brak dostępu. Usługę kupuje się i przedłuża na stronie API w Centrum konfiguracji.
404 Nieprawidłowy token. Token generuje się i zmienia na stronie API w Centrum konfiguracji.

Przykład odpowiedzi

HTTP 200
{
  "current_page": 1,
  "data": [ { "ID": "F.RRMMDD.GGMMSS.XXXXXX", "NrR": "FV/N/RRRR/MM" } ],
  "per_page": 10,
  "total": 1
}

Przykład cURL

curl -s '{base_url}/invoice?type=VAT&page=1&perpage=10' \
  -H 'X-FTToken: TWOJ-TOKEN' \
  -H 'F-service: firmatec_api' \
  -H 'Accept: application/json' \
  -H 'Accept-Language: pl'

# Dokumenty magazynowe PZ:
curl -s '{base_url}/invoice?type=PZ&page=1&perpage=10' \
  -H 'X-FTToken: TWOJ-TOKEN' \
  -H 'F-service: firmatec_api' \
  -H 'Accept: application/json'
GET /invoice/{id}

Szczegóły faktury

X-FTToken + F-service

Pobiera jeden dokument (fakturę albo dok magazynowy WZ/PW/RW/PZ), także anulowany.
Format jest wybierany nagłówkiem Accept: JSON (nagłówek i pozycje w spec), PDF albo podgląd HTML. PDF i HTML mają układ wydruku Krajowego Systemu e-Faktur, strona A4.

Nagłówki4
NagłówekWymaganyDomyślneOpis
X-FTToken tak — Token firmy
F-service tak — firmatec_api
Accept nie application/json application/json, application/pdf albo text/html.
Accept-Language nie — pl albo en - język komunikatów błędów

Parametry ścieżki

ParametrTypWymaganyDomyślneOpis
id string tak — Identyfikator faktury z listy albo z zapisu, np. F.RRMMDD.GGMMSS.XXXXXX.

Kody błędów

HTTPOpis
403 Brak dostępu. Usługę kupuje się i przedłuża na stronie API w Centrum konfiguracji.
404 Nie znaleziono faktury albo token jest nieprawidłowy

Przykład odpowiedzi

HTTP 200
Accept: application/json
{ "data": { "ID": "F.RRMMDD.GGMMSS.XXXXXX", "NrR": "FV/N/RRRR/MM", "spec": [] } }

Accept: application/pdf  - plik PDF (A4)
Accept: text/html        - HTML (ta sama wizualizacja)
Przykład cURL 
# JSON
curl -s '{base_url}/invoice/F.RRMMDD.GGMMSS.XXXXXX' \
  -H 'X-FTToken: TWOJ-TOKEN' \
  -H 'F-service: firmatec_api' \
  -H 'Accept: application/json' \
  -H 'Accept-Language: pl'

# PDF
curl -s '{base_url}/invoice/F.RRMMDD.GGMMSS.XXXXXX' \
  -H 'X-FTToken: TWOJ-TOKEN' \
  -H 'F-service: firmatec_api' \
  -H 'Accept: application/pdf' \
  -H 'Accept-Language: pl' \
  -o faktura.pdf
POST /invoice

Zapis faktury / dokumentu magazynowego (XML / JSON)

X-FTToken + F-service

Wczytuje fakturę z pliku XML programu Faktura iBiznes albo z JSON.
Przy JSON bez use_provided_document numer nadaje numeracja firmy (w Centrum konfiguracji: Numerowanie).
Gdy ID i numer mają pochodzić z żądania — use_provided_document: true oraz kompletny obiekt document (wszystkie pola wymagane; przykład poniżej).

Dokumenty magazynowe (kind): wz, pw, rw, pz — zapis w tabeli dok. pw/pz zwiększają stan, wz/rw zmniejszają. pz wymaga buyer.name.

Nagłówki5
NagłówekWymaganyDomyślneOpis
X-FTToken tak — Token firmy
F-service tak — firmatec_api
Accept nie application/json Format odpowiedzi JSON.
Content-Type nie — application/xml, text/xml, application/json albo multipart/form-data
Accept-Language nie — pl albo en - język komunikatów błędów
Body (JSON)74
PoleTypWymaganyDomyślneOpis
kind string nie vat Rodzaj: vat, proforma, zaliczkowa, koncowa, korygujaca, rachunek, paragon, marza, wdt, zakup, wz, pw, rw, pz. Dokumenty magazynowe (wz/pw/rw/pz) zapisują się w tabeli dok. PZ wymaga dostawcy (buyer.name) i zwiększa stan magazynowy.
typ string nie — Nadpisanie typu dokumentu. Puste zostawia typ wynikający z kind.
issue_date string nie — Data wystawienia, RRRR-MM-DD. Pusta oznacza datę bieżącą.
sale_date string nie issue_date Data sprzedaży, RRRR-MM-DD.
due_date string nie issue_date Termin płatności, RRRR-MM-DD.
issue_time string nie — Godzina wystawienia. Pusta oznacza brak osobnej godziny.
payment_method string nie pusta Nazwa formy płatności z GET /payment.
payment_days int nie 0 Liczba dni.
currency string nie PLN Waluta.
kurs number nie 1 Kurs waluty. (dla PLN).
price_mode string nie net net albo gross.
paid number nie 0 Kwota zapłacona.
paid_date string nie — Data zapłaty, RRRR-MM-DD. Pusta oznacza brak daty, dopóki faktura nie jest opłacona w całości.
notes string nie pusta Notatka.
operator string nie api Alias operatora.
issuer string nie operator Wystawiający.
prefer_invoice_number string nie — Proponowany numer kolejny, gdy numer nadaje system. Ignorowane przy use_provided_document.
ksef string nie pusty Numer KSeF.
ksef_mode string nie pusty Tryb wystawienia KSeF.
exemption_basis string nie — Podstawa zwolnienia z VAT. Używana, gdy pozycja ma vat zw.
te string nie puste Dodatkowe tagi nagłówka.
include_bank bool nie false. Przelew dopisuje rachunek także bez tego pola true dopisuje rachunek bankowy.
bank_id string nie — Identyfikator rachunku z ustawień firmy. Pusty oznacza rachunek domyślny, gdy rachunek jest dopisywany.
bank_name string nie — Nazwa banku, gdy nie ma bank_id.
bank_account string nie — Numer rachunku, gdy nie ma bank_id.
use_provided_document bool nie false true — numer i ID pochodzą z obiektu document (system nie nadaje kolejnego numeru). false — numeracja firmy.
document.id string nie — Unikalny ID w bazie (klucz główny). Format przykładowy: F.RRMMDD.GGMMSS.XXXXXX. Wymagany przy use_provided_document=true.
document.typ string nie — Typ dokumentu zapisany w nagłówku (np. VAT). Pusty = typ z kind / typ.
document.nr int nie — Numer kolejny w rejestrze (liczba > 0). Wymagany przy use_provided_document=true.
document.rej string nie — Symbol rejestru numeracji (np. FV). Wymagany przy use_provided_document=true.
document.rok string nie — Rok numeru, cztery cyfry (RRRR). Wymagany przy use_provided_document=true.
document.mc string nie — Miesiąc numeru, dwie cyfry (MM). Wymagany przy use_provided_document=true.
document.nrr string nie — Pełny numer widoczny na dokumencie (zgodny z szablonem firmy), np. FV/N/RRRR/MM. Wymagany przy use_provided_document=true.
advance_gross number nie — Kwota zaliczki brutto. Wymagana, gdy kind to zaliczkowa.
advance_received_date string nie — Data otrzymania zaliczki, RRRR-MM-DD. Przy kind zaliczkowa pusta oznacza datę wystawienia.
source_invoice_id string nie — Identyfikator faktury źródłowej przy rozliczeniu zaliczki.
buyer.id string nie — ID klienta. Puste oznacza brak powiązania z kartą.
buyer.name string nie — Nazwa nabywcy.
buyer.name2 string nie — Druga linia nazwy nabywcy.
buyer.alias string nie — Alias nabywcy.
buyer.tax_id string nie — NIP nabywcy.
buyer.regon string nie — REGON nabywcy.
buyer.country_code string nie — Prefiks NIP nabywcy.
buyer.address string nie — Ulica nabywcy.
buyer.postal_code string nie — Kod pocztowy nabywcy.
buyer.city string nie — Miasto nabywcy.
buyer.email string nie — E-mail nabywcy.
buyer.phone string nie — Telefon nabywcy.
buyer.gv string nie — Grupa VAT nabywcy.
has_recipient bool nie false true zapisuje odbiorcę z recipient.
recipient.alias string nie — Alias odbiorcy. Używany, gdy has_recipient jest true.
recipient.name string nie — Nazwa odbiorcy.
recipient.tax_id string nie — NIP odbiorcy.
recipient.address string nie — Ulica odbiorcy.
recipient.postal_code string nie — Kod pocztowy odbiorcy.
recipient.city string nie — Miasto odbiorcy.
recipient.country_code string nie — Prefiks NIP odbiorcy.
recipient.phone string nie — Telefon odbiorcy. Używany, gdy telefon nabywcy jest pusty.
recipient.rol string nie — Rola odbiorcy.
recipient.idw string nie — Identyfikator wewnętrzny odbiorcy.
items object[] tak — Pozycje. Co najmniej jedna z niepustym name.
items[].name string tak — Nazwa pozycji.
items[].quantity number nie 0 Ilość.
items[].product_code string nie pusty Kod towaru.
items[].product_id string nie pusty Identyfikator towaru.
items[].warehouse string nie 1 Magazyn.
items[].unit string nie szt Jednostka.
items[].price_net number nie 0 Cena netto.
items[].vat string nie 23 Stawka VAT, np. 23, 8, 5, zw, np, oo.
items[].discount_percent number nie 0 Rabat procentowy, od 0 do 100.
items[].line_type string nie T T - towar, U - usługa.
items[].pkw string nie puste PKWiU.
items[].st_vat int nie — Status VAT pozycji. Puste zostawia puste.
items[].ka string nie — Pole KA. Puste zostawia puste.

Jak przesłać żądanie

Sposób transportu body (XML albo JSON) — nie mylić z rodzajem dokumentu (VAT, PZ, WZ…).

SposóbOpis
XML — plik Formularz multipart: pole xml albo file z plikiem eksportu Faktura iBiznes. Content-Type: multipart/form-data.
XML — treść body Całe body to dokument XML. Content-Type: application/xml albo text/xml.
JSON — pola dokumentu Content-Type: application/json. Pola z tabeli Body. Gotowe scenariusze (własny numer, rodzaj dokumentu itd.) — w sekcji „Przykłady żądania” poniżej.
JSON — opakowany XML Content-Type: application/json, gdy klient obsługuje tylko JSON, a dostępny jest już plik XML: {"xml":"<?xml …>…"}. To nadal import XML, nie mapa pól Body.

Przykłady żądania

Faktura VAT — numer z systemu JSON. Numer ID/NrR nadaje numeracja firmy (use_provided_document pominięte lub false). 
{
  "kind": "vat",
  "issue_date": "2026-01-15",
  "buyer": {
    "name": "Nabywca przykładowy",
    "tax_id": "0000000000",
    "city": "Miasto",
    "address": "Ulica 1",
    "postal_code": "00-000"
  },
  "items": [
    { "name": "Pozycja przykładowa", "quantity": 1, "price_net": 100, "vat": "23", "unit": "szt" }
  ]
}
Faktura — własny numer (document) JSON z use_provided_document=true. Wszystkie pola document są wymagane; system nie przydziela kolejnego numeru. Wartości ID/NrR poniżej — placeholdery, nie dane produkcyjne. 
{
  "kind": "vat",
  "use_provided_document": true,
  "issue_date": "2026-01-15",
  "document": {
    "id": "F.RRMMDD.GGMMSS.XXXXXX",
    "typ": "VAT",
    "nr": 1,
    "rej": "FV",
    "rok": "RRRR",
    "mc": "MM",
    "nrr": "FV/N/RRRR/MM"
  },
  "buyer": { "name": "Nabywca przykładowy", "tax_id": "0000000000", "city": "Miasto" },
  "items": [
    { "name": "Pozycja przykładowa", "quantity": 1, "price_net": 100, "vat": "23", "unit": "szt" }
  ]
}
PZ — przyjęcie zewnętrzne JSON, kind=pz. Wymagany dostawca (buyer.name). Zwiększa stan magazynowy. 
{
  "kind": "pz",
  "issue_date": "2026-01-15",
  "buyer": { "name": "Dostawca przykładowy", "tax_id": "0000000000" },
  "items": [
    { "name": "Towar przykładowy", "quantity": 5, "price_net": 12.5, "vat": "23", "warehouse": "1" }
  ]
}
WZ — wydanie zewnętrzne JSON, kind=wz. Zmniejsza stan. Kupujący opcjonalny. 
{
  "kind": "wz",
  "issue_date": "2026-01-15",
  "buyer": { "name": "Odbiorca przykładowy" },
  "items": [
    { "code": "KOD-1", "name": "Towar przykładowy", "quantity": 2, "price_net": 1.5, "vat": "23", "warehouse": "1" }
  ]
}
PW — przyjęcie wewnętrzne JSON, kind=pw. Zwiększa stan (np. inwentaryzacja plus). 
{
  "kind": "pw",
  "issue_date": "2026-01-15",
  "items": [
    { "name": "Towar przykładowy", "quantity": 10, "price_net": 5, "vat": "23", "warehouse": "1" }
  ]
}
RW — rozchód wewnętrzny JSON, kind=rw. Zmniejsza stan. 
{
  "kind": "rw",
  "issue_date": "2026-01-15",
  "items": [
    { "code": "KOD-1", "name": "Towar przykładowy", "quantity": 3, "price_net": 1.5, "vat": "23", "warehouse": "1" }
  ]
}
XML — treść żądania Całe body to plik eksportu Faktura iBiznes. Content-Type: application/xml. 
<?xml version="1.0" encoding="UTF-8"?>
<DOKUMENT>
  <!-- eksport z Faktura iBiznes — sekcje ZAPIS co="faktury" oraz ZAPIS co="spec" -->
</DOKUMENT>

Sekcje XML Firmatec

Opis pól: dokumentacja eksportu XML

SekcjaZnaczenie
ZAPIS co="faktury" Nagłówek faktury (wymagany)
ZAPIS co="spec" Pozycje specyfikacji (wymagane, co najmniej jedna)
Inne sekcje klienci, towary, wystawil - opcjonalne, przy imporcie pomijane

Kody błędów

HTTPOpis
403 Brak dostępu. Usługę kupuje się i przedłuża na stronie API w Centrum konfiguracji.
404 Nieprawidłowy token. Token generuje się i zmienia na stronie API w Centrum konfiguracji.
409 Faktura o podanym ID, numerze NrR albo numerze kolejnym już istnieje
422 Nie da się wczytać dokumentu: brak pozycji, niepełny numer, brak dostawcy przy PZ, nieznany format albo błąd danych
503 Tabela dokumentów (dok) jest niedostępna przy kind wz / pw / rw / pz

Przykład odpowiedzi

HTTP 201
{
  "message": "Faktura zapisana.",
  "data": { "ID": "F.RRMMDD.GGMMSS.XXXXXX", "NrR": "FV/N/RRRR/MM", "spec": [] }
}
Przykład cURL 
curl -s -X POST '{base_url}/invoice' \
  -H 'X-FTToken: TWOJ-TOKEN' \
  -H 'F-service: firmatec_api' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/xml' \
  -H 'Accept-Language: pl' \
  --data-binary @faktura.xml

# Faktura JSON z własnym numerem (use_provided_document):
curl -s -X POST '{base_url}/invoice' \
  -H 'X-FTToken: TWOJ-TOKEN' \
  -H 'F-service: firmatec_api' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
    "kind": "vat",
    "use_provided_document": true,
    "issue_date": "2026-01-15",
    "document": {
      "id": "F.RRMMDD.GGMMSS.XXXXXX",
      "typ": "VAT",
      "nr": 1,
      "rej": "FV",
      "rok": "RRRR",
      "mc": "MM",
      "nrr": "FV/N/RRRR/MM"
    },
    "buyer": { "name": "Nabywca przykładowy", "tax_id": "0000000000", "city": "Miasto" },
    "items": [
      { "name": "Pozycja przykładowa", "quantity": 1, "price_net": 100, "vat": "23", "unit": "szt" }
    ]
  }'

# PZ (JSON):
curl -s -X POST '{base_url}/invoice' \
  -H 'X-FTToken: TWOJ-TOKEN' \
  -H 'F-service: firmatec_api' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
    "kind": "pz",
    "issue_date": "2026-01-15",
    "buyer": { "name": "Dostawca przykładowy", "tax_id": "0000000000" },
    "items": [
      { "name": "Towar przykładowy", "quantity": 5, "price_net": 12.5, "vat": "23", "warehouse": "1" }
    ]
  }'

Zamówienia

GET /order

Lista zamówień

X-FTToken + F-service

Zwraca listę zamówień, które nie zostały anulowane.
Wynik jest podzielony na strony.

Nagłówki4
NagłówekWymaganyDomyślneOpis
X-FTToken tak — Token firmy
F-service tak — firmatec_api
Accept nie application/json Format odpowiedzi JSON.
Accept-Language nie — pl albo en - język komunikatów błędów
Parametry query6
ParametrTypWymaganyDomyślneOpis
perpage int nie 10 Liczba rekordów na stronę. Najwyżej 200.
page int nie 1 Numer strony.
date_from string nie — Data wystawienia od, np. 2026-01-01.
date_to string nie — Data wystawienia do, np. 2026-01-31.
sort_by string nie DWy Pole sortowania: id, DWy (data wystawienia) albo amount (kwota).
sort_direction string nie DESC ASC - rosnąco, DESC - malejąco.

Kody błędów

HTTPOpis
403 Brak dostępu. Usługę kupuje się i przedłuża na stronie API w Centrum konfiguracji.
404 Nieprawidłowy token. Token generuje się i zmienia na stronie API w Centrum konfiguracji.

Przykład odpowiedzi

HTTP 200
{
  "current_page": 1,
  "data": [ { "ID": "Z.RRMMDD.GGMMSS.XXXXXX", "NrR": "ZAI/N/RRRR/MM" } ],
  "per_page": 10,
  "total": 1
}

Przykład cURL

curl -s '{base_url}/order?page=1&perpage=10' \
  -H 'X-FTToken: TWOJ-TOKEN' \
  -H 'F-service: firmatec_api' \
  -H 'Accept: application/json' \
  -H 'Accept-Language: pl'
GET /order/{id}

Szczegóły zamówienia

X-FTToken + F-service

Pobiera jedno zamówienie.
Format jest wybierany nagłówkiem Accept: JSON (nagłówek i pozycje w spec) albo XML programu Faktura iBiznes. Opis układu XML: eksport zamówień XML.

Nagłówki4
NagłówekWymaganyDomyślneOpis
X-FTToken tak — Token firmy
F-service tak — firmatec_api
Accept nie application/json application/json albo application/xml.
Accept-Language nie — pl albo en - język komunikatów błędów

Parametry ścieżki

ParametrTypWymaganyDomyślneOpis
id string tak — Identyfikator zamówienia z listy albo z zapisu, np. Z.RRMMDD.GGMMSS.XXXXXX.

Kody błędów

HTTPOpis
403 Brak dostępu. Usługę kupuje się i przedłuża na stronie API w Centrum konfiguracji.
404 Nie znaleziono zamówienia albo token jest nieprawidłowy

Przykład odpowiedzi

HTTP 200
Accept: application/json
{ "data": { "ID": "Z.RRMMDD.GGMMSS.XXXXXX", "NrR": "ZAI/N/RRRR/MM", "spec": [] } }

Accept: application/xml  - dokument XML (DOKUMENT / ZAPIS)
Przykład cURL 
# JSON
curl -s '{base_url}/order/Z.RRMMDD.GGMMSS.XXXXXX' \
  -H 'X-FTToken: TWOJ-TOKEN' \
  -H 'F-service: firmatec_api' \
  -H 'Accept: application/json' \
  -H 'Accept-Language: pl'

# XML
curl -s '{base_url}/order/Z.RRMMDD.GGMMSS.XXXXXX' \
  -H 'X-FTToken: TWOJ-TOKEN' \
  -H 'F-service: firmatec_api' \
  -H 'Accept: application/xml' \
  -H 'Accept-Language: pl' \
  -o zamowienie.xml
POST /order

Zapis zamówienia (XML / JSON)

X-FTToken + F-service

Wczytuje zamówienie z pliku XML programu Faktura iBiznes albo z JSON.
Jeśli w pliku jest kompletny numer (ID, Nr, Rej, Rok, Mc, NrR) - jest zapisywany bez zmian, łącznie z symbolem rejestru. W przeciwnym razie numer nadaje system, a rejestr bierze z Centrum konfiguracji: Ustawienia globalne - Numerowanie - Rejestry dokumentów, typ Zamówienia internetowe (ZAI). Gdy takiego rejestru nie ma, używany jest ZAI. Samo Rej z przykładu dokumentacji nie zmienia rejestru, gdy numer nadaje system. Nabywca jest szukany po NIP, gdy buyer.id nie jest podane. Opis układu XML: eksport zamówień XML. Formy płatności mogą wcześniej być pobrane przez GET /payment.

Nagłówki5
NagłówekWymaganyDomyślneOpis
X-FTToken tak — Token firmy
F-service tak — firmatec_api
Accept nie application/json Format odpowiedzi JSON.
Content-Type nie — application/xml, text/xml, application/json albo multipart/form-data
Accept-Language nie — pl albo en - język komunikatów błędów
Body (JSON)45
PoleTypWymaganyDomyślneOpis
issue_date string nie — Data wystawienia, RRRR-MM-DD. Pusta oznacza datę bieżącą.
fulfillment_date string nie — Termin realizacji, RRRR-MM-DD. Brak pola oznacza datę wystawienia. Pusta wartość oznacza brak terminu.
payment_method string nie pusta Nazwa formy płatności z GET /payment.
payment_days int nie — Liczba dni. Brak pola oznacza brak liczby dni.
currency string nie PLN Waluta.
price_mode string nie net net albo gross.
paid number nie 0 Kwota zapłacona.
notes string nie puste Uwagi.
description string nie pusty Opis.
stage string nie pusty Etap, najwyżej 50 znaków.
delivery_terms string nie puste Warunki dostawy.
delivery_address string nie pusty Adres dostawy.
operator string nie api Alias operatora.
external_id string nie pusty Identyfikator zewnętrzny.
use_provided_document bool nie false true — numer i ID pochodzą z obiektu document. false — numeracja firmy.
document.id string nie — Unikalny ID zamówienia. Format przykładowy: Z.RRMMDD.GGMMSS.XXXXXX. Wymagany przy use_provided_document=true.
document.nr int nie — Numer kolejny (> 0). Wymagany przy use_provided_document=true.
document.rej string nie — Symbol rejestru (np. ZAM). Wymagany przy use_provided_document=true.
document.rok string nie — Rok, cztery cyfry (RRRR). Wymagany przy use_provided_document=true.
document.mc string nie — Miesiąc, dwie cyfry (MM). Wymagany przy use_provided_document=true.
document.nrr string nie — Pełny numer na dokumencie, np. ZAM/N/RRRR/MM. Wymagany przy use_provided_document=true.
buyer.id string nie — ID klienta. Puste - szukanie po buyer.tax_id.
buyer.name string nie — Nazwa nabywcy. Wymagana w zapisie. Przy pustym polu i podanym NIP nazwa jest brana z karty klienta.
buyer.name2 string nie — Druga linia nazwy nabywcy.
buyer.alias string nie — Alias nabywcy. Pusty oznacza operator.
buyer.tax_id string nie — NIP nabywcy. Przy pustym buyer.id karta jest szukana po tym numerze.
buyer.country_code string nie — Prefiks NIP nabywcy.
buyer.address string nie — Ulica nabywcy.
buyer.postal_code string nie — Kod pocztowy nabywcy.
buyer.city string nie — Miasto nabywcy.
buyer.email string nie — E-mail nabywcy.
buyer.phone string nie — Telefon nabywcy.
buyer.person string nie — Osoba kontaktowa.
items object[] tak — Pozycje. Co najmniej jedna z niepustym name.
items[].name string tak — Nazwa pozycji.
items[].quantity number nie 1 Ilość.
items[].product_code string nie pusty Kod towaru.
items[].warehouse string nie 1 Magazyn.
items[].unit string nie szt Jednostka.
items[].price_net number nie 0 Cena netto.
items[].price_gross number nie — Cena brutto. Używana, gdy price_mode to gross albo price_net jest puste.
items[].vat string nie 23 Stawka VAT: 23, 8, 5 albo inna (traktowana jako 0).
items[].discount_percent number nie 0 Rabat procentowy, od 0 do 100.
items[].type string nie pusty Typ pozycji.
items[].description string nie pusty Opis pozycji.

Jak przesłać żądanie

Sposób transportu body (XML albo JSON) — nie mylić z rodzajem dokumentu (VAT, PZ, WZ…).

SposóbOpis
XML — plik Formularz multipart: pole xml albo file z plikiem eksportu Faktura iBiznes. Content-Type: multipart/form-data.
XML — treść body Całe body to dokument XML. Content-Type: application/xml albo text/xml.
JSON — pola dokumentu Content-Type: application/json. Pola z tabeli Body. Gotowe scenariusze (własny numer, rodzaj dokumentu itd.) — w sekcji „Przykłady żądania” poniżej.
JSON — opakowany XML Content-Type: application/json, gdy klient obsługuje tylko JSON, a dostępny jest już plik XML: {"xml":"<?xml …>…"}. To nadal import XML, nie mapa pól Body.

Przykłady żądania

Zamówienie JSON — numer z systemu Content-Type: application/json. Pola z tabeli Body; numer nadaje system. 
{
  "issue_date": "2026-01-15",
  "buyer": {
    "name": "Nabywca przykładowy",
    "tax_id": "0000000000",
    "city": "Miasto",
    "address": "Ulica 1",
    "postal_code": "00-000"
  },
  "payment_method": "Przelew",
  "items": [
    { "name": "Pozycja przykładowa", "quantity": 2, "price_net": 49.99, "vat": "23", "unit": "szt" }
  ]
}
Zamówienie — własny numer (document) use_provided_document=true — ID i NrR pochodzą z obiektu document. Wartości poniżej — placeholdery. 
{
  "use_provided_document": true,
  "issue_date": "2026-01-15",
  "document": {
    "id": "Z.RRMMDD.GGMMSS.XXXXXX",
    "nr": 1,
    "rej": "ZAM",
    "rok": "RRRR",
    "mc": "MM",
    "nrr": "ZAM/N/RRRR/MM"
  },
  "buyer": { "name": "Nabywca przykładowy", "tax_id": "0000000000" },
  "items": [
    { "name": "Pozycja przykładowa", "quantity": 1, "price_net": 20, "vat": "23" }
  ]
}

Sekcje XML Firmatec

Opis pól: dokumentacja eksportu XML

SekcjaZnaczenie
ZAPIS co="zamowienia" Nagłówek zamówienia (wymagany; ta sama sekcja bywa nazwana zamówienia albo zams)
ZAPIS co="zamsy" Pozycje zamówienia (wymagana co najmniej jedna; ta sama sekcja bywa nazwana spec albo pozycje)
Inne sekcje klienci, towary - opcjonalne, przy imporcie pomijane

Kody błędów

HTTPOpis
403 Brak dostępu. Usługę kupuje się i przedłuża na stronie API w Centrum konfiguracji.
404 Nieprawidłowy token. Token generuje się i zmienia na stronie API w Centrum konfiguracji.
409 Zamówienie o podanym ID albo numerze NrR już istnieje
422 Nie da się wczytać zamówienia: brak nagłówka albo pozycji, brak nabywcy, niepełny numer, nieznany format

Przykład odpowiedzi

HTTP 201
{
  "message": "Zamówienie zapisane.",
  "data": { "ID": "Z.RRMMDD.GGMMSS.XXXXXX", "NrR": "ZAI/N/RRRR/MM", "spec": [] }
}

Przykład cURL

curl -s -X POST '{base_url}/order' \
  -H 'X-FTToken: TWOJ-TOKEN' \
  -H 'F-service: firmatec_api' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/xml' \
  -H 'Accept-Language: pl' \
  --data-binary @zamowienie.xml

Formy płatności

GET /payment

Lista form płatności

X-FTToken + F-service

Zwraca formy płatności z programu Faktura iBiznes dla firmy.
Te wartości mogą potem być użyte przy zapisie zamówienia i karty klienta (Fp). Pole id służy do edycji formy.

Nagłówki4
NagłówekWymaganyDomyślneOpis
X-FTToken tak — Token firmy
F-service tak — firmatec_api
Accept nie application/json Format odpowiedzi JSON.
Accept-Language nie — pl albo en - język komunikatów błędów

Kody błędów

HTTPOpis
403 Brak dostępu. Usługę kupuje się i przedłuża na stronie API w Centrum konfiguracji.
404 Nieprawidłowy token. Token generuje się i zmienia na stronie API w Centrum konfiguracji.

Przykład odpowiedzi

HTTP 200
{
  "data": [
    { "id": "FP1", "name": "Gotówka", "days": 0 },
    { "id": "FP2", "name": "Karta płatnicza", "days": 0 },
    { "id": "FP3", "name": "Przedpłata", "days": 0 },
    { "id": "FP4", "name": "Przelew", "days": 7 }
  ]
}

Lista zależy od ustawień w bazie firmy. Powyżej - typowy zestaw startowy.

Przykład cURL

curl -s '{base_url}/payment' \
  -H 'X-FTToken: TWOJ-TOKEN' \
  -H 'F-service: firmatec_api' \
  -H 'Accept: application/json' \
  -H 'Accept-Language: pl'
PUT /payment/{id}

Edycja formy płatności

X-FTToken + F-service

Zmienia nazwę i/lub liczbę dni istniejącej formy.
Nowa forma nie jest tu dodawana. Wymagane jest name albo days. Karty klientów zachowują dotychczasowe Fp i Dni.

Nagłówki5
NagłówekWymaganyDomyślneOpis
X-FTToken tak — Token firmy
F-service tak — firmatec_api
Accept nie application/json Format odpowiedzi JSON.
Content-Type tak — application/json
Accept-Language nie — pl albo en - język komunikatów błędów

Parametry ścieżki

ParametrTypWymaganyDomyślneOpis
id string tak — ID wiersza z GET /payment, np. FP4.

Body (JSON)

PoleTypWymaganyDomyślneOpis
name string nie — Nowa nazwa. Można pominąć. Pusta nazwa nie jest zapisywana. Wymagane jest name albo days.
days int nie — Nowa liczba dni, zero lub więcej. Można pominąć. Wymagane jest name albo days.

Jak przesłać żądanie

Sposób transportu body (XML albo JSON) — nie mylić z rodzajem dokumentu (VAT, PZ, WZ…).

SposóbOpis
JSON Content-Type: application/json. Pola opisane w tabeli Body. Przykład poniżej.

Przykłady żądania

Zmiana liczby dni Wystarczy days albo name (albo oba). 
{ "days": 14 }
Zmiana nazwy i dni Oba pola opcjonalne, ale co najmniej jedno wymagane. 
{ "name": "Przelew 14 dni", "days": 14 }

Kody błędów

HTTPOpis
403 Brak dostępu. Usługę kupuje się i przedłuża na stronie API w Centrum konfiguracji.
404 Nie znaleziono formy płatności albo token jest nieprawidłowy
422 Brak name i days, pusta nazwa albo ujemna liczba dni

Przykład odpowiedzi

HTTP 200
{ "data": { "id": "FP4", "name": "Przelew", "days": 14 } }

Przykład cURL

curl -s -X PUT '{base_url}/payment/FP4' \
  -H 'X-FTToken: TWOJ-TOKEN' \
  -H 'F-service: firmatec_api' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Accept-Language: pl' \
  -d '{"days": 14}'

Klienci

GET /client

Lista klientów

X-FTToken + F-service

Zwraca listę kart z kartoteki, które nie zostały anulowane.
Wynik jest podzielony na strony. Parametr q szuka po ID, aliasie, NIP i nazwie.

Nagłówki4
NagłówekWymaganyDomyślneOpis
X-FTToken tak — Token firmy
F-service tak — firmatec_api
Accept nie application/json Format odpowiedzi JSON.
Accept-Language nie — pl albo en - język komunikatów błędów

Parametry query

ParametrTypWymaganyDomyślneOpis
page int nie 1 Numer strony.
perpage int nie 20 Liczba kart na stronę. Najwyżej 200.
per_page int nie — To samo co perpage. Używane, gdy perpage nie jest podane.
q string nie — Fragment ID, aliasu, NIP albo nazwy. Puste oznacza całą listę.

Kody błędów

HTTPOpis
403 Brak dostępu. Usługę kupuje się i przedłuża na stronie API w Centrum konfiguracji.
404 Nieprawidłowy token. Token generuje się i zmienia na stronie API w Centrum konfiguracji.

Przykład odpowiedzi

HTTP 200
{
  "data": [
    { "ID": "KL.RRMMDD.GGMMSS.XXXXXX", "Alias": "Klient", "NIP": "0000000000", "Nazw": "Klient przykładowy" }
  ],
  "page": 1,
  "per_page": 20,
  "total": 1
}

Przykład cURL

curl -s '{base_url}/client?page=1&perpage=20&q=Klient' \
  -H 'X-FTToken: TWOJ-TOKEN' \
  -H 'F-service: firmatec_api' \
  -H 'Accept: application/json' \
  -H 'Accept-Language: pl'
GET /client/{key}

Karta klienta

X-FTToken + F-service

Pobiera jedną kartę, także anulowaną.
Szukanie po kolei: ID, alias, numer klienta (ksk), NIP. Gdy NIP albo ksk pasuje do kilku kart, odpowiedź zawiera listę do wyboru (multiple: true), bez pełnej karty. Hasło nie jest zwracane.

Nagłówki4
NagłówekWymaganyDomyślneOpis
X-FTToken tak — Token firmy
F-service tak — firmatec_api
Accept nie application/json Format odpowiedzi JSON.
Accept-Language nie — pl albo en - język komunikatów błędów

Parametry ścieżki

ParametrTypWymaganyDomyślneOpis
key string tak — ID, alias, numer klienta (ksk) albo NIP. Dopasowanie dokładne. Kolejność: ID, alias, ksk, NIP.

Kody błędów

HTTPOpis
403 Brak dostępu. Usługę kupuje się i przedłuża na stronie API w Centrum konfiguracji.
404 Nie znaleziono klienta albo token jest nieprawidłowy

Przykład odpowiedzi

HTTP 200
{ "data": { "ID": "KL.RRMMDD.GGMMSS.XXXXXX", "Alias": "Klient", "Nazw": "Klient przykładowy", "NIP": "0000000000" } }

HTTP 200, kilka kart
{
  "data": [
    { "ID": "KL.RRMMDD.GGMMSS.XXXXXX", "Alias": "Klient", "NIP": "0000000000", "Nazw": "Klient przykładowy" }
  ],
  "multiple": true
}

Przykład cURL

curl -s '{base_url}/client/Klient' \
  -H 'X-FTToken: TWOJ-TOKEN' \
  -H 'F-service: firmatec_api' \
  -H 'Accept: application/json' \
  -H 'Accept-Language: pl'
POST /client

Nowy klient

X-FTToken + F-service

Tworzy kartę klienta.
Pola wymagane i opcjonalne są w tabeli Body. Brak pola opcjonalnego oznacza wartość domyślną. Hasło nie wraca w odpowiedzi. Przy konflikcie aliasu albo niepustego ksk odpowiedź zawiera istniejącą kartę.

Nagłówki5
NagłówekWymaganyDomyślneOpis
X-FTToken tak — Token firmy
F-service tak — firmatec_api
Accept nie application/json Format odpowiedzi JSON.
Content-Type tak — application/json
Accept-Language nie — pl albo en - język komunikatów błędów
Body (JSON)37
PoleTypWymaganyDomyślneOpis
Alias string tak — Unikalny wśród kart z Anul innym niż T. Litery i cyfry, najwyżej 120 znaków.
Hasl string tak — Hasło w base64. W odpowiedzi nie wraca. Pusta wartość przy edycji nie nadpisuje kolumny.
Nazw string tak — Nazwa.
Ulic string tak — Ulica.
KodP string tak — Kod pocztowy.
Mias string tak — Miasto.
NIPx string tak — Prefiks NIP. Przy tworzeniu pole jest wymagane, wartość może być pusta. Pusta wartość przy edycji nie nadpisuje kolumny.
NIP string tak — NIP. Nie musi być unikalny. Pusta wartość przy edycji nie nadpisuje kolumny.
Rodz string tak — o - odbiorca, d - dostawca.
REGPES string tak — R - REGON w polu Reg, P - PESEL w polu Reg.
Reg string tak — REGON albo PESEL.
Tk string tak — Telefon główny. Pusta wartość przy edycji nie nadpisuje kolumny.
Mail string tak — Adres e-mail. Pusta wartość przy edycji nie nadpisuje kolumny.
Nazw2 string nie pusta Druga linia nazwy.
T1 string nie pusty Telefon dodatkowy.
T2 string nie pusty Drugi telefon dodatkowy.
www string nie pusty Adres strony.
notk string nie pusta Notatka.
OsU string nie pusta Osoba upoważniona.
IDplat string nie pusty Alias płatnika. Pusty albo alias istniejącej żywej karty, albo alias zapisywanej karty.
IDz string nie pusty Identyfikator zewnętrzny.
nID string nie pusty Numeryczny identyfikator zewnętrzny albo pusty.
Fp string nie puste Nazwa z GET /payment. Dni są zapisywane z tej formy i osobno nie są podawane. Puste Fp zapisuje Fp puste i Dni 0.
Cen int nie 0 Numer poziomu z GET /client/dict/price.
Rab number nie 0 Rabat, liczba nieujemna.
pkt number nie 0 Punkty, liczba nieujemna.
Kat string nie puste A, B, C albo puste.
ks string[] nie pusta tablica Tablica nazw z GET /client/dict/keyword. Pusta tablica czyści listę.
cech string[] nie pusta tablica Tablica nazw z GET /client/dict/feature. Pusta tablica czyści listę.
OW string nie pusta Jedna nazwa z GET /client/dict/agent.
AdrD string nie pusty Adres dostawy.
Datnw string nie pusta Data w formacie RRRRMMDDGGMMSS albo pusta.
LastW string nie pusta Data w formacie RRRRMMDDGGMMSS albo pusta.
Dp string nie pusta Data w formacie RRRRMMDDGGMMSS albo pusta.
ksk string nie pusty. Pusty jest dozwolony. Niepusty musi być unikalny Numer klienta.
Blok string nie N T albo N.
jez int nie 0 Numer z GET /client/dict/language, od 0 do 18.

Jak przesłać żądanie

Sposób transportu body (XML albo JSON) — nie mylić z rodzajem dokumentu (VAT, PZ, WZ…).

SposóbOpis
JSON Content-Type: application/json. Pola opisane w tabeli Body. Przykład poniżej.

Przykłady żądania

Nowy klient — pełny JSON Hasł w Base64. Pola opcjonalne można pominąć (wtedy wartości domyślne z tabeli Body). 
{
  "Alias": "Klient",
  "Hasl": "dGVzdA==",
  "Nazw": "Klient przykładowy",
  "Ulic": "Ulica 1",
  "KodP": "00-000",
  "Mias": "Miasto",
  "NIPx": "",
  "NIP": "0000000000",
  "Rodz": "o",
  "REGPES": "R",
  "Reg": "000000000",
  "Tk": "000000000",
  "Mail": "klient@example.com"
}

Kody błędów

HTTPOpis
403 Brak dostępu. Usługę kupuje się i przedłuża na stronie API w Centrum konfiguracji.
404 Nieprawidłowy token. Token generuje się i zmienia na stronie API w Centrum konfiguracji.
409 Alias albo niepusty numer klienta (ksk) już istnieje - w data jest istniejąca karta
422 Brak pola, zła wartość albo nieznana pozycja słownika

Przykład odpowiedzi

HTTP 201
{ "data": { "ID": "KL.RRMMDD.GGMMSS.XXXXXX", "Alias": "Klient", "Nazw": "Klient przykładowy" } }

Przykład cURL

curl -s -X POST '{base_url}/client' \
  -H 'X-FTToken: TWOJ-TOKEN' \
  -H 'F-service: firmatec_api' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Accept-Language: pl' \
  -d '{"Alias":"Klient","Hasl":"dGVzdA==","Nazw":"Klient przykładowy","Ulic":"Ulica 1","KodP":"00-000","Mias":"Miasto","NIPx":"","NIP":"0000000000","Rodz":"o","REGPES":"R","Reg":"000000000","Tk":"000000000","Mail":"klient@example.com"}'
PUT /client/{key}

Edycja klienta

X-FTToken + F-service

Zmienia tylko pola obecne w JSON.
Brak pola zostawia dotychczasową wartość. JSON null jest traktowany jak brak pola. Puste NIPx, NIP, Hasl, Mail i Tk nie nadpisują kolumny. Puste Alias, Nazw, Ulic, KodP, Mias, Rodz, REGPES i Reg są odrzucane. Pusta wartość pozostałych pól czyści je. Puste body zwraca kartę bez zwiększania Wers. Anulowanie jest osobnym wywołaniem. Przy kilku kartach pasujących do klucza nic nie jest zmieniane.

Nagłówki5
NagłówekWymaganyDomyślneOpis
X-FTToken tak — Token firmy
F-service tak — firmatec_api
Accept nie application/json Format odpowiedzi JSON.
Content-Type tak — application/json
Accept-Language nie — pl albo en - język komunikatów błędów

Parametry ścieżki

ParametrTypWymaganyDomyślneOpis
key string tak — ID, alias, numer klienta (ksk) albo NIP. Dopasowanie dokładne. Kolejność: ID, alias, ksk, NIP.
Body (JSON)37
PoleTypWymaganyDomyślneOpis
Alias string nie — Unikalny wśród kart z Anul innym niż T. Litery i cyfry, najwyżej 120 znaków.
Hasl string nie — Hasło w base64. W odpowiedzi nie wraca. Pusta wartość przy edycji nie nadpisuje kolumny.
Nazw string nie — Nazwa.
Ulic string nie — Ulica.
KodP string nie — Kod pocztowy.
Mias string nie — Miasto.
NIPx string nie — Prefiks NIP. Przy tworzeniu pole jest wymagane, wartość może być pusta. Pusta wartość przy edycji nie nadpisuje kolumny.
NIP string nie — NIP. Nie musi być unikalny. Pusta wartość przy edycji nie nadpisuje kolumny.
Rodz string nie — o - odbiorca, d - dostawca.
REGPES string nie — R - REGON w polu Reg, P - PESEL w polu Reg.
Reg string nie — REGON albo PESEL.
Tk string nie — Telefon główny. Pusta wartość przy edycji nie nadpisuje kolumny.
Mail string nie — Adres e-mail. Pusta wartość przy edycji nie nadpisuje kolumny.
Nazw2 string nie pusta Druga linia nazwy.
T1 string nie pusty Telefon dodatkowy.
T2 string nie pusty Drugi telefon dodatkowy.
www string nie pusty Adres strony.
notk string nie pusta Notatka.
OsU string nie pusta Osoba upoważniona.
IDplat string nie pusty Alias płatnika. Pusty albo alias istniejącej żywej karty, albo alias zapisywanej karty.
IDz string nie pusty Identyfikator zewnętrzny.
nID string nie pusty Numeryczny identyfikator zewnętrzny albo pusty.
Fp string nie puste Nazwa z GET /payment. Dni są zapisywane z tej formy i osobno nie są podawane. Puste Fp zapisuje Fp puste i Dni 0.
Cen int nie 0 Numer poziomu z GET /client/dict/price.
Rab number nie 0 Rabat, liczba nieujemna.
pkt number nie 0 Punkty, liczba nieujemna.
Kat string nie puste A, B, C albo puste.
ks string[] nie pusta tablica Tablica nazw z GET /client/dict/keyword. Pusta tablica czyści listę.
cech string[] nie pusta tablica Tablica nazw z GET /client/dict/feature. Pusta tablica czyści listę.
OW string nie pusta Jedna nazwa z GET /client/dict/agent.
AdrD string nie pusty Adres dostawy.
Datnw string nie pusta Data w formacie RRRRMMDDGGMMSS albo pusta.
LastW string nie pusta Data w formacie RRRRMMDDGGMMSS albo pusta.
Dp string nie pusta Data w formacie RRRRMMDDGGMMSS albo pusta.
ksk string nie pusty. Pusty jest dozwolony. Niepusty musi być unikalny Numer klienta.
Blok string nie N T albo N.
jez int nie 0 Numer z GET /client/dict/language, od 0 do 18.

Jak przesłać żądanie

Sposób transportu body (XML albo JSON) — nie mylić z rodzajem dokumentu (VAT, PZ, WZ…).

SposóbOpis
JSON Content-Type: application/json. Pola opisane w tabeli Body. Przykład poniżej.

Przykłady żądania

Częściowa edycja Tylko podane pola są zmieniane. Tu: blokada karty. 
{ "Blok": "T" }
Zmiana adresu Kilka pól naraz — pozostałe bez zmian. 
{
  "Ulic": "Ulica 2",
  "KodP": "00-000",
  "Mias": "Miasto"
}

Kody błędów

HTTPOpis
403 Brak dostępu. Usługę kupuje się i przedłuża na stronie API w Centrum konfiguracji.
404 Nie znaleziono klienta albo token jest nieprawidłowy
409 Konflikt aliasu albo ksk, albo klucz pasuje do kilku kart
422 Zła wartość pola albo nieznana pozycja słownika

Przykład odpowiedzi

HTTP 200
{ "data": { "ID": "KL.RRMMDD.GGMMSS.XXXXXX", "Wers": 1 } }

Przykład cURL

curl -s -X PUT '{base_url}/client/Klient' \
  -H 'X-FTToken: TWOJ-TOKEN' \
  -H 'F-service: firmatec_api' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Accept-Language: pl' \
  -d '{"Blok":"T"}'
POST /client/{key}/anul

Anulowanie klienta

X-FTToken + F-service

Ustawia Anul na T.
Karty nie usuwa. Gdy karta już jest anulowana, odpowiedź to 200 i Wers się nie zmienia. Przy kilku kartach pasujących do klucza nic nie jest zmieniane. Body nie jest używane.

Nagłówki4
NagłówekWymaganyDomyślneOpis
X-FTToken tak — Token firmy
F-service tak — firmatec_api
Accept nie application/json Format odpowiedzi JSON.
Accept-Language nie — pl albo en - język komunikatów błędów

Parametry ścieżki

ParametrTypWymaganyDomyślneOpis
key string tak — ID, alias, numer klienta (ksk) albo NIP. Dopasowanie dokładne. Kolejność: ID, alias, ksk, NIP.

Jak przesłać żądanie

Sposób transportu body (XML albo JSON) — nie mylić z rodzajem dokumentu (VAT, PZ, WZ…).

SposóbOpis
Bez body Wystarczą nagłówki i parametry ścieżki. Body nie jest używane.

Kody błędów

HTTPOpis
403 Brak dostępu. Usługę kupuje się i przedłuża na stronie API w Centrum konfiguracji.
404 Nie znaleziono klienta albo token jest nieprawidłowy
409 Klucz pasuje do kilku kart

Przykład odpowiedzi

HTTP 200
{ "data": { "Anul": "T" } }

Przykład cURL

curl -s -X POST '{base_url}/client/KL.RRMMDD.GGMMSS.XXXXXX/anul' \
  -H 'X-FTToken: TWOJ-TOKEN' \
  -H 'F-service: firmatec_api' \
  -H 'Accept: application/json' \
  -H 'Accept-Language: pl'
POST /client/{key}/restore

Przywrócenie klienta

X-FTToken + F-service

Ustawia Anul na N.
Gdy karta już jest aktywna, odpowiedź to 200 i Wers się nie zmienia. Przy kilku kartach pasujących do klucza nic nie jest zmieniane. Body nie jest używane.

Nagłówki4
NagłówekWymaganyDomyślneOpis
X-FTToken tak — Token firmy
F-service tak — firmatec_api
Accept nie application/json Format odpowiedzi JSON.
Accept-Language nie — pl albo en - język komunikatów błędów

Parametry ścieżki

ParametrTypWymaganyDomyślneOpis
key string tak — ID, alias, numer klienta (ksk) albo NIP. Dopasowanie dokładne. Kolejność: ID, alias, ksk, NIP.

Jak przesłać żądanie

Sposób transportu body (XML albo JSON) — nie mylić z rodzajem dokumentu (VAT, PZ, WZ…).

SposóbOpis
Bez body Wystarczą nagłówki i parametry ścieżki. Body nie jest używane.

Kody błędów

HTTPOpis
403 Brak dostępu. Usługę kupuje się i przedłuża na stronie API w Centrum konfiguracji.
404 Nie znaleziono klienta albo token jest nieprawidłowy
409 Klucz pasuje do kilku kart

Przykład odpowiedzi

HTTP 200
{ "data": { "Anul": "N" } }

Przykład cURL

curl -s -X POST '{base_url}/client/KL.RRMMDD.GGMMSS.XXXXXX/restore' \
  -H 'X-FTToken: TWOJ-TOKEN' \
  -H 'F-service: firmatec_api' \
  -H 'Accept: application/json' \
  -H 'Accept-Language: pl'
GET /client/dict/price

Poziomy cen

X-FTToken + F-service

Zwraca poziomy nieanulowanych cen ze słownika cen.
W kartę klienta jest zapisywany level (pole Cen).

Nagłówki4
NagłówekWymaganyDomyślneOpis
X-FTToken tak — Token firmy
F-service tak — firmatec_api
Accept nie application/json Format odpowiedzi JSON.
Accept-Language nie — pl albo en - język komunikatów błędów

Kody błędów

HTTPOpis
403 Brak dostępu. Usługę kupuje się i przedłuża na stronie API w Centrum konfiguracji.
404 Nieprawidłowy token. Token generuje się i zmienia na stronie API w Centrum konfiguracji.

Przykład odpowiedzi

HTTP 200
{ "data": [ { "id": "CS1", "level": 1, "name": "Podstawowa" } ] }

Przykład cURL

curl -s '{base_url}/client/dict/price' \
  -H 'X-FTToken: TWOJ-TOKEN' \
  -H 'F-service: firmatec_api' \
  -H 'Accept: application/json' \
  -H 'Accept-Language: pl'
GET /client/dict/keyword

Słowa kluczowe

X-FTToken + F-service

Zwraca słowa kluczowe ze słownika.
Do karty klienta jest wysyłana tablica pól name w ks.

Nagłówki4
NagłówekWymaganyDomyślneOpis
X-FTToken tak — Token firmy
F-service tak — firmatec_api
Accept nie application/json Format odpowiedzi JSON.
Accept-Language nie — pl albo en - język komunikatów błędów

Kody błędów

HTTPOpis
403 Brak dostępu. Usługę kupuje się i przedłuża na stronie API w Centrum konfiguracji.
404 Nieprawidłowy token. Token generuje się i zmienia na stronie API w Centrum konfiguracji.

Przykład odpowiedzi

HTTP 200
{ "data": [ { "id": "...", "name": "Kluczowe3" } ] }

Przykład cURL

curl -s '{base_url}/client/dict/keyword' \
  -H 'X-FTToken: TWOJ-TOKEN' \
  -H 'F-service: firmatec_api' \
  -H 'Accept: application/json' \
  -H 'Accept-Language: pl'
GET /client/dict/agent

Akwizytorzy

X-FTToken + F-service

Zwraca akwizytorów ze słownika.
W kartę klienta trafia jedno name (pole OW).

Nagłówki4
NagłówekWymaganyDomyślneOpis
X-FTToken tak — Token firmy
F-service tak — firmatec_api
Accept nie application/json Format odpowiedzi JSON.
Accept-Language nie — pl albo en - język komunikatów błędów

Kody błędów

HTTPOpis
403 Brak dostępu. Usługę kupuje się i przedłuża na stronie API w Centrum konfiguracji.
404 Nieprawidłowy token. Token generuje się i zmienia na stronie API w Centrum konfiguracji.

Przykład odpowiedzi

HTTP 200
{ "data": [ { "id": "...", "name": "Aktywizor2" } ] }

Przykład cURL

curl -s '{base_url}/client/dict/agent' \
  -H 'X-FTToken: TWOJ-TOKEN' \
  -H 'F-service: firmatec_api' \
  -H 'Accept: application/json' \
  -H 'Accept-Language: pl'
GET /client/dict/feature

Cechy klienta

X-FTToken + F-service

Zwraca cechy ze słownika cech klientów.
Do karty klienta jest wysyłana tablica pól name w cech.

Nagłówki4
NagłówekWymaganyDomyślneOpis
X-FTToken tak — Token firmy
F-service tak — firmatec_api
Accept nie application/json Format odpowiedzi JSON.
Accept-Language nie — pl albo en - język komunikatów błędów

Kody błędów

HTTPOpis
403 Brak dostępu. Usługę kupuje się i przedłuża na stronie API w Centrum konfiguracji.
404 Nieprawidłowy token. Token generuje się i zmienia na stronie API w Centrum konfiguracji.

Przykład odpowiedzi

HTTP 200
{ "data": [ { "id": "...", "name": "Podstawowa" } ] }

Przykład cURL

curl -s '{base_url}/client/dict/feature' \
  -H 'X-FTToken: TWOJ-TOKEN' \
  -H 'F-service: firmatec_api' \
  -H 'Accept: application/json' \
  -H 'Accept-Language: pl'
GET /client/dict/language

Języki klienta

X-FTToken + F-service

Zwraca stałą listę języków.
W kartę jest zapisywany id (pole jez). Lista nie jest edytowana.

Nagłówki4
NagłówekWymaganyDomyślneOpis
X-FTToken tak — Token firmy
F-service tak — firmatec_api
Accept nie application/json Format odpowiedzi JSON.
Accept-Language nie — pl albo en - język komunikatów błędów

Kody błędów

HTTPOpis
403 Brak dostępu. Usługę kupuje się i przedłuża na stronie API w Centrum konfiguracji.
404 Nieprawidłowy token. Token generuje się i zmienia na stronie API w Centrum konfiguracji.

Przykład odpowiedzi

HTTP 200
{ "data": [ { "id": 0, "name": "Polskim" }, { "id": 1, "name": "Angielskim" } ] }

Przykład cURL

curl -s '{base_url}/client/dict/language' \
  -H 'X-FTToken: TWOJ-TOKEN' \
  -H 'F-service: firmatec_api' \
  -H 'Accept: application/json' \
  -H 'Accept-Language: pl'

Towary

GET /product

Lista towarów

X-FTToken + F-service

Zwraca listę kart towarów, które nie zostały anulowane.
Wiersz ma ID, Kod, Nazw, MAG, type i Anul. Parametr q szuka po ID, kodzie, EAN i nazwie.

Nagłówki4
NagłówekWymaganyDomyślneOpis
X-FTToken tak — Token firmy
F-service tak — firmatec_api
Accept nie application/json Format odpowiedzi JSON.
Accept-Language nie — pl albo en - język komunikatów błędów

Parametry query

ParametrTypWymaganyDomyślneOpis
page int nie 1 Numer strony.
perpage int nie 20 Liczba kart na stronę. Najwyżej 200.
per_page int nie — To samo co perpage.
q string nie — Fragment ID, kodu, EAN albo nazwy.
warehouse string nie — Kod magazynu (MAG), np. 1.

Kody błędów

HTTPOpis
403 Brak dostępu. Usługę kupuje się i przedłuża na stronie API w Centrum konfiguracji.
404 Nieprawidłowy token. Token generuje się i zmienia na stronie API w Centrum konfiguracji.

Przykład odpowiedzi

HTTP 200
{
  "data": [
    { "ID": "INT.1", "Kod": "KOD-1", "Nazw": "Towar przykładowy", "MAG": "1", "type": "towar", "Anul": "N" }
  ],
  "page": 1,
  "per_page": 20,
  "total": 1
}

Przykład cURL

curl -s '{base_url}/product?page=1&perpage=20&warehouse=1' \
  -H 'X-FTToken: TWOJ-TOKEN' \
  -H 'F-service: firmatec_api' \
  -H 'Accept: application/json'
GET /product/{key}

Karta towaru

X-FTToken + F-service

Pełna karta towaru.
Szukanie: ID, Kod, EAN. Gdy ten sam Kod/EAN występuje na kilku magazynach bez parametru warehouse, odpowiedź zawiera listę skróconych kart i multiple: true (bez pełnej karty). Do pełnej karty wymagany jest warehouse albo ID. Zdjęcia tymczasowo niedostępne.

Nagłówki4
NagłówekWymaganyDomyślneOpis
X-FTToken tak — Token firmy
F-service tak — firmatec_api
Accept nie application/json Format odpowiedzi JSON.
Accept-Language nie — pl albo en - język komunikatów błędów

Parametry query

ParametrTypWymaganyDomyślneOpis
warehouse string nie — Magazyn (MAG), gdy Kod/EAN nie jest unikalny.

Parametry ścieżki

ParametrTypWymaganyDomyślneOpis
key string tak — ID, Kod albo EAN.

Kody błędów

HTTPOpis
403 Brak dostępu. Usługę kupuje się i przedłuża na stronie API w Centrum konfiguracji.
404 Nie znaleziono towaru albo token jest nieprawidłowy

Przykład odpowiedzi

HTTP 200
{ "data": { "ID": "INT.1", "Kod": "KOD-1", "Nazw": "Towar przykładowy", "type": "towar", "CN1": 10, "CB1": 12.3 } }

HTTP 200, kilka kart
{ "data": [ { "ID": "…", "Kod": "KOD-1", "MAG": "1", … }, { "ID": "…", "Kod": "KOD-1", "MAG": "2", … } ], "multiple": true }

Przykład cURL

curl -s '{base_url}/product/KOD-1?warehouse=1' \
  -H 'X-FTToken: TWOJ-TOKEN' \
  -H 'F-service: firmatec_api' \
  -H 'Accept: application/json'
POST /product

Dodanie towaru

X-FTToken + F-service

Tworzy kartę towaru w magazynie.
Pola wymagane są oznaczone poniżej (polskie nazwy pól jak w iBiznes). Rodzaj (type), grupa i producent pochodzą ze słowników (GET /product/dict/…). quantity ustawia stan początkowy. Przy polach podano opcjonalne angielskie aliasy (np. Nazw albo name, Waga albo weight) — to tylko alternatywne klucze body, nie zmieniają nazw odpowiedzi. Zdjęcia tymczasowo niedostępne.

Nagłówki5
NagłówekWymaganyDomyślneOpis
X-FTToken tak — Token firmy
F-service tak — firmatec_api
Accept nie application/json Format odpowiedzi JSON.
Content-Type tak — application/json
Accept-Language nie — pl albo en - język komunikatów błędów
Body (JSON)44
PoleTypWymaganyDomyślneOpis
MAG string tak — Magazyn z GET /product/dict/warehouse, np. 1. Alias (EN): warehouse.
Kod string tak — Kod towaru. Unikalny w parze z MAG. Alias (EN): code.
Nazw string tak — Nazwa. Alias (EN): name.
type string tak — Rodzaj z GET /product/dict/type (towar, usluga, koszt, komis, wyrob_gotowy, zestaw, transport).
JM string tak — Jednostka miary (nazwa), np. szt. Alias (EN): unit.
NB string tak — Tryb cen: N (netto) albo B (brutto).
Cz number tak — Cena zakupu netto. Alias (EN): purchase.
vat string|number tak — Stawka: 0, 5, 8, 23 albo ZW. Opcjonalnie NVat i/lub stVAT — muszą być zgodne z vat.
prices object[] tak — 4 poziomy cen. Na poziom: netto albo brutto (klucze netto/brutto albo CN/CB). Brakujący poziom = 0. Alternatywa: CN1…CN4 / CB1…CB4. Jeśli netto i brutto naraz nie zgadzają się z VAT - 422.
NVat string nie — Tekst stawki, np. 23% albo ZW. Opcjonalnie zamiast/razem z vat (musi się zgadzać).
stVAT int nie — Kod poziomu VAT (0=0%, 1=8%, 2=23%, 3=ZW, 4=5%). Opcjonalnie; musi zgadzać się z vat.
CN1 number nie — Cena netto poziomu 1 (zamiast prices[].netto). Analogicznie CN2…CN4.
CB1 number nie — Cena brutto poziomu 1 (zamiast prices[].brutto). Analogicznie CB2…CB4.
RoCN string nie NNNN 4 znaki T/M/N (narzut / marża / nic) dla poziomów 1…4.
na1 number nie — Procent narzutu/marży poziomu 1 (gdy RoCN ma T lub M). Bez wartości — wyliczenie z Cz i CN1. Analogicznie na2…na4.
na2 number nie — Procent narzutu/marży poziomu 2.
na3 number nie — Procent narzutu/marży poziomu 3.
na4 number nie — Procent narzutu/marży poziomu 4.
Pr string nie puste Nazwa producenta (GET/POST /product/dict/producer). Alias (EN): producer.
Gr string nie puste Nazwa grupy z GET /product/dict/group (name). Alias (EN): group.
quantity number nie 0 Stan początkowy (≥0). Alias (EN): stan.
Cd number nie 0 Cena walutowa.
Wal string nie PLN Waluta z GET /product/dict/currency. Alias (EN): currency.
Walw string nie jak Wal / PLN Waluta ceny dewizowej / 4. poziomu. Alias (EN): currency_fx.
Alias string nie puste Alias dostawcy/klienta.
Nazd string nie pusta Nazwa dostawcy.
Nazw2 string nie pusta (nie kopiuje Nazw) Nazwa w drugim języku. Alias (EN): name2.
kat string nie pusty Nr katalogowy zewnętrzny (numer dostawcy).
Pkw string nie pusty Kod PKWiU/PKOB.
kk string nie pusty EAN / kod kreskowy. Aliasy (EN): ean, barcode.
Opis string nie pusty Opis. Alias (EN): description.
Notk string nie pusta Notatka. Alias (EN): note.
lokm string nie pusta Półka magazynowa. Alias (EN): shelf.
Waga number nie 0 Waga netto. Alias (EN): weight.
WagaB number nie 0 Waga brutto. Alias (EN): weight_gross.
dwaz string nie pusta Data ważności.
pkt number nie 0 Punkty lojalnościowe.
zID string nie pusty Zewnętrzny ID (integracje). Alias (EN): external_id.
IDzam string nie — Id grupy zamienników. Alias (EN): substitute_group. Puste = bez grupy. Albo POST /product/substitutes.
iNET string nie N T/N — widoczność w sklepach internetowych.
NA string nie N T/N — nieaktywny.
Anul string nie N; zwykle przez /anul i /restore T/N — anulowany. Przy create.
cech object[] nie puste Cechy towaru: [{ "name": "Cecha", "value": "…" }]. name z GET /product/dict/feature. Alias (EN): features. Pusta tablica czyści.
JM2 string nie pusta (bez automatycznego wypełnienia) Druga jednostka miary (np. karton, opak.). Alias (EN): unit2.

Jak przesłać żądanie

Sposób transportu body (XML albo JSON) — nie mylić z rodzajem dokumentu (VAT, PZ, WZ…).

SposóbOpis
JSON Content-Type: application/json. Pola opisane w tabeli Body. Przykład poniżej.

Przykłady żądania

Nowy towar ze stanem początkowym Polskie nazwy pól jak w iBiznes. prices: 4 ceny (netto); quantity ustawia STAN. 
{
  "MAG": "1",
  "Kod": "KOD-1",
  "Nazw": "Towar przykładowy",
  "type": "towar",
  "JM": "szt",
  "NB": "B",
  "Cz": 10,
  "vat": 23,
  "prices": [{ "netto": 14.18 }, {}, {}, {}],
  "quantity": 5
}

Kody błędów

HTTPOpis
403 Brak dostępu. Usługę kupuje się i przedłuża na stronie API w Centrum konfiguracji.
404 Nieprawidłowy token. Token generuje się i zmienia na stronie API w Centrum konfiguracji.
409 Kod+MAG już istnieje
422 Walidacja (brak pól, VAT, ceny, słowniki)

Przykład odpowiedzi

HTTP 201
{ "data": { "ID": "INT.…", "Kod": "KOD-1", "type": "towar", "STAN": 5 } }

Przykład cURL

curl -s -X POST '{base_url}/product' \
  -H 'X-FTToken: TWOJ-TOKEN' \
  -H 'F-service: firmatec_api' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -d '{"MAG":"1","Kod":"KOD-1","Nazw":"Towar przykładowy","type":"towar","JM":"szt","NB":"B","Cz":10,"vat":23,"prices":[{"netto":14.18},{},{},{}],"quantity":5}'
PUT /product/{key}

Edycja towaru

X-FTToken + F-service

Częściowa aktualizacja.
Te same polskie nazwy pól co przy create (opcjonalnie angielskie aliasy z listy Body). Domyślnie aktualizuje jedną kartę: przy kilku magazynach dla tego Kod/EAN bez warehouse — 409. Parametr all_warehouses=1 aktualizuje wszystkie dopasowane karty (nie zmienia MAG). Brak DELETE — /anul.

Nagłówki5
NagłówekWymaganyDomyślneOpis
X-FTToken tak — Token firmy
F-service tak — firmatec_api
Accept nie application/json Format odpowiedzi JSON.
Content-Type tak — application/json
Accept-Language nie — pl albo en - język komunikatów błędów

Parametry query

ParametrTypWymaganyDomyślneOpis
warehouse string nie — Magazyn (MAG), gdy key nie jest unikalny.
all_warehouses int nie wyłączone (0). Nie łączyć ze zmianą MAG 1 — aktualizacja wszystkich magazynów z tym Kod/EAN.

Parametry ścieżki

ParametrTypWymaganyDomyślneOpis
key string tak — ID, Kod albo EAN.
Body (JSON)44
PoleTypWymaganyDomyślneOpis
MAG string nie — Magazyn z GET /product/dict/warehouse, np. 1. Alias (EN): warehouse.
Kod string nie — Kod towaru. Unikalny w parze z MAG. Alias (EN): code.
Nazw string nie — Nazwa. Alias (EN): name.
type string nie — Rodzaj z GET /product/dict/type (towar, usluga, koszt, komis, wyrob_gotowy, zestaw, transport).
JM string nie — Jednostka miary (nazwa), np. szt. Alias (EN): unit.
NB string nie — Tryb cen: N (netto) albo B (brutto).
Cz number nie — Cena zakupu netto. Alias (EN): purchase.
vat string|number nie — Stawka: 0, 5, 8, 23 albo ZW. Opcjonalnie NVat i/lub stVAT — muszą być zgodne z vat.
prices object[] nie — 4 poziomy cen. Na poziom: netto albo brutto (klucze netto/brutto albo CN/CB). Brakujący poziom = 0. Alternatywa: CN1…CN4 / CB1…CB4. Jeśli netto i brutto naraz nie zgadzają się z VAT - 422.
NVat string nie — Tekst stawki, np. 23% albo ZW. Opcjonalnie zamiast/razem z vat (musi się zgadzać).
stVAT int nie — Kod poziomu VAT (0=0%, 1=8%, 2=23%, 3=ZW, 4=5%). Opcjonalnie; musi zgadzać się z vat.
CN1 number nie — Cena netto poziomu 1 (zamiast prices[].netto). Analogicznie CN2…CN4.
CB1 number nie — Cena brutto poziomu 1 (zamiast prices[].brutto). Analogicznie CB2…CB4.
RoCN string nie NNNN 4 znaki T/M/N (narzut / marża / nic) dla poziomów 1…4.
na1 number nie — Procent narzutu/marży poziomu 1 (gdy RoCN ma T lub M). Bez wartości — wyliczenie z Cz i CN1. Analogicznie na2…na4.
na2 number nie — Procent narzutu/marży poziomu 2.
na3 number nie — Procent narzutu/marży poziomu 3.
na4 number nie — Procent narzutu/marży poziomu 4.
Pr string nie puste Nazwa producenta (GET/POST /product/dict/producer). Alias (EN): producer.
Gr string nie puste Nazwa grupy z GET /product/dict/group (name). Alias (EN): group.
quantity number nie 0 Stan początkowy (≥0). Alias (EN): stan.
Cd number nie 0 Cena walutowa.
Wal string nie PLN Waluta z GET /product/dict/currency. Alias (EN): currency.
Walw string nie jak Wal / PLN Waluta ceny dewizowej / 4. poziomu. Alias (EN): currency_fx.
Alias string nie puste Alias dostawcy/klienta.
Nazd string nie pusta Nazwa dostawcy.
Nazw2 string nie pusta (nie kopiuje Nazw) Nazwa w drugim języku. Alias (EN): name2.
kat string nie pusty Nr katalogowy zewnętrzny (numer dostawcy).
Pkw string nie pusty Kod PKWiU/PKOB.
kk string nie pusty EAN / kod kreskowy. Aliasy (EN): ean, barcode.
Opis string nie pusty Opis. Alias (EN): description.
Notk string nie pusta Notatka. Alias (EN): note.
lokm string nie pusta Półka magazynowa. Alias (EN): shelf.
Waga number nie 0 Waga netto. Alias (EN): weight.
WagaB number nie 0 Waga brutto. Alias (EN): weight_gross.
dwaz string nie pusta Data ważności.
pkt number nie 0 Punkty lojalnościowe.
zID string nie pusty Zewnętrzny ID (integracje). Alias (EN): external_id.
IDzam string nie — Id grupy zamienników. Alias (EN): substitute_group. Puste = bez grupy. Albo POST /product/substitutes.
iNET string nie N T/N — widoczność w sklepach internetowych.
NA string nie N T/N — nieaktywny.
Anul string nie N; zwykle przez /anul i /restore T/N — anulowany. Przy create.
cech object[] nie puste Cechy towaru: [{ "name": "Cecha", "value": "…" }]. name z GET /product/dict/feature. Alias (EN): features. Pusta tablica czyści.
JM2 string nie pusta (bez automatycznego wypełnienia) Druga jednostka miary (np. karton, opak.). Alias (EN): unit2.

Jak przesłać żądanie

Sposób transportu body (XML albo JSON) — nie mylić z rodzajem dokumentu (VAT, PZ, WZ…).

SposóbOpis
JSON Content-Type: application/json. Pola opisane w tabeli Body. Przykład poniżej.

Przykłady żądania

Zmiana nazwy (jeden magazyn) Query warehouse=1 gdy Kod nie jest unikalny. 
{ "Nazw": "Nazwa przykładowa" }
Zmiana wagi na wszystkich magazynach Query all_warehouses=1. Nie łączyć ze zmianą MAG. 
{ "Waga": 1.5 }

Kody błędów

HTTPOpis
403 Brak dostępu. Usługę kupuje się i przedłuża na stronie API w Centrum konfiguracji.
404 Nie znaleziono towaru
409 Niejednoznaczny klucz (wymagany ID, warehouse albo all_warehouses=1) albo duplicate Kod+MAG
422 Walidacja (np. all_warehouses=1 + zmiana MAG)

Przykład odpowiedzi

HTTP 200 (jedna karta)
{ "data": { "ID": "INT.1", "Nazw": "Nazwa przykładowa" } }

HTTP 200 (all_warehouses=1)
{ "data": [ { "ID": "…", "MAG": "1", … }, { "ID": "…", "MAG": "2", … } ], "updated": 2, "all_warehouses": true }
Przykład cURL 
curl -s -X PUT '{base_url}/product/KOD-1?warehouse=1' \
  -H 'X-FTToken: TWOJ-TOKEN' \
  -H 'F-service: firmatec_api' \
  -H 'Content-Type: application/json' \
  -d '{"Nazw":"Nazwa przykładowa"}'

# wszystkie magazyny z tym kodem:
curl -s -X PUT '{base_url}/product/KOD-1?all_warehouses=1' \
  -H 'X-FTToken: TWOJ-TOKEN' \
  -H 'F-service: firmatec_api' \
  -H 'Content-Type: application/json' \
  -d '{"Waga":1.5}'
POST /product/{key}/anul

Anulowanie towaru

X-FTToken + F-service

Ustawia Anul=T. Przywrócenie: /restore.

Nagłówki5
NagłówekWymaganyDomyślneOpis
X-FTToken tak — Token firmy
F-service tak — firmatec_api
Accept nie application/json Format odpowiedzi JSON.
Content-Type tak — application/json
Accept-Language nie — pl albo en - język komunikatów błędów

Parametry ścieżki

ParametrTypWymaganyDomyślneOpis
key string tak — ID, Kod albo EAN.

Jak przesłać żądanie

Sposób transportu body (XML albo JSON) — nie mylić z rodzajem dokumentu (VAT, PZ, WZ…).

SposóbOpis
Bez body Wystarczą nagłówki i parametry ścieżki. Body nie jest używane.

Kody błędów

HTTPOpis
403 Brak dostępu. Usługę kupuje się i przedłuża na stronie API w Centrum konfiguracji.
404 Nieprawidłowy token. Token generuje się i zmienia na stronie API w Centrum konfiguracji.

Przykład odpowiedzi

HTTP 200
{ "data": { "ID": "INT.1", "Anul": "T" } }

Przykład cURL

curl -s -X POST '{base_url}/product/INT.1/anul' \
  -H 'X-FTToken: TWOJ-TOKEN' \
  -H 'F-service: firmatec_api'
POST /product/{key}/restore

Przywrócenie towaru

X-FTToken + F-service

Ustawia Anul=N.

Nagłówki5
NagłówekWymaganyDomyślneOpis
X-FTToken tak — Token firmy
F-service tak — firmatec_api
Accept nie application/json Format odpowiedzi JSON.
Content-Type tak — application/json
Accept-Language nie — pl albo en - język komunikatów błędów

Parametry ścieżki

ParametrTypWymaganyDomyślneOpis
key string tak — ID, Kod albo EAN.

Jak przesłać żądanie

Sposób transportu body (XML albo JSON) — nie mylić z rodzajem dokumentu (VAT, PZ, WZ…).

SposóbOpis
Bez body Wystarczą nagłówki i parametry ścieżki. Body nie jest używane.

Kody błędów

HTTPOpis
403 Brak dostępu. Usługę kupuje się i przedłuża na stronie API w Centrum konfiguracji.
404 Nieprawidłowy token. Token generuje się i zmienia na stronie API w Centrum konfiguracji.

Przykład odpowiedzi

HTTP 200
{ "data": { "ID": "INT.1", "Anul": "N" } }

Przykład cURL

curl -s -X POST '{base_url}/product/INT.1/restore' \
  -H 'X-FTToken: TWOJ-TOKEN' \
  -H 'F-service: firmatec_api'
POST /product/substitutes

Powiązanie zamienników

X-FTToken + F-service

Łączy towary w jedną grupę zamienników.
API generuje nowy wspólny IDzam i zapisuje go w polu IDzam każdej wskazanej karty (min. 2 różne towary). Klucze muszą wskazywać jedną kartę (przy kilku magazynach wymagany jest ID).

Nagłówki5
NagłówekWymaganyDomyślneOpis
X-FTToken tak — Token firmy
F-service tak — firmatec_api
Accept nie application/json Format odpowiedzi JSON.
Content-Type tak — application/json
Accept-Language nie — pl albo en - język komunikatów błędów

Body (JSON)

PoleTypWymaganyDomyślneOpis
keys string[] tak — Lista ID (zalecane) albo unikalnych Kodów towarów (min. 2).

Jak przesłać żądanie

Sposób transportu body (XML albo JSON) — nie mylić z rodzajem dokumentu (VAT, PZ, WZ…).

SposóbOpis
JSON Content-Type: application/json. Pola opisane w tabeli Body. Przykład poniżej.

Przykłady żądania

Powiązanie dwóch towarów Min. 2 różne klucze (ID lub unikalny Kod). 
{ "keys": ["KOD-A", "KOD-B"] }

Kody błędów

HTTPOpis
403 Brak dostępu. Usługę kupuje się i przedłuża na stronie API w Centrum konfiguracji.
404 Nie znaleziono jednego z towarów
422 Za mało kluczy

Przykład odpowiedzi

HTTP 200
{ "data": { "IDzam": "Z.…", "products": [ … ] } }

Przykład cURL

curl -s -X POST '{base_url}/product/substitutes' \
  -H 'X-FTToken: TWOJ-TOKEN' \
  -H 'F-service: firmatec_api' \
  -H 'Content-Type: application/json' \
  -d '{"keys":["KOD-A","KOD-B"]}'
GET /product/dict/producer

Producenci — lista

X-FTToken + F-service

Słownik producentów wg słownika w iBiznes. W karcie towaru używane jest pole name. Dodawanie: POST /product/dict/producer.

Nagłówki4
NagłówekWymaganyDomyślneOpis
X-FTToken tak — Token firmy
F-service tak — firmatec_api
Accept nie application/json Format odpowiedzi JSON.
Accept-Language nie — pl albo en - język komunikatów błędów

Kody błędów

HTTPOpis
403 Brak dostępu. Usługę kupuje się i przedłuża na stronie API w Centrum konfiguracji.
404 Nieprawidłowy token. Token generuje się i zmienia na stronie API w Centrum konfiguracji.

Przykład odpowiedzi

HTTP 200
{ "data": [ { "id": "PR.…", "name": "Producent" } ] }

Przykład cURL

curl -s '{base_url}/product/dict/producer' \
  -H 'X-FTToken: TWOJ-TOKEN' \
  -H 'F-service: firmatec_api'
POST /product/dict/producer

Producenci — dodanie

X-FTToken + F-service

Dodaje producenta do słownika iBiznes.
Jeśli nazwa już istnieje (bez względu na wielkość liter), zwraca istniejący rekord z created: false. W towarze używane jest zwrócone name.

Nagłówki5
NagłówekWymaganyDomyślneOpis
X-FTToken tak — Token firmy
F-service tak — firmatec_api
Accept nie application/json Format odpowiedzi JSON.
Content-Type tak — application/json
Accept-Language nie — pl albo en - język komunikatów błędów

Body (JSON)

PoleTypWymaganyDomyślneOpis
name string tak — Nazwa producenta. Najwyżej 250 znaków.

Jak przesłać żądanie

Sposób transportu body (XML albo JSON) — nie mylić z rodzajem dokumentu (VAT, PZ, WZ…).

SposóbOpis
JSON Content-Type: application/json. Pola opisane w tabeli Body. Przykład poniżej.

Przykłady żądania

Dodanie producenta Jeśli nazwa już istnieje — HTTP 200 i created: false. 
{ "name": "Producent" }

Kody błędów

HTTPOpis
403 Brak dostępu. Usługę kupuje się i przedłuża na stronie API w Centrum konfiguracji.
404 Nieprawidłowy token. Token generuje się i zmienia na stronie API w Centrum konfiguracji.
422 Brak name albo nazwa pusta / za długa

Przykład odpowiedzi

HTTP 201 (nowy)
{ "data": { "id": "PR.…", "name": "Producent" }, "created": true }

HTTP 200 (już był)
{ "data": { "id": "PR.…", "name": "Producent" }, "created": false }

Przykład cURL

curl -s -X POST '{base_url}/product/dict/producer' \
  -H 'X-FTToken: TWOJ-TOKEN' \
  -H 'F-service: firmatec_api' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -d '{"name":"Producent"}'
GET /product/dict/group

Grupy towarowe

X-FTToken + F-service

Słownik grup towarowych wg słownika w iBiznes. W karcie towaru używane jest name (nazwa grupy).

Nagłówki4
NagłówekWymaganyDomyślneOpis
X-FTToken tak — Token firmy
F-service tak — firmatec_api
Accept nie application/json Format odpowiedzi JSON.
Accept-Language nie — pl albo en - język komunikatów błędów

Kody błędów

HTTPOpis
403 Brak dostępu. Usługę kupuje się i przedłuża na stronie API w Centrum konfiguracji.
404 Nieprawidłowy token. Token generuje się i zmienia na stronie API w Centrum konfiguracji.

Przykład odpowiedzi

HTTP 200
{ "data": [ { "id": "S.…", "name": "Grupa" } ] }

Przykład cURL

curl -s '{base_url}/product/dict/group' \
  -H 'X-FTToken: TWOJ-TOKEN' \
  -H 'F-service: firmatec_api'
GET /product/dict/unit

Jednostki miary

X-FTToken + F-service

Słownik jednostek miary wg słownika w iBiznes. W polu JM używane jest name (np. szt).

Nagłówki4
NagłówekWymaganyDomyślneOpis
X-FTToken tak — Token firmy
F-service tak — firmatec_api
Accept nie application/json Format odpowiedzi JSON.
Accept-Language nie — pl albo en - język komunikatów błędów

Kody błędów

HTTPOpis
403 Brak dostępu. Usługę kupuje się i przedłuża na stronie API w Centrum konfiguracji.
404 Nieprawidłowy token. Token generuje się i zmienia na stronie API w Centrum konfiguracji.

Przykład odpowiedzi

HTTP 200
{ "data": [ { "id": "JM1", "name": "szt" } ] }

Przykład cURL

curl -s '{base_url}/product/dict/unit' \
  -H 'X-FTToken: TWOJ-TOKEN' \
  -H 'F-service: firmatec_api'
GET /product/dict/warehouse

Magazyny

X-FTToken + F-service

Słownik magazynów wg słownika w iBiznes. W polu MAG używane jest name (np. 1).

Nagłówki4
NagłówekWymaganyDomyślneOpis
X-FTToken tak — Token firmy
F-service tak — firmatec_api
Accept nie application/json Format odpowiedzi JSON.
Accept-Language nie — pl albo en - język komunikatów błędów

Kody błędów

HTTPOpis
403 Brak dostępu. Usługę kupuje się i przedłuża na stronie API w Centrum konfiguracji.
404 Nieprawidłowy token. Token generuje się i zmienia na stronie API w Centrum konfiguracji.

Przykład odpowiedzi

HTTP 200
{ "data": [ { "id": "S.…", "name": "1" } ] }

Przykład cURL

curl -s '{base_url}/product/dict/warehouse' \
  -H 'X-FTToken: TWOJ-TOKEN' \
  -H 'F-service: firmatec_api'
GET /product/dict/vat

Stawki VAT

X-FTToken + F-service

Lista stawek VAT używanych przy zapisie towaru.

Nagłówki4
NagłówekWymaganyDomyślneOpis
X-FTToken tak — Token firmy
F-service tak — firmatec_api
Accept nie application/json Format odpowiedzi JSON.
Accept-Language nie — pl albo en - język komunikatów błędów

Kody błędów

HTTPOpis
403 Brak dostępu. Usługę kupuje się i przedłuża na stronie API w Centrum konfiguracji.
404 Nieprawidłowy token. Token generuje się i zmienia na stronie API w Centrum konfiguracji.

Przykład odpowiedzi

HTTP 200
{ "data": [ { "code": "23", "percent": 23, "st_vat": 2, "label": "23%" } ] }

Przykład cURL

curl -s '{base_url}/product/dict/vat' \
  -H 'X-FTToken: TWOJ-TOKEN' \
  -H 'F-service: firmatec_api'
GET /product/dict/type

Rodzaje towaru

X-FTToken + F-service

Rodzaje pozycji jak w iBiznes (towar, usługa, transport…). W karcie używane jest tylko pole type (id z listy).

Nagłówki4
NagłówekWymaganyDomyślneOpis
X-FTToken tak — Token firmy
F-service tak — firmatec_api
Accept nie application/json Format odpowiedzi JSON.
Accept-Language nie — pl albo en - język komunikatów błędów

Kody błędów

HTTPOpis
403 Brak dostępu. Usługę kupuje się i przedłuża na stronie API w Centrum konfiguracji.
404 Nieprawidłowy token. Token generuje się i zmienia na stronie API w Centrum konfiguracji.

Przykład odpowiedzi

HTTP 200
{ "data": [ { "id": "towar", "name": "Towar" }, { "id": "usluga", "name": "Usługa" } ] }

Przykład cURL

curl -s '{base_url}/product/dict/type' \
  -H 'X-FTToken: TWOJ-TOKEN' \
  -H 'F-service: firmatec_api'
GET /product/dict/currency

Waluty

X-FTToken + F-service

Lista kodów walut.

Nagłówki4
NagłówekWymaganyDomyślneOpis
X-FTToken tak — Token firmy
F-service tak — firmatec_api
Accept nie application/json Format odpowiedzi JSON.
Accept-Language nie — pl albo en - język komunikatów błędów

Kody błędów

HTTPOpis
403 Brak dostępu. Usługę kupuje się i przedłuża na stronie API w Centrum konfiguracji.
404 Nieprawidłowy token. Token generuje się i zmienia na stronie API w Centrum konfiguracji.

Przykład odpowiedzi

HTTP 200
{ "data": [ { "id": "PLN", "name": "PLN" } ] }

Przykład cURL

curl -s '{base_url}/product/dict/currency' \
  -H 'X-FTToken: TWOJ-TOKEN' \
  -H 'F-service: firmatec_api'
GET /product/dict/feature

Cechy towaru

X-FTToken + F-service

Słownik cech towaru wg słownika w iBiznes. W polu cech przekazywana jest tablica {name, value}.

Nagłówki4
NagłówekWymaganyDomyślneOpis
X-FTToken tak — Token firmy
F-service tak — firmatec_api
Accept nie application/json Format odpowiedzi JSON.
Accept-Language nie — pl albo en - język komunikatów błędów

Kody błędów

HTTPOpis
403 Brak dostępu. Usługę kupuje się i przedłuża na stronie API w Centrum konfiguracji.
404 Nieprawidłowy token. Token generuje się i zmienia na stronie API w Centrum konfiguracji.

Przykład odpowiedzi

HTTP 200
{ "data": [ { "id": "o.…", "name": "Cecha" } ] }

Przykład cURL

curl -s '{base_url}/product/dict/feature' \
  -H 'X-FTToken: TWOJ-TOKEN' \
  -H 'F-service: firmatec_api'

Stany magazynowe

GET /stock

Lista stanów

X-FTToken + F-service

Zwraca ilości towarów na stanie.
Tylko karty, które nie zostały anulowane. Usługi nie wchodzą do listy. Jedna karta to jeden magazyn. W wierszu są tylko id, kod, magazyn i ilość z karty towaru.

Nagłówki4
NagłówekWymaganyDomyślneOpis
X-FTToken tak — Token firmy
F-service tak — firmatec_api
Accept nie application/json Format odpowiedzi JSON.
Accept-Language nie — pl albo en - język komunikatów błędów
Parametry query10
ParametrTypWymaganyDomyślneOpis
warehouse string nie — Kod magazynu (pole Mag). Puste oznacza wszystkie magazyny firmy.
page int nie 1 Numer strony.
perpage int nie 20 Liczba kart na stronę. Najwyżej 200.
per_page int nie — To samo co perpage. Używane, gdy perpage nie jest podane.
q string nie — Fragment id, kodu, kodu kreskowego albo nazwy (name i name2).
in_stock int nie — 1 - tylko ilość większa od zera. 0 - bez tego filtra.
group string nie — Grupa towaru, pole Gr.
producer string nie — Producent, pole Pr.
sort_by string nie code Pole sortowania: id, code, warehouse albo quantity.
sort_direction string nie ASC ASC - rosnąco, DESC - malejąco. W odpowiedzi: asc albo desc.

Kody błędów

HTTPOpis
403 Brak dostępu. Usługę kupuje się i przedłuża na stronie API w Centrum konfiguracji.
404 Nieprawidłowy token. Token generuje się i zmienia na stronie API w Centrum konfiguracji.
422 page albo perpage nie jest liczbą, perpage jest większe niż 200, in_stock nie jest 0 albo 1, albo sort_by / sort_direction jest nieznane

Przykład odpowiedzi

HTTP 200
{
  "data": [
    { "id": "TW.RRMMDD.GGMMSS.XXXXXX", "code": "KOD-1", "warehouse": "MAG1", "quantity": 12.5 }
  ],
  "page": 1,
  "per_page": 20,
  "total": 1,
  "sort_by": "code",
  "sort_direction": "asc"
}

Przykład cURL

curl -s '{base_url}/stock?warehouse=MAG1&in_stock=1&page=1&perpage=20&sort_by=quantity&sort_direction=desc' \
  -H 'X-FTToken: TWOJ-TOKEN' \
  -H 'F-service: firmatec_api' \
  -H 'Accept: application/json' \
  -H 'Accept-Language: pl'
GET /stock/{key}

Stan towaru

X-FTToken + F-service

Pobiera jedną kartę towaru.
Szukanie po kolei: id, kod, kod kreskowy. name to nazwa podstawowa, name2 to nazwa w drugim języku. Gdy kod albo kod kreskowy pasuje do kilku kart (różne magazyny), odpowiedź zawiera listę id, kodu, magazynu i ilości oraz multiple: true. Parametr warehouse zawęża to do jednego magazynu.

Nagłówki4
NagłówekWymaganyDomyślneOpis
X-FTToken tak — Token firmy
F-service tak — firmatec_api
Accept nie application/json Format odpowiedzi JSON.
Accept-Language nie — pl albo en - język komunikatów błędów

Parametry query

ParametrTypWymaganyDomyślneOpis
warehouse string nie — Kod magazynu. Zawęża szukanie po kodzie albo kodzie kreskowym do jednego magazynu.

Parametry ścieżki

ParametrTypWymaganyDomyślneOpis
key string tak — Id towaru, kod albo kod kreskowy.

Kody błędów

HTTPOpis
403 Brak dostępu. Usługę kupuje się i przedłuża na stronie API w Centrum konfiguracji.
404 Nie znaleziono towaru albo token jest nieprawidłowy
Przykład odpowiedzi 
HTTP 200
{
  "data": {
    "id": "TW.RRMMDD.GGMMSS.XXXXXX",
    "code": "KOD-1",
    "barcode": "5901234123457",
    "name": "Śruba M8",
    "name2": "Screw M8",
    "warehouse": "MAG1",
    "unit": "szt",
    "quantity": 12.5
  }
}

HTTP 200, kilka kart
{
  "data": [
    { "id": "TW.1", "code": "KOD-1", "warehouse": "MAG1", "quantity": 12.5 },
    { "id": "TW.2", "code": "KOD-1", "warehouse": "MAG2", "quantity": 3 }
  ],
  "multiple": true
}

Przykład cURL

curl -s '{base_url}/stock/KOD-1?warehouse=MAG1' \
  -H 'X-FTToken: TWOJ-TOKEN' \
  -H 'F-service: firmatec_api' \
  -H 'Accept: application/json' \
  -H 'Accept-Language: pl'

Dokumentacja API Firmatec © 2026 Firmatec. Pytania i zgłoszenia: www@firmatec.pl.