Proszę czekać, ładujemy treść.
Base URL, nagłówki, idempotency, content types, korelacja
Ten opisuje standardowe konwencje używane w Public API dla integratorów.
# Produkcja
https://<twoj-host-ksefcore>
# Demo/Sandbox
https://demo-<twoj-host-ksefcore>
Wszystkie endpointy integratora są pod /api/v1/*.
Oprócz nagłówków autentykacji, zalecamy wysyłanie następujących nagłówków:
X-API-Token: YOUR_API_TOKEN
Dla operacji, które mogą być powtarzane (POST, PUT, PATCH):
Idempotency-Key: uuid-v4-string
Content-Type: ...
X-Correlation-Id: YOUR_CORRELATION_ID
W zależności od endpointu:
application/json (np. POST /api/v1/webhooks)multipart/form-data (np. POST /api/v1/submissions z xml=@file)Najczęściej application/json. Dla pobierania plików:
GET /api/v1/submissions/{id}/xml → application/xmlGET /api/v1/submissions/{id}/pdf → application/pdfGET /api/v1/documents/{id}/xml → application/xmlGET /api/v1/documents/{id}/pdf → application/pdfAPI zwraca standardowe kody HTTP:
200 OK - Request zakończony sukcesem201 Created - Zasób został utworzony204 No Content - Request zakończony sukcesem bez zwracania treści400 Bad Request - Nieprawidłowe dane wejściowe401 Unauthorized - Brak autentykacji403 Forbidden - Brak uprawnień404 Not Found - Zasób nie znaleziony409 Conflict - Konflikt (np. duplikat)422 Unprocessable Entity - Błąd walidacji429 Too Many Requests - Przekroczony limit requestów500 Internal Server Error - Błąd serwera502 Bad Gateway - Błąd bramy503 Service Unavailable - Serwis niedostępnyjson
{
"error": {
"code": "VALIDATION_ERROR",
"message": "Request validation failed",
"details": {
"field": "invoice_number",
"issue": "Invoice number is required"
},
"request_id": "req_1234567890abcdef"
}
}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.
Wszystkie daty/czasy w API i webhookach są zwracane jako ISO8601. Integracja powinna zakładać UTC.
429).