Zaktualizuj fakturę marża

Zakres: api:invoices:write.

PUT

https://api.sandbox-infakt.pl/v3/margin_invoices/{uuid}.json

Autoryzacja

ApiKey
opcjonalne
API key in header

Token
opcjonalne
API key in header

Path parameters

uuid
string
wymagane
format: uuid

Query parameters

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

margin_invoice

object

wymagane

number
opcjonalne
string
check_duplicate_number
opcjonalne
boolean
Odrzuć żądanie, gdy istnieje faktura o tym samym numerze.
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.
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).
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
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.
bdo_code
opcjonalne
string
Dziewięć cyfr.

pattern: ^\d{9}$
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}$

allow_correction
opcjonalne
boolean
Potwierdź zmianę, która skoryguje złożone deklaracje; działa jak parametr zapytania allow_correction.
margin_kind
opcjonalne
second_hand_goods
or
travel_agencies
or
works_of_art
or
collectables_and_antiques
Domyślnie second_hand_goods.
services
opcjonalne
array of
object
Wymagana jest co najmniej jedna pozycja. Przy aktualizacji wysłana lista zastępuje wszystkie pozycje.
- name
  string
  wymagane
- gtu_id
  opcjonalne
  integer
  format: int64
- unit
  opcjonalne
  string
- quantity
  opcjonalne
  number
  format: double · default: 1
- gross_with_margin_amount_price
  opcjonalne
  integer
  Cena sprzedaży z marżą.
  
  format: int64
- margin_amount_price
  opcjonalne
  integer
  Kwota marży; VAT nalicza się od niej według stawki podstawowej.
  
  format: int64
- flat_rate_tax_symbol
  opcjonalne
  string
}

Example request

{
  "margin_invoice": {
    "client_id": 1003,
    "margin_kind": "second_hand_goods",
    "invoice_date": "2026-10-01",
    "sale_date": "2026-10-01",
    "payment_date": "2026-10-15",
    "payment_method": "transfer",
    "services": [
      {
        "name": "Samochód osobowy używany",
        "unit": "szt.",
        "quantity": 1,
        "gross_with_margin_amount_price": 1500000,
        "margin_amount_price": 300000
      }
    ]
  }
}

Odpowiedzi

200

Sukces

JSON

id
integer
wymagane
format: int64
uuid
string
wymagane
format: uuid
number
string
wymagane
currency
string
wymagane
Kod ISO 4217.
paid_price
integer
wymagane
Kwota w groszach (1/100 PLN). 12300 oznacza 123,00 PLN.

format: int64
kind
vat
or
proforma
or
margin
or
advance
or
correction
or
margin_correction
+5 more
wymagane
payment_method
wymagane
One of the following:
PaymentMethod
null
}
recipient_signature
string
wymagane
seller_signature
string
wymagane
invoice_date
string
wymagane
format: date
sale_date
wymagane
One of the following:
string
null
}
vat_date_value
string
wymagane
Data powstania obowiązku VAT: sale_date, issue_date albo paid_date (metoda kasowa).
occasional_sale
boolean
wymagane
status
draft
or
sent
or
printed
or
unpaid
or
paid
or
scheduled
wymagane
payment_date
wymagane
One of the following:
string
null
}
paid_date
wymagane
One of the following:
string
null
}
gross_price
integer
wymagane
Kwota w groszach (1/100 PLN). 12300 oznacza 123,00 PLN.

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

format: int64
client_id
wymagane
One of the following:
integer
null
}
client_uuid
wymagane
One of the following:
Uuid
null
}
client_company_name
wymagane
One of the following:
string
null
}
client_first_name
wymagane
One of the following:
string
null
}
client_last_name
wymagane
One of the following:
string
null
}
client_business_activity_kind
wymagane
One of the following:
BusinessActivityKind
null
}
client_street
wymagane
One of the following:
string
null
}
client_street_number
wymagane
One of the following:
string
null
}
client_flat_number
wymagane
One of the following:
string
null
}
client_city
wymagane
One of the following:
string
null
}
client_post_code
wymagane
One of the following:
string
null
}
client_tax_code
string
wymagane
client_country
wymagane
One of the following:
CountryCode
null
}
sale_type
service
or
merchandise
or
wymagane
Tylko transakcje zagraniczne; w pozostałych "".
invoice_date_kind
wymagane
One of the following:
InvoiceDateKind
null
}
document_markings_ids
wymagane
ID oznaczeń dokumentu jako stringi. Zobacz GET /incomes_documents_markings.json.
One of the following:
array<string>
null
}
bdo_code
wymagane
One of the following:
string
null
}
not_income
wymagane
One of the following:
boolean
null
}
vat_exchange_date_kind
wymagane
One of the following:
string
null
}
sales_kind
sprzedaz_podstawowa
or
sprzedaz_pozostala
wymagane
amount_in_words
wymagane
One of the following:
string
null
}
local_government_recipient_address
wymagane
One of the following:
LocalGovernmentAddress
company_name
wymagane
One of the following:
string
null
nip
wymagane
One of the following:
string
null
street
wymagane
One of the following:
string
null
street_number
wymagane
One of the following:
string
null
flat_number
wymagane
One of the following:
string
null
postal_code
wymagane
One of the following:
string
null
city
wymagane
One of the following:
string
null
country
wymagane
One of the following:
CountryCode
null
null
}
third_party_addresses
array of
object
wymagane
- id
  integer
  wymagane
  format: int64
- company_name
  wymagane
  One of the following:
  string
  null
- tax_id
  wymagane
  One of the following:
  string
  null
- street
  wymagane
  One of the following:
  string
  null
- building_number
  wymagane
  One of the following:
  string
  null
- door_number
  wymagane
  One of the following:
  string
  null
- post_code
  wymagane
  One of the following:
  string
  null
- city
  wymagane
  One of the following:
  string
  null
- country_code
  wymagane
  One of the following:
  CountryCode
  null
- role_code
  wymagane
  Kod roli podmiotu trzeciego w KSeF; zobacz ThirdPartyAddressInput.role_code.
  
  One of the following:
  string
  null
- internal_identifier
  wymagane
  One of the following:
  string
  null
}
building_service
boolean
wymagane
created_at
string
wymagane
format: date-time
ksef_number
wymagane
One of the following:
string
null
}
transaction_terms
wymagane
One of the following:
TransactionTerms
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
null
}
notes
wymagane
One of the following:
string
null
}
ksef_data
wymagane
One of the following:
InvoiceKsefData
request_uuid
wymagane
null dla faktur odrzuconych przed wysyłką.

One of the following:
string
null
ksef_number
wymagane
Numer KSeF nadany po przyjęciu.

One of the following:
string
null
status
pending
or
sent
or
success
or
error
or
cancelled
or
rejected
wymagane
rejected tylko w odpowiedziach zbiorczych, dla dokumentów, których w ogóle nie wysłano.

status_description
wymagane
One of the following:
string
null
timestamps
object
wymagane
request_created_at
string
wymagane
request_finished_at
wymagane
One of the following:
string
null
KsefSendError
status
error
wymagane
status_description
string
wymagane
null
}
related_exchange_differences_internal_evidences
array of
object
wymagane
- id
  integer
  wymagane
  format: int64
- number
  string
  wymagane
- uuid
  string
  wymagane
  format: uuid
}
margin_kind_id
integer
wymagane
format: int64
margin_kind
string
wymagane
Nazwa procedury marży po polsku.
margin_kind_symbol
second_hand_goods
or
travel_agencies
or
works_of_art
or
collectables_and_antiques
wymagane
margin_amount_price
integer
wymagane
Łączna marża.

format: int64
bank_account
wymagane
Ustawione tylko dla metod płatności transfer i accredited.
One of the following:
string
null
}
bank_name
wymagane
One of the following:
string
null
}
swift
wymagane
One of the following:
string
null
}
services
array of
object
wymagane
- id
  integer
  wymagane
  format: int64
- name
  string
  wymagane
- gtu_id
  wymagane
  One of the following:
  integer
  null
- unit
  string
  wymagane
  "", gdy nie ustawiono.
- quantity
  number
  wymagane
  format: double
- gross_with_margin_amount_price
  integer
  wymagane
  Cena sprzedaży z marżą.
  
  format: int64
- margin_amount_price
  integer
  wymagane
  Kwota marży.
  
  format: int64
- flat_rate_tax_symbol
  opcjonalne
  Tylko u podatników na ryczałcie.
  
  One of the following:
  string
  null
}
previous_invoice_uuid
opcjonalne
Tylko w odpowiedzi get.
One of the following:
Uuid
null
}
following_invoice_uuid
opcjonalne
Tylko w odpowiedzi get.
One of the following:
Uuid
null
}
client_vat_number_active
opcjonalne
Tylko w odpowiedzi get. Numer VAT klienta jest czynny w rejestrze VAT.
One of the following:
boolean
null
}
show_sales_kind
opcjonalne
boolean
Tylko w odpowiedzi get.
exchange_rates_data
opcjonalne
Tylko w odpowiedzi get; null dla faktur w PLN.
One of the following:
ExchangeRatesData
vat_exchange_table_number
wymagane
One of the following:
string
null
vat_exchange_date
wymagane
One of the following:
string
null
pit_exchange_table_number
wymagane
One of the following:
string
null
pit_exchange_date
wymagane
One of the following:
string
null
exchange_vat_rate
string
wymagane
Kurs z przecinkiem dziesiętnym, np. 4,2512.

exchange_pit_rate
string
wymagane
Kurs z przecinkiem dziesiętnym, np. 4,2512.

null
}
statuses
opcjonalne
array of
object
Tylko w odpowiedzi get.
- symbol
  string
  wymagane
- name
  string
  wymagane
- group
  string
  wymagane
}
parent_invoice_data
opcjonalne
Tylko w odpowiedzi get. null, chyba że faktura VAT lub zaliczkowa została wystawiona z innego dokumentu.
One of the following:
ParentInvoiceData
uuid
string
wymagane
format: uuid
number
string
wymagane
gross_price
integer
wymagane
Kwota w groszach (1/100 PLN). 12300 oznacza 123,00 PLN.

format: int64
invoice_date
string
wymagane
format: date
null
}

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

404

Nie znaleziono zasobu.

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

Walidacja nie powiodła się; szczegóły w errors.

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

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