{ "openapi": "3.0.3", "info": { "title": "Zaksio API", "version": "1.0.0", "description": "Publiczne API Zaksio v1: produkty, stany magazynowe, kontrahenci i faktury sprzedazowe. Uwierzytelnianie kluczem API (`Authorization: Bearer zk_live_...`), kwoty w groszach, bledy w formacie RFC 9457, paginacja kursorowa i `Idempotency-Key` na zapisach." }, "servers": [ { "url": "https://api.zaksio.pl", "description": "Produkcja" } ], "tags": [ { "name": "Konto", "description": "Informacje o kluczu API uzytym w zadaniu." }, { "name": "Produkty", "description": "Kartoteka produktow i uslug." }, { "name": "Stany magazynowe", "description": "Aktualne stany magazynowe (odczyt)." }, { "name": "Kontrahenci", "description": "Klienci i dostawcy." }, { "name": "Faktury", "description": "Faktury sprzedazowe: odczyt, PDF i wystawianie." } ], "paths": { "/v1/whoami": { "get": { "operationId": "whoami", "summary": "Informacje o kluczu", "tags": ["Konto"], "description": "Zwraca firme, zakresy i limit biezacego klucza. Przydatne do sprawdzenia, czy klucz dziala i do czego daje dostep. Nie wymaga zadnego zakresu.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "key": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string" }, "prefix": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } }, "rateLimitPerMin": { "type": "integer" } }, "required": ["id", "name", "prefix", "scopes", "rateLimitPerMin"], "additionalProperties": false }, "company": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string" }, "nip": { "nullable": true, "type": "string" } }, "required": ["id", "name", "nip"], "additionalProperties": false } }, "required": ["key", "company"], "additionalProperties": false }, "example": { "key": { "id": "5e8d2b1c-9f3a-4b7d-8c6e-2a1b3c4d5e6f", "name": "Integracja sklepu", "prefix": "zk_live_AbCd1234", "scopes": ["products:read", "stock:read"], "rateLimitPerMin": 120 }, "company": { "id": "9c1d2e3f-4a5b-4c6d-8e7f-0a1b2c3d4e5f", "name": "Moja Firma Sp. z o.o.", "nip": "5252248481" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } }, "x-required-scope": null, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET \"https://api.zaksio.pl/v1/whoami\" \\\n -H \"Authorization: Bearer $ZAKSIO_API_KEY\"" }, { "lang": "javascript", "label": "JavaScript (Node.js)", "source": "const response = await fetch(\"https://api.zaksio.pl/v1/whoami\", {\n method: \"GET\",\n headers: {\n Authorization: `Bearer ${process.env.ZAKSIO_API_KEY}`,\n },\n});\n\nconst data = await response.json();\nif (!response.ok) throw new Error(`${data.code}: ${data.detail}`); // application/problem+json\nconsole.log(data);" }, { "lang": "python", "label": "Python", "source": "import os\nimport requests\n\nresponse = requests.request(\n \"GET\",\n \"https://api.zaksio.pl/v1/whoami\",\n headers={\n \"Authorization\": f\"Bearer {os.environ['ZAKSIO_API_KEY']}\",\n },\n timeout=30,\n)\n\nif not response.ok:\n problem = response.json() # application/problem+json\n raise RuntimeError(f\"{problem['code']}: {problem['detail']}\")\nprint(response.json())" }, { "lang": "php", "label": "PHP", "source": " 'GET',\n CURLOPT_RETURNTRANSFER => true,\n CURLOPT_TIMEOUT => 30,\n CURLOPT_HTTPHEADER => [\n 'Authorization: Bearer ' . getenv('ZAKSIO_API_KEY'),\n ],\n]);\n$body = curl_exec($ch);\n$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);\ncurl_close($ch);\n\n$data = json_decode($body, true);\nif ($status >= 400) {\n // application/problem+json\n throw new RuntimeException($data['code'] . ': ' . $data['detail']);\n}\nprint_r($data);" } ] } }, "/v1/products": { "get": { "operationId": "listProducts", "summary": "Lista produktow", "tags": ["Produkty"], "description": "Produkty z kartoteki firmy przypisanej do klucza. Paginacja kursorowa; domyslnie od najstarszych (`order=asc`), bez produktow nieaktywnych.", "parameters": [ { "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 200 }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "string", "maxLength": 300 }, "in": "query", "name": "cursor", "required": false }, { "schema": { "default": "asc", "type": "string", "enum": ["asc", "desc"] }, "in": "query", "name": "order", "required": false }, { "schema": { "type": "string", "maxLength": 100 }, "in": "query", "name": "q", "required": false, "description": "Szukaj w SKU i nazwie albo dokladny kod EAN" }, { "schema": { "type": "string", "maxLength": 64 }, "in": "query", "name": "sku", "required": false, "description": "Dokladny SKU" }, { "schema": { "type": "string", "enum": ["good", "service"] }, "in": "query", "name": "kind", "required": false }, { "schema": { "default": "false", "type": "string", "enum": ["true", "false"] }, "in": "query", "name": "includeInactive", "required": false } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Product" } }, "pagination": { "type": "object", "properties": { "limit": { "type": "integer" }, "hasMore": { "type": "boolean" }, "nextCursor": { "nullable": true, "type": "string" } }, "required": ["limit", "hasMore", "nextCursor"], "additionalProperties": false } }, "required": ["data", "pagination"], "additionalProperties": false }, "example": { "data": [ { "id": "3f9a1b2c-4d5e-4f60-8a7b-9c0d1e2f3a4b", "sku": "KAW-001", "name": "Kawa ziarnista 1 kg", "kind": "good", "unit": "kg", "ean": "5901234123457", "vatRate": "8", "defaultNetPrice": 4500, "tracking": "none", "hasExpiry": false, "weightG": 1000, "hazmat": false, "active": true, "createdAt": "2026-10-12T08:15:00.000Z" } ], "pagination": { "limit": 50, "hasMore": false, "nextCursor": null } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } }, "x-required-scope": "products:read", "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET \"https://api.zaksio.pl/v1/products?limit=50&q=kawa\" \\\n -H \"Authorization: Bearer $ZAKSIO_API_KEY\"" }, { "lang": "javascript", "label": "JavaScript (Node.js)", "source": "const response = await fetch(\"https://api.zaksio.pl/v1/products?limit=50&q=kawa\", {\n method: \"GET\",\n headers: {\n Authorization: `Bearer ${process.env.ZAKSIO_API_KEY}`,\n },\n});\n\nconst data = await response.json();\nif (!response.ok) throw new Error(`${data.code}: ${data.detail}`); // application/problem+json\nconsole.log(data);" }, { "lang": "python", "label": "Python", "source": "import os\nimport requests\n\nresponse = requests.request(\n \"GET\",\n \"https://api.zaksio.pl/v1/products\",\n headers={\n \"Authorization\": f\"Bearer {os.environ['ZAKSIO_API_KEY']}\",\n },\n params={\n \"limit\": \"50\",\n \"q\": \"kawa\",\n },\n timeout=30,\n)\n\nif not response.ok:\n problem = response.json() # application/problem+json\n raise RuntimeError(f\"{problem['code']}: {problem['detail']}\")\nprint(response.json())" }, { "lang": "php", "label": "PHP", "source": " 'GET',\n CURLOPT_RETURNTRANSFER => true,\n CURLOPT_TIMEOUT => 30,\n CURLOPT_HTTPHEADER => [\n 'Authorization: Bearer ' . getenv('ZAKSIO_API_KEY'),\n ],\n]);\n$body = curl_exec($ch);\n$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);\ncurl_close($ch);\n\n$data = json_decode($body, true);\nif ($status >= 400) {\n // application/problem+json\n throw new RuntimeException($data['code'] . ': ' . $data['detail']);\n}\nprint_r($data);" } ] }, "post": { "operationId": "createProduct", "summary": "Dodanie produktu", "tags": ["Produkty"], "description": "Dodaje produkt do kartoteki. SKU i EAN musza byc unikalne w firmie (409 `sku_or_ean_taken`). Obsluguje `Idempotency-Key`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "sku": { "type": "string", "minLength": 1, "maxLength": 64 }, "name": { "type": "string", "minLength": 1, "maxLength": 300 }, "kind": { "default": "good", "type": "string", "enum": ["good", "service"] }, "unit": { "default": "szt.", "type": "string", "minLength": 1, "maxLength": 20 }, "ean": { "type": "string" }, "vatRate": { "default": "23", "type": "string", "enum": ["0", "5", "8", "23", "zw", "np"] }, "defaultNetPrice": { "type": "integer", "minimum": 0 }, "tracking": { "default": "none", "type": "string", "enum": ["none", "lot", "serial"] }, "hasExpiry": { "default": false, "type": "boolean" }, "weightG": { "type": "integer", "minimum": 0 }, "hazmat": { "default": false, "type": "boolean" } }, "required": ["sku", "name"] }, "example": { "sku": "KAW-001", "name": "Kawa ziarnista 1 kg", "unit": "kg", "vatRate": "8", "defaultNetPrice": 4500, "ean": "5901234123457" } } } }, "parameters": [ { "schema": { "type": "string", "maxLength": 255 }, "in": "header", "name": "Idempotency-Key", "required": false, "description": "Unikalny klucz zapisu (np. UUID). Powtorzenie zadania z tym samym kluczem zwraca zapamietana odpowiedz zamiast wykonywac zapis drugi raz (24 h)." } ], "security": [ { "bearerAuth": [] } ], "responses": { "201": { "description": "Utworzono", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Product" }, "example": { "id": "3f9a1b2c-4d5e-4f60-8a7b-9c0d1e2f3a4b", "sku": "KAW-001", "name": "Kawa ziarnista 1 kg", "kind": "good", "unit": "kg", "ean": "5901234123457", "vatRate": "8", "defaultNetPrice": 4500, "tracking": "none", "hasExpiry": false, "weightG": 1000, "hazmat": false, "active": true, "createdAt": "2026-10-12T08:15:00.000Z" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/LicenceReadOnly" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } }, "x-required-scope": "products:write", "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST \"https://api.zaksio.pl/v1/products\" \\\n -H \"Authorization: Bearer $ZAKSIO_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -H \"Idempotency-Key: 6f1c8a3e-2b4d-4e5f-9a7b-3c2d1e0f9a8b\" \\\n -d '{\"sku\":\"KAW-001\",\"name\":\"Kawa ziarnista 1 kg\",\"unit\":\"kg\",\"vatRate\":\"8\",\"defaultNetPrice\":4500,\"ean\":\"5901234123457\"}'" }, { "lang": "javascript", "label": "JavaScript (Node.js)", "source": "const response = await fetch(\"https://api.zaksio.pl/v1/products\", {\n method: \"POST\",\n headers: {\n Authorization: `Bearer ${process.env.ZAKSIO_API_KEY}`,\n \"Content-Type\": \"application/json\",\n \"Idempotency-Key\": \"6f1c8a3e-2b4d-4e5f-9a7b-3c2d1e0f9a8b\",\n },\n body: JSON.stringify({\n \"sku\": \"KAW-001\",\n \"name\": \"Kawa ziarnista 1 kg\",\n \"unit\": \"kg\",\n \"vatRate\": \"8\",\n \"defaultNetPrice\": 4500,\n \"ean\": \"5901234123457\"\n }),\n});\n\nconst data = await response.json();\nif (!response.ok) throw new Error(`${data.code}: ${data.detail}`); // application/problem+json\nconsole.log(data);" }, { "lang": "python", "label": "Python", "source": "import os\nimport requests\n\nresponse = requests.request(\n \"POST\",\n \"https://api.zaksio.pl/v1/products\",\n headers={\n \"Authorization\": f\"Bearer {os.environ['ZAKSIO_API_KEY']}\",\n \"Content-Type\": \"application/json\",\n \"Idempotency-Key\": \"6f1c8a3e-2b4d-4e5f-9a7b-3c2d1e0f9a8b\",\n },\n json={\n \"sku\": \"KAW-001\",\n \"name\": \"Kawa ziarnista 1 kg\",\n \"unit\": \"kg\",\n \"vatRate\": \"8\",\n \"defaultNetPrice\": 4500,\n \"ean\": \"5901234123457\",\n },\n timeout=30,\n)\n\nif not response.ok:\n problem = response.json() # application/problem+json\n raise RuntimeError(f\"{problem['code']}: {problem['detail']}\")\nprint(response.json())" }, { "lang": "php", "label": "PHP", "source": " 'POST',\n CURLOPT_RETURNTRANSFER => true,\n CURLOPT_TIMEOUT => 30,\n CURLOPT_HTTPHEADER => [\n 'Authorization: Bearer ' . getenv('ZAKSIO_API_KEY'),\n 'Content-Type: application/json',\n 'Idempotency-Key: 6f1c8a3e-2b4d-4e5f-9a7b-3c2d1e0f9a8b',\n ],\n CURLOPT_POSTFIELDS => json_encode([\n 'sku' => 'KAW-001',\n 'name' => 'Kawa ziarnista 1 kg',\n 'unit' => 'kg',\n 'vatRate' => '8',\n 'defaultNetPrice' => 4500,\n 'ean' => '5901234123457',\n ]),\n]);\n$body = curl_exec($ch);\n$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);\ncurl_close($ch);\n\n$data = json_decode($body, true);\nif ($status >= 400) {\n // application/problem+json\n throw new RuntimeException($data['code'] . ': ' . $data['detail']);\n}\nprint_r($data);" } ] } }, "/v1/products/{id}": { "get": { "operationId": "getProduct", "summary": "Szczegoly produktu", "tags": ["Produkty"], "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Product" }, "example": { "id": "3f9a1b2c-4d5e-4f60-8a7b-9c0d1e2f3a4b", "sku": "KAW-001", "name": "Kawa ziarnista 1 kg", "kind": "good", "unit": "kg", "ean": "5901234123457", "vatRate": "8", "defaultNetPrice": 4500, "tracking": "none", "hasExpiry": false, "weightG": 1000, "hazmat": false, "active": true, "createdAt": "2026-10-12T08:15:00.000Z" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } }, "x-required-scope": "products:read", "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET \"https://api.zaksio.pl/v1/products/3f9a1b2c-4d5e-4f60-8a7b-9c0d1e2f3a4b\" \\\n -H \"Authorization: Bearer $ZAKSIO_API_KEY\"" }, { "lang": "javascript", "label": "JavaScript (Node.js)", "source": "const response = await fetch(\"https://api.zaksio.pl/v1/products/3f9a1b2c-4d5e-4f60-8a7b-9c0d1e2f3a4b\", {\n method: \"GET\",\n headers: {\n Authorization: `Bearer ${process.env.ZAKSIO_API_KEY}`,\n },\n});\n\nconst data = await response.json();\nif (!response.ok) throw new Error(`${data.code}: ${data.detail}`); // application/problem+json\nconsole.log(data);" }, { "lang": "python", "label": "Python", "source": "import os\nimport requests\n\nresponse = requests.request(\n \"GET\",\n \"https://api.zaksio.pl/v1/products/3f9a1b2c-4d5e-4f60-8a7b-9c0d1e2f3a4b\",\n headers={\n \"Authorization\": f\"Bearer {os.environ['ZAKSIO_API_KEY']}\",\n },\n timeout=30,\n)\n\nif not response.ok:\n problem = response.json() # application/problem+json\n raise RuntimeError(f\"{problem['code']}: {problem['detail']}\")\nprint(response.json())" }, { "lang": "php", "label": "PHP", "source": " 'GET',\n CURLOPT_RETURNTRANSFER => true,\n CURLOPT_TIMEOUT => 30,\n CURLOPT_HTTPHEADER => [\n 'Authorization: Bearer ' . getenv('ZAKSIO_API_KEY'),\n ],\n]);\n$body = curl_exec($ch);\n$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);\ncurl_close($ch);\n\n$data = json_decode($body, true);\nif ($status >= 400) {\n // application/problem+json\n throw new RuntimeException($data['code'] . ': ' . $data['detail']);\n}\nprint_r($data);" } ] }, "patch": { "operationId": "updateProduct", "summary": "Zmiana produktu", "tags": ["Produkty"], "description": "Zmienia tylko przekazane pola. Rodzaju (`kind`) nie zmienia sie; sledzenie partii i terminow waznosci mozna zmienic tylko dla produktu bez historii ruchow magazynowych.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "sku": { "type": "string", "minLength": 1, "maxLength": 64 }, "name": { "type": "string", "minLength": 1, "maxLength": 300 }, "unit": { "type": "string", "minLength": 1, "maxLength": 20 }, "ean": { "type": "string" }, "vatRate": { "type": "string", "enum": ["0", "5", "8", "23", "zw", "np"] }, "defaultNetPrice": { "type": "integer", "minimum": 0 }, "tracking": { "type": "string", "enum": ["none", "lot", "serial"] }, "hasExpiry": { "type": "boolean" }, "weightG": { "type": "integer", "minimum": 0 }, "hazmat": { "type": "boolean" } } }, "example": { "name": "Kawa ziarnista Arabica 1 kg", "defaultNetPrice": 4900 } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true }, { "schema": { "type": "string", "maxLength": 255 }, "in": "header", "name": "Idempotency-Key", "required": false, "description": "Unikalny klucz zapisu (np. UUID). Powtorzenie zadania z tym samym kluczem zwraca zapamietana odpowiedz zamiast wykonywac zapis drugi raz (24 h)." } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Product" }, "example": { "id": "3f9a1b2c-4d5e-4f60-8a7b-9c0d1e2f3a4b", "sku": "KAW-001", "name": "Kawa ziarnista Arabica 1 kg", "kind": "good", "unit": "kg", "ean": "5901234123457", "vatRate": "8", "defaultNetPrice": 4900, "tracking": "none", "hasExpiry": false, "weightG": 1000, "hazmat": false, "active": true, "createdAt": "2026-10-12T08:15:00.000Z" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/LicenceReadOnly" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } }, "x-required-scope": "products:write", "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X PATCH \"https://api.zaksio.pl/v1/products/3f9a1b2c-4d5e-4f60-8a7b-9c0d1e2f3a4b\" \\\n -H \"Authorization: Bearer $ZAKSIO_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -H \"Idempotency-Key: 6f1c8a3e-2b4d-4e5f-9a7b-3c2d1e0f9a8b\" \\\n -d '{\"name\":\"Kawa ziarnista Arabica 1 kg\",\"defaultNetPrice\":4900}'" }, { "lang": "javascript", "label": "JavaScript (Node.js)", "source": "const response = await fetch(\"https://api.zaksio.pl/v1/products/3f9a1b2c-4d5e-4f60-8a7b-9c0d1e2f3a4b\", {\n method: \"PATCH\",\n headers: {\n Authorization: `Bearer ${process.env.ZAKSIO_API_KEY}`,\n \"Content-Type\": \"application/json\",\n \"Idempotency-Key\": \"6f1c8a3e-2b4d-4e5f-9a7b-3c2d1e0f9a8b\",\n },\n body: JSON.stringify({\n \"name\": \"Kawa ziarnista Arabica 1 kg\",\n \"defaultNetPrice\": 4900\n }),\n});\n\nconst data = await response.json();\nif (!response.ok) throw new Error(`${data.code}: ${data.detail}`); // application/problem+json\nconsole.log(data);" }, { "lang": "python", "label": "Python", "source": "import os\nimport requests\n\nresponse = requests.request(\n \"PATCH\",\n \"https://api.zaksio.pl/v1/products/3f9a1b2c-4d5e-4f60-8a7b-9c0d1e2f3a4b\",\n headers={\n \"Authorization\": f\"Bearer {os.environ['ZAKSIO_API_KEY']}\",\n \"Content-Type\": \"application/json\",\n \"Idempotency-Key\": \"6f1c8a3e-2b4d-4e5f-9a7b-3c2d1e0f9a8b\",\n },\n json={\n \"name\": \"Kawa ziarnista Arabica 1 kg\",\n \"defaultNetPrice\": 4900,\n },\n timeout=30,\n)\n\nif not response.ok:\n problem = response.json() # application/problem+json\n raise RuntimeError(f\"{problem['code']}: {problem['detail']}\")\nprint(response.json())" }, { "lang": "php", "label": "PHP", "source": " 'PATCH',\n CURLOPT_RETURNTRANSFER => true,\n CURLOPT_TIMEOUT => 30,\n CURLOPT_HTTPHEADER => [\n 'Authorization: Bearer ' . getenv('ZAKSIO_API_KEY'),\n 'Content-Type: application/json',\n 'Idempotency-Key: 6f1c8a3e-2b4d-4e5f-9a7b-3c2d1e0f9a8b',\n ],\n CURLOPT_POSTFIELDS => json_encode([\n 'name' => 'Kawa ziarnista Arabica 1 kg',\n 'defaultNetPrice' => 4900,\n ]),\n]);\n$body = curl_exec($ch);\n$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);\ncurl_close($ch);\n\n$data = json_decode($body, true);\nif ($status >= 400) {\n // application/problem+json\n throw new RuntimeException($data['code'] . ': ' . $data['detail']);\n}\nprint_r($data);" } ] } }, "/v1/stock": { "get": { "operationId": "listStock", "summary": "Stany magazynowe", "tags": ["Stany magazynowe"], "description": "Stan kazdego produktu, ktory ma ruchy magazynowe: suma oraz podzial na magazyny. Lista jest uporzadkowana po identyfikatorze produktu, a kursor wskazuje ostatni zwrocony produkt.", "parameters": [ { "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 200 }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "string", "maxLength": 300 }, "in": "query", "name": "cursor", "required": false }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "query", "name": "warehouseId", "required": false, "description": "Ogranicz do jednego magazynu" } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/StockLevel" } }, "pagination": { "type": "object", "properties": { "limit": { "type": "integer" }, "hasMore": { "type": "boolean" }, "nextCursor": { "nullable": true, "type": "string" } }, "required": ["limit", "hasMore", "nextCursor"], "additionalProperties": false } }, "required": ["data", "pagination"], "additionalProperties": false }, "example": { "data": [ { "productId": "3f9a1b2c-4d5e-4f60-8a7b-9c0d1e2f3a4b", "sku": "KAW-001", "name": "Kawa ziarnista 1 kg", "unit": "kg", "quantity": "42.5", "warehouses": [ { "warehouseId": "a1b2c3d4-0000-4000-8000-000000000001", "warehouseCode": "MAG", "quantity": "40" }, { "warehouseId": "a1b2c3d4-0000-4000-8000-000000000002", "warehouseCode": "SKLEP", "quantity": "2.5" } ] } ], "pagination": { "limit": 50, "hasMore": false, "nextCursor": null } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } }, "x-required-scope": "stock:read", "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET \"https://api.zaksio.pl/v1/stock?limit=50\" \\\n -H \"Authorization: Bearer $ZAKSIO_API_KEY\"" }, { "lang": "javascript", "label": "JavaScript (Node.js)", "source": "const response = await fetch(\"https://api.zaksio.pl/v1/stock?limit=50\", {\n method: \"GET\",\n headers: {\n Authorization: `Bearer ${process.env.ZAKSIO_API_KEY}`,\n },\n});\n\nconst data = await response.json();\nif (!response.ok) throw new Error(`${data.code}: ${data.detail}`); // application/problem+json\nconsole.log(data);" }, { "lang": "python", "label": "Python", "source": "import os\nimport requests\n\nresponse = requests.request(\n \"GET\",\n \"https://api.zaksio.pl/v1/stock\",\n headers={\n \"Authorization\": f\"Bearer {os.environ['ZAKSIO_API_KEY']}\",\n },\n params={\n \"limit\": \"50\",\n },\n timeout=30,\n)\n\nif not response.ok:\n problem = response.json() # application/problem+json\n raise RuntimeError(f\"{problem['code']}: {problem['detail']}\")\nprint(response.json())" }, { "lang": "php", "label": "PHP", "source": " 'GET',\n CURLOPT_RETURNTRANSFER => true,\n CURLOPT_TIMEOUT => 30,\n CURLOPT_HTTPHEADER => [\n 'Authorization: Bearer ' . getenv('ZAKSIO_API_KEY'),\n ],\n]);\n$body = curl_exec($ch);\n$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);\ncurl_close($ch);\n\n$data = json_decode($body, true);\nif ($status >= 400) {\n // application/problem+json\n throw new RuntimeException($data['code'] . ': ' . $data['detail']);\n}\nprint_r($data);" } ] } }, "/v1/stock/{id}": { "get": { "operationId": "getStock", "summary": "Stan jednego produktu", "tags": ["Stany magazynowe"], "description": "Stan produktu o podanym identyfikatorze. Produkt bez ruchow magazynowych ma stan 0.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StockLevel" }, "example": { "productId": "3f9a1b2c-4d5e-4f60-8a7b-9c0d1e2f3a4b", "sku": "KAW-001", "name": "Kawa ziarnista 1 kg", "unit": "kg", "quantity": "42.5", "warehouses": [ { "warehouseId": "a1b2c3d4-0000-4000-8000-000000000001", "warehouseCode": "MAG", "quantity": "40" }, { "warehouseId": "a1b2c3d4-0000-4000-8000-000000000002", "warehouseCode": "SKLEP", "quantity": "2.5" } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } }, "x-required-scope": "stock:read", "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET \"https://api.zaksio.pl/v1/stock/3f9a1b2c-4d5e-4f60-8a7b-9c0d1e2f3a4b\" \\\n -H \"Authorization: Bearer $ZAKSIO_API_KEY\"" }, { "lang": "javascript", "label": "JavaScript (Node.js)", "source": "const response = await fetch(\"https://api.zaksio.pl/v1/stock/3f9a1b2c-4d5e-4f60-8a7b-9c0d1e2f3a4b\", {\n method: \"GET\",\n headers: {\n Authorization: `Bearer ${process.env.ZAKSIO_API_KEY}`,\n },\n});\n\nconst data = await response.json();\nif (!response.ok) throw new Error(`${data.code}: ${data.detail}`); // application/problem+json\nconsole.log(data);" }, { "lang": "python", "label": "Python", "source": "import os\nimport requests\n\nresponse = requests.request(\n \"GET\",\n \"https://api.zaksio.pl/v1/stock/3f9a1b2c-4d5e-4f60-8a7b-9c0d1e2f3a4b\",\n headers={\n \"Authorization\": f\"Bearer {os.environ['ZAKSIO_API_KEY']}\",\n },\n timeout=30,\n)\n\nif not response.ok:\n problem = response.json() # application/problem+json\n raise RuntimeError(f\"{problem['code']}: {problem['detail']}\")\nprint(response.json())" }, { "lang": "php", "label": "PHP", "source": " 'GET',\n CURLOPT_RETURNTRANSFER => true,\n CURLOPT_TIMEOUT => 30,\n CURLOPT_HTTPHEADER => [\n 'Authorization: Bearer ' . getenv('ZAKSIO_API_KEY'),\n ],\n]);\n$body = curl_exec($ch);\n$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);\ncurl_close($ch);\n\n$data = json_decode($body, true);\nif ($status >= 400) {\n // application/problem+json\n throw new RuntimeException($data['code'] . ': ' . $data['detail']);\n}\nprint_r($data);" } ] } }, "/v1/contractors": { "get": { "operationId": "listContractors", "summary": "Lista kontrahentow", "tags": ["Kontrahenci"], "description": "Kontrahenci firmy przypisanej do klucza. Paginacja kursorowa.", "parameters": [ { "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 200 }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "string", "maxLength": 300 }, "in": "query", "name": "cursor", "required": false }, { "schema": { "default": "asc", "type": "string", "enum": ["asc", "desc"] }, "in": "query", "name": "order", "required": false }, { "schema": { "type": "string", "maxLength": 100 }, "in": "query", "name": "q", "required": false, "description": "Szukaj w nazwie, e-mailu i miescie" }, { "schema": { "type": "string", "maxLength": 20 }, "in": "query", "name": "nip", "required": false, "description": "Dokladny NIP (cyfry)" } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Contractor" } }, "pagination": { "type": "object", "properties": { "limit": { "type": "integer" }, "hasMore": { "type": "boolean" }, "nextCursor": { "nullable": true, "type": "string" } }, "required": ["limit", "hasMore", "nextCursor"], "additionalProperties": false } }, "required": ["data", "pagination"], "additionalProperties": false }, "example": { "data": [ { "id": "7d2c9e10-5a4b-4c3d-9e8f-1a2b3c4d5e6f", "name": "Przykladowa Sp. z o.o.", "nip": "5252248481", "country": "PL", "street": "Prosta 1", "postalCode": "00-001", "city": "Warszawa", "email": "ksiegowosc@przyklad.pl", "createdAt": "2026-10-12T08:20:00.000Z" } ], "pagination": { "limit": 50, "hasMore": false, "nextCursor": null } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } }, "x-required-scope": "contractors:read", "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET \"https://api.zaksio.pl/v1/contractors?q=przyklad\" \\\n -H \"Authorization: Bearer $ZAKSIO_API_KEY\"" }, { "lang": "javascript", "label": "JavaScript (Node.js)", "source": "const response = await fetch(\"https://api.zaksio.pl/v1/contractors?q=przyklad\", {\n method: \"GET\",\n headers: {\n Authorization: `Bearer ${process.env.ZAKSIO_API_KEY}`,\n },\n});\n\nconst data = await response.json();\nif (!response.ok) throw new Error(`${data.code}: ${data.detail}`); // application/problem+json\nconsole.log(data);" }, { "lang": "python", "label": "Python", "source": "import os\nimport requests\n\nresponse = requests.request(\n \"GET\",\n \"https://api.zaksio.pl/v1/contractors\",\n headers={\n \"Authorization\": f\"Bearer {os.environ['ZAKSIO_API_KEY']}\",\n },\n params={\n \"q\": \"przyklad\",\n },\n timeout=30,\n)\n\nif not response.ok:\n problem = response.json() # application/problem+json\n raise RuntimeError(f\"{problem['code']}: {problem['detail']}\")\nprint(response.json())" }, { "lang": "php", "label": "PHP", "source": " 'GET',\n CURLOPT_RETURNTRANSFER => true,\n CURLOPT_TIMEOUT => 30,\n CURLOPT_HTTPHEADER => [\n 'Authorization: Bearer ' . getenv('ZAKSIO_API_KEY'),\n ],\n]);\n$body = curl_exec($ch);\n$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);\ncurl_close($ch);\n\n$data = json_decode($body, true);\nif ($status >= 400) {\n // application/problem+json\n throw new RuntimeException($data['code'] . ': ' . $data['detail']);\n}\nprint_r($data);" } ] }, "post": { "operationId": "createContractor", "summary": "Dodanie kontrahenta", "tags": ["Kontrahenci"], "description": "Dodaje kontrahenta. Obsluguje `Idempotency-Key`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 300 }, "nip": { "type": "string" }, "country": { "default": "PL", "type": "string", "minLength": 2, "maxLength": 2 }, "street": { "type": "string", "maxLength": 200 }, "postalCode": { "type": "string", "maxLength": 20 }, "city": { "type": "string", "maxLength": 100 }, "email": { "type": "string", "format": "email", "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "vatEuNumber": { "type": "string" }, "isConsumer": { "type": "boolean" } }, "required": ["name"] }, "example": { "name": "Przykladowa Sp. z o.o.", "nip": "5252248481", "street": "Prosta 1", "postalCode": "00-001", "city": "Warszawa", "email": "ksiegowosc@przyklad.pl" } } } }, "parameters": [ { "schema": { "type": "string", "maxLength": 255 }, "in": "header", "name": "Idempotency-Key", "required": false, "description": "Unikalny klucz zapisu (np. UUID). Powtorzenie zadania z tym samym kluczem zwraca zapamietana odpowiedz zamiast wykonywac zapis drugi raz (24 h)." } ], "security": [ { "bearerAuth": [] } ], "responses": { "201": { "description": "Utworzono", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Contractor" }, "example": { "id": "7d2c9e10-5a4b-4c3d-9e8f-1a2b3c4d5e6f", "name": "Przykladowa Sp. z o.o.", "nip": "5252248481", "country": "PL", "street": "Prosta 1", "postalCode": "00-001", "city": "Warszawa", "email": "ksiegowosc@przyklad.pl", "createdAt": "2026-10-12T08:20:00.000Z" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/LicenceReadOnly" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } }, "x-required-scope": "contractors:write", "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST \"https://api.zaksio.pl/v1/contractors\" \\\n -H \"Authorization: Bearer $ZAKSIO_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -H \"Idempotency-Key: 6f1c8a3e-2b4d-4e5f-9a7b-3c2d1e0f9a8b\" \\\n -d '{\"name\":\"Przykladowa Sp. z o.o.\",\"nip\":\"5252248481\",\"street\":\"Prosta 1\",\"postalCode\":\"00-001\",\"city\":\"Warszawa\",\"email\":\"ksiegowosc@przyklad.pl\"}'" }, { "lang": "javascript", "label": "JavaScript (Node.js)", "source": "const response = await fetch(\"https://api.zaksio.pl/v1/contractors\", {\n method: \"POST\",\n headers: {\n Authorization: `Bearer ${process.env.ZAKSIO_API_KEY}`,\n \"Content-Type\": \"application/json\",\n \"Idempotency-Key\": \"6f1c8a3e-2b4d-4e5f-9a7b-3c2d1e0f9a8b\",\n },\n body: JSON.stringify({\n \"name\": \"Przykladowa Sp. z o.o.\",\n \"nip\": \"5252248481\",\n \"street\": \"Prosta 1\",\n \"postalCode\": \"00-001\",\n \"city\": \"Warszawa\",\n \"email\": \"ksiegowosc@przyklad.pl\"\n }),\n});\n\nconst data = await response.json();\nif (!response.ok) throw new Error(`${data.code}: ${data.detail}`); // application/problem+json\nconsole.log(data);" }, { "lang": "python", "label": "Python", "source": "import os\nimport requests\n\nresponse = requests.request(\n \"POST\",\n \"https://api.zaksio.pl/v1/contractors\",\n headers={\n \"Authorization\": f\"Bearer {os.environ['ZAKSIO_API_KEY']}\",\n \"Content-Type\": \"application/json\",\n \"Idempotency-Key\": \"6f1c8a3e-2b4d-4e5f-9a7b-3c2d1e0f9a8b\",\n },\n json={\n \"name\": \"Przykladowa Sp. z o.o.\",\n \"nip\": \"5252248481\",\n \"street\": \"Prosta 1\",\n \"postalCode\": \"00-001\",\n \"city\": \"Warszawa\",\n \"email\": \"ksiegowosc@przyklad.pl\",\n },\n timeout=30,\n)\n\nif not response.ok:\n problem = response.json() # application/problem+json\n raise RuntimeError(f\"{problem['code']}: {problem['detail']}\")\nprint(response.json())" }, { "lang": "php", "label": "PHP", "source": " 'POST',\n CURLOPT_RETURNTRANSFER => true,\n CURLOPT_TIMEOUT => 30,\n CURLOPT_HTTPHEADER => [\n 'Authorization: Bearer ' . getenv('ZAKSIO_API_KEY'),\n 'Content-Type: application/json',\n 'Idempotency-Key: 6f1c8a3e-2b4d-4e5f-9a7b-3c2d1e0f9a8b',\n ],\n CURLOPT_POSTFIELDS => json_encode([\n 'name' => 'Przykladowa Sp. z o.o.',\n 'nip' => '5252248481',\n 'street' => 'Prosta 1',\n 'postalCode' => '00-001',\n 'city' => 'Warszawa',\n 'email' => 'ksiegowosc@przyklad.pl',\n ]),\n]);\n$body = curl_exec($ch);\n$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);\ncurl_close($ch);\n\n$data = json_decode($body, true);\nif ($status >= 400) {\n // application/problem+json\n throw new RuntimeException($data['code'] . ': ' . $data['detail']);\n}\nprint_r($data);" } ] } }, "/v1/contractors/{id}": { "get": { "operationId": "getContractor", "summary": "Szczegoly kontrahenta", "tags": ["Kontrahenci"], "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Contractor" }, "example": { "id": "7d2c9e10-5a4b-4c3d-9e8f-1a2b3c4d5e6f", "name": "Przykladowa Sp. z o.o.", "nip": "5252248481", "country": "PL", "street": "Prosta 1", "postalCode": "00-001", "city": "Warszawa", "email": "ksiegowosc@przyklad.pl", "createdAt": "2026-10-12T08:20:00.000Z" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } }, "x-required-scope": "contractors:read", "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET \"https://api.zaksio.pl/v1/contractors/7d2c9e10-5a4b-4c3d-9e8f-1a2b3c4d5e6f\" \\\n -H \"Authorization: Bearer $ZAKSIO_API_KEY\"" }, { "lang": "javascript", "label": "JavaScript (Node.js)", "source": "const response = await fetch(\"https://api.zaksio.pl/v1/contractors/7d2c9e10-5a4b-4c3d-9e8f-1a2b3c4d5e6f\", {\n method: \"GET\",\n headers: {\n Authorization: `Bearer ${process.env.ZAKSIO_API_KEY}`,\n },\n});\n\nconst data = await response.json();\nif (!response.ok) throw new Error(`${data.code}: ${data.detail}`); // application/problem+json\nconsole.log(data);" }, { "lang": "python", "label": "Python", "source": "import os\nimport requests\n\nresponse = requests.request(\n \"GET\",\n \"https://api.zaksio.pl/v1/contractors/7d2c9e10-5a4b-4c3d-9e8f-1a2b3c4d5e6f\",\n headers={\n \"Authorization\": f\"Bearer {os.environ['ZAKSIO_API_KEY']}\",\n },\n timeout=30,\n)\n\nif not response.ok:\n problem = response.json() # application/problem+json\n raise RuntimeError(f\"{problem['code']}: {problem['detail']}\")\nprint(response.json())" }, { "lang": "php", "label": "PHP", "source": " 'GET',\n CURLOPT_RETURNTRANSFER => true,\n CURLOPT_TIMEOUT => 30,\n CURLOPT_HTTPHEADER => [\n 'Authorization: Bearer ' . getenv('ZAKSIO_API_KEY'),\n ],\n]);\n$body = curl_exec($ch);\n$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);\ncurl_close($ch);\n\n$data = json_decode($body, true);\nif ($status >= 400) {\n // application/problem+json\n throw new RuntimeException($data['code'] . ': ' . $data['detail']);\n}\nprint_r($data);" } ] }, "patch": { "operationId": "updateContractor", "summary": "Zmiana kontrahenta", "tags": ["Kontrahenci"], "description": "Zmienia tylko przekazane pola; `null` czysci pole (poza nazwa i krajem). Faktury juz wystawione zachowuja dane z chwili wystawienia.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 300 }, "nip": { "nullable": true, "type": "string" }, "country": { "type": "string", "minLength": 2, "maxLength": 2 }, "street": { "nullable": true, "type": "string", "maxLength": 200 }, "postalCode": { "nullable": true, "type": "string", "maxLength": 20 }, "city": { "nullable": true, "type": "string", "maxLength": 100 }, "email": { "nullable": true, "type": "string", "format": "email", "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "vatEuNumber": { "nullable": true, "type": "string" }, "isConsumer": { "type": "boolean" } } }, "example": { "city": "Krakow", "email": null } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true }, { "schema": { "type": "string", "maxLength": 255 }, "in": "header", "name": "Idempotency-Key", "required": false, "description": "Unikalny klucz zapisu (np. UUID). Powtorzenie zadania z tym samym kluczem zwraca zapamietana odpowiedz zamiast wykonywac zapis drugi raz (24 h)." } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Contractor" }, "example": { "id": "7d2c9e10-5a4b-4c3d-9e8f-1a2b3c4d5e6f", "name": "Przykladowa Sp. z o.o.", "nip": "5252248481", "country": "PL", "street": "Prosta 1", "postalCode": "00-001", "city": "Krakow", "email": null, "createdAt": "2026-10-12T08:20:00.000Z" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/LicenceReadOnly" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } }, "x-required-scope": "contractors:write", "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X PATCH \"https://api.zaksio.pl/v1/contractors/7d2c9e10-5a4b-4c3d-9e8f-1a2b3c4d5e6f\" \\\n -H \"Authorization: Bearer $ZAKSIO_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -H \"Idempotency-Key: 6f1c8a3e-2b4d-4e5f-9a7b-3c2d1e0f9a8b\" \\\n -d '{\"city\":\"Krakow\",\"email\":null}'" }, { "lang": "javascript", "label": "JavaScript (Node.js)", "source": "const response = await fetch(\"https://api.zaksio.pl/v1/contractors/7d2c9e10-5a4b-4c3d-9e8f-1a2b3c4d5e6f\", {\n method: \"PATCH\",\n headers: {\n Authorization: `Bearer ${process.env.ZAKSIO_API_KEY}`,\n \"Content-Type\": \"application/json\",\n \"Idempotency-Key\": \"6f1c8a3e-2b4d-4e5f-9a7b-3c2d1e0f9a8b\",\n },\n body: JSON.stringify({\n \"city\": \"Krakow\",\n \"email\": null\n }),\n});\n\nconst data = await response.json();\nif (!response.ok) throw new Error(`${data.code}: ${data.detail}`); // application/problem+json\nconsole.log(data);" }, { "lang": "python", "label": "Python", "source": "import os\nimport requests\n\nresponse = requests.request(\n \"PATCH\",\n \"https://api.zaksio.pl/v1/contractors/7d2c9e10-5a4b-4c3d-9e8f-1a2b3c4d5e6f\",\n headers={\n \"Authorization\": f\"Bearer {os.environ['ZAKSIO_API_KEY']}\",\n \"Content-Type\": \"application/json\",\n \"Idempotency-Key\": \"6f1c8a3e-2b4d-4e5f-9a7b-3c2d1e0f9a8b\",\n },\n json={\n \"city\": \"Krakow\",\n \"email\": None,\n },\n timeout=30,\n)\n\nif not response.ok:\n problem = response.json() # application/problem+json\n raise RuntimeError(f\"{problem['code']}: {problem['detail']}\")\nprint(response.json())" }, { "lang": "php", "label": "PHP", "source": " 'PATCH',\n CURLOPT_RETURNTRANSFER => true,\n CURLOPT_TIMEOUT => 30,\n CURLOPT_HTTPHEADER => [\n 'Authorization: Bearer ' . getenv('ZAKSIO_API_KEY'),\n 'Content-Type: application/json',\n 'Idempotency-Key: 6f1c8a3e-2b4d-4e5f-9a7b-3c2d1e0f9a8b',\n ],\n CURLOPT_POSTFIELDS => json_encode([\n 'city' => 'Krakow',\n 'email' => null,\n ]),\n]);\n$body = curl_exec($ch);\n$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);\ncurl_close($ch);\n\n$data = json_decode($body, true);\nif ($status >= 400) {\n // application/problem+json\n throw new RuntimeException($data['code'] . ': ' . $data['detail']);\n}\nprint_r($data);" } ] }, "delete": { "operationId": "deleteContractor", "summary": "Usuniecie kontrahenta", "tags": ["Kontrahenci"], "description": "Usuwa kontrahenta, ktory nie wystepuje na zadnym dokumencie (409 `contractor_in_use` w przeciwnym razie).", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true }, { "schema": { "type": "string", "maxLength": 255 }, "in": "header", "name": "Idempotency-Key", "required": false, "description": "Unikalny klucz zapisu (np. UUID). Powtorzenie zadania z tym samym kluczem zwraca zapamietana odpowiedz zamiast wykonywac zapis drugi raz (24 h)." } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK" }, "204": { "description": "Brak tresci" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/LicenceReadOnly" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } }, "x-required-scope": "contractors:write", "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X DELETE \"https://api.zaksio.pl/v1/contractors/7d2c9e10-5a4b-4c3d-9e8f-1a2b3c4d5e6f\" \\\n -H \"Authorization: Bearer $ZAKSIO_API_KEY\" \\\n -H \"Idempotency-Key: 6f1c8a3e-2b4d-4e5f-9a7b-3c2d1e0f9a8b\"" }, { "lang": "javascript", "label": "JavaScript (Node.js)", "source": "const response = await fetch(\"https://api.zaksio.pl/v1/contractors/7d2c9e10-5a4b-4c3d-9e8f-1a2b3c4d5e6f\", {\n method: \"DELETE\",\n headers: {\n Authorization: `Bearer ${process.env.ZAKSIO_API_KEY}`,\n \"Idempotency-Key\": \"6f1c8a3e-2b4d-4e5f-9a7b-3c2d1e0f9a8b\",\n },\n});\n\nif (!response.ok) {\n const problem = await response.json(); // application/problem+json\n throw new Error(`${problem.code}: ${problem.detail}`);\n}" }, { "lang": "python", "label": "Python", "source": "import os\nimport requests\n\nresponse = requests.request(\n \"DELETE\",\n \"https://api.zaksio.pl/v1/contractors/7d2c9e10-5a4b-4c3d-9e8f-1a2b3c4d5e6f\",\n headers={\n \"Authorization\": f\"Bearer {os.environ['ZAKSIO_API_KEY']}\",\n \"Idempotency-Key\": \"6f1c8a3e-2b4d-4e5f-9a7b-3c2d1e0f9a8b\",\n },\n timeout=30,\n)\n\nif not response.ok:\n problem = response.json() # application/problem+json\n raise RuntimeError(f\"{problem['code']}: {problem['detail']}\")" }, { "lang": "php", "label": "PHP", "source": " 'DELETE',\n CURLOPT_RETURNTRANSFER => true,\n CURLOPT_TIMEOUT => 30,\n CURLOPT_HTTPHEADER => [\n 'Authorization: Bearer ' . getenv('ZAKSIO_API_KEY'),\n 'Idempotency-Key: 6f1c8a3e-2b4d-4e5f-9a7b-3c2d1e0f9a8b',\n ],\n]);\n$body = curl_exec($ch);\n$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);\ncurl_close($ch);\n\n$data = json_decode($body, true);\nif ($status >= 400) {\n // application/problem+json\n throw new RuntimeException($data['code'] . ': ' . $data['detail']);\n}" } ] } }, "/v1/invoices": { "get": { "operationId": "listInvoices", "summary": "Lista faktur sprzedazowych", "tags": ["Faktury"], "description": "Faktury (i korekty) firmy przypisanej do klucza, bez pozycji (szczegoly: `GET /v1/invoices/{id}`). Paginacja kursorowa; do synchronizacji przyrostowej uzyj `order=asc` i zapamietaj ostatni kursor.", "parameters": [ { "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 200 }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "string", "maxLength": 300 }, "in": "query", "name": "cursor", "required": false }, { "schema": { "default": "asc", "type": "string", "enum": ["asc", "desc"] }, "in": "query", "name": "order", "required": false }, { "schema": { "type": "string", "enum": ["draft", "issued"] }, "in": "query", "name": "status", "required": false }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "query", "name": "contractorId", "required": false }, { "schema": { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$" }, "in": "query", "name": "issueDateFrom", "required": false }, { "schema": { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$" }, "in": "query", "name": "issueDateTo", "required": false } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "number": { "nullable": true, "description": "Numer nadawany przy wystawieniu; szkic go nie ma", "type": "string" }, "kind": { "type": "string", "enum": ["sales", "correction"] }, "status": { "type": "string", "enum": ["draft", "issued"] }, "contractorId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "issueDate": { "type": "string" }, "saleDate": { "type": "string" }, "dueDate": { "nullable": true, "type": "string" }, "currency": { "type": "string" }, "paymentMethod": { "nullable": true, "type": "string" }, "bankAccount": { "nullable": true, "type": "string" }, "notes": { "nullable": true, "type": "string" }, "vatExemptionBasis": { "nullable": true, "type": "string" }, "netTotal": { "type": "integer" }, "vatTotal": { "type": "integer" }, "grossTotal": { "type": "integer" }, "paidTotal": { "type": "integer" }, "paidAt": { "nullable": true, "type": "string" }, "correctsInvoiceId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "ksefNumber": { "nullable": true, "type": "string" }, "ksefStatus": { "nullable": true, "type": "string" }, "issuedAt": { "nullable": true, "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" } }, "required": [ "id", "number", "kind", "status", "contractorId", "issueDate", "saleDate", "dueDate", "currency", "paymentMethod", "bankAccount", "notes", "vatExemptionBasis", "netTotal", "vatTotal", "grossTotal", "paidTotal", "paidAt", "correctsInvoiceId", "ksefNumber", "ksefStatus", "issuedAt", "createdAt" ], "additionalProperties": false } }, "pagination": { "type": "object", "properties": { "limit": { "type": "integer" }, "hasMore": { "type": "boolean" }, "nextCursor": { "nullable": true, "type": "string" } }, "required": ["limit", "hasMore", "nextCursor"], "additionalProperties": false } }, "required": ["data", "pagination"], "additionalProperties": false }, "example": { "data": [ { "id": "0b6f7a3e-1c2d-4e5f-8a9b-0c1d2e3f4a5b", "number": "FV/001/10/2026", "kind": "sales", "status": "issued", "contractorId": "7d2c9e10-5a4b-4c3d-9e8f-1a2b3c4d5e6f", "issueDate": "2026-10-12", "saleDate": "2026-10-12", "dueDate": "2026-10-26", "currency": "PLN", "paymentMethod": "przelew", "bankAccount": null, "notes": null, "vatExemptionBasis": null, "netTotal": 25000, "vatTotal": 5000, "grossTotal": 30000, "paidTotal": 0, "paidAt": null, "correctsInvoiceId": null, "ksefNumber": null, "ksefStatus": null, "issuedAt": "2026-10-12T09:30:00.000Z", "createdAt": "2026-10-12T09:30:00.000Z" } ], "pagination": { "limit": 50, "hasMore": false, "nextCursor": null } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } }, "x-required-scope": "invoices:read", "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET \"https://api.zaksio.pl/v1/invoices?status=issued&issueDateFrom=2026-10-01&limit=50\" \\\n -H \"Authorization: Bearer $ZAKSIO_API_KEY\"" }, { "lang": "javascript", "label": "JavaScript (Node.js)", "source": "const response = await fetch(\"https://api.zaksio.pl/v1/invoices?status=issued&issueDateFrom=2026-10-01&limit=50\", {\n method: \"GET\",\n headers: {\n Authorization: `Bearer ${process.env.ZAKSIO_API_KEY}`,\n },\n});\n\nconst data = await response.json();\nif (!response.ok) throw new Error(`${data.code}: ${data.detail}`); // application/problem+json\nconsole.log(data);" }, { "lang": "python", "label": "Python", "source": "import os\nimport requests\n\nresponse = requests.request(\n \"GET\",\n \"https://api.zaksio.pl/v1/invoices\",\n headers={\n \"Authorization\": f\"Bearer {os.environ['ZAKSIO_API_KEY']}\",\n },\n params={\n \"status\": \"issued\",\n \"issueDateFrom\": \"2026-10-01\",\n \"limit\": \"50\",\n },\n timeout=30,\n)\n\nif not response.ok:\n problem = response.json() # application/problem+json\n raise RuntimeError(f\"{problem['code']}: {problem['detail']}\")\nprint(response.json())" }, { "lang": "php", "label": "PHP", "source": " 'GET',\n CURLOPT_RETURNTRANSFER => true,\n CURLOPT_TIMEOUT => 30,\n CURLOPT_HTTPHEADER => [\n 'Authorization: Bearer ' . getenv('ZAKSIO_API_KEY'),\n ],\n]);\n$body = curl_exec($ch);\n$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);\ncurl_close($ch);\n\n$data = json_decode($body, true);\nif ($status >= 400) {\n // application/problem+json\n throw new RuntimeException($data['code'] . ': ' . $data['detail']);\n}\nprint_r($data);" } ] }, "post": { "operationId": "createInvoice", "summary": "Wystawienie faktury", "tags": ["Faktury"], "description": "Tworzy fakture sprzedazowa i (domyslnie) od razu ja wystawia: numeracja bez luk, ksiegowanie i podsumowanie VAT jak w aplikacji. Kwoty w groszach, ilosc jako tekst dziesietny. Wystawienie i zapis to jedna transakcja: przy bledzie nie zostaje szkic. **Zawsze podawaj `Idempotency-Key`**, zeby ponowienie po bledzie sieci nie wystawilo faktury drugi raz.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "contractorId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "issueDate": { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$" }, "saleDate": { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$" }, "dueDate": { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$" }, "currency": { "type": "string", "pattern": "^[A-Za-z]{3}$" }, "taxPointDate": { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$" }, "vatScenario": { "type": "string", "enum": [ "domestic", "domestic_reverse_charge", "wdt", "export_goods", "services_eu_b2b", "services_non_eu" ] }, "vatOptions": { "type": "object", "properties": { "reverseChargeBasis": { "type": "string", "enum": ["art_145e_ust_1", "art_17_ust_1_pkt_5", "other"] }, "reverseChargeLegalBasisText": { "type": "string", "maxLength": 240 }, "evidenceReceivedDate": { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$" }, "newMeansOfTransport": { "type": "boolean" }, "triangular": { "type": "string", "enum": ["first", "second"] }, "afterImportProcedure": { "type": "string", "enum": ["42", "63"] }, "destinationTreatment": { "type": "string", "enum": ["reverse_charge", "exempt_or_zero_rated", "supplier_liable"] }, "art28lService": { "type": "boolean" }, "specialPlaceRule": { "type": "string", "maxLength": 120 }, "relatedParties": { "type": "boolean" } }, "additionalProperties": false }, "buyerVatId": { "type": "string" }, "paymentMethod": { "type": "string", "maxLength": 50 }, "bankAccount": { "type": "string", "maxLength": 40 }, "notes": { "type": "string", "maxLength": 2000 }, "vatExemptionBasis": { "type": "string", "maxLength": 240 }, "lines": { "minItems": 1, "maxItems": 1000, "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 500 }, "unit": { "type": "string", "maxLength": 20 }, "quantity": { "type": "string", "pattern": "^\\d+(\\.\\d{1,4})?$" }, "unitNetPrice": { "type": "integer", "minimum": 0 }, "vatRate": { "type": "string", "enum": ["0", "5", "8", "23", "zw", "np"] }, "productId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": ["name", "quantity", "unitNetPrice", "vatRate"] } }, "issue": { "default": true, "description": "true (domyslnie): faktura jest od razu wystawiana (numer, ksiegowanie); false: zapisuje szkic do pozniejszego wystawienia", "type": "boolean" } }, "required": ["contractorId", "issueDate", "saleDate", "lines"] }, "example": { "contractorId": "7d2c9e10-5a4b-4c3d-9e8f-1a2b3c4d5e6f", "issueDate": "2026-10-12", "saleDate": "2026-10-12", "dueDate": "2026-10-26", "paymentMethod": "przelew", "lines": [ { "name": "Usluga A", "quantity": "2", "unitNetPrice": 10000, "vatRate": "23" }, { "name": "Usluga B", "quantity": "1", "unitNetPrice": 5000, "vatRate": "8" } ] } } } }, "parameters": [ { "schema": { "type": "string", "maxLength": 255 }, "in": "header", "name": "Idempotency-Key", "required": false, "description": "Unikalny klucz zapisu (np. UUID). Powtorzenie zadania z tym samym kluczem zwraca zapamietana odpowiedz zamiast wykonywac zapis drugi raz (24 h)." } ], "security": [ { "bearerAuth": [] } ], "responses": { "201": { "description": "Utworzono", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Invoice" }, "example": { "id": "0b6f7a3e-1c2d-4e5f-8a9b-0c1d2e3f4a5b", "number": "FV/001/10/2026", "kind": "sales", "status": "issued", "contractorId": "7d2c9e10-5a4b-4c3d-9e8f-1a2b3c4d5e6f", "issueDate": "2026-10-12", "saleDate": "2026-10-12", "dueDate": "2026-10-26", "currency": "PLN", "paymentMethod": "przelew", "bankAccount": null, "notes": null, "vatExemptionBasis": null, "netTotal": 25000, "vatTotal": 5000, "grossTotal": 30000, "paidTotal": 0, "paidAt": null, "correctsInvoiceId": null, "ksefNumber": null, "ksefStatus": null, "issuedAt": "2026-10-12T09:30:00.000Z", "createdAt": "2026-10-12T09:30:00.000Z", "lines": [ { "position": 1, "name": "Usluga A", "unit": "szt.", "quantity": "2", "unitNetPrice": 10000, "vatRate": "23", "net": 20000, "productId": null }, { "position": 2, "name": "Usluga B", "unit": "szt.", "quantity": "1", "unitNetPrice": 5000, "vatRate": "8", "net": 5000, "productId": null } ], "vatSummary": [ { "vatRate": "23", "net": 20000, "vat": 4600, "gross": 24600 }, { "vatRate": "8", "net": 5000, "vat": 400, "gross": 5400 } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/LicenceReadOnly" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } }, "x-required-scope": "invoices:write", "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST \"https://api.zaksio.pl/v1/invoices\" \\\n -H \"Authorization: Bearer $ZAKSIO_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -H \"Idempotency-Key: 6f1c8a3e-2b4d-4e5f-9a7b-3c2d1e0f9a8b\" \\\n -d '{\"contractorId\":\"7d2c9e10-5a4b-4c3d-9e8f-1a2b3c4d5e6f\",\"issueDate\":\"2026-10-12\",\"saleDate\":\"2026-10-12\",\"dueDate\":\"2026-10-26\",\"paymentMethod\":\"przelew\",\"lines\":[{\"name\":\"Usluga A\",\"quantity\":\"2\",\"unitNetPrice\":10000,\"vatRate\":\"23\"},{\"name\":\"Usluga B\",\"quantity\":\"1\",\"unitNetPrice\":5000,\"vatRate\":\"8\"}]}'" }, { "lang": "javascript", "label": "JavaScript (Node.js)", "source": "const response = await fetch(\"https://api.zaksio.pl/v1/invoices\", {\n method: \"POST\",\n headers: {\n Authorization: `Bearer ${process.env.ZAKSIO_API_KEY}`,\n \"Content-Type\": \"application/json\",\n \"Idempotency-Key\": \"6f1c8a3e-2b4d-4e5f-9a7b-3c2d1e0f9a8b\",\n },\n body: JSON.stringify({\n \"contractorId\": \"7d2c9e10-5a4b-4c3d-9e8f-1a2b3c4d5e6f\",\n \"issueDate\": \"2026-10-12\",\n \"saleDate\": \"2026-10-12\",\n \"dueDate\": \"2026-10-26\",\n \"paymentMethod\": \"przelew\",\n \"lines\": [\n {\n \"name\": \"Usluga A\",\n \"quantity\": \"2\",\n \"unitNetPrice\": 10000,\n \"vatRate\": \"23\"\n },\n {\n \"name\": \"Usluga B\",\n \"quantity\": \"1\",\n \"unitNetPrice\": 5000,\n \"vatRate\": \"8\"\n }\n ]\n }),\n});\n\nconst data = await response.json();\nif (!response.ok) throw new Error(`${data.code}: ${data.detail}`); // application/problem+json\nconsole.log(data);" }, { "lang": "python", "label": "Python", "source": "import os\nimport requests\n\nresponse = requests.request(\n \"POST\",\n \"https://api.zaksio.pl/v1/invoices\",\n headers={\n \"Authorization\": f\"Bearer {os.environ['ZAKSIO_API_KEY']}\",\n \"Content-Type\": \"application/json\",\n \"Idempotency-Key\": \"6f1c8a3e-2b4d-4e5f-9a7b-3c2d1e0f9a8b\",\n },\n json={\n \"contractorId\": \"7d2c9e10-5a4b-4c3d-9e8f-1a2b3c4d5e6f\",\n \"issueDate\": \"2026-10-12\",\n \"saleDate\": \"2026-10-12\",\n \"dueDate\": \"2026-10-26\",\n \"paymentMethod\": \"przelew\",\n \"lines\": [\n {\n \"name\": \"Usluga A\",\n \"quantity\": \"2\",\n \"unitNetPrice\": 10000,\n \"vatRate\": \"23\",\n },\n {\n \"name\": \"Usluga B\",\n \"quantity\": \"1\",\n \"unitNetPrice\": 5000,\n \"vatRate\": \"8\",\n },\n ],\n },\n timeout=30,\n)\n\nif not response.ok:\n problem = response.json() # application/problem+json\n raise RuntimeError(f\"{problem['code']}: {problem['detail']}\")\nprint(response.json())" }, { "lang": "php", "label": "PHP", "source": " 'POST',\n CURLOPT_RETURNTRANSFER => true,\n CURLOPT_TIMEOUT => 30,\n CURLOPT_HTTPHEADER => [\n 'Authorization: Bearer ' . getenv('ZAKSIO_API_KEY'),\n 'Content-Type: application/json',\n 'Idempotency-Key: 6f1c8a3e-2b4d-4e5f-9a7b-3c2d1e0f9a8b',\n ],\n CURLOPT_POSTFIELDS => json_encode([\n 'contractorId' => '7d2c9e10-5a4b-4c3d-9e8f-1a2b3c4d5e6f',\n 'issueDate' => '2026-10-12',\n 'saleDate' => '2026-10-12',\n 'dueDate' => '2026-10-26',\n 'paymentMethod' => 'przelew',\n 'lines' => [\n [\n 'name' => 'Usluga A',\n 'quantity' => '2',\n 'unitNetPrice' => 10000,\n 'vatRate' => '23',\n ],\n [\n 'name' => 'Usluga B',\n 'quantity' => '1',\n 'unitNetPrice' => 5000,\n 'vatRate' => '8',\n ],\n ],\n ]),\n]);\n$body = curl_exec($ch);\n$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);\ncurl_close($ch);\n\n$data = json_decode($body, true);\nif ($status >= 400) {\n // application/problem+json\n throw new RuntimeException($data['code'] . ': ' . $data['detail']);\n}\nprint_r($data);" } ] } }, "/v1/invoices/{id}": { "get": { "operationId": "getInvoice", "summary": "Szczegoly faktury", "tags": ["Faktury"], "description": "Faktura z pozycjami i podsumowaniem VAT.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Invoice" }, "example": { "id": "0b6f7a3e-1c2d-4e5f-8a9b-0c1d2e3f4a5b", "number": "FV/001/10/2026", "kind": "sales", "status": "issued", "contractorId": "7d2c9e10-5a4b-4c3d-9e8f-1a2b3c4d5e6f", "issueDate": "2026-10-12", "saleDate": "2026-10-12", "dueDate": "2026-10-26", "currency": "PLN", "paymentMethod": "przelew", "bankAccount": null, "notes": null, "vatExemptionBasis": null, "netTotal": 25000, "vatTotal": 5000, "grossTotal": 30000, "paidTotal": 0, "paidAt": null, "correctsInvoiceId": null, "ksefNumber": null, "ksefStatus": null, "issuedAt": "2026-10-12T09:30:00.000Z", "createdAt": "2026-10-12T09:30:00.000Z", "lines": [ { "position": 1, "name": "Usluga A", "unit": "szt.", "quantity": "2", "unitNetPrice": 10000, "vatRate": "23", "net": 20000, "productId": null }, { "position": 2, "name": "Usluga B", "unit": "szt.", "quantity": "1", "unitNetPrice": 5000, "vatRate": "8", "net": 5000, "productId": null } ], "vatSummary": [ { "vatRate": "23", "net": 20000, "vat": 4600, "gross": 24600 }, { "vatRate": "8", "net": 5000, "vat": 400, "gross": 5400 } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } }, "x-required-scope": "invoices:read", "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET \"https://api.zaksio.pl/v1/invoices/0b6f7a3e-1c2d-4e5f-8a9b-0c1d2e3f4a5b\" \\\n -H \"Authorization: Bearer $ZAKSIO_API_KEY\"" }, { "lang": "javascript", "label": "JavaScript (Node.js)", "source": "const response = await fetch(\"https://api.zaksio.pl/v1/invoices/0b6f7a3e-1c2d-4e5f-8a9b-0c1d2e3f4a5b\", {\n method: \"GET\",\n headers: {\n Authorization: `Bearer ${process.env.ZAKSIO_API_KEY}`,\n },\n});\n\nconst data = await response.json();\nif (!response.ok) throw new Error(`${data.code}: ${data.detail}`); // application/problem+json\nconsole.log(data);" }, { "lang": "python", "label": "Python", "source": "import os\nimport requests\n\nresponse = requests.request(\n \"GET\",\n \"https://api.zaksio.pl/v1/invoices/0b6f7a3e-1c2d-4e5f-8a9b-0c1d2e3f4a5b\",\n headers={\n \"Authorization\": f\"Bearer {os.environ['ZAKSIO_API_KEY']}\",\n },\n timeout=30,\n)\n\nif not response.ok:\n problem = response.json() # application/problem+json\n raise RuntimeError(f\"{problem['code']}: {problem['detail']}\")\nprint(response.json())" }, { "lang": "php", "label": "PHP", "source": " 'GET',\n CURLOPT_RETURNTRANSFER => true,\n CURLOPT_TIMEOUT => 30,\n CURLOPT_HTTPHEADER => [\n 'Authorization: Bearer ' . getenv('ZAKSIO_API_KEY'),\n ],\n]);\n$body = curl_exec($ch);\n$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);\ncurl_close($ch);\n\n$data = json_decode($body, true);\nif ($status >= 400) {\n // application/problem+json\n throw new RuntimeException($data['code'] . ': ' . $data['detail']);\n}\nprint_r($data);" } ] } }, "/v1/invoices/{id}/pdf": { "get": { "operationId": "getInvoicePdf", "summary": "PDF faktury", "tags": ["Faktury"], "description": "Plik PDF faktury w tym samym ksztalcie co w aplikacji (`Content-Type: application/pdf`). Pobieraj PDF wystawionej faktury: szkic nie ma jeszcze numeru.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Plik PDF faktury", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } }, "x-required-scope": "invoices:read", "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET \"https://api.zaksio.pl/v1/invoices/0b6f7a3e-1c2d-4e5f-8a9b-0c1d2e3f4a5b/pdf\" \\\n -H \"Authorization: Bearer $ZAKSIO_API_KEY\" \\\n -o faktura.pdf" }, { "lang": "javascript", "label": "JavaScript (Node.js)", "source": "import { writeFileSync } from \"node:fs\";\n\nconst response = await fetch(\"https://api.zaksio.pl/v1/invoices/0b6f7a3e-1c2d-4e5f-8a9b-0c1d2e3f4a5b/pdf\", {\n method: \"GET\",\n headers: {\n Authorization: `Bearer ${process.env.ZAKSIO_API_KEY}`,\n },\n});\n\nif (!response.ok) throw new Error(`${response.status}: ${await response.text()}`);\nwriteFileSync(\"faktura.pdf\", Buffer.from(await response.arrayBuffer()));" }, { "lang": "python", "label": "Python", "source": "import os\nimport requests\n\nresponse = requests.request(\n \"GET\",\n \"https://api.zaksio.pl/v1/invoices/0b6f7a3e-1c2d-4e5f-8a9b-0c1d2e3f4a5b/pdf\",\n headers={\n \"Authorization\": f\"Bearer {os.environ['ZAKSIO_API_KEY']}\",\n },\n timeout=30,\n)\n\nif not response.ok:\n problem = response.json() # application/problem+json\n raise RuntimeError(f\"{problem['code']}: {problem['detail']}\")\nopen(\"faktura.pdf\", \"wb\").write(response.content)" }, { "lang": "php", "label": "PHP", "source": " 'GET',\n CURLOPT_RETURNTRANSFER => true,\n CURLOPT_TIMEOUT => 30,\n CURLOPT_HTTPHEADER => [\n 'Authorization: Bearer ' . getenv('ZAKSIO_API_KEY'),\n ],\n]);\n$body = curl_exec($ch);\n$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);\ncurl_close($ch);\n\nif ($status >= 400) { throw new RuntimeException($body); }\nfile_put_contents('faktura.pdf', $body);" } ] } }, "/v1/invoices/{id}/issue": { "post": { "operationId": "issueInvoice", "summary": "Wystawienie szkicu faktury", "tags": ["Faktury"], "description": "Wystawia fakture zapisana wczesniej jako szkic (z API albo z aplikacji). Wystawionej faktury nie mozna wystawic ponownie (409 `invoice_not_draft`). Obsluguje `Idempotency-Key`.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true }, { "schema": { "type": "string", "maxLength": 255 }, "in": "header", "name": "Idempotency-Key", "required": false, "description": "Unikalny klucz zapisu (np. UUID). Powtorzenie zadania z tym samym kluczem zwraca zapamietana odpowiedz zamiast wykonywac zapis drugi raz (24 h)." } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Invoice" }, "example": { "id": "0b6f7a3e-1c2d-4e5f-8a9b-0c1d2e3f4a5b", "number": "FV/001/10/2026", "kind": "sales", "status": "issued", "contractorId": "7d2c9e10-5a4b-4c3d-9e8f-1a2b3c4d5e6f", "issueDate": "2026-10-12", "saleDate": "2026-10-12", "dueDate": "2026-10-26", "currency": "PLN", "paymentMethod": "przelew", "bankAccount": null, "notes": null, "vatExemptionBasis": null, "netTotal": 25000, "vatTotal": 5000, "grossTotal": 30000, "paidTotal": 0, "paidAt": null, "correctsInvoiceId": null, "ksefNumber": null, "ksefStatus": null, "issuedAt": "2026-10-12T09:30:00.000Z", "createdAt": "2026-10-12T09:30:00.000Z", "lines": [ { "position": 1, "name": "Usluga A", "unit": "szt.", "quantity": "2", "unitNetPrice": 10000, "vatRate": "23", "net": 20000, "productId": null }, { "position": 2, "name": "Usluga B", "unit": "szt.", "quantity": "1", "unitNetPrice": 5000, "vatRate": "8", "net": 5000, "productId": null } ], "vatSummary": [ { "vatRate": "23", "net": 20000, "vat": 4600, "gross": 24600 }, { "vatRate": "8", "net": 5000, "vat": 400, "gross": 5400 } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/LicenceReadOnly" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } }, "x-required-scope": "invoices:write", "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST \"https://api.zaksio.pl/v1/invoices/0b6f7a3e-1c2d-4e5f-8a9b-0c1d2e3f4a5b/issue\" \\\n -H \"Authorization: Bearer $ZAKSIO_API_KEY\" \\\n -H \"Idempotency-Key: 6f1c8a3e-2b4d-4e5f-9a7b-3c2d1e0f9a8b\"" }, { "lang": "javascript", "label": "JavaScript (Node.js)", "source": "const response = await fetch(\"https://api.zaksio.pl/v1/invoices/0b6f7a3e-1c2d-4e5f-8a9b-0c1d2e3f4a5b/issue\", {\n method: \"POST\",\n headers: {\n Authorization: `Bearer ${process.env.ZAKSIO_API_KEY}`,\n \"Idempotency-Key\": \"6f1c8a3e-2b4d-4e5f-9a7b-3c2d1e0f9a8b\",\n },\n});\n\nconst data = await response.json();\nif (!response.ok) throw new Error(`${data.code}: ${data.detail}`); // application/problem+json\nconsole.log(data);" }, { "lang": "python", "label": "Python", "source": "import os\nimport requests\n\nresponse = requests.request(\n \"POST\",\n \"https://api.zaksio.pl/v1/invoices/0b6f7a3e-1c2d-4e5f-8a9b-0c1d2e3f4a5b/issue\",\n headers={\n \"Authorization\": f\"Bearer {os.environ['ZAKSIO_API_KEY']}\",\n \"Idempotency-Key\": \"6f1c8a3e-2b4d-4e5f-9a7b-3c2d1e0f9a8b\",\n },\n timeout=30,\n)\n\nif not response.ok:\n problem = response.json() # application/problem+json\n raise RuntimeError(f\"{problem['code']}: {problem['detail']}\")\nprint(response.json())" }, { "lang": "php", "label": "PHP", "source": " 'POST',\n CURLOPT_RETURNTRANSFER => true,\n CURLOPT_TIMEOUT => 30,\n CURLOPT_HTTPHEADER => [\n 'Authorization: Bearer ' . getenv('ZAKSIO_API_KEY'),\n 'Idempotency-Key: 6f1c8a3e-2b4d-4e5f-9a7b-3c2d1e0f9a8b',\n ],\n]);\n$body = curl_exec($ch);\n$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);\ncurl_close($ch);\n\n$data = json_decode($body, true);\nif ($status >= 400) {\n // application/problem+json\n throw new RuntimeException($data['code'] . ': ' . $data['detail']);\n}\nprint_r($data);" } ] } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "zk_live_...", "description": "Klucz API utworzony w Ustawienia > API i integracje. Przekazuj go w naglowku `Authorization: Bearer zk_live_...`." } }, "schemas": { "ProductInput": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "sku": { "type": "string" }, "name": { "type": "string" }, "kind": { "type": "string", "enum": ["good", "service"] }, "unit": { "type": "string" }, "ean": { "nullable": true, "type": "string" }, "vatRate": { "type": "string", "description": "Stawka VAT: 23, 8, 5, 0, zw albo np" }, "defaultNetPrice": { "nullable": true, "description": "Domyslna cena netto w groszach", "type": "integer" }, "tracking": { "type": "string", "enum": ["none", "lot", "serial"] }, "hasExpiry": { "type": "boolean" }, "weightG": { "nullable": true, "type": "integer" }, "hazmat": { "type": "boolean" }, "active": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" } }, "required": [ "id", "sku", "name", "kind", "unit", "ean", "vatRate", "defaultNetPrice", "tracking", "hasExpiry", "weightG", "hazmat", "active", "createdAt" ] }, "ContractorInput": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string" }, "nip": { "nullable": true, "type": "string" }, "country": { "type": "string", "description": "Kod kraju ISO 3166-1 alpha-2" }, "street": { "nullable": true, "type": "string" }, "postalCode": { "nullable": true, "type": "string" }, "city": { "nullable": true, "type": "string" }, "email": { "nullable": true, "type": "string" }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" } }, "required": [ "id", "name", "nip", "country", "street", "postalCode", "city", "email", "createdAt" ] }, "StockLevelInput": { "type": "object", "properties": { "productId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "sku": { "type": "string" }, "name": { "type": "string" }, "unit": { "type": "string" }, "quantity": { "type": "string", "description": "Stan lacznie, ilosc dziesietna jako tekst" }, "warehouses": { "type": "array", "items": { "type": "object", "properties": { "warehouseId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "warehouseCode": { "type": "string" }, "quantity": { "type": "string" } }, "required": ["warehouseId", "warehouseCode", "quantity"] } } }, "required": ["productId", "sku", "name", "unit", "quantity", "warehouses"] }, "InvoiceInput": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "number": { "nullable": true, "description": "Numer nadawany przy wystawieniu; szkic go nie ma", "type": "string" }, "kind": { "type": "string", "enum": ["sales", "correction"] }, "status": { "type": "string", "enum": ["draft", "issued"] }, "contractorId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "issueDate": { "type": "string" }, "saleDate": { "type": "string" }, "dueDate": { "nullable": true, "type": "string" }, "currency": { "type": "string" }, "paymentMethod": { "nullable": true, "type": "string" }, "bankAccount": { "nullable": true, "type": "string" }, "notes": { "nullable": true, "type": "string" }, "vatExemptionBasis": { "nullable": true, "type": "string" }, "netTotal": { "type": "integer" }, "vatTotal": { "type": "integer" }, "grossTotal": { "type": "integer" }, "paidTotal": { "type": "integer" }, "paidAt": { "nullable": true, "type": "string" }, "correctsInvoiceId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "ksefNumber": { "nullable": true, "type": "string" }, "ksefStatus": { "nullable": true, "type": "string" }, "issuedAt": { "nullable": true, "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "lines": { "type": "array", "items": { "type": "object", "properties": { "position": { "type": "integer" }, "name": { "type": "string" }, "unit": { "type": "string" }, "quantity": { "type": "string" }, "unitNetPrice": { "type": "integer", "description": "Cena jednostkowa netto w groszach" }, "vatRate": { "type": "string" }, "net": { "type": "integer", "description": "Wartosc netto pozycji w groszach" }, "productId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "position", "name", "unit", "quantity", "unitNetPrice", "vatRate", "net", "productId" ] } }, "vatSummary": { "type": "array", "items": { "type": "object", "properties": { "vatRate": { "type": "string" }, "net": { "type": "integer" }, "vat": { "type": "integer" }, "gross": { "type": "integer" } }, "required": ["vatRate", "net", "vat", "gross"] } } }, "required": [ "id", "number", "kind", "status", "contractorId", "issueDate", "saleDate", "dueDate", "currency", "paymentMethod", "bankAccount", "notes", "vatExemptionBasis", "netTotal", "vatTotal", "grossTotal", "paidTotal", "paidAt", "correctsInvoiceId", "ksefNumber", "ksefStatus", "issuedAt", "createdAt", "lines", "vatSummary" ] }, "Product": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "sku": { "type": "string" }, "name": { "type": "string" }, "kind": { "type": "string", "enum": ["good", "service"] }, "unit": { "type": "string" }, "ean": { "nullable": true, "type": "string" }, "vatRate": { "type": "string", "description": "Stawka VAT: 23, 8, 5, 0, zw albo np" }, "defaultNetPrice": { "nullable": true, "description": "Domyslna cena netto w groszach", "type": "integer" }, "tracking": { "type": "string", "enum": ["none", "lot", "serial"] }, "hasExpiry": { "type": "boolean" }, "weightG": { "nullable": true, "type": "integer" }, "hazmat": { "type": "boolean" }, "active": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" } }, "required": [ "id", "sku", "name", "kind", "unit", "ean", "vatRate", "defaultNetPrice", "tracking", "hasExpiry", "weightG", "hazmat", "active", "createdAt" ], "additionalProperties": false }, "Contractor": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string" }, "nip": { "nullable": true, "type": "string" }, "country": { "type": "string", "description": "Kod kraju ISO 3166-1 alpha-2" }, "street": { "nullable": true, "type": "string" }, "postalCode": { "nullable": true, "type": "string" }, "city": { "nullable": true, "type": "string" }, "email": { "nullable": true, "type": "string" }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" } }, "required": [ "id", "name", "nip", "country", "street", "postalCode", "city", "email", "createdAt" ], "additionalProperties": false }, "StockLevel": { "type": "object", "properties": { "productId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "sku": { "type": "string" }, "name": { "type": "string" }, "unit": { "type": "string" }, "quantity": { "type": "string", "description": "Stan lacznie, ilosc dziesietna jako tekst" }, "warehouses": { "type": "array", "items": { "type": "object", "properties": { "warehouseId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "warehouseCode": { "type": "string" }, "quantity": { "type": "string" } }, "required": ["warehouseId", "warehouseCode", "quantity"], "additionalProperties": false } } }, "required": ["productId", "sku", "name", "unit", "quantity", "warehouses"], "additionalProperties": false }, "Invoice": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "number": { "nullable": true, "description": "Numer nadawany przy wystawieniu; szkic go nie ma", "type": "string" }, "kind": { "type": "string", "enum": ["sales", "correction"] }, "status": { "type": "string", "enum": ["draft", "issued"] }, "contractorId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "issueDate": { "type": "string" }, "saleDate": { "type": "string" }, "dueDate": { "nullable": true, "type": "string" }, "currency": { "type": "string" }, "paymentMethod": { "nullable": true, "type": "string" }, "bankAccount": { "nullable": true, "type": "string" }, "notes": { "nullable": true, "type": "string" }, "vatExemptionBasis": { "nullable": true, "type": "string" }, "netTotal": { "type": "integer" }, "vatTotal": { "type": "integer" }, "grossTotal": { "type": "integer" }, "paidTotal": { "type": "integer" }, "paidAt": { "nullable": true, "type": "string" }, "correctsInvoiceId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "ksefNumber": { "nullable": true, "type": "string" }, "ksefStatus": { "nullable": true, "type": "string" }, "issuedAt": { "nullable": true, "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "lines": { "type": "array", "items": { "type": "object", "properties": { "position": { "type": "integer" }, "name": { "type": "string" }, "unit": { "type": "string" }, "quantity": { "type": "string" }, "unitNetPrice": { "type": "integer", "description": "Cena jednostkowa netto w groszach" }, "vatRate": { "type": "string" }, "net": { "type": "integer", "description": "Wartosc netto pozycji w groszach" }, "productId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "position", "name", "unit", "quantity", "unitNetPrice", "vatRate", "net", "productId" ], "additionalProperties": false } }, "vatSummary": { "type": "array", "items": { "type": "object", "properties": { "vatRate": { "type": "string" }, "net": { "type": "integer" }, "vat": { "type": "integer" }, "gross": { "type": "integer" } }, "required": ["vatRate", "net", "vat", "gross"], "additionalProperties": false } } }, "required": [ "id", "number", "kind", "status", "contractorId", "issueDate", "saleDate", "dueDate", "currency", "paymentMethod", "bankAccount", "notes", "vatExemptionBasis", "netTotal", "vatTotal", "grossTotal", "paidTotal", "paidAt", "correctsInvoiceId", "ksefNumber", "ksefStatus", "issuedAt", "createdAt", "lines", "vatSummary" ], "additionalProperties": false }, "Problem": { "type": "object", "description": "Blad w formacie RFC 9457 (application/problem+json).", "required": ["type", "title", "status", "detail", "instance", "code", "requestId"], "properties": { "type": { "type": "string", "format": "uri", "description": "Adres opisu bledu w dokumentacji (kotwica #blad-)." }, "title": { "type": "string", "description": "Krotki, stabilny tytul rodzaju bledu." }, "status": { "type": "integer", "description": "Kod HTTP." }, "detail": { "type": "string", "description": "Opis tego konkretnego bledu (po polsku)." }, "instance": { "type": "string", "description": "Sciezka zadania, ktore spowodowalo blad." }, "code": { "type": "string", "description": "Stabilny kod maszynowy, np. insufficient_scope. Na nim opieraj obsluge bledow." }, "requestId": { "type": "string", "description": "Identyfikator zadania (tez w naglowku X-Request-Id); podaj go w zgloszeniu." }, "errors": { "type": "array", "description": "Tylko dla validation_error: lista nieprawidlowych pol.", "items": { "type": "object", "required": ["pointer", "detail"], "properties": { "pointer": { "type": "string", "description": "Wskaznik JSON do pola, np. /lines/0/quantity." }, "detail": { "type": "string" } } } } }, "example": { "type": "https://zaksio.pl/dokumentacja-api#blad-insufficient-scope", "title": "Brak dostepu", "status": 403, "detail": "Klucz nie ma zakresu products:write (albo tworca klucza utracil odpowiednie uprawnienie)", "instance": "/v1/products", "code": "insufficient_scope", "requestId": "req-1a2b3c" } } }, "responses": { "BadRequest": { "description": "Nieprawidlowe zadanie (validation_error, invalid_cursor, invalid_idempotency_key)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "Unauthorized": { "description": "Brak, nieprawidlowy, wygasly lub odwolany klucz API", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "LicenceReadOnly": { "description": "Licencja wygasla lub platnosc zalegla: zapisy zablokowane (licence_read_only)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "Forbidden": { "description": "Klucz nie ma zakresu albo adres IP nie jest dozwolony", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "NotFound": { "description": "Nie znaleziono zasobu (w tej firmie)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "Conflict": { "description": "Konflikt ze stanem zasobu (np. zajety SKU, faktura juz wystawiona, idempotency_in_progress)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "Unprocessable": { "description": "Zadanie poprawne skladniowo, ale niedozwolone przez reguly (np. idempotency_key_reuse, brak kontrahenta)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "TooManyRequests": { "description": "Przekroczono limit zapytan klucza (naglowek Retry-After)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "ServerError": { "description": "Blad serwera; ponow zadanie z tym samym Idempotency-Key", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "security": [ { "bearerAuth": [] } ], "x-scopes": [ { "id": "products:read", "group": "Produkty", "label": "Produkty: odczyt", "description": "Lista i szczegoly produktow z kartoteki.", "available": true }, { "id": "products:write", "group": "Produkty", "label": "Produkty: zapis", "description": "Dodawanie i zmiana produktow w kartotece.", "available": true }, { "id": "stock:read", "group": "Magazyn", "label": "Stany magazynowe: odczyt", "description": "Stany magazynowe produktow (suma i podzial na magazyny).", "available": true }, { "id": "contractors:read", "group": "Kontrahenci", "label": "Kontrahenci: odczyt", "description": "Lista i szczegoly kontrahentow.", "available": true }, { "id": "contractors:write", "group": "Kontrahenci", "label": "Kontrahenci: zapis", "description": "Dodawanie, zmiana i usuwanie kontrahentow.", "available": true }, { "id": "invoices:read", "group": "Faktury", "label": "Faktury: odczyt", "description": "Lista, szczegoly i PDF faktur sprzedazowych.", "available": true }, { "id": "invoices:write", "group": "Faktury", "label": "Faktury: wystawianie", "description": "Tworzenie i wystawianie faktur sprzedazowych (numeracja i ksiegowanie jak w aplikacji).", "available": true }, { "id": "orders:read", "group": "Zamowienia", "label": "Zamowienia: odczyt", "description": "Zamowienia ze wszystkich kanalow (w przygotowaniu).", "available": false }, { "id": "orders:write", "group": "Zamowienia", "label": "Zamowienia: zapis", "description": "Tworzenie i zmiana zamowien (w przygotowaniu).", "available": false }, { "id": "shipments:read", "group": "Przesylki", "label": "Przesylki: odczyt", "description": "Przesylki i statusy (w przygotowaniu).", "available": false }, { "id": "shipments:write", "group": "Przesylki", "label": "Przesylki: zapis", "description": "Tworzenie przesylek i etykiet (w przygotowaniu).", "available": false } ], "x-webhook-events": [ { "type": "invoice.issued", "group": "Faktury", "label": "Faktura wystawiona", "description": "Faktura sprzedazowa (lub korekta) zostala wystawiona i zaksiegowana.", "example": { "id": "b9f1c2d3-4e5f-4a6b-8c7d-0e1f2a3b4c5d", "type": "invoice.issued", "apiVersion": "v1", "createdAt": "2026-10-12T09:30:00.000Z", "companyId": "9c1d2e3f-4a5b-4c6d-8e7f-0a1b2c3d4e5f", "data": { "invoice": { "id": "0b6f7a3e-1c2d-4e5f-8a9b-0c1d2e3f4a5b", "number": "FV/001/10/2026", "kind": "sales", "status": "issued", "grossTotal": 12300, "currency": "PLN" } } } }, { "type": "invoice.paid", "group": "Faktury", "label": "Faktura oplacona", "description": "Na fakturze zarejestrowano pierwsza wplate (pole paidAt ma wartosc).", "example": { "id": "b9f1c2d3-4e5f-4a6b-8c7d-0e1f2a3b4c5d", "type": "invoice.paid", "apiVersion": "v1", "createdAt": "2026-10-12T09:30:00.000Z", "companyId": "9c1d2e3f-4a5b-4c6d-8e7f-0a1b2c3d4e5f", "data": { "invoice": { "id": "0b6f7a3e-1c2d-4e5f-8a9b-0c1d2e3f4a5b", "number": "FV/001/10/2026", "grossTotal": 12300, "paidTotal": 12300, "paidAt": "2026-10-14" } } } }, { "type": "contractor.created", "group": "Kontrahenci", "label": "Kontrahent dodany", "description": "Dodano kontrahenta (z aplikacji, API albo importu).", "example": { "id": "b9f1c2d3-4e5f-4a6b-8c7d-0e1f2a3b4c5d", "type": "contractor.created", "apiVersion": "v1", "createdAt": "2026-10-12T09:30:00.000Z", "companyId": "9c1d2e3f-4a5b-4c6d-8e7f-0a1b2c3d4e5f", "data": { "contractor": { "id": "7d2c9e10-5a4b-4c3d-9e8f-1a2b3c4d5e6f", "name": "Przykladowa Sp. z o.o.", "nip": "5252248481" } } } }, { "type": "contractor.updated", "group": "Kontrahenci", "label": "Kontrahent zmieniony", "description": "Zmieniono dane kontrahenta.", "example": { "id": "b9f1c2d3-4e5f-4a6b-8c7d-0e1f2a3b4c5d", "type": "contractor.updated", "apiVersion": "v1", "createdAt": "2026-10-12T09:30:00.000Z", "companyId": "9c1d2e3f-4a5b-4c6d-8e7f-0a1b2c3d4e5f", "data": { "contractor": { "id": "7d2c9e10-5a4b-4c3d-9e8f-1a2b3c4d5e6f", "name": "Przykladowa Sp. z o.o.", "city": "Warszawa" } } } }, { "type": "product.created", "group": "Produkty", "label": "Produkt dodany", "description": "Dodano produkt do kartoteki.", "example": { "id": "b9f1c2d3-4e5f-4a6b-8c7d-0e1f2a3b4c5d", "type": "product.created", "apiVersion": "v1", "createdAt": "2026-10-12T09:30:00.000Z", "companyId": "9c1d2e3f-4a5b-4c6d-8e7f-0a1b2c3d4e5f", "data": { "product": { "id": "3f9a1b2c-4d5e-4f60-8a7b-9c0d1e2f3a4b", "sku": "KAW-001", "name": "Kawa 1 kg" } } } }, { "type": "product.updated", "group": "Produkty", "label": "Produkt zmieniony", "description": "Zmieniono dane produktu w kartotece (takze dezaktywacja).", "example": { "id": "b9f1c2d3-4e5f-4a6b-8c7d-0e1f2a3b4c5d", "type": "product.updated", "apiVersion": "v1", "createdAt": "2026-10-12T09:30:00.000Z", "companyId": "9c1d2e3f-4a5b-4c6d-8e7f-0a1b2c3d4e5f", "data": { "product": { "id": "3f9a1b2c-4d5e-4f60-8a7b-9c0d1e2f3a4b", "sku": "KAW-001", "active": false } } } }, { "type": "product.stock_changed", "group": "Magazyn", "label": "Stan produktu zmieniony", "description": "Zmienil sie stan magazynowy produktu. Kilka ruchow zapisanych w krotkim czasie (zanim zdarzenie zostanie rozeslane) zlewa sie w jedno zdarzenie z aktualnym stanem.", "example": { "id": "b9f1c2d3-4e5f-4a6b-8c7d-0e1f2a3b4c5d", "type": "product.stock_changed", "apiVersion": "v1", "createdAt": "2026-10-12T09:30:00.000Z", "companyId": "9c1d2e3f-4a5b-4c6d-8e7f-0a1b2c3d4e5f", "data": { "stock": { "productId": "3f9a1b2c-4d5e-4f60-8a7b-9c0d1e2f3a4b", "sku": "KAW-001", "quantity": "42", "warehouses": [ { "warehouseId": "a1b2c3d4-0000-4000-8000-000000000001", "warehouseCode": "MAG", "quantity": "42" } ] } } } } ], "x-webhook-test-event": { "type": "webhook.test", "example": { "id": "b9f1c2d3-4e5f-4a6b-8c7d-0e1f2a3b4c5d", "type": "webhook.test", "apiVersion": "v1", "createdAt": "2026-10-12T09:30:00.000Z", "companyId": null, "data": { "message": "To jest testowe zdarzenie z Zaksio" } } }, "x-webhook-verification": [ { "lang": "javascript", "label": "JavaScript (Node.js)", "source": "import { createHmac, timingSafeEqual } from \"node:crypto\";\n\n// rawBody: surowa tresc zadania (Buffer lub string), NIE ponownie zserializowany JSON\nexport function verifyZaksioSignature(secret, header, rawBody, toleranceSeconds = 300) {\n const parts = header.split(\",\").map((p) => p.trim());\n const timestamp = Number(parts.find((p) => p.startsWith(\"t=\"))?.slice(2));\n if (!Number.isInteger(timestamp)) return false;\n if (Math.abs(Date.now() / 1000 - timestamp) > toleranceSeconds) return false;\n const expected = createHmac(\"sha256\", secret).update(`${timestamp}.${rawBody}`).digest();\n return parts\n .filter((p) => p.startsWith(\"v1=\"))\n .some((p) => {\n const given = Buffer.from(p.slice(3), \"hex\");\n return given.length === expected.length && timingSafeEqual(given, expected);\n });\n}" }, { "lang": "python", "label": "Python", "source": "import hashlib\nimport hmac\nimport time\n\n\ndef verify_zaksio_signature(secret: str, header: str, raw_body: bytes, tolerance: int = 300) -> bool:\n parts = [p.strip() for p in header.split(\",\")]\n try:\n timestamp = int(next(p[2:] for p in parts if p.startswith(\"t=\")))\n except (StopIteration, ValueError):\n return False\n if abs(time.time() - timestamp) > tolerance:\n return False\n signed = f\"{timestamp}.\".encode() + raw_body\n expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()\n return any(\n hmac.compare_digest(p[3:], expected) for p in parts if p.startswith(\"v1=\")\n )" }, { "lang": "php", "label": "PHP", "source": " $tolerance) {\n return false;\n }\n $expected = hash_hmac('sha256', $timestamp . '.' . $rawBody, $secret);\n foreach ($signatures as $signature) {\n if (hash_equals($expected, $signature)) {\n return true;\n }\n }\n return false;\n}\n\n// $rawBody = file_get_contents('php://input');\n// $header = $_SERVER['HTTP_ZAKSIO_SIGNATURE'] ?? '';" }, { "lang": "curl", "label": "Bash (openssl)", "source": "#!/usr/bin/env bash\n# Sprawdzenie podpisu z wiersza polecen (do diagnozy): SECRET, HEADER i plik z surowa trescia zadania\nSECRET=\"whsec_...\"\nHEADER=\"t=1760261400,v1=...\" # naglowek Zaksio-Signature\nBODY_FILE=\"body.json\" # surowa tresc zadania, bajt w bajt\n\nT=$(echo \"$HEADER\" | tr ',' '\\n' | sed -n 's/^t=//p')\nEXPECTED=$( (printf '%s.' \"$T\"; cat \"$BODY_FILE\") | openssl dgst -sha256 -hmac \"$SECRET\" -hex | sed 's/^.* //')\nif echo \"$HEADER\" | tr ',' '\\n' | grep -qx \"v1=$EXPECTED\"; then echo \"podpis poprawny\"; else echo \"podpis NIEPOPRAWNY\"; fi\n# pamietaj tez o sprawdzeniu, ze t= nie jest starsze niz 5 minut" } ], "x-error-codes": [ { "code": "missing_api_key", "status": 401, "description": "Brak naglowka Authorization: Bearer zk_live_..." }, { "code": "invalid_api_key", "status": 401, "description": "Klucz ma zly format albo nie istnieje" }, { "code": "api_key_revoked", "status": 401, "description": "Klucz zostal odwolany" }, { "code": "api_key_expired", "status": 401, "description": "Klucz wygasl (takze po okresie przejsciowym rotacji)" }, { "code": "api_key_owner_removed", "status": 401, "description": "Osoba, ktora utworzyla klucz, nie nalezy juz do organizacji" }, { "code": "ip_not_allowed", "status": 403, "description": "Adres IP zadania nie jest na liscie dozwolonych dla klucza" }, { "code": "insufficient_scope", "status": 403, "description": "Klucz nie ma zakresu wymaganego przez operacje (albo tworca klucza utracil uprawnienie)" }, { "code": "feature_disabled", "status": 403, "description": "Publiczne API jest wylaczone dla organizacji" }, { "code": "module_disabled", "status": 403, "description": "Modul (katalog, magazyn) nie jest wlaczony w profilu firmy" }, { "code": "tenant_deleted", "status": 403, "description": "Organizacja zostala usunieta" }, { "code": "licence_read_only", "status": 402, "description": "Licencja wygasla lub platnosc zalegla: dozwolony tylko odczyt" }, { "code": "document_limit_reached", "status": 402, "description": "Wyczerpano miesieczny limit dokumentow w planie" }, { "code": "validation_error", "status": 400, "description": "Nieprawidlowe dane; lista pol w errors[]" }, { "code": "invalid_cursor", "status": 400, "description": "Kursor paginacji jest nieprawidlowy" }, { "code": "invalid_idempotency_key", "status": 400, "description": "Idempotency-Key ma niedozwolone znaki albo jest za dlugi" }, { "code": "not_found", "status": 404, "description": "Nie ma takiego adresu w API v1" }, { "code": "product_not_found", "status": 404, "description": "Nie znaleziono produktu" }, { "code": "contractor_not_found", "status": 404, "description": "Nie znaleziono kontrahenta (przy tworzeniu faktury: 422)" }, { "code": "invoice_not_found", "status": 404, "description": "Nie znaleziono faktury" }, { "code": "sku_or_ean_taken", "status": 409, "description": "SKU lub kod EAN jest juz uzyty w tej firmie" }, { "code": "product_has_stock_history", "status": 409, "description": "Nie zmienia sie sledzenia partii produktu z historia ruchow" }, { "code": "contractor_in_use", "status": 409, "description": "Kontrahent wystepuje na dokumentach i nie mozna go usunac" }, { "code": "invoice_not_draft", "status": 409, "description": "Wystawionej faktury nie mozna zmieniac ani wystawic ponownie" }, { "code": "period_closed", "status": 409, "description": "Okres ksiegowy jest zamkniety" }, { "code": "idempotency_in_progress", "status": 409, "description": "Zadanie z tym Idempotency-Key jest wlasnie wykonywane; ponow po chwili" }, { "code": "idempotency_key_reuse", "status": 422, "description": "Ten Idempotency-Key byl juz uzyty z innymi danymi zadania" }, { "code": "invalid_service", "status": 422, "description": "Usluga nie ma partii, terminu waznosci ani cech ADR" }, { "code": "exemption_basis_required", "status": 422, "description": "Pozycje zwolnione z VAT (zw) wymagaja podstawy zwolnienia" }, { "code": "non_positive_total", "status": 422, "description": "Kwota faktury musi byc dodatnia" }, { "code": "too_many_failed_auth", "status": 429, "description": "Zbyt wiele blednych prob uwierzytelnienia z jednego adresu" }, { "code": "rate_limited", "status": 429, "description": "Przekroczono limit zapytan na minute dla klucza" }, { "code": "maintenance", "status": 503, "description": "Tryb serwisowy: zapisy chwilowo zablokowane" }, { "code": "internal_error", "status": 500, "description": "Blad serwera; podaj requestId w zgloszeniu" } ] }