Konwencje

Base URL, nagłówki, idempotency, content types, korelacja

Ten opisuje standardowe konwencje używane w Public API dla integratorów.

Base URL

# Produkcja
https://<twoj-host-ksefcore>

# Demo/Sandbox
https://demo-<twoj-host-ksefcore>

Wszystkie endpointy integratora są pod /api/v1/*.

Standardowe nagłówki

Oprócz nagłówków autentykacji, zalecamy wysyłanie następujących nagłówków:

X-API-Token

X-API-Token: YOUR_API_TOKEN

Idempotency-Key

Dla operacji, które mogą być powtarzane (POST, PUT, PATCH):

Idempotency-Key: uuid-v4-string

Content-Type

Content-Type: ...

X-Correlation-Id

X-Correlation-Id: YOUR_CORRELATION_ID

Formaty danych

Request body

W zależności od endpointu:

• application/json (np. POST /api/v1/webhooks)
• multipart/form-data (np. POST /api/v1/submissions z xml=@file)

Response body

Najczęściej application/json. Dla pobierania plików:

• GET /api/v1/submissions/{id}/xml → application/xml
• GET /api/v1/submissions/{id}/pdf → application/pdf
• GET /api/v1/documents/{id}/xml → application/xml
• GET /api/v1/documents/{id}/pdf → application/pdf

Obsługa błędów

API zwraca standardowe kody HTTP:

Kody sukcesu

• 200 OK - Request zakończony sukcesem
• 201 Created - Zasób został utworzony
• 204 No Content - Request zakończony sukcesem bez zwracania treści

Kody błędów klienta

• 400 Bad Request - Nieprawidłowe dane wejściowe
• 401 Unauthorized - Brak autentykacji
• 403 Forbidden - Brak uprawnień
• 404 Not Found - Zasób nie znaleziony
• 409 Conflict - Konflikt (np. duplikat)
• 422 Unprocessable Entity - Błąd walidacji
• 429 Too Many Requests - Przekroczony limit requestów

Kody błędów serwera

• 500 Internal Server Error - Błąd serwera
• 502 Bad Gateway - Błąd bramy
• 503 Service Unavailable - Serwis niedostępny

Format błędu

{
"error": {
  "code": "VALIDATION_ERROR",
  "message": "Request validation failed",
  "details": {
    "field": "invoice_number",
    "issue": "Invoice number is required"
  },
  "request_id": "req_1234567890abcdef"
}
}

Korelacja

Dla ścieżek /api/v1/* middleware dopisuje X-Correlation-Id do odpowiedzi. Możesz przesłać własny X-Correlation-Id w request — zostanie użyty w odpowiedzi.

Timezone

Wszystkie daty/czasy w API i webhookach są zwracane jako ISO8601. Integracja powinna zakładać UTC.

⚠ Braki kontraktowe

• Brak publicznie opisanej polityki rate limit (poza samą obserwacją, że może pojawić się 429).