Szybki start

Pierwsze kroki z Public API (/api/v1/*) — token, submissions, webhooki

Quickstart (15 minut)

Cel: uruchomić end-to-end flow:

• wygenerować X-API-Token
• wysłać XML przez POST /api/v1/submissions
• odebrać webhook ksef.outgoing.queued
• doprowadzić flow do stanu finalnego (webhook albo polling)

Krok 0 — przygotuj API token

Wygeneruj token w panelu KSeFCore i zapisz go jako zmienną środowiskową:

export KSEFCORE_API_TOKEN="..."
export KSEFCORE_BASE_URL="https://<twoj-host-ksefcore>"

Krok 1 — przygotuj endpoint do odbioru webhooków

Webhook to HTTP POST na Twój URL.

Minimalny handler powinien:

• zwracać 2xx szybko
• deduplikować po X-Event-Id
• weryfikować podpis HMAC (patrz: Webhooks → Bezpieczeństwo)

Krok 2 — zarejestruj webhook w KSeFCore

curl -sS "$KSEFCORE_BASE_URL/api/v1/webhooks" \
  -H "X-API-Token: $KSEFCORE_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "erp-webhook",
    "url": "https://<twoj-host>/ksefcore/webhooks",
    "events": [
      "ksef.outgoing.queued",
      "ksef.outgoing.sent",
      "ksef.outgoing.accepted",
      "ksef.outgoing.rejected",
      "ksef.outgoing.failed"
    ]
  }'

Z odpowiedzi zapisz secret — jest zwracany tylko raz.

Krok 3 — wyślij fakturę XML

curl -sS "$KSEFCORE_BASE_URL/api/v1/submissions" \
  -H "X-API-Token: $KSEFCORE_API_TOKEN" \
  -H "Idempotency-Key: demo-001" \
  -F "xml=@./invoice.xml" \
  -F "context_type=nip" \
  -F "context_value=<NIP>" \
  -F "mode=online"

Odpowiedź zawiera m.in. submission_id.

Krok 4 — finalizacja (2 opcje)

Opcja A: webhooki

Czekaj na jeden z finalnych eventów:

• ksef.outgoing.accepted
• ksef.outgoing.rejected
• ksef.outgoing.failed

Opcja B: polling

curl -sS "$KSEFCORE_BASE_URL/api/v1/submissions/<submission_id>" \
  -H "X-API-Token: $KSEFCORE_API_TOKEN"

Zakończ polling gdy status jest finalny.

Najczęstsze problemy

• 403: brak scope albo token nie jest powiązany z klientem.
• 409: konflikt wersji / duplikat (patrz: API → Submissions → Idempotency).
• brak webhooków: sprawdź GET /api/v1/webhooks/deliveries.