Publiczne API v0.3.0-preview.1 · OpenAPI 3.1.2

Publiczne API v1

Dokumentacja jest dostępna publicznie. Dostęp przedpremierowy do kont i integracji wymaga zaproszenia. Rzeczywiste fakturowanie i wysyłka do KSeF nie są jeszcze udostępnione.

Wersjonowany kontrakt dla dowolnego klienta InvoiceIQ. Bieżący kontrakt zawiera 50 operacji klienckich (wdrożonych, częściowych lub jawnie planowanych) i 24 granularnych scope’ów.

OAuth 2.0

Token jest przyjmowany wyłącznie w nagłówku Authorization: Bearer …. Klient jest po stronie serwera przypisany do jednej organizacji; payload nie wybiera tenanta ani roli. Sekret klienta jest pokazywany tylko raz, podlega rotacji i revoke.

Metadata: authorization server · protected resource

Scope’y

Operacje

Reguły integracji

• Każda mutacja biznesowa wymaga unikalnego Idempotency-Key; replay z innym payloadem kończy się konfliktem.
• Warunkowe aktualizacje używają ETag/If-Match; wersja odczytana przez klienta musi być nadal aktualna.
• Status KSeF należy uzgadniać przez polling i podpisane webhooki. Samo HTTP 2xx nie oznacza przyjęcia przez KSeF.
• Klient webhooka weryfikuje podpis, timestamp, identyfikator delivery i obsługuje duplikaty.

Bezpieczne przykłady kontraktu

AuthorizationServerMetadataExample

Synthetic deployment metadata

{
    "issuer": "https://invoiceiq.invalid",
    "authorization_endpoint": "https://invoiceiq.invalid/oauth/authorize",
    "token_endpoint": "https://invoiceiq.invalid/oauth/token",
    "grant_types_supported": [
        "authorization_code",
        "client_credentials",
        "refresh_token"
    ],
    "response_types_supported": [
        "code"
    ],
    "code_challenge_methods_supported": [
        "plain",
        "S256"
    ],
    "token_endpoint_auth_methods_supported": [
        "client_secret_basic",
        "client_secret_post"
    ],
    "scopes_supported": [
        "customers:read",
        "customers:write",
        "invoice-drafts:read",
        "invoice-drafts:write",
        "invoice-previews:read",
        "invoice-approvals:request",
        "invoice-approvals:read",
        "invoice-correction-approvals:read",
        "invoice-correction-approvals:request",
        "invoice-correction-artifacts:read",
        "invoice-correction-ksef-submissions:read",
        "invoice-correction-ksef-submissions:retry",
        "invoice-correction-ksef-submissions:send",
        "invoice-corrections:issue",
        "invoice-corrections:read",
        "invoice-corrections:write",
        "invoices:read",
        "invoices:issue",
        "ksef-submissions:read",
        "ksef-submissions:send",
        "ksef-submissions:retry",
        "artifacts:read",
        "webhook-endpoints:read",
        "webhook-endpoints:write"
    ]
}

ProtectedResourceMetadataExample

Synthetic protected-resource metadata

{
    "resource": "https://invoiceiq.invalid/api/v1",
    "authorization_servers": [
        "https://invoiceiq.invalid"
    ],
    "scopes_supported": [
        "customers:read",
        "customers:write",
        "invoice-drafts:read",
        "invoice-drafts:write",
        "invoice-previews:read",
        "invoice-approvals:request",
        "invoice-approvals:read",
        "invoice-correction-approvals:read",
        "invoice-correction-approvals:request",
        "invoice-correction-artifacts:read",
        "invoice-correction-ksef-submissions:read",
        "invoice-correction-ksef-submissions:retry",
        "invoice-correction-ksef-submissions:send",
        "invoice-corrections:issue",
        "invoice-corrections:read",
        "invoice-corrections:write",
        "invoices:read",
        "invoices:issue",
        "ksef-submissions:read",
        "ksef-submissions:send",
        "ksef-submissions:retry",
        "artifacts:read",
        "webhook-endpoints:read",
        "webhook-endpoints:write"
    ],
    "bearer_methods_supported": [
        "header"
    ]
}

CustomerCreateRequestExample

Synthetic Polish buyer

{
    "name": "Synthetic Buyer sp. z o.o.",
    "tax_identifier": "9999999999",
    "address": {
        "country_code": "PL",
        "address_line_1": "00-001 Synthetic City, Testowa 1"
    },
    "external_system": "synthetic_erp",
    "external_reference": "customer/SYN-0001"
}

CustomerCollectionExample

One-item synthetic customer page

{
    "data": [
        {
            "id": "0198a9c0-7000-7000-8000-000000000001",
            "type": "customer",
            "version": 1,
            "name": "Synthetic Buyer sp. z o.o.",
            "external_system": "synthetic_erp",
            "external_reference": "customer/SYN-0001",
            "lifecycle_status": "active",
            "meta": {
                "created_at": "2026-08-17T10:15:30Z",
                "updated_at": "2026-08-17T10:15:30Z"
            }
        }
    ],
    "meta": {
        "correlation_id": "0198a9c0-7000-7000-8000-000000000010",
        "page": {
            "limit": 25,
            "has_more": false
        }
    },
    "links": {
        "self": "/api/v1/customers?limit=25"
    }
}

BadRequestErrorExample

Malformed protocol input

{
    "error": {
        "code": "bad_request",
        "message": "The request could not be parsed.",
        "correlation_id": "0198a9c0-7000-7000-8000-000000000010"
    }
}