Autentykacja API

Jak uwierzytelnić się w KSeFCore API - klucze API, nagłówki, bezpieczeństwo

Public API dla integratorów używa jednego mechanizmu uwierzytelnienia:

X-API-Token: <token>

Token generujesz w panelu KSeFCore i traktujesz jak sekret (nie umieszczaj w kodzie frontendu, nie commituj do repo).

Scopes

Każdy token ma listę scope’ów. API weryfikuje, czy token ma wymagany scope dla endpointu.

| Scope | Endpointy | |---|---| | submissions:read | GET /api/v1/submissions, GET /api/v1/submissions/{id}, GET /api/v1/submissions/{id}/result, GET /api/v1/submissions/{id}/xml, GET /api/v1/submissions/{id}/pdf, GET /api/v1/submissions/{id}/upo | | submissions:write | POST /api/v1/submissions | | documents:read | GET /api/v1/documents, GET /api/v1/documents/{id}, GET /api/v1/documents/{id}/xml, GET /api/v1/documents/{id}/pdf | | documents:write | POST /api/v1/documents/sync | | webhooks:read | GET /api/v1/webhooks, GET /api/v1/webhooks/{id}, GET /api/v1/webhooks/deliveries, GET /api/v1/webhooks/deliveries/{id} | | webhooks:write | POST /api/v1/webhooks, PUT /api/v1/webhooks/{id}, DELETE /api/v1/webhooks/{id} |

Endpoint bez scope

GET /api/v1/me wymaga tokena, ale nie wymaga konkretnego scope.

Najczęstsze 403

• token nie jest powiązany z klientem
• token nie ma wymaganego scope
• w POST /api/v1/submissions kontekst NIP nie jest zgodny z NIP przypisanym do tokena

Przykład kompletnego requestu

curl -sS "$KSEFCORE_BASE_URL/api/v1/me" \
  -H "X-API-Token: $KSEFCORE_API_TOKEN"

Environment variables

Dla bezpieczeństwa przechowuj token w environment variables:

.env

KSEFCORE_API_TOKEN=YOUR_API_TOKEN
KSEFCORE_BASE_URL=https://<twoj-host-ksefcore>

Użycie w kodzie

const apiToken = process.env.KSEFCORE_API_TOKEN;
const baseUrl = process.env.KSEFCORE_BASE_URL;

const headers = {
'X-API-Token': apiToken,
'Content-Type': 'application/json'
};

import os

api_token = os.getenv('KSEFCORE_API_TOKEN')
base_url = os.getenv('KSEFCORE_BASE_URL')

headers = {
  'X-API-Token': api_token,
  'Content-Type': 'application/json'
}

Rotacja tokenów

Zalecamy regularną rotację tokenów dla bezpieczeństwa:

1. Wygeneruj nowy token w panelu
2. Zaktualizuj swoją aplikację nowym tokenem
3. Przetestuj integrację z nowym tokenem
4. Usuń stary token

Rate limiting

Public API może zwrócić 429 Too Many Requests. Jeśli zobaczysz 429, zaimplementuj backoff (np. exponential backoff) i spróbuj ponownie.