Utwórz fakturę asynchronicznie

Zakres: api:invoices:write. Kolejkuje utworzenie dokumentu i zwraca zadanie. Treść żądania jest taka sama jak w synchronicznym endpoincie tworzenia.

POST

https://api.sandbox-infakt.pl/v3/async/invoices.json

Autoryzacja

ApiKey
opcjonalne
API key in header

Token
opcjonalne
API key in header

Query parameters

send_to_ksef
opcjonalne
boolean
Wyślij dokument do KSeF po utworzeniu.
allow_correction
opcjonalne
boolean
Potwierdź akcję, która skoryguje złożone deklaracje (zamknięty okres księgowy). Bez tego takie żądania zwracają 422 z errors.allow_correction albo errors.locked_accounting, gdy plan nie pozwala na korekty (wtedy ta flaga jest ignorowana). Można też podać w treści żądania.

Treść żądania JSON required

invoice

object

wymagane

invoice_date domyślnie to dzisiejsza data, a payment_date to invoice_date plus termin płatności klienta lub konta. client_company_name (albo client_first_name i client_last_name dla osób prywatnych) oraz client_city są wymagane, chyba że rodzaj faktury nie ma klienta. sales_kind domyślnie ma wartość sprzedaz_podstawowa. vat_exchange_date_kind domyślnie pochodzi z ustawień konta i jest wymagane dla walut obcych.

number
opcjonalne
string
check_duplicate_number
opcjonalne
boolean
Odrzuć żądanie, gdy istnieje faktura o tym samym numerze.
kind
opcjonalne
vat
or
proforma
or
margin
or
advance
or
correction
or
margin_correction
+5 more
currency
opcjonalne
string
paid_price
opcjonalne
integer
Kwota w groszach (1/100 PLN). 12300 oznacza 123,00 PLN.

format: int64
left_to_pay
opcjonalne
integer
Kwota w groszach (1/100 PLN). 12300 oznacza 123,00 PLN.

format: int64
notes
opcjonalne
string
maxLength: 5000
payment_method
opcjonalne
transfer
or
cash
or
card
or
barter
or
check
or
delivery
+11 more
Metoda płatności.
split_payment
opcjonalne
boolean
split_payment_type
opcjonalne
required
or
optional
recipient_signature
opcjonalne
string
maxLength: 255
seller_signature
opcjonalne
string
maxLength: 255
invoice_date
opcjonalne
string
format: date
sale_date
opcjonalne
string
format: date
vat_date_value
opcjonalne
sale_date
or
issue_date
or
paid_date
sale_date, issue_date albo paid_date (metoda kasowa).
continuous_service_start_on
opcjonalne
string
format: date
continuous_service_end_on
opcjonalne
string
format: date
occasional_sale
opcjonalne
boolean
payment_date
opcjonalne
string
format: date
paid_date
opcjonalne
string
format: date
client_id
opcjonalne
integer
ID istniejącego klienta; niewysłane pola klienta są z niego kopiowane. Bez client_id klient jest dopasowywany po client_tax_code, client_company_name albo client_first_name i client_last_name (zawężonych przez client_business_activity_kind), a gdy nie ma dopasowania, jest tworzony z pól client_*.

format: int64
client_company_name
opcjonalne
string
client_first_name
opcjonalne
string
client_last_name
opcjonalne
string
client_business_activity_kind
opcjonalne
private_person
or
self_employed
or
other_business
Forma prawna klienta.
client_street
opcjonalne
string
client_street_number
opcjonalne
string
client_flat_number
opcjonalne
string
client_city
opcjonalne
string
client_post_code
opcjonalne
string
client_tax_code
opcjonalne
string
client_country
opcjonalne
string
Dwuliterowy kod kraju jak alpha_2 w GET /countries.json: ISO 3166-1 alpha-2, z wyjątkiem EL dla Grecji (GR nie jest rozpoznawany) i XI dla Irlandii Północnej.

pattern: ^[A-Z]{2}$
bank_account
opcjonalne
string
Musi być jednym z kont bankowych użytkownika (GET /bank_accounts.json); pominięty swift jest brany z tego konta.
bank_name
opcjonalne
string
swift
opcjonalne
string
vat_exemption_reason
opcjonalne
integer
Wymagane, gdy pozycja ma stawkę VAT zw.

format: int64
sale_type
opcjonalne
service
or
merchandise
Wymagane dla klientów zagranicznych i sprzedaży z odwrotnym obciążeniem; ignorowane przy sprzedaży krajowej.
invoice_date_kind
opcjonalne
sale_date
or
service_date
or
cargo_date
or
continuous_service_end_on
Rodzaj daty drukowanej obok daty sprzedaży.
document_markings_ids
opcjonalne
array of
string
Najwyżej jedno ID oznaczenia dokumentu. Zobacz GET /incomes_documents_markings.json.
transaction_kind_id
opcjonalne
integer
format: int64
bdo_code
opcjonalne
string
Dziewięć cyfr.

pattern: ^\d{9}$
receipt_number
opcjonalne
string
not_income
opcjonalne
boolean
vat_exchange_date_kind
opcjonalne
pit
or
vat
sales_kind
opcjonalne
sprzedaz_podstawowa
or
sprzedaz_pozostala
ksef_number
opcjonalne
string
transaction_terms
opcjonalne
object
- contracts
  opcjonalne
  array of
  object
  number
  string
  wymagane
  date
  string
  wymagane
  format: date
- orders
  opcjonalne
  array of
  object
  number
  string
  wymagane
  date
  string
  wymagane
  format: date
}
local_government_recipient_address
opcjonalne
object
Przy aktualizacji pominięcie tego pola usuwa istniejący adres.
- company_name
  string
  wymagane
- street
  string
  wymagane
  maxLength: 65
- building_number
  string
  wymagane
  maxLength: 9
- city
  string
  wymagane
- tax_id
  opcjonalne
  string
  NIP.
- door_number
  opcjonalne
  string
  maxLength: 10
- post_code
  opcjonalne
  string
- country_id
  opcjonalne
  integer
  Liczbowe ID kraju (GET /countries.json); domyślnie Polska.
  
  format: int64
}
local_government_seller_address
opcjonalne
object
Domyślnie adres z ustawień konta, gdy jego wyświetlanie na fakturach jest włączone.
- company_name
  string
  wymagane
- street
  string
  wymagane
  maxLength: 65
- building_number
  string
  wymagane
  maxLength: 9
- city
  string
  wymagane
- tax_id
  opcjonalne
  string
  NIP.
- door_number
  opcjonalne
  string
  maxLength: 10
- post_code
  opcjonalne
  string
- country_id
  opcjonalne
  integer
  Liczbowe ID kraju (GET /countries.json); domyślnie Polska.
  
  format: int64
}

third_party_addresses

opcjonalne

array of

object

Podmioty trzecie w KSeF. Ignorowane przez POST /invoices.json; uwzględniane przy aktualizacji i przy tworzeniu asynchronicznym. Przy aktualizacji wpisy bez id są dodawane, a niewysłane istniejące adresy zostają.

id
opcjonalne
integer
Tylko przy aktualizacji: ID istniejącego adresu do zmiany lub usunięcia.

format: int64
_destroy
opcjonalne
boolean
Tylko przy aktualizacji: usuń adres wskazany w id.
company_name
opcjonalne
string
Wymagane, chyba że _destroy ma wartość true.
tax_id
opcjonalne
string
street
opcjonalne
string
building_number
opcjonalne
string
door_number
opcjonalne
string
post_code
opcjonalne
string
city
opcjonalne
string
country_code
opcjonalne
string
Kod kraju alpha-2; ma pierwszeństwo przed country_id.

pattern: ^[A-Z]{2}$
country_id
opcjonalne
integer
Liczbowe ID kraju (GET /countries.json).

format: int64

role_code

opcjonalne

+5 more

Rola podmiotu trzeciego w KSeF (Podmiot3), wymagana, chyba że _destroy ma wartość true:

Kod	Rola
`1`	Faktor
`2`	Odbiorca
`3`	Podmiot pierwotny
`4`	Dodatkowy nabywca
`5`	Wystawca faktury
`6`	Dokonujący płatności
`7`	JST – wystawca
`8`	JST – odbiorca
`9`	Członek grupy VAT – wystawca
`10`	Członek grupy VAT – odbiorca
`11`	Pracownik

internal_identifier
opcjonalne
string
Identyfikator wewnętrzny, np. 1234567890-00001.

pattern: ^[1-9]((\d[1-9])|([1-9]\d))\d{7}-\d{5}$

scheduled_dates
opcjonalne
array of
string
W POST /invoices.json liczy się tylko najwcześniejsza data: gdy wszystkie daty są w przyszłości, staje się ona invoice_date i powstaje jedna faktura draft.

format: date
allow_correction
opcjonalne
boolean
Potwierdź zmianę, która skoryguje złożone deklaracje; działa jak parametr zapytania allow_correction.
services
opcjonalne
array of
object
Przy aktualizacji wysłana lista zastępuje wszystkie pozycje.
- name
  string
  wymagane
- tax_symbol
  string
  wymagane
  Symbol stawki VAT. Zobacz GET /vat_rates.json.
- unit
  opcjonalne
  string
- quantity
  opcjonalne
  number
  format: double · default: 1
- unit_net_price
  opcjonalne
  integer
  Kwota w groszach (1/100 PLN). 12300 oznacza 123,00 PLN.
  
  format: int64
- net_price
  opcjonalne
  integer
  Kwota w groszach (1/100 PLN). 12300 oznacza 123,00 PLN.
  
  format: int64
- gross_price
  opcjonalne
  integer
  Kwota w groszach (1/100 PLN). 12300 oznacza 123,00 PLN.
  
  format: int64
- tax_price
  opcjonalne
  integer
  Kwota w groszach (1/100 PLN). 12300 oznacza 123,00 PLN.
  
  format: int64
- symbol
  opcjonalne
  string
- pkwiu
  opcjonalne
  string
- cn
  opcjonalne
  string
- pkob
  opcjonalne
  string
- gtin
  opcjonalne
  string
- flat_rate_tax_symbol
  opcjonalne
  string
  Stawka ryczałtu; domyślnie z ustawień konta. Używana tylko u podatników na ryczałcie.
- discount
  opcjonalne
  number
  Rabat w procentach.
  
  format: double · default: 0
- unit_net_price_before_discount
  opcjonalne
  integer
  Kwota w groszach (1/100 PLN). 12300 oznacza 123,00 PLN.
  
  format: int64
- gtu_id
  opcjonalne
  integer
  format: int64
- related_id
  opcjonalne
  integer
  Faktury zaliczkowe i końcowe: ID pozycji z poprzedniej faktury zaliczkowej, którą kontynuuje ta pozycja.
  
  format: int64
- user_calculated
  opcjonalne
  boolean
  Zachowaj wysłane kwoty bez przeliczania niespójnych wartości.
}

Example request

{
  "invoice": {
    "kind": "vat",
    "payment_method": "transfer",
    "invoice_date": "2026-10-01",
    "sale_date": "2026-10-01",
    "payment_date": "2026-10-15",
    "client_id": 1003,
    "bank_account": "61109010140000071219812874",
    "services": [
      {
        "name": "Usługa programistyczna",
        "tax_symbol": "23",
        "unit": "godz.",
        "quantity": 1,
        "unit_net_price": 10000,
        "pkwiu": "62.01.11.0"
      }
    ]
  }
}

Odpowiedzi

201

Utworzono

JSON

invoice_task_reference_number
string
wymagane
Uuid zadania; użyj go w endpoincie statusu.

format: uuid
processing_code
integer
wymagane
100 zainicjowane, 120 oczekuje, 140 w trakcie, 201 faktura utworzona, 200 akcja wykonana, 422 błąd (zobacz invoice_errors).

format: int32
action
create_invoice
or
mark_as_paid
wymagane
create_invoice albo mark_as_paid.
timestamps
object
wymagane
- task_created_at
  string
  wymagane
}
processing_description
opcjonalne
string
invoice_kind
opcjonalne
string
invoice_errors
opcjonalne
Błędy, gdy processing_code to 422: błędy pól według nazwy pola w API (lista albo pojedynczy komunikat, np. {"status": "Faktura już została oznaczona jako zapłacona."}) albo zwykły komunikat przy nieoczekiwanych błędach.
One of the following:
object
string
}
invoice_uuid
opcjonalne
string
Ustawiane, gdy faktura już istnieje.

format: uuid

401

Brak klucza API, nieprawidłowy klucz albo klucz bez wymaganego zakresu uprawnień.

JSON

error
opcjonalne
Komunikat po polsku (po angielsku dla 429). Niektóre akcje zamiast jednego tekstu zwracają listę komunikatów albo błędy walidacji według pól.
One of the following:
string
array<string>
object
}
errors
opcjonalne
Błędy walidacji według nazw pól API; na niektórych endpointach zwykły komunikat.
One of the following:
object
string
}
limit
opcjonalne
string
Kod limitu planu, np. limit_exceeded, plan_upgrade_needed, cant_add_client.
type
opcjonalne
redirect
or
email_not_confirmed
url
opcjonalne
string
action_url
opcjonalne
string

402

API niedostępne w obecnym planie (limit: plan_upgrade_needed) albo osiągnięty limit dokumentów.

JSON

error
opcjonalne
Komunikat po polsku (po angielsku dla 429). Niektóre akcje zamiast jednego tekstu zwracają listę komunikatów albo błędy walidacji według pól.
One of the following:
string
array<string>
object
}
errors
opcjonalne
Błędy walidacji według nazw pól API; na niektórych endpointach zwykły komunikat.
One of the following:
object
string
}
limit
opcjonalne
string
Kod limitu planu, np. limit_exceeded, plan_upgrade_needed, cant_add_client.
type
opcjonalne
redirect
or
email_not_confirmed
url
opcjonalne
string
action_url
opcjonalne
string

406

Ścieżka nie kończy się na .json.

JSON

error
opcjonalne
Komunikat po polsku (po angielsku dla 429). Niektóre akcje zamiast jednego tekstu zwracają listę komunikatów albo błędy walidacji według pól.
One of the following:
string
array<string>
object
}
errors
opcjonalne
Błędy walidacji według nazw pól API; na niektórych endpointach zwykły komunikat.
One of the following:
object
string
}
limit
opcjonalne
string
Kod limitu planu, np. limit_exceeded, plan_upgrade_needed, cant_add_client.
type
opcjonalne
redirect
or
email_not_confirmed
url
opcjonalne
string
action_url
opcjonalne
string

422

Nie utworzono zadania; szczegóły w errors.

JSON

errors
object
wymagane

423

Niepotwierdzony adres e-mail albo wymagana weryfikacja tożsamości.

JSON

error
opcjonalne
Komunikat po polsku (po angielsku dla 429). Niektóre akcje zamiast jednego tekstu zwracają listę komunikatów albo błędy walidacji według pól.
One of the following:
string
array<string>
object
}
errors
opcjonalne
Błędy walidacji według nazw pól API; na niektórych endpointach zwykły komunikat.
One of the following:
object
string
}
limit
opcjonalne
string
Kod limitu planu, np. limit_exceeded, plan_upgrade_needed, cant_add_client.
type
opcjonalne
redirect
or
email_not_confirmed
url
opcjonalne
string
action_url
opcjonalne
string

429

Przekroczony limit zapytań. Komunikat jest po angielsku, np. API rate limit exceeded. Try again in 60 seconds.

JSON

error
opcjonalne
Komunikat po polsku (po angielsku dla 429). Niektóre akcje zamiast jednego tekstu zwracają listę komunikatów albo błędy walidacji według pól.
One of the following:
string
array<string>
object
}
errors
opcjonalne
Błędy walidacji według nazw pól API; na niektórych endpointach zwykły komunikat.
One of the following:
object
string
}
limit
opcjonalne
string
Kod limitu planu, np. limit_exceeded, plan_upgrade_needed, cant_add_client.
type
opcjonalne
redirect
or
email_not_confirmed
url
opcjonalne
string
action_url
opcjonalne
string