Submissions

Jak wysłać XML i obsłużyć lifecycle zgłoszenia (submission)

Utworzenie submission

Endpoint: POST /api/v1/submissions

Wymagania:

• header X-API-Token
• scope submissions:write
• multipart/form-data

Przykład:

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

Idempotency (2 mechanizmy)

• Idempotency-Key (header lub form)
• deduplikacja po hash XML (sha256)

Lifecycle

Statusy finalne: accepted, rejected, failed_final, cancelled.

Webhooki

Typowy zestaw eventów:

• ksef.outgoing.queued
• ksef.outgoing.sent
• ksef.outgoing.accepted
• ksef.outgoing.rejected
• ksef.outgoing.failed

Polling (gdy nie masz webhooków)

• GET /api/v1/submissions/{submission_id}
• GET /api/v1/submissions/{submission_id}/result

⚠ Braki kontraktowe

W implementacji POST /api/v1/submissions mogą pojawiać się dodatkowe statusy schedulera (np. planowanie/batchowanie). Traktuj je jak „queued w przyszłości”.