CRATEAPI

Dokumentacja API

Pełna lista endpointów dla obu produktów CrateAPI: przykłady curl, odpowiedzi, uwierzytelnianie, limity. Ś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.

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

EndpointUwierzytelnianieUwagi
POST /v1/validate/ubldarmoweWaliduje fakturę UBL. `profile`: en16931, peppol, xrechnung, ro, fr, fr-extended.
POST /v1/validate/ciidarmoweWaliduje fakturę CII. `profile`: en16931, xrechnung, fr, fr-extended.
POST /v1/validate/facturapadarmoweTylko walidacja strukturalna XSD dla FatturaPA (nie istnieje oficjalny zestaw reguł schematron do zwendoryzowania).
POST /v1/validate/orderxdarmoweOrder-X Basic - pełna walidacja XSD + oficjalny schematron.
POST /v1/pdfa/validatedarmoweWalidacja PDF/A (veraPDF). `flavour`: auto|1a|1b|2a|2b|2u|3a|3b|3u|4|4e|4f.
GET /validatordarmoweWalidator drag-and-drop w przeglądarce, ten sam silnik, bez rejestracji.
POST /v1/generate/ublwymaga X-API-KeyModel faktury JSON → XML UBL. `profile`: en16931, peppol, xrechnung, ro.
POST /v1/generate/ciiwymaga X-API-KeyModel faktury JSON → XML CII. `profile`: en16931, xrechnung.
POST /v1/generate/facturxwymaga X-API-KeyNasz minimalistyczny wizualny PDF + osadzony XML CII (EN16931).
POST /v1/generate/facturx/embedwymaga X-API-KeyTwój PDF w Twojej marce + JSON faktury → PDF/A-3 z osadzonym CII (multipart).
POST /v1/generate/facturapawymaga X-API-KeyXML 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/orderxwymaga X-API-KeyXML zamówienia Order-X Basic (nie faktura).
POST /v1/convert/ubl-to-ciiwymaga X-API-KeyBez strat albo odrzucone: 422 ze szczegółami zamiast cichej degradacji.
POST /v1/convert/cii-to-ublwymaga X-API-KeyTa sama gwarancja, w drugą stronę.
POST /v1/render/htmlwymaga X-API-KeyXML faktury → czytelny HTML (oficjalna wizualizacja KoSIT).
POST /v1/render/pdfwymaga X-API-KeyXML faktury → PDF. `style`: compact (domyślnie, 1 strona) lub kosit (formularz audytowy).
POST /v1/pdfa/convertwymaga X-API-KeyDowolny PDF → PDF/A-3b, z opcjonalnymi osadzonymi plikami.
POST /v1/pdfa/consistencywymaga X-API-KeyFactur-X: czy osadzony XML zgadza się z widocznym tekstem PDF?
POST /v1/repair/ublwymaga X-API-KeyAuto-naprawa best-effort: daty spoza ISO, rozjazdy arytmetyczne w sumach.
POST /v1/repair/ciiwymaga X-API-KeyTo samo, składnia CII.

API Narzędzi Dokumentów

PDF, zrzuty ekranu, walidacja e-mail, ekstrakcja treści. Uwierzytelnianie: skontaktuj się z nami po bezpośredni dostęp. Specyfikacje per API: /pdf/openapi.json, /screenshot/openapi.json, /email/openapi.json, /extract/openapi.json.

APIEndpointUwagi
pdfPOST /pdf/mergeŁączy 2+ PDF-y, w kolejności przesłania.
pdfPOST /pdf/splitWyodrębnia strony, np. `pages=1-3,5`.
pdfPOST /pdf/watermarkUkośny znak wodny z tekstem - `text`, `opacity`, `color`, `font_size`.
pdfPOST /pdf/protectSzyfrowanie hasłem AES-256.
pdfPOST /pdf/compressRekompresja Ghostscript - `level`: low|medium|high; nigdy nie zwraca pliku większego niż wejściowy.
pdfPOST /pdf/from-htmlSurowy HTML → PDF (headless Chromium).
pdfPOST /pdf/from-urlPubliczny URL → PDF, ta sama ochrona anty-SSRF co /screenshot.
pdfPOST /pdf/to-imagesStrony → PNG/JPEG, zwracane jako ZIP.
pdfPOST /pdf/extract-textEkstrakcja tekstu z uwzględnieniem układu (poppler, awaryjnie pypdf).
pdfPOST /pdf/metadataLiczba stron, flaga szyfrowania, pola informacji o dokumencie.
screenshotGET /screenshot/takeURL → PNG/JPEG. `block_ads`, `block_trackers`, `block_cookie_banners`, `cache_ttl`, `full_page`, `delay_ms`.
emailGET /email/validateSygnały składni + MX + jednorazowości + konta funkcyjnego + darmowego dostawcy, z wynikiem punktowym.
emailPOST /email/validate-batchDo 100 adresów, treść JSON.
emailPOST /email/validate-bulkPrzesłanie CSV, do 5000 adresów; `format=json` lub `format=csv` (wyniki dopisywane).
extractGET /extract/articleURL → czysty tekst artykułu + metadane, bez zbędnych elementów.
extractPOST /extract-htmlSurowy 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.

Narzędzia dokumentów: 100 zapytań/mies. w planie darmowym, do 50 000/mies. w Ultra - zobacz cennik. Masowa walidacja e-mail ograniczona do 5000 adresów / 2 MB na jedno przesłanie.

Serwer MCP (agenty AI)

Self-hosted, działa już dziś z Twoim własnym kluczem API - nie trzeba czekać na hostowany endpoint:

{"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. Podsumowanie tej całej strony czytelne dla maszyn: /llms.txt · /ai (JSON).