{ "openapi": "3.1.0", "info": { "title": "Fakturák REST API", "version": "1.0.0", "description": "Firma je určena Bearer klíčem. Nepodporované pole je chyba. Ceny bez DPH u plátce, konečné u neplátce; současné jádro podporuje běžné tuzemské doklady. Na API se vztahuje aktuální entitlement a oprávnění vlastníka klíče. Kompatibilní nová pole lze doplňovat; klient ignoruje neznámá pole odpovědi. Nekompatibilní změny půjdou do v2." }, "servers": [ { "url": "https://api.fakturak.cz/v1" } ], "security": [ { "BearerAuth": [] } ], "paths": { "/me": { "get": { "summary": "Identita firmy a scope klíče", "operationId": "get_me", "responses": { "200": { "description": "Úspěšný výsledek.", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "name", "scope" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "registration_number": { "type": [ "string", "null" ] }, "vat_id": { "type": [ "string", "null" ] }, "vat_status": { "type": "string" }, "scope": { "type": "string", "enum": [ "read", "read_write" ] }, "street": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "zip": { "type": [ "string", "null" ] }, "country_code": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] } } } } } }, "default": { "$ref": "#/components/responses/Error" } }, "parameters": [] } }, "/company": { "get": { "summary": "Údaje napojené firmy", "operationId": "get_company", "responses": { "200": { "description": "Úspěšný výsledek.", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "name", "scope" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "registration_number": { "type": [ "string", "null" ] }, "vat_id": { "type": [ "string", "null" ] }, "vat_status": { "type": "string" }, "scope": { "type": "string", "enum": [ "read", "read_write" ] }, "street": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "zip": { "type": [ "string", "null" ] }, "country_code": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] } } } } } }, "default": { "$ref": "#/components/responses/Error" } }, "parameters": [] } }, "/bank-accounts": { "get": { "summary": "Aktivní bankovní účty", "operationId": "get_bank_accounts", "responses": { "200": { "description": "Úspěšný výsledek.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "is_default": { "type": "boolean" }, "name": { "type": [ "string", "null" ] }, "account_prefix": { "type": [ "string", "null" ] }, "account_number": { "type": [ "string", "null" ] }, "bank_code": { "type": [ "string", "null" ] }, "iban": { "type": [ "string", "null" ] }, "bic": { "type": [ "string", "null" ] }, "currency": { "type": [ "string", "null" ] } } } } } } } } }, "default": { "$ref": "#/components/responses/Error" } }, "parameters": [] } }, "/number-series": { "get": { "summary": "Aktivní číselné řady", "operationId": "get_number_series", "responses": { "200": { "description": "Úspěšný výsledek.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "is_default": { "type": "boolean" }, "name": { "type": [ "string", "null" ] }, "document_type": { "type": [ "string", "null" ] }, "number_format": { "type": [ "string", "null" ] }, "variable_symbol_format": { "type": [ "string", "null" ] } } } } } } } } }, "default": { "$ref": "#/components/responses/Error" } }, "parameters": [] } }, "/contacts": { "get": { "summary": "Seznam se stránkováním data + meta; sestupně podle pořadí vytvoření.", "operationId": "get_contacts", "responses": { "200": { "description": "Úspěšný výsledek.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Contact" } }, "meta": { "$ref": "#/components/schemas/PageMeta" } } } } } }, "default": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, { "name": "q", "in": "query", "schema": { "type": "string", "maxLength": 190 } }, { "name": "external_id", "in": "query", "schema": { "type": "string" } }, { "name": "updated_since", "in": "query", "schema": { "type": "string", "format": "date-time" }, "description": "Inkluzivní filtr; pro překryv deduplikujte podle UUID. Nejedná se o kanál událostí úhrad." } ] }, "post": { "summary": "Vytvoření contacts", "operationId": "post_contacts", "responses": { "201": { "description": "Úspěšný výsledek.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Contact" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 128, "pattern": "^[A-Za-z0-9_.:-]+$" }, "description": "Stabilní klíč pro jednu operaci. Stejný obsah opakuje původní výsledek; jiný obsah vrací 409. Rozsah firma + metoda + cesta; záznamy automaticky nemažeme." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string" }, "registration_number": { "type": "string" }, "vat_id": { "type": "string" }, "street": { "type": "string" }, "city": { "type": "string" }, "zip": { "type": "string" }, "country_code": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": "string" }, "website": { "type": "string" }, "note": { "type": "string" }, "external_id": { "type": "string" }, "active": { "type": "boolean", "default": true } }, "required": [ "name" ] } } } } } }, "/contacts/{id}": { "get": { "summary": "Detail contacts", "operationId": "get_contacts_id", "responses": { "200": { "description": "Úspěšný výsledek.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Contact" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Stávající UUIDv7. Nikdy číselné ID z databáze." } } ] }, "patch": { "summary": "Částečná aktualizace podle stejných pravidel jako app.", "operationId": "patch_contacts_id", "responses": { "200": { "description": "Úspěšný výsledek.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Contact" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Stávající UUIDv7. Nikdy číselné ID z databáze." } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 128, "pattern": "^[A-Za-z0-9_.:-]+$" }, "description": "Stabilní klíč pro jednu operaci. Stejný obsah opakuje původní výsledek; jiný obsah vrací 409. Rozsah firma + metoda + cesta; záznamy automaticky nemažeme." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string" }, "registration_number": { "type": "string" }, "vat_id": { "type": "string" }, "street": { "type": "string" }, "city": { "type": "string" }, "zip": { "type": "string" }, "country_code": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": "string" }, "website": { "type": "string" }, "note": { "type": "string" }, "external_id": { "type": "string" }, "active": { "type": "boolean", "default": true } }, "required": [] } } } } } }, "/invoices": { "get": { "summary": "Seznam se stránkováním data + meta; sestupně podle pořadí vytvoření.", "operationId": "get_invoices", "responses": { "200": { "description": "Úspěšný výsledek.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/InvoiceSummary" } }, "meta": { "$ref": "#/components/schemas/PageMeta" } } } } } }, "default": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, { "name": "q", "in": "query", "schema": { "type": "string", "maxLength": 190 } }, { "name": "external_id", "in": "query", "schema": { "type": "string" } }, { "name": "updated_since", "in": "query", "schema": { "type": "string", "format": "date-time" }, "description": "Inkluzivní filtr; pro překryv deduplikujte podle UUID. Nejedná se o kanál událostí úhrad." }, { "name": "type", "in": "query", "schema": { "type": "string", "enum": [ "invoice", "proforma" ] } }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "draft", "issued", "cancelled" ] } }, { "name": "currency", "in": "query", "schema": { "type": "string", "enum": [ "CZK", "EUR", "USD", "GBP", "CHF", "PLN", "HUF", "JPY" ] } }, { "name": "from", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "schema": { "type": "string", "format": "date" } } ] }, "post": { "summary": "Vytvoření invoices", "operationId": "post_invoices", "responses": { "201": { "description": "Úspěšný výsledek.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Invoice" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 128, "pattern": "^[A-Za-z0-9_.:-]+$" }, "description": "Stabilní klíč pro jednu operaci. Stejný obsah opakuje původní výsledek; jiný obsah vrací 409. Rozsah firma + metoda + cesta; záznamy automaticky nemažeme." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "contact_id", "status", "items" ], "properties": { "contact_id": { "type": "string", "format": "uuid", "description": "Stávající UUIDv7. Nikdy číselné ID z databáze." }, "document_type": { "type": "string", "enum": [ "invoice", "proforma" ] }, "status": { "type": "string", "enum": [ "draft", "issued" ], "description": "Explicitní volba při vytvoření; PATCH toto pole nepřijímá." }, "currency": { "type": "string", "enum": [ "CZK", "EUR", "USD", "GBP", "CHF", "PLN", "HUF", "JPY" ] }, "payment_method": { "type": "string", "enum": [ "bank", "cash", "card", "other" ] }, "number_series_id": { "type": "string", "format": "uuid", "description": "Stávající UUIDv7. Nikdy číselné ID z databáze." }, "bank_account_id": { "type": [ "string", "null" ], "format": "uuid" }, "issue_date": { "type": "string", "format": "date" }, "due_date": { "type": "string", "format": "date" }, "tax_date": { "type": [ "string", "null" ], "format": "date" }, "exchange_rate": { "type": "string" }, "vat_note": { "type": "string" }, "note": { "type": "string", "maxLength": 4000 }, "items": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "type": "object", "additionalProperties": false, "required": [ "description", "quantity", "unit_price" ], "properties": { "description": { "type": "string", "maxLength": 500 }, "quantity": { "type": "string", "pattern": "^\\d{1,7}(\\.\\d{1,3})?$" }, "unit": { "type": "string", "maxLength": 20 }, "unit_price": { "type": "string", "pattern": "^\\d{1,7}(\\.\\d{1,2})?$", "examples": [ "350.00" ] }, "vat_rate": { "oneOf": [ { "type": "integer", "enum": [ 0, 12, 21 ] }, { "type": "string", "enum": [ "0", "12", "21" ] } ] } } } }, "custom_link": { "type": [ "string", "null" ], "format": "uri", "maxLength": 2048, "description": "Absolutní HTTPS URL bez přihlašovacích údajů; použije ji placeholder {:custom_link:}." }, "send_email": { "type": "boolean", "default": false, "description": "Vyžaduje platný e-mail aktivního kontaktu. Vrací asynchronní email_job." }, "external_id": { "type": "string", "minLength": 1, "maxLength": 190 } } } } } } } }, "/invoices/{id}": { "get": { "summary": "Detail invoices", "operationId": "get_invoices_id", "responses": { "200": { "description": "Úspěšný výsledek.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Invoice" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Stávající UUIDv7. Nikdy číselné ID z databáze." } } ] }, "patch": { "summary": "Částečná aktualizace podle stejných pravidel jako app.", "operationId": "patch_invoices_id", "responses": { "200": { "description": "Úspěšný výsledek.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Invoice" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Stávající UUIDv7. Nikdy číselné ID z databáze." } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 128, "pattern": "^[A-Za-z0-9_.:-]+$" }, "description": "Stabilní klíč pro jednu operaci. Stejný obsah opakuje původní výsledek; jiný obsah vrací 409. Rozsah firma + metoda + cesta; záznamy automaticky nemažeme." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "version" ], "properties": { "contact_id": { "type": "string", "format": "uuid", "description": "Stávající UUIDv7. Nikdy číselné ID z databáze." }, "document_type": { "type": "string", "enum": [ "invoice", "proforma" ] }, "currency": { "type": "string", "enum": [ "CZK", "EUR", "USD", "GBP", "CHF", "PLN", "HUF", "JPY" ] }, "payment_method": { "type": "string", "enum": [ "bank", "cash", "card", "other" ] }, "number_series_id": { "type": "string", "format": "uuid", "description": "Stávající UUIDv7. Nikdy číselné ID z databáze." }, "bank_account_id": { "type": [ "string", "null" ], "format": "uuid" }, "issue_date": { "type": "string", "format": "date" }, "due_date": { "type": "string", "format": "date" }, "tax_date": { "type": [ "string", "null" ], "format": "date" }, "exchange_rate": { "type": "string" }, "vat_note": { "type": "string" }, "note": { "type": "string", "maxLength": 4000 }, "items": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "type": "object", "additionalProperties": false, "required": [ "description", "quantity", "unit_price" ], "properties": { "description": { "type": "string", "maxLength": 500 }, "quantity": { "type": "string", "pattern": "^\\d{1,7}(\\.\\d{1,3})?$" }, "unit": { "type": "string", "maxLength": 20 }, "unit_price": { "type": "string", "pattern": "^\\d{1,7}(\\.\\d{1,2})?$", "examples": [ "350.00" ] }, "vat_rate": { "oneOf": [ { "type": "integer", "enum": [ 0, 12, 21 ] }, { "type": "string", "enum": [ "0", "12", "21" ] } ] } } } }, "custom_link": { "type": [ "string", "null" ], "format": "uri", "maxLength": 2048, "description": "Absolutní HTTPS URL bez přihlašovacích údajů; použije ji placeholder {:custom_link:}." }, "version": { "type": "integer", "minimum": 1 } } } } } } } }, "/invoices/{id}/issue": { "post": { "summary": "Vystavení konceptu", "operationId": "post_invoices_id_issue", "responses": { "200": { "description": "Úspěšný výsledek.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Invoice" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Stávající UUIDv7. Nikdy číselné ID z databáze." } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 128, "pattern": "^[A-Za-z0-9_.:-]+$" }, "description": "Stabilní klíč pro jednu operaci. Stejný obsah opakuje původní výsledek; jiný obsah vrací 409. Rozsah firma + metoda + cesta; záznamy automaticky nemažeme." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "version" ], "additionalProperties": false, "properties": { "version": { "type": "integer", "minimum": 1 } } } } } } } }, "/invoices/{id}/cancel": { "post": { "summary": "Storno vystaveného dokladu", "operationId": "post_invoices_id_cancel", "responses": { "200": { "description": "Úspěšný výsledek.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Invoice" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Stávající UUIDv7. Nikdy číselné ID z databáze." } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 128, "pattern": "^[A-Za-z0-9_.:-]+$" }, "description": "Stabilní klíč pro jednu operaci. Stejný obsah opakuje původní výsledek; jiný obsah vrací 409. Rozsah firma + metoda + cesta; záznamy automaticky nemažeme." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "version" ], "additionalProperties": false, "properties": { "version": { "type": "integer", "minimum": 1 } } } } } } } }, "/invoices/{id}/send": { "post": { "summary": "Zařazení asynchronní úlohy pro e-mail s PDF a ISDOC", "operationId": "post_invoices_id_send", "responses": { "202": { "description": "Úspěšný výsledek.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Job" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Stávající UUIDv7. Nikdy číselné ID z databáze." } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 128, "pattern": "^[A-Za-z0-9_.:-]+$" }, "description": "Stabilní klíč pro jednu operaci. Stejný obsah opakuje původní výsledek; jiný obsah vrací 409. Rozsah firma + metoda + cesta; záznamy automaticky nemažeme." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false } } } } } }, "/invoices/{id}/payments": { "post": { "summary": "Evidence příchozí úhrady; plná úhrada neplátcovy zálohovky vytvoří navazující fakturu.", "operationId": "post_invoices_id_payments", "responses": { "201": { "description": "Úspěšný výsledek.", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "invoice" ], "properties": { "id": { "type": "string", "format": "uuid" }, "invoice": { "$ref": "#/components/schemas/Invoice" } } } } } }, "default": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Stávající UUIDv7. Nikdy číselné ID z databáze." } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 128, "pattern": "^[A-Za-z0-9_.:-]+$" }, "description": "Stabilní klíč pro jednu operaci. Stejný obsah opakuje původní výsledek; jiný obsah vrací 409. Rozsah firma + metoda + cesta; záznamy automaticky nemažeme." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "paid_date", "amount", "method" ], "properties": { "paid_date": { "type": "string", "format": "date" }, "amount": { "type": "string", "pattern": "^\\d{1,7}(\\.\\d{1,2})?$", "examples": [ "350.00" ] }, "method": { "type": "string", "enum": [ "bank", "cash", "card", "other" ] }, "reference": { "type": "string", "maxLength": 190 } } } } } } } }, "/invoices/preview-number": { "get": { "summary": "Nezávazný náhled čísla/VS, bez rezervace.", "operationId": "get_invoices_preview_number", "responses": { "200": { "description": "Úspěšný výsledek.", "content": { "application/json": { "schema": { "type": "object", "required": [ "number", "variable_symbol", "reserved" ], "properties": { "number": { "type": "string" }, "variable_symbol": { "type": "string" }, "reserved": { "const": false } } } } } }, "default": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "type", "in": "query", "schema": { "type": "string", "enum": [ "invoice", "proforma" ] } }, { "name": "number_series_id", "in": "query", "schema": { "type": "string", "format": "uuid", "description": "Stávající UUIDv7. Nikdy číselné ID z databáze." } } ] } }, "/invoices/{id}/pdf": { "get": { "summary": "Stažení PDF", "operationId": "get_invoices_id_pdf", "responses": { "200": { "description": "Binární soubor.", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "default": { "$ref": "#/components/responses/Error" }, "202": { "description": "PDF se připravuje. Opakujte GET podle Retry-After; nevytvářejte nový doklad.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Job" } } }, "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Doporučený odstup v sekundách (5)." } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Stávající UUIDv7. Nikdy číselné ID z databáze." } } ] } }, "/invoices/{id}/isdoc": { "get": { "summary": "Stažení ISDOC", "operationId": "get_invoices_id_isdoc", "responses": { "200": { "description": "Binární soubor.", "content": { "application/xml": { "schema": { "type": "string", "format": "binary" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Stávající UUIDv7. Nikdy číselné ID z databáze." } } ] } }, "/jobs/{id}": { "get": { "summary": "Stav PDF/e-mailové úlohy, e-mail pending/processing/sent/failed/cancelled podle fronty.", "operationId": "get_jobs_id", "responses": { "200": { "description": "Úspěšný výsledek.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Job" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Stávající UUIDv7. Nikdy číselné ID z databáze." } } ] } }, "/jobs/{id}/retry": { "post": { "summary": "Znovu spustit neúspěšnou úlohu; neaktuální PDF se obnoví novým GET dokladu.", "operationId": "post_jobs_id_retry", "responses": { "202": { "description": "Úspěšný výsledek.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Job" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Stávající UUIDv7. Nikdy číselné ID z databáze." } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 128, "pattern": "^[A-Za-z0-9_.:-]+$" }, "description": "Stabilní klíč pro jednu operaci. Stejný obsah opakuje původní výsledek; jiný obsah vrací 409. Rozsah firma + metoda + cesta; záznamy automaticky nemažeme." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false } } } } } }, "/webhooks": { "get": { "summary": "Seznam konfigurací bez podpisového tajemství.", "operationId": "get_webhooks", "parameters": [], "responses": { "200": { "description": "Úspěšný výsledek.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Webhook" } } } } } } }, "default": { "$ref": "#/components/responses/Error" } } }, "post": { "summary": "Vytvořit webhook; platný entitlement webhooks a nejvýše5konfigurací na firmu.", "operationId": "post_webhooks", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 128, "pattern": "^[A-Za-z0-9_.:-]+$" }, "description": "Stabilní klíč pro jednu operaci. Stejný obsah opakuje původní výsledek; jiný obsah vrací 409. Rozsah firma + metoda + cesta; záznamy automaticky nemažeme." } ], "responses": { "201": { "description": "Úspěšný výsledek.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhook" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "url", "events" ], "properties": { "url": { "type": "string", "format": "uri", "description": "Veřejný HTTPS hostname, port443, žádné userinfo/fragment. Přesměrování se nenásledují." }, "events": { "type": "array", "minItems": 1, "items": { "type": "string", "enum": [ "invoice.created", "invoice.updated", "invoice.issued", "invoice.cancelled", "invoice.payment_added", "invoice.paid", "invoice.payment_removed", "invoice.settled", "invoice.pdf_ready", "webhook.test" ] } }, "active": { "type": "boolean" } } } } } } } }, "/webhooks/{id}": { "get": { "summary": "Detail konfigurace bez tajemství.", "operationId": "get_webhooks_id", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Úspěšný výsledek.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhook" } } } }, "default": { "$ref": "#/components/responses/Error" } } }, "patch": { "summary": "Změnit konfiguraci; stará čekající doručení se zruší.", "operationId": "patch_webhooks_id", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 128, "pattern": "^[A-Za-z0-9_.:-]+$" }, "description": "Stabilní klíč pro jednu operaci. Stejný obsah opakuje původní výsledek; jiný obsah vrací 409. Rozsah firma + metoda + cesta; záznamy automaticky nemažeme." } ], "responses": { "200": { "description": "Úspěšný výsledek.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhook" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "version" ], "properties": { "url": { "type": "string", "format": "uri", "description": "Veřejný HTTPS hostname, port443, žádné userinfo/fragment. Přesměrování se nenásledují." }, "events": { "type": "array", "minItems": 1, "items": { "type": "string", "enum": [ "invoice.created", "invoice.updated", "invoice.issued", "invoice.cancelled", "invoice.payment_added", "invoice.paid", "invoice.payment_removed", "invoice.settled", "invoice.pdf_ready", "webhook.test" ] } }, "active": { "type": "boolean" }, "version": { "type": "integer", "minimum": 1 } } } } } } }, "delete": { "summary": "Smazat konfiguraci a zrušit čekající doručení.", "operationId": "delete_webhooks_id", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 128, "pattern": "^[A-Za-z0-9_.:-]+$" }, "description": "Stabilní klíč pro jednu operaci. Stejný obsah opakuje původní výsledek; jiný obsah vrací 409. Rozsah firma + metoda + cesta; záznamy automaticky nemažeme." } ], "responses": { "204": { "description": "Úspěšný výsledek." }, "default": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "version" ], "properties": { "version": { "type": "integer", "minimum": 1 } } } } } } } }, "/webhooks/{id}/rotate-secret": { "post": { "summary": "Rotace podpisového tajemství s kontrolou verze.", "operationId": "post_webhooks_id_rotate_secret", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 128, "pattern": "^[A-Za-z0-9_.:-]+$" }, "description": "Stabilní klíč pro jednu operaci. Stejný obsah opakuje původní výsledek; jiný obsah vrací 409. Rozsah firma + metoda + cesta; záznamy automaticky nemažeme." } ], "responses": { "200": { "description": "Úspěšný výsledek.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhook" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "version" ], "properties": { "version": { "type": "integer", "minimum": 1 } } } } } } } }, "/webhooks/{id}/test": { "post": { "summary": "Zařadit syntetickou testovací událost.", "operationId": "post_webhooks_id_test", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 128, "pattern": "^[A-Za-z0-9_.:-]+$" }, "description": "Stabilní klíč pro jednu operaci. Stejný obsah opakuje původní výsledek; jiný obsah vrací 409. Rozsah firma + metoda + cesta; záznamy automaticky nemažeme." } ], "responses": { "202": { "description": "Úspěšný výsledek.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "const": "pending" } } } } } }, "default": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false } } } } } }, "/webhooks/{id}/deliveries": { "get": { "summary": "Stránkovaná historie doručení bez citlivých odpovědí příjemce.", "operationId": "get_webhooks_id_deliveries", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1 } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "enum": [ 10, 25, 50 ], "default": 25 } } ], "responses": { "200": { "description": "Úspěšný výsledek.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object" } }, "meta": { "$ref": "#/components/schemas/PageMeta" } } } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/webhook-deliveries/{id}/retry": { "post": { "summary": "Ruční opakování selhaného doručení aktuální aktivní konfigurace.", "operationId": "post_webhook_deliveries_id_retry", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 128, "pattern": "^[A-Za-z0-9_.:-]+$" }, "description": "Stabilní klíč pro jednu operaci. Stejný obsah opakuje původní výsledek; jiný obsah vrací 409. Rozsah firma + metoda + cesta; záznamy automaticky nemažeme." } ], "responses": { "202": { "description": "Úspěšný výsledek.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "const": "pending" } } } } } }, "default": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false } } } } } } }, "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer" } }, "responses": { "Error": { "description": "Jednotná chyba s anglickým strojovým kódem a přeloženou zprávou.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } } } } } } } } }, "schemas": { "ContactInput": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string" }, "registration_number": { "type": "string" }, "vat_id": { "type": "string" }, "street": { "type": "string" }, "city": { "type": "string" }, "zip": { "type": "string" }, "country_code": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": "string" }, "website": { "type": "string" }, "note": { "type": "string" }, "external_id": { "type": "string" }, "active": { "type": "boolean", "default": true } }, "required": [ "name" ] }, "InvoiceInput": { "type": "object", "additionalProperties": false, "required": [ "contact_id", "status", "items" ], "properties": { "contact_id": { "type": "string", "format": "uuid", "description": "Stávající UUIDv7. Nikdy číselné ID z databáze." }, "document_type": { "type": "string", "enum": [ "invoice", "proforma" ] }, "status": { "type": "string", "enum": [ "draft", "issued" ], "description": "Explicitní volba při vytvoření; PATCH toto pole nepřijímá." }, "currency": { "type": "string", "enum": [ "CZK", "EUR", "USD", "GBP", "CHF", "PLN", "HUF", "JPY" ] }, "payment_method": { "type": "string", "enum": [ "bank", "cash", "card", "other" ] }, "number_series_id": { "type": "string", "format": "uuid", "description": "Stávající UUIDv7. Nikdy číselné ID z databáze." }, "bank_account_id": { "type": [ "string", "null" ], "format": "uuid" }, "issue_date": { "type": "string", "format": "date" }, "due_date": { "type": "string", "format": "date" }, "tax_date": { "type": [ "string", "null" ], "format": "date" }, "exchange_rate": { "type": "string" }, "vat_note": { "type": "string" }, "note": { "type": "string", "maxLength": 4000 }, "items": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "type": "object", "additionalProperties": false, "required": [ "description", "quantity", "unit_price" ], "properties": { "description": { "type": "string", "maxLength": 500 }, "quantity": { "type": "string", "pattern": "^\\d{1,7}(\\.\\d{1,3})?$" }, "unit": { "type": "string", "maxLength": 20 }, "unit_price": { "type": "string", "pattern": "^\\d{1,7}(\\.\\d{1,2})?$", "examples": [ "350.00" ] }, "vat_rate": { "oneOf": [ { "type": "integer", "enum": [ 0, 12, 21 ] }, { "type": "string", "enum": [ "0", "12", "21" ] } ] } } } }, "custom_link": { "type": [ "string", "null" ], "format": "uri", "maxLength": 2048, "description": "Absolutní HTTPS URL bez přihlašovacích údajů; použije ji placeholder {:custom_link:}." }, "send_email": { "type": "boolean", "default": false, "description": "Vyžaduje platný e-mail aktivního kontaktu. Vrací asynchronní email_job." }, "external_id": { "type": "string", "minLength": 1, "maxLength": 190 } } }, "InvoicePatch": { "type": "object", "additionalProperties": false, "required": [ "version" ], "properties": { "contact_id": { "type": "string", "format": "uuid", "description": "Stávající UUIDv7. Nikdy číselné ID z databáze." }, "document_type": { "type": "string", "enum": [ "invoice", "proforma" ] }, "currency": { "type": "string", "enum": [ "CZK", "EUR", "USD", "GBP", "CHF", "PLN", "HUF", "JPY" ] }, "payment_method": { "type": "string", "enum": [ "bank", "cash", "card", "other" ] }, "number_series_id": { "type": "string", "format": "uuid", "description": "Stávající UUIDv7. Nikdy číselné ID z databáze." }, "bank_account_id": { "type": [ "string", "null" ], "format": "uuid" }, "issue_date": { "type": "string", "format": "date" }, "due_date": { "type": "string", "format": "date" }, "tax_date": { "type": [ "string", "null" ], "format": "date" }, "exchange_rate": { "type": "string" }, "vat_note": { "type": "string" }, "note": { "type": "string", "maxLength": 4000 }, "items": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "type": "object", "additionalProperties": false, "required": [ "description", "quantity", "unit_price" ], "properties": { "description": { "type": "string", "maxLength": 500 }, "quantity": { "type": "string", "pattern": "^\\d{1,7}(\\.\\d{1,3})?$" }, "unit": { "type": "string", "maxLength": 20 }, "unit_price": { "type": "string", "pattern": "^\\d{1,7}(\\.\\d{1,2})?$", "examples": [ "350.00" ] }, "vat_rate": { "oneOf": [ { "type": "integer", "enum": [ 0, 12, 21 ] }, { "type": "string", "enum": [ "0", "12", "21" ] } ] } } } }, "custom_link": { "type": [ "string", "null" ], "format": "uri", "maxLength": 2048, "description": "Absolutní HTTPS URL bez přihlašovacích údajů; použije ji placeholder {:custom_link:}." }, "version": { "type": "integer", "minimum": 1 } } }, "ItemInput": { "type": "object", "additionalProperties": false, "required": [ "description", "quantity", "unit_price" ], "properties": { "description": { "type": "string", "maxLength": 500 }, "quantity": { "type": "string", "pattern": "^\\d{1,7}(\\.\\d{1,3})?$" }, "unit": { "type": "string", "maxLength": 20 }, "unit_price": { "type": "string", "pattern": "^\\d{1,7}(\\.\\d{1,2})?$", "examples": [ "350.00" ] }, "vat_rate": { "oneOf": [ { "type": "integer", "enum": [ 0, 12, 21 ] }, { "type": "string", "enum": [ "0", "12", "21" ] } ] } } }, "Contact": { "type": "object", "required": [ "id", "name", "active" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "registration_number": { "type": "string" }, "vat_id": { "type": "string" }, "street": { "type": "string" }, "city": { "type": "string" }, "zip": { "type": "string" }, "country_code": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": "string" }, "website": { "type": "string" }, "note": { "type": "string" }, "active": { "type": "boolean", "default": true }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "InvoiceSummary": { "type": "object", "required": [ "id", "document_type", "status", "currency", "total_gross", "paid_amount", "remaining_amount" ], "properties": { "id": { "type": "string", "format": "uuid" }, "version": { "type": "integer" }, "document_type": { "type": "string", "enum": [ "invoice", "proforma" ] }, "status": { "type": "string", "enum": [ "draft", "issued", "cancelled" ] }, "number": { "type": [ "string", "null" ] }, "variable_symbol": { "type": [ "string", "null" ] }, "contact_id": { "type": [ "string", "null" ], "format": "uuid" }, "contact_name": { "type": "string" }, "currency": { "type": "string" }, "issue_date": { "type": [ "string", "null" ], "format": "date" }, "due_date": { "type": [ "string", "null" ], "format": "date" }, "total_gross": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "paid_amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "remaining_amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "Invoice": { "type": "object", "required": [ "id", "document_type", "status", "currency", "total_gross", "paid_amount", "remaining_amount" ], "properties": { "id": { "type": "string", "format": "uuid" }, "version": { "type": "integer" }, "document_type": { "type": "string", "enum": [ "invoice", "proforma" ] }, "status": { "type": "string", "enum": [ "draft", "issued", "cancelled" ] }, "number": { "type": [ "string", "null" ] }, "variable_symbol": { "type": [ "string", "null" ] }, "contact_id": { "type": [ "string", "null" ], "format": "uuid" }, "currency": { "type": "string" }, "issue_date": { "type": [ "string", "null" ], "format": "date" }, "due_date": { "type": [ "string", "null" ], "format": "date" }, "total_gross": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "paid_amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "remaining_amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "payment_method": { "type": "string", "enum": [ "bank", "cash", "card", "other" ] }, "tax_date": { "type": [ "string", "null" ], "format": "date" }, "custom_link": { "type": [ "string", "null" ], "format": "uri" }, "note": { "type": "string" }, "supplier": { "type": "object" }, "receiver": { "type": "object" }, "items": { "type": "array", "items": { "type": "object", "properties": { "description": { "type": "string" }, "quantity": { "type": "string" }, "unit": { "type": "string" }, "unit_price": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "vat_rate": { "type": [ "integer", "null" ], "enum": [ null, 0, 12, 21 ] }, "total_net": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "total_vat": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "total_gross": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" } } } }, "total_net": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "total_vat": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "payment_state": { "type": "string", "enum": [ "draft", "cancelled", "paid", "partial", "unpaid", "overdue" ] }, "followup_invoice_id": { "type": [ "string", "null" ], "format": "uuid" }, "public_url": { "type": [ "string", "null" ], "format": "uri" }, "pdf_url": { "type": "string", "format": "uri" }, "isdoc_url": { "type": "string", "format": "uri" }, "email_job": { "$ref": "#/components/schemas/Job" } } }, "Job": { "type": "object", "required": [ "id", "type", "status" ], "properties": { "id": { "type": "string", "format": "uuid" }, "type": { "type": "string", "enum": [ "pdf", "email" ] }, "status": { "type": "string", "enum": [ "pending", "processing", "ready", "queued", "sent", "failed", "cancelled" ] }, "status_url": { "type": "string", "format": "uri" }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } }, "PageMeta": { "type": "object", "required": [ "page", "per_page", "total", "pages" ], "properties": { "page": { "type": "integer", "minimum": 1 }, "per_page": { "type": "integer", "minimum": 1 }, "total": { "type": "integer", "minimum": 0 }, "pages": { "type": "integer", "minimum": 1 } } }, "Webhook": { "type": "object", "required": [ "id", "url", "events", "active", "version" ], "properties": { "id": { "type": "string", "format": "uuid" }, "url": { "type": "string", "format": "uri", "description": "Veřejný HTTPS hostname, port443, žádné userinfo/fragment. Přesměrování se nenásledují." }, "events": { "type": "array", "minItems": 1, "items": { "type": "string", "enum": [ "invoice.created", "invoice.updated", "invoice.issued", "invoice.cancelled", "invoice.payment_added", "invoice.paid", "invoice.payment_removed", "invoice.settled", "invoice.pdf_ready", "webhook.test" ] } }, "active": { "type": "boolean" }, "version": { "type": "integer", "minimum": 1 }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "secret": { "type": "string", "description": "Pouze při vytvoření/rotaci a opakování stejné idempotentní operace. Běžný GET tajemství nikdy nevrací." } } } } } }