Přejít na obsah
FakturanetAPI v1.0.0
OpenAPI API klíče

Doklady

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écesta

ID záznamu.

  • Minimum: 1
If-Matchstringhlavička

ETag 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_typestring

Typ 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_datedate

Datum vystavení. Výchozí dnešní den.

supply_datedate

Datum uskutečnění zdanitelného plnění (DUZP). Výchozí datum vystavení.

due_datedate

Datum splatnosti. Výchozí 14 dní od vystavení.

contact_idinteger

ID kontaktu odběratele. Pokud chybí customer, odběratel se převezme z kontaktu.

customerParty

Odbě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
namestring

Název firmy nebo jméno osoby.

  • Max. znaků: 190
company_nostring | null

IČO. Mezery se odstraní.

  • Max. znaků: 20
vat_nostring | null

DIČ.

  • Max. znaků: 30
streetstring | null

Ulice a číslo.

  • Max. znaků: 190
citystring | null

Obec.

  • Max. znaků: 120
zipstring | null

PSČ.

  • Max. znaků: 20
countrystring | null

Kód země ISO 3166-1 alpha-2. Výchozí CZ.

  • Výchozí: CZ
  • Vzorec: ^[A-Za-z]{2}$
emailemail | null

E-mail; použije se jako výchozí příjemce faktury.

  • Max. znaků: 190
phonestring | null

Telefon.

  • Max. znaků: 40
webstring | null

Web.

  • Max. znaků: 190
bank_account_idinteger | null

ID 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_methodstring

Způ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
currencystring

Měna ISO 4217.

  • Výchozí: CZK
  • Vzorec: ^[A-Z]{3}$
exchange_ratedecimal

Kurz 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})?$
languagestring

Jazyk 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_treatmentstring

Rež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).

roundingstring

Zaokrouhlení 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
templatestring

Vzhled PDF. Hodnoty: modern – moderní; simple – jednoduchý; custom – vlastní.

  • Výchozí: modern
colorstring

Barva dokladu #RRGGBB. Výchozí barva firmy.

  • Vzorec: ^#[0-9A-Fa-f]{6}$
show_qrboolean

Tisknout QR platbu.

  • Výchozí: true
prices_include_vatboolean

Jednotkové ceny jsou včetně DPH.

  • Výchozí: false
discount_pctdecimal

Sleva na celý doklad v procentech (0–100, nejvýše 2 desetinná místa).

  • Vzorec: ^-?\d{1,12}(\.\d{1,8})?$
issued_bystring

Kdo doklad vystavil.

  • Max. znaků: 120
notestring

Poznámka na dokladu.

  • Max. znaků: 10000
reg_numberstring

Evidenční číslo.

  • Max. znaků: 40
order_numberstring

Číslo objednávky odběratele.

  • Max. znaků: 60
variable_symbolstring

Variabilní symbol, nejvýše 10 číslic. Při vystavení se jinak odvodí z čísla dokladu.

  • Vzorec: ^\d{0,10}$
constant_symbolstring

Konstantní symbol.

  • Max. znaků: 10
specific_symbolstring

Specifický symbol.

  • Max. znaků: 20

Položky dokladu (1–500).

  • Min. položek: 1
  • Max. položek: 500
Vnořená pole 6
descriptionstringpovinné v objektu

Popis položky.

  • Max. znaků: 500
quantitydecimal

Množ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})?$
unitstring

Jednotka, například ks, hod. Výchozí ks.

  • Max. znaků: 20
unit_pricedecimalpovinné v objektu

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_ratedecimal

Sazba 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_pctdecimal

Sleva 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 | null

Důvod opravy u opravného daňového dokladu (credit_note). Při vystavení je povinný.

  • Max. znaků: 255
reverse_charge_codestring | null

Př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: 1 1a 3 3a 4 4a 5 6 7 11 12 13 14 15 16 17 18 19 20 21 null

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-Match při změně, nebo v If-None-Match při dalším čtení.

application/json

dataInvoicepovinné
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

JSON · 400
{
  "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"
}

Přehled typů chyb

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-Authenticate
Bearer realm="Fakturanet API"

application/problem+json

Schéma: Problem

JSON · 401
{
  "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"
}

Přehled typů chyb

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

JSON · 403
{
  "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"
}

Přehled typů chyb

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

JSON · 404
{
  "type": "https://api.fakturanet.cz/#problem-not-found",
  "title": "Not found",
  "status": 404,
  "detail": "The requested record does not exist.",
  "request_id": "9f2c41d0a7b3e815"
}

Přehled typů chyb

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

JSON · 409
{
  "type": "https://api.fakturanet.cz/#problem-already-issued",
  "title": "Already issued",
  "status": 409,
  "detail": "Only a draft can be issued.",
  "request_id": "9f2c41d0a7b3e815"
}

Přehled typů chyb

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

JSON · 413
{
  "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"
}

Přehled typů chyb

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

JSON · 415
{
  "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"
}

Přehled typů chyb

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

JSON · 422
{
  "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."
    }
  ]
}

Přehled typů chyb

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

JSON · 429
{
  "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"
}

Přehled typů chyb

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

JSON · 500
{
  "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"
}

Přehled typů chyb

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-Match při změně, nebo v If-None-Match při dalším čtení.

application/problem+json

Schéma: Problem

JSON · 412
{
  "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"
}

Přehled typů chyb

Požadavek · cURL
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}"'
Požadavek · PHP
<?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.

Odpověď · 200
{
  "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
  }
}

Hledat v dokumentaci

Hledejte endpoint, pole, objekt, typ chyby nebo téma příručky.