Skip to content
API inFakt
Nawigacja

Utwórz fakturę zaliczkową 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/advance_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

  • advance_invoice
    object
    wymagane
    • 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
    • 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
    • vat_date_value
      opcjonalne
      sale_date
      or
      issue_date
      or
      paid_date

      sale_date, issue_date albo paid_date (metoda kasowa).

    • 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
        1
        or
        2
        or
        3
        or
        4
        or
        5
        or
        6
        +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}$
    • 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.

    • advance_date
      opcjonalne
      string
      format: date
    • advance_price
      opcjonalne
      integer

      Otrzymana kwota.

      format: int64
    • previous_advance_id
      opcjonalne
      integer

      Poprzednia faktura zaliczkowa w grupie; pomiń przy pierwszej zaliczce. Gdy jest podana, a żadna pozycja nie ma related_id, pozycje są zastępowane pozycjami ostatniej zaliczki w grupie.

      format: int64

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

Type to search…

↑↓ wybór↵ otwórzEsc zamyka