Dokumentacja API v1
Pełna lista endpointów dla obu produktów CrateAPI: przykłady curl, odpowiedzi, uwierzytelnianie, limity.
Wolisz surowe OpenAPI? Czytelna maszynowo specyfikacja i Swagger UI znajdują się pod adresem api.crateapi.com/docs →
Pierwsze kroki
Trzy kroki do pierwszego wywołania API.
Odbierz swój darmowy klucz
Darmowy klucz API jest dostępny od razu, tu na stronie — bez karty. Płatne plany otworzą się przy starcie: dołącz do listy po 20% zniżki.
Wyślij swój klucz
Jeden nagłówek w każdym żądaniu: X-Api-Key. Bez zabawy z OAuth, bez wymaganego SDK.
Wysyłaj dokumenty
Zwykłe HTTP + JSON/XML na wejściu, wyniki na wyjściu. Dokumentacja pokazuje działający curl dla każdego endpointu.
albo pozwól swojemu agentowi AI ją wywołać — serwer MCP →
Uwierzytelnianie
Bazowy URL e-fakturowania: https://api.crateapi.com/v1. Bazowy URL narzędzi dokumentów: https://api.crateapi.com (ścieżki /pdf, /screenshot, /email, /extract).
Wyślij swój klucz jako X-API-Key: <twój klucz>. Potrzebujesz darmowego klucza? Zdobądź go od razu na crateapi.com/account/ - bez formularza, wystarczy Twój e-mail.
Endpointy oznaczone darmowe nie wymagają żadnego klucza - to celowe, nie okres próbny: walidacja pozostaje darmowa na zawsze.
curl -X POST https://api.crateapi.com/v1/validate/ubl \ -H "Content-Type: application/xml" \ --data-binary @invoice.xml {"profile":"peppol","valid":true,"counts":{"fatal":0,"warning":0},"findings":[],"duration_ms":12}
curl -X POST https://api.crateapi.com/v1/generate/ubl?profile=peppol \ -H "X-API-Key: YOUR_KEY" -H "Content-Type: application/json" \ -d @invoice.json -o invoice.xml
API e-fakturowania
EN 16931: UBL/Peppol BIS, CII, Factur-X, FatturaPA (Włochy: faktury TD01/TD04/TD05 i noty korygujące, kody Natura wraz z forfettario), Facturae (Hiszpania: faktury sektora publicznego), FA_VAT/KSeF (Polska) i Order-X (zamówienia zakupu). Pełna specyfikacja OpenAPI: /openapi.json · dokumentacja interaktywna: /docs (Swagger UI).
| Endpoint | Uwierzytelnianie | Uwagi |
|---|---|---|
POST /v1/validate/ubl | darmowe | Waliduje fakturę UBL. `profile` domyślnie to `peppol`; przekaż `profile=auto`, aby wykryć go automatycznie na podstawie CustomizationID dokumentu (w razie niepowodzenia en16931), albo wybierz jawnie: en16931, peppol, xrechnung, ro, fr, fr-extended, ehf, nlcius, pint. |
POST /v1/validate/cii | darmowe | Waliduje fakturę CII. `profile` domyślnie to `en16931`; przekaż `profile=auto`, aby wykryć go automatycznie na podstawie CustomizationID dokumentu (w razie niepowodzenia en16931), albo wybierz jawnie: en16931, xrechnung, fr, fr-extended. |
POST /v1/validate/facturapa | darmowe | Tylko walidacja strukturalna XSD dla FatturaPA (nie istnieje oficjalny zestaw reguł schematron do zwendoryzowania). |
POST /v1/validate/orderx | darmowe | Order-X Basic - pełna walidacja XSD + oficjalny schematron. |
POST /v1/pdfa/validate | darmowe | Walidacja PDF/A (veraPDF). `flavour`: auto|1a|1b|2a|2b|2u|3a|3b|3u|4|4e|4f. |
GET /validator | darmowe | Walidator drag-and-drop w przeglądarce, ten sam silnik, bez rejestracji. |
POST /v1/generate/ubl | wymaga X-API-Key | Model faktury JSON → XML UBL. `profile`: en16931, peppol, xrechnung, ro, ehf, nlcius, pint. |
POST /v1/generate/cii | wymaga X-API-Key | Model faktury JSON → XML CII. `profile`: en16931, xrechnung. |
POST /v1/generate/facturx | wymaga X-API-Key | Nasz minimalistyczny wizualny PDF + osadzony XML CII (EN16931). |
POST /v1/generate/facturx/embed | wymaga X-API-Key | Twój PDF w Twojej marce + JSON faktury → PDF/A-3 z osadzonym CII (multipart). |
POST /v1/generate/facturapa | wymaga X-API-Key | XML FatturaPA (Włochy): faktury TD01, noty korygujące TD04/TD05, kody zwolnienia VAT Natura (w tym forfettario N2.2), opcjonalne ritenuta/bollo/cassa. |
POST /v1/generate/orderx | wymaga X-API-Key | XML zamówienia Order-X Basic (nie faktura). |
POST /v1/convert/ubl-to-cii | wymaga X-API-Key | Bez strat albo odrzucone: 422 ze szczegółami zamiast cichej degradacji. |
POST /v1/convert/cii-to-ubl | wymaga X-API-Key | Ta sama gwarancja, w drugą stronę. |
POST /v1/render/html | wymaga X-API-Key | XML faktury → czytelny HTML (oficjalna wizualizacja KoSIT). |
POST /v1/render/pdf | wymaga X-API-Key | XML faktury → PDF. `style`: compact (domyślnie, 1 strona) lub kosit (formularz audytowy). |
POST /v1/pdfa/convert | wymaga X-API-Key | Dowolny PDF → PDF/A-3b, z opcjonalnymi osadzonymi plikami. |
POST /v1/pdfa/consistency | wymaga X-API-Key | Factur-X: czy osadzony XML zgadza się z widocznym tekstem PDF? |
POST /v1/repair/ubl | wymaga X-API-Key | Auto-naprawa best-effort: daty spoza ISO, rozjazdy arytmetyczne w sumach. |
POST /v1/repair/cii | wymaga X-API-Key | To samo, składnia CII. |
API Narzędzi Dokumentów
PDF, zrzuty ekranu, walidacja e-mail, ekstrakcja treści. Uwierzytelnianie: darmowy klucz z crateapi.com/account/ obejmuje API e-fakturowania — plany Document Tools otworzą się przy starcie, dołącz do listy. Specyfikacje per API: /pdf/openapi.json, /screenshot/openapi.json, /email/openapi.json, /extract/openapi.json.
| API | Endpoint | Uwagi |
|---|---|---|
POST /pdf/merge | Łączy 2+ PDF-y, w kolejności przesłania. | |
POST /pdf/split | Wyodrębnia strony, np. `pages=1-3,5`. | |
POST /pdf/watermark | Ukośny znak wodny z tekstem - `text`, `opacity`, `color`, `font_size`. | |
POST /pdf/protect | Szyfrowanie hasłem AES-256. | |
POST /pdf/compress | Rekompresja Ghostscript - `level`: low|medium|high; nigdy nie zwraca pliku większego niż wejściowy. | |
POST /pdf/from-html | Surowy HTML → PDF (headless Chromium). | |
POST /pdf/from-url | Publiczny URL → PDF, ta sama ochrona anty-SSRF co /screenshot. | |
POST /pdf/to-images | Strony → PNG/JPEG, zwracane jako ZIP. | |
POST /pdf/extract-text | Ekstrakcja tekstu z uwzględnieniem układu (poppler, awaryjnie pypdf). | |
POST /pdf/metadata | Liczba stron, flaga szyfrowania, pola informacji o dokumencie. | |
| screenshot | GET /screenshot/take | URL → PNG/JPEG. `block_ads`, `block_trackers`, `block_cookie_banners`, `cache_ttl`, `full_page`, `delay_ms`. |
GET /email/validate | Sygnały składni + MX + jednorazowości + konta funkcyjnego + darmowego dostawcy, z wynikiem punktowym. | |
POST /email/validate-batch | Do 100 adresów, treść JSON. | |
POST /email/validate-bulk | Przesłanie CSV, do 5000 adresów; `format=json` lub `format=csv` (wyniki dopisywane). | |
| extract | GET /extract/article | URL → czysty tekst artykułu + metadane, bez zbędnych elementów. |
| extract | POST /extract-html | Surowy HTML → czysty tekst (bez pobierania). |
Limity
E-fakturowanie: treść XML ograniczona do 2 MB, przesyłanie PDF do 10 MB. Miesięczna pula na klucz (kalibrowana per plan, hojna domyślnie - zobacz cennik) dotyczy każdego endpointu poza /validate/* i /pdfa/validate, które pozostają bez limitu.
Document tools: te liczby opisują plany, które wystartują przy starcie (100 zapytań/mies. w planie darmowym, do 50 000/mies. w Ultra - zobacz cennik). Nie istnieje jeszcze żaden klucz API do Document Tools - wypróbuj każde narzędzie już dziś na żywo w przeglądarce na /products/, i dołącz do listy, by dostać klucz przy starcie. Masowa walidacja e-mail ograniczona do 5000 adresów / 2 MB na jedno przesłanie.
Serwer MCP (agenty AI)
Hostowany pod https://api.crateapi.com/mcp (streamable HTTP) - dodaj URL bezpośrednio do konfiguracji swojego klienta MCP, nic do uruchamiania:
{"mcpServers": {"crateapi-einvoicing": { "type": "http", "url": "https://api.crateapi.com/mcp", "headers": {"X-API-Key": "your-key-here"}}}}
validate_invoice nie wymaga klucza; pozostałe trzy odczytują nagłówek X-API-Key. Walidacja bez klucza jest ograniczona fair-use per IP, tak samo jak darmowy walidator na stronie.
Wolisz self-hosting - ze względu na prywatność, odizolowane środowisko albo lokalny rozwój? Te same narzędzia, jako Twój własny proces:
{"mcpServers": {"crateapi-einvoicing": { "command": "python", "args": ["-m", "einvoicing.mcp_server"], "env": {"EINVOICE_API_KEY": "your-key-here"}}}}
Narzędzia: validate_invoice (darmowe), repair_invoice, generate_invoice, convert_invoice. Pełny opis: /mcp/. Podsumowanie tej całej strony czytelne dla maszyn: /llms.txt · /ai (JSON).
Ścieżki endpointów, przykłady curl, nazwy parametrów i profili oraz payloady JSON pozostają wszędzie po angielsku - kod do skopiowania i wklejenia nie powinien wymagać tłumaczenia.