Upravit doklad
PATCH/invoices/{id}
Částečná úprava (JSON Merge Patch): neuvedená pole zůstanou beze změny.
Oprávnění klíče: invoices:write
Parametry
idintegerpovinnécestaID záznamu.
- Minimum:
1
If-MatchstringhlavičkaETag záznamu, jak jste ho naposledy přečetli. Když se záznam mezitím změnil, API změnu odmítne s 412 a nic neprovede. Bez hlavičky se změna provede vždy.
Tělo požadavku
doc_typestringTyp dokladu. Doklady s DPH vyžadují, aby firma byla plátce DPH. Hodnoty: invoice_vat – faktura – daňový doklad; invoice_non_vat – faktura neplátce DPH; credit_note – opravný daňový doklad (dobropis); reverse_charge – faktura s přenesenou daňovou povinností; proforma – zálohová faktura; advance – daňový doklad k přijaté platbě; quote_vat – nabídka s DPH; quote_non_vat – nabídka bez DPH.
- Výchozí:
invoice_non_vat
issue_datedateDatum vystavení. Výchozí dnešní den.
supply_datedateDatum uskutečnění zdanitelného plnění (DUZP). Výchozí datum vystavení.
due_datedateDatum splatnosti. Výchozí 14 dní od vystavení.
contact_idintegerID kontaktu odběratele. Pokud chybí customer, odběratel se převezme z kontaktu.
customerPartyOdběratel. Bez contact_id se existující kontakt najde podle IČO, bez IČO podle názvu; jinak se založí nový.
Vnořená pole 10
namestringNázev firmy nebo jméno osoby.
- Max. znaků:
190
company_nostring | nullIČO. Mezery se odstraní.
- Max. znaků:
20
vat_nostring | nullDIČ.
- Max. znaků:
30
streetstring | nullUlice a číslo.
- Max. znaků:
190
citystring | nullObec.
- Max. znaků:
120
zipstring | nullPSČ.
- Max. znaků:
20
countrystring | nullKód země ISO 3166-1 alpha-2. Výchozí CZ.
- Výchozí:
CZ - Vzorec:
^[A-Za-z]{2}$
emailemail | nullE-mail; použije se jako výchozí příjemce faktury.
- Max. znaků:
190
phonestring | nullTelefon.
- Max. znaků:
40
webstring | nullWeb.
- Max. znaků:
190
bank_account_idinteger | nullID bankovního účtu firmy, který se vytiskne na doklad. Když ho při vytvoření dokladu placeného převodem neuvedete, použije se výchozí účet firmy jako v aplikaci; null doklad vytvoří bez účtu.
payment_methodstringZpůsob úhrady. Hodnoty: bank_transfer – bankovní převod; cash – hotovost; cash_on_delivery – dobírka; card – platební karta; paypal – PayPal; mutual_offset – vzájemný zápočet.
- Výchozí:
bank_transfer
currencystringMěna ISO 4217.
- Výchozí:
CZK - Vzorec:
^[A-Z]{3}$
exchange_ratedecimalKurz k CZK. U CZK musí být 1, u jiné měny kurz ČNB ke dni zdanitelného plnění (1 se odmítne).
- Vzorec:
^-?\d{1,12}(\.\d{1,8})?$
languagestringJazyk dokladu. Hodnoty: cs – cs; sk – sk; en – en; de – de; de-AT – de-AT; pl – pl; fr – fr; nl – nl; es – es; uk – uk; sr – sr.
- Výchozí:
cs
vat_treatmentstringRežim DPH. Výchozí podle toho, zda je firma plátce DPH. Hodnoty: domestic – tuzemské plnění; non_payer – neplátce DPH; eu_goods – dodání zboží do EU; eu_services – služby do EU; domestic_reverse_charge – tuzemské přenesení daňové povinnosti; export – vývoz mimo EU; oss – prodej spotřebiteli v jiném státě EU v režimu OSS (sazba státu spotřeby, vyžaduje registraci k OSS).
roundingstringZaokrouhlení celkové částky. Hodnoty: none – bez zaokrouhlení; 0.10 – na desetníky; 0.50 – na padesátníky; 1.00 – na celé koruny.
- Výchozí:
none
templatestringVzhled PDF. Hodnoty: modern – moderní; simple – jednoduchý; custom – vlastní.
- Výchozí:
modern
colorstringBarva dokladu #RRGGBB. Výchozí barva firmy.
- Vzorec:
^#[0-9A-Fa-f]{6}$
show_qrbooleanTisknout QR platbu.
- Výchozí:
true
prices_include_vatbooleanJednotkové ceny jsou včetně DPH.
- Výchozí:
false
discount_pctdecimalSleva na celý doklad v procentech (0–100, nejvýše 2 desetinná místa).
- Vzorec:
^-?\d{1,12}(\.\d{1,8})?$
issued_bystringKdo doklad vystavil.
- Max. znaků:
120
notestringPoznámka na dokladu.
- Max. znaků:
10000
reg_numberstringEvidenční číslo.
- Max. znaků:
40
order_numberstringČíslo objednávky odběratele.
- Max. znaků:
60
variable_symbolstringVariabilní symbol, nejvýše 10 číslic. Při vystavení se jinak odvodí z čísla dokladu.
- Vzorec:
^\d{0,10}$
constant_symbolstringKonstantní symbol.
- Max. znaků:
10
specific_symbolstringSpecifický symbol.
- Max. znaků:
20
Položky dokladu (1–500).
- Min. položek:
1 - Max. položek:
500
Vnořená pole 6
descriptionstringpovinné v objektuPopis položky.
- Max. znaků:
500
quantitydecimalMnožství, nejvýše 4 desetinná místa. Nesmí být 0; záporné jen u opravného dokladu. Výchozí 1.
- Vzorec:
^-?\d{1,12}(\.\d{1,8})?$
unitstringJednotka, například ks, hod. Výchozí ks.
- Max. znaků:
20
Jednotková cena, nejvýše 4 desetinná místa. Podle prices_include_vat bez DPH, nebo s DPH.
- Vzorec:
^-?\d{1,12}(\.\d{1,8})?$
vat_ratedecimalSazba DPH v procentech (0–100). U dokladů neplátce a přenesené daňové povinnosti se použije 0.
- Vzorec:
^-?\d{1,12}(\.\d{1,8})?$
discount_pctdecimalSleva na položku v procentech (0–100, nejvýše 2 desetinná místa). Uplatní se před slevou na celý doklad. Výchozí 0.
- Vzorec:
^-?\d{1,12}(\.\d{1,8})?$
correction_reasonstring | nullDůvod opravy u opravného daňového dokladu (credit_note). Při vystavení je povinný.
- Max. znaků:
255
reverse_charge_codestring | nullPředmět plnění při tuzemském přenesení daňové povinnosti (vat_treatment = domestic_reverse_charge), kód podle § 92a ZDPH pro kontrolní hlášení A.1, např. 4 – stavební a montážní práce.
- Hodnoty:
11a33a44a5671112131415161718192021null
Odpovědi
200Upravený záznam.
Hlavičky
X-Request-Id- ID požadavku pro podporu. Vlastní hodnotu z 8–64 písmen, číslic a
._-API vrátí beze změny, jinak vytvoří novou. RateLimit- Zbývající požadavky a sekundy do obnovení, např.
"default";r=118;t=42. RateLimit-Policy- Pravidlo limitu:
"default";q=120;w=60. ETag- Verze vrácené podoby záznamu. Pošlete ji v
If-Matchpři změně, nebo vIf-None-Matchpři dalším čtení.
application/json
400Chybný požadavek.
Hlavičky
X-Request-Id- ID požadavku pro podporu. Vlastní hodnotu z 8–64 písmen, číslic a
._-API vrátí beze změny, jinak vytvoří novou.
application/problem+json
Schéma: Problem
{
"type": "https://api.fakturanet.cz/#problem-invalid-parameter",
"title": "Invalid parameter",
"status": 400,
"detail": "page must be at least 1 and limit between 1 and 100.",
"request_id": "9f2c41d0a7b3e815"
}
401Chybí nebo neplatí API klíč.
Hlavičky
X-Request-Id- ID požadavku pro podporu. Vlastní hodnotu z 8–64 písmen, číslic a
._-API vrátí beze změny, jinak vytvoří novou. WWW-AuthenticateBearer realm="Fakturanet API"
application/problem+json
Schéma: Problem
{
"type": "https://api.fakturanet.cz/#problem-unauthorized",
"title": "Unauthorized",
"status": 401,
"detail": "Send an API key as \"Authorization: Bearer <key>\" or in the X-Api-Key header.",
"request_id": "9f2c41d0a7b3e815"
}
403Chybí oprávnění, role nebo funkce tarifu.
Hlavičky
X-Request-Id- ID požadavku pro podporu. Vlastní hodnotu z 8–64 písmen, číslic a
._-API vrátí beze změny, jinak vytvoří novou.
application/problem+json
Schéma: Problem
{
"type": "https://api.fakturanet.cz/#problem-insufficient-scope",
"title": "Insufficient scope",
"status": 403,
"detail": "This API key does not have the invoices:write scope.",
"request_id": "9f2c41d0a7b3e815"
}
404Záznam nenalezen.
Hlavičky
X-Request-Id- ID požadavku pro podporu. Vlastní hodnotu z 8–64 písmen, číslic a
._-API vrátí beze změny, jinak vytvoří novou.
application/problem+json
Schéma: Problem
{
"type": "https://api.fakturanet.cz/#problem-not-found",
"title": "Not found",
"status": 404,
"detail": "The requested record does not exist.",
"request_id": "9f2c41d0a7b3e815"
}
409Konflikt se stavem záznamu.
Hlavičky
X-Request-Id- ID požadavku pro podporu. Vlastní hodnotu z 8–64 písmen, číslic a
._-API vrátí beze změny, jinak vytvoří novou.
application/problem+json
Schéma: Problem
{
"type": "https://api.fakturanet.cz/#problem-already-issued",
"title": "Already issued",
"status": 409,
"detail": "Only a draft can be issued.",
"request_id": "9f2c41d0a7b3e815"
}
413Tělo je příliš velké.
Hlavičky
X-Request-Id- ID požadavku pro podporu. Vlastní hodnotu z 8–64 písmen, číslic a
._-API vrátí beze změny, jinak vytvoří novou.
application/problem+json
Schéma: Problem
{
"type": "https://api.fakturanet.cz/#problem-payload-too-large",
"title": "Payload too large",
"status": 413,
"detail": "The request body is limited to 1 MB.",
"request_id": "9f2c41d0a7b3e815"
}
415Tělo není JSON.
Hlavičky
X-Request-Id- ID požadavku pro podporu. Vlastní hodnotu z 8–64 písmen, číslic a
._-API vrátí beze změny, jinak vytvoří novou.
application/problem+json
Schéma: Problem
{
"type": "https://api.fakturanet.cz/#problem-unsupported-media-type",
"title": "Unsupported media type",
"status": 415,
"detail": "Send the request body as application/json.",
"request_id": "9f2c41d0a7b3e815"
}
422Data neprošla kontrolou.
Hlavičky
X-Request-Id- ID požadavku pro podporu. Vlastní hodnotu z 8–64 písmen, číslic a
._-API vrátí beze změny, jinak vytvoří novou.
application/problem+json
Schéma: Problem
{
"type": "https://api.fakturanet.cz/#problem-validation-failed",
"title": "Validation failed",
"status": 422,
"detail": "2 fields are invalid. See errors.",
"request_id": "9f2c41d0a7b3e815",
"errors": [
{
"pointer": "/due_date",
"detail": "Must be a date in YYYY-MM-DD format."
},
{
"pointer": "/items/0/price",
"detail": "Unknown field."
}
]
}
429Překročen limit požadavků.
Hlavičky
X-Request-Id- ID požadavku pro podporu. Vlastní hodnotu z 8–64 písmen, číslic a
._-API vrátí beze změny, jinak vytvoří novou. Retry-After- Sekundy do dalšího pokusu.
application/problem+json
Schéma: Problem
{
"type": "https://api.fakturanet.cz/#problem-rate-limited",
"title": "Too many requests",
"status": 429,
"detail": "The limit is 120 requests per 60 seconds per key. Retry in 42 s.",
"request_id": "9f2c41d0a7b3e815"
}
500Neočekávaná chyba.
Hlavičky
X-Request-Id- ID požadavku pro podporu. Vlastní hodnotu z 8–64 písmen, číslic a
._-API vrátí beze změny, jinak vytvoří novou.
application/problem+json
Schéma: Problem
{
"type": "https://api.fakturanet.cz/#problem-server-error",
"title": "Server error",
"status": 500,
"detail": "The request could not be completed. Quote request ID 9f2c41d0a7b3e815 when contacting support.",
"request_id": "9f2c41d0a7b3e815"
}
412Záznam se změnil od čtení s `If-Match`; nic se neprovedlo. Hlavička `ETag` nese aktuální verzi.
Hlavičky
ETag- Verze vrácené podoby záznamu. Pošlete ji v
If-Matchpři změně, nebo vIf-None-Matchpři dalším čtení.
application/problem+json
Schéma: Problem
{
"type": "https://api.fakturanet.cz/#problem-precondition-failed",
"title": "Precondition failed",
"status": 412,
"detail": "The record has changed since you read it. Fetch it again and repeat the change with its new ETag.",
"request_id": "9f2c41d0a7b3e815"
}
curl -X PATCH "https://api.fakturanet.cz/v1/invoices/123" \
-H "Authorization: Bearer $FAKTURANET_API_KEY" \
-H "Content-Type: application/json" \
--data-raw '"{\n \"type\": \"https://api.fakturanet.cz/#problem-precondition-failed\",\n \"title\": \"Precondition failed\",\n \"status\": 412,\n \"detail\": \"The record has changed since you read it. Fetch it again and repeat the change with its new ETag.\",\n \"request_id\": \"9f2c41d0a7b3e815\"\n}"'
<?php
declare(strict_types=1);
$key = getenv('FAKTURANET_API_KEY');
if (!$key) { throw new RuntimeException('Nastavte FAKTURANET_API_KEY.'); }
$headers = ["Authorization: Bearer $key"];
$headers[] = 'Content-Type: application/json';
$body = <<<'JSON'
"{\n \"type\": \"https://api.fakturanet.cz/#problem-precondition-failed\",\n \"title\": \"Precondition failed\",\n \"status\": 412,\n \"detail\": \"The record has changed since you read it. Fetch it again and repeat the change with its new ETag.\",\n \"request_id\": \"9f2c41d0a7b3e815\"\n}"
JSON;
$ch = curl_init('https://api.fakturanet.cz/v1/invoices/123');
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'PATCH',
CURLOPT_HTTPHEADER => $headers,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CONNECTTIMEOUT => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
if ($status >= 400) { throw new RuntimeException('HTTP ' . $status . ': ' . $response); }
$data = json_decode($response, true, 512, JSON_THROW_ON_ERROR);
ID 123 nahraďte ID svého záznamu.
{
"data": {
"id": 123,
"contact_id": 123,
"doc_type": "invoice_vat",
"number": "2026110003",
"reg_number": "",
"variable_symbol": "2026110003",
"constant_symbol": "",
"specific_symbol": "",
"order_number": "",
"issued_by": "",
"issue_date": "2026-11-18",
"supply_date": "2026-11-18",
"due_date": "2026-12-16",
"payment_method": "bank_transfer",
"bank_account_id": 1,
"language": "cs",
"currency": "CZK",
"exchange_rate": "1",
"vat_treatment": "domestic",
"rounding": "none",
"show_qr": true,
"template": "modern",
"color": "#172136",
"prices_include_vat": false,
"discount_pct": "0",
"note": "Splatnost prodloužena na žádost odběratele.",
"supplier_snapshot": {
"name": "Bozkurt Group s.r.o.",
"company_no": "03662268",
"vat_no": "CZ03662268",
"is_vat_payer": true,
"street": "Klimentská 1207/10",
"city": "Praha",
"zip": "11000",
"country": "CZ",
"email": "info@fakturanet.cz",
"phone": null,
"web": "https://fakturanet.cz",
"register_note": "Zapsaná v obchodním rejstříku vedeném Městským soudem v Praze, oddíl C, vložka 234971."
},
"customer_snapshot": {
"name": "Jan Novák",
"city": "Praha",
"country": "CZ",
"email": "jan.novak@example.com"
},
"bank_snapshot": {
"account_no": "19-2000145399",
"bank_code": "0800",
"iban": "CZ6508000000192000145399",
"swift": "GIBACZPX",
"currency": "CZK"
},
"vat_summary": [
{
"rate": "21",
"net": "948.00",
"vat": "199.08",
"gross": "1147.08"
}
],
"total_net": "948",
"total_vat": "199.08",
"total_gross": "1147.08",
"rounding_amount": "0",
"paid_amount": "0",
"status": "issued",
"paid_at": null,
"revision": 2,
"related_invoice_id": null,
"recurring_id": null,
"scheduled_date": null,
"created_at": "2026-11-18T10:15:00+01:00",
"updated_at": "2026-11-18T10:15:00+01:00",
"correction_reason": null,
"vies_check": null,
"reverse_charge_code": null,
"payment_status": "unpaid",
"pdf_url": "https://api.fakturanet.cz/v1/invoices/123/pdf",
"items": [
{
"id": 1,
"position": 0,
"quantity": "1",
"unit": "ks",
"description": "Fakturanet Professional – roční předplatné",
"vat_rate": "21",
"unit_price": "948",
"net": "948",
"vat": "199.08",
"gross": "1147.08",
"discount_pct": "0"
}
],
"deleted_at": null
}
}