Utwórz fakturę OSS 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/oss_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

oss_invoice
object
wymagane
- country
  string
  wymagane
  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}$
- service_date
  string
  wymagane
  format: date
- issue_date
  string
  wymagane
  format: date
- sale_type
  merchandise
  or
  service
  wymagane
- number
  opcjonalne
  string
- check_duplicate_number
  opcjonalne
  boolean
- client_email
  opcjonalne
  string
- client_name
  opcjonalne
  string
  Wymagane, chyba że podano client_first_name i client_last_name.
- client_first_name
  opcjonalne
  string
- client_last_name
  opcjonalne
  string
- client_street
  opcjonalne
  string
- client_street_number
  opcjonalne
  string
- client_flat_number
  opcjonalne
  string
- client_post_code
  opcjonalne
  string
- client_city
  opcjonalne
  string
- payment_date
  opcjonalne
  string
  Nie później niż service_date. Domyślnie dzisiaj.
  
  format: date
- service_type
  opcjonalne
  string
  Wymagane dla sale_type: service, np. electronic.
- service_place_primary
  opcjonalne
  string
- service_place_secondary
  opcjonalne
  string
- currency
  opcjonalne
  string
- seller_signature
  opcjonalne
  string
- recipient_signature
  opcjonalne
  string
- notes
  opcjonalne
  string
- advance_price
  opcjonalne
  integer
  Kwota w groszach (1/100 PLN). 12300 oznacza 123,00 PLN.
  
  format: int64
- services
  opcjonalne
  array of
  object
  name
  string
  wymagane
  unit
  opcjonalne
  string
  quantity
  opcjonalne
  number
  format: double
  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
  tax_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
  additional_price
  opcjonalne
  integer
  Kwota w groszach (1/100 PLN). 12300 oznacza 123,00 PLN.
  
  format: int64
  tax_rate
  opcjonalne
  number
  Stawka VAT kraju konsumenta, w procentach. Zobacz GET /moss_vat_rates.json.
  
  format: double
  flat_rate_tax_symbol
  opcjonalne
  string
  Symbol stawki ryczałtu; wymagany u ryczałtowców, u pozostałych odrzucany.
}

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

curl --request POST \ --url https://api.sandbox-infakt.pl/v3/async/oss_invoices.json \ --header 'Content-Type: application/json' \ --header 'X-inFakt-ApiKey: <X-inFakt-ApiKey>' \ --data ' { "oss_invoice": { "number": "string", "check_duplicate_number": true, "country": "PL", "client_email": "string", "client_name": "string", "client_first_name": "string", "client_last_name": "string", "client_street": "string", "client_street_number": "string", "client_flat_number": "string", "client_post_code": "string", "client_city": "string", "service_date": "2019-08-24", "issue_date": "2019-08-24", "payment_date": "2019-08-24", "service_type": "string", "service_place_primary": "string", "service_place_secondary": "string", "currency": "string", "seller_signature": "string", "recipient_signature": "string", "notes": "string", "advance_price": 12300, "sale_type": "merchandise", "services": [ { "name": "string", "unit": "string", "quantity": 0.1, "unit_net_price": 12300, "net_price": 12300, "tax_price": 12300, "gross_price": 12300, "additional_price": 12300, "tax_rate": 0.1, "flat_rate_tax_symbol": "string" } ] } } '

{ "invoice_task_reference_number": "4f6a8c1e-2b3d-4e5f-9a7b-8c9d0e1f2a3b", "processing_code": 100, "processing_description": "Zlecenie przyjęte", "action": "create_invoice", "invoice_kind": "oss_invoice", "timestamps": { "task_created_at": "2026-10-02 12:00:00 +0200" } }