Document Verification API

Endpointy

Uwierzytelnianie: Authorization: Bearer elg_live_...

POST   /v1/verifications                 utworz sesje
GET    /v1/verifications/{id}            stan i wynik
POST   /v1/verifications/{id}/cancel     przerwij
POST   /v1/verifications/{id}/retry      otworz kolejna probe
GET    /v1/verifications/fields          lista dostepnych pol

Utworzenie sesji

curl -X POST https://elogowanie.pl/v1/verifications \
  -H "Authorization: Bearer elg_live_..." \
  -H "content-type: application/json" \
  -d '{
    "fields": ["given_names", "surname", "date_of_birth"],
    "webhook_url": "https://twojsklep.pl/hooks/elogowanie",
    "redirect_url": "https://twojsklep.pl/po-weryfikacji",
    "max_attempts": 5,
    "ttl_minutes": 30
  }'

{
  "verification_id": "ver_8k2m4x9q...",
  "status": "pending",
  "requested_fields": ["given_names", "surname", "date_of_birth"],
  "attempt": 0,
  "max_attempts": 5,
  "attempts_left": 5,
  "result": null,
  "expires_at": "2026-09-07T15:30:00.000Z",
  "source_document_deleted_at": null,
  "verification_url": "https://elogowanie.pl/weryfikacja/xK9...",
  "webhook_secret": "whsec_..."
}

verification_url i webhook_secret pokazujemy dokladnie raz. W bazie trzymamy wylacznie skrot adresu, wiec nie da sie go odtworzyc — zgubiony oznacza nowa sesje.

Odczyt wyniku

{
  "verification_id": "ver_8k2m4x9q...",
  "status": "verified",
  "result": {
    "given_names": "ANNA MARIA",
    "surname": "KOWALSKA",
    "date_of_birth": "1990-01-01"
  },
  "attempt": 2,
  "source_document_deleted_at": "2026-09-07T15:12:41.000Z",
  "attempts_log": [
    { "attempt": 1, "status": "retry_required", "reason": "DOCUMENT_GLARE",
      "source_deleted_at": "2026-09-07T15:12:10.000Z" },
    { "attempt": 2, "status": "verified",
      "source_deleted_at": "2026-09-07T15:12:41.000Z" }
  ]
}

result zawiera wylacznie pola z fields. Nawet jesli dokument niesie wiecej danych, reszta nie opuszcza procesu weryfikacji.

Pola

Nie kazdy dokument niesie kazde pole — brakujace wracaja jako null.

Statusy

Powody ponowienia

DOCUMENT_BLURRY DOCUMENT_TOO_DARK DOCUMENT_OVEREXPOSED DOCUMENT_GLARE DOCUMENT_PARTIALLY_VISIBLE DOCUMENT_OUT_OF_FRAME DOCUMENT_LOW_RESOLUTION DOCUMENT_NOT_DETECTED DOCUMENT_UNREADABLE OCR_FAILED MRZ_UNREADABLE TEMPORARY_PROCESSING_ERROR

Powody koncowe: MAX_ATTEMPTS_REACHED, SESSION_EXPIRED, USER_CANCELLED oraz RISK_BLOCKED. Ten ostatni jest celowo ogolny — nie opisujemy, co wykrylismy, zeby nie podpowiadac, jak to obejsc.

Webhooki

Zdarzenia: verification.started, verification.completed, verification.failed, verification.expired.

POST https://twojsklep.pl/hooks/elogowanie
elg-event: verification.completed
elg-signature: t=1788789000,v1=<hmac-sha256>

{ "event": "verification.completed",
  "verification_id": "ver_8k2m...",
  "status": "verified",
  "reason": null,
  "attempt": 2 }

Sprawdzenie podpisu:

const [, ts, sig] = /^t=(\d+),v1=([a-f0-9]{64})$/.exec(header)
const expected = crypto.createHmac('sha256', webhookSecret)
  .update(`${ts}.${rawBody}`).digest('hex')
// porownaj czasem stalym i odrzuc znacznik starszy niz 5 minut

W webhooku nie ma obrazu ani danych osobowych — po zdarzeniu odbierz wynik przez GET /v1/verifications/{id}. Ponowienia: 6 prob z narastajaca przerwa (10 s → 6 h).

Retencja materialu

Rozroznienie, ktore ma tu znaczenie:

• •

  Material zrodlowy (zdjecie dokumentu)

  Zapisywany do katalogu tymczasowego wylacznie na czas analizy jednej proby i kasowany w bloku finally — takze gdy analiza rzuci wyjatkiem. Osobna zamiatarka co minute usuwa wszystko starsze niz TTL, patrzac na czas pliku, a nie na stan bazy. Nieudane proby podlegaja dokladnie tej samej regule.

• •

  Wynik weryfikacji

  Odczytane pola przechowujemy przy sesji, zeby firma mogla je pobrac. Po przekazaniu ich Tobie odpowiadasz za nie we wlasnym systemie — tego juz nie kontrolujemy i nie obiecujemy usuniecia.

Pole source_document_deleted_at w API jest ustawiane dopiero po potwierdzeniu, ze plikow nie ma na dysku. Jesli kasowanie sie nie powiodlo, pole zostaje puste, a zadanie trafia do ponowienia.

Stan wdrozenia — czytaj przed integracja

Modul dziala od strony przeplywu, ale automatyczny odczyt danych z dokumentu jest domyslnie wylaczony. Bez niego sesja z poprawnym zdjeciem konczy sie statusem inconclusive, a nie verified — wolimy powiedziec "nie wiem" niz zwrocic zgadniete dane osobowe.

Wykrywanie naduzyc ogranicza sie dzis do powtorzonego materialu (skrot percepcyjny miedzy sesjami) i sygnalow z klienta. To nie jest pelna ochrona przed zdjeciem ekranu ani przed wirtualna kamera.