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

Doklady

Seznam dokladů

GET/invoices

Doklady firmy (faktury, dobropisy, zálohové faktury, nabídky) bez položek. Smazané se nevrací.

Oprávnění klíče: invoices:read

Parametry

pageintegerdotaz

Stránka.

  • Výchozí: 1
  • Minimum: 1
limitintegerdotaz

Záznamů na stránku (nejvýše 100).

  • Výchozí: 20
  • Minimum: 1
  • Maximum: 100
qstringdotaz

Fulltext v čísle, odběrateli a poznámce.

statusstringdotaz

Stav úhrady: draft koncept, unpaid nezaplaceno, paid zaplaceno, overdue po splatnosti, future naplánováno – datum vystavení v budoucnu.

  • Hodnoty: draft unpaid paid overdue future
fromdatedotaz

Datum vystavení od (RRRR-MM-DD).

todatedotaz

Datum vystavení do (RRRR-MM-DD).

contact_idintegerdotaz

Jen doklady kontaktu.

doc_typestringdotaz

Typ dokladu.

  • Hodnoty: invoice_vat invoice_non_vat credit_note reverse_charge proforma advance quote_vat quote_non_vat
payment_methodstringdotaz

Způsob úhrady.

  • Hodnoty: bank_transfer cash cash_on_delivery card paypal mutual_offset
mindecimaldotaz

Částka celkem od.

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

Částka celkem do.

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

Jen záznamy změněné od tohoto času včetně, seřazené od nejstarší změny. Vrací i smazané záznamy s vyplněným deleted_at.

Odpovědi

200Stránka záznamů od nejnovějšího.

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.
Link
Odkazy na další a předchozí stránku (RFC 8288).

application/json

dataarray<Invoice>povinné
metaPageMetapovinné
linksPageLinkspovinné
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

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

Požadavek · cURL
curl "https://api.fakturanet.cz/v1/invoices" \
  -H "Authorization: Bearer $FAKTURANET_API_KEY" \
  -H "Content-Type: application/json" \
  --data-raw '"{\n  \"type\": \"https://api.fakturanet.cz/#problem-server-error\",\n  \"title\": \"Server error\",\n  \"status\": 500,\n  \"detail\": \"The request could not be completed. Quote request ID 9f2c41d0a7b3e815 when contacting support.\",\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-server-error\",\n  \"title\": \"Server error\",\n  \"status\": 500,\n  \"detail\": \"The request could not be completed. Quote request ID 9f2c41d0a7b3e815 when contacting support.\",\n  \"request_id\": \"9f2c41d0a7b3e815\"\n}"
JSON;

$ch = curl_init('https://api.fakturanet.cz/v1/invoices');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'GET',
    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);
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": "1147.08",
      "status": "issued",
      "paid_at": "2026-11-18T00:00:00+01:00",
      "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": "paid",
      "pdf_url": "https://api.fakturanet.cz/v1/invoices/123/pdf",
      "deleted_at": null
    }
  ],
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 1,
    "pages": 1
  },
  "links": {
    "next": null,
    "prev": null
  }
}

Hledat v dokumentaci

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