Dokumente

Dokumente werden einer Anfrage zugeordnet, nicht direkt einem Antragsteller. Jeder Upload bringt die übergeordnete Anfrage näher an „bereit zur Einreichung“ — sobald pendingDocTypes leer ist, können Sie die Anfrage zur Verarbeitung einreichen.

Ein Dokument hochladen

POST /api/v1/kyc/requests/:requestId/documents    Berechtigungsbereich: kyc:write

Multipart-Upload. Übergeben Sie documentType (und gegebenenfalls side) als Abfrageparameter und die Datei in einem Formularfeld file.

Abfrageparameter

Formular-Body

Dokumenttypen

Beispiel

# Upload the front of a driver's license
curl -X POST "https://app.certivant.com/api/v1/kyc/requests/req_01J.../documents?documentType=GOVERNMENT_ID&side=front" \
  -H "Authorization: Bearer ck_live_..." \
  -F "file=@/path/to/license-front.jpg"

Antwort (201)

{
  "id": "doc_01J...",
  "documentType": "GOVERNMENT_ID",
  "side": "front",
  "status": "pending",
  "fileSize": 412938,
  "mimeType": "image/jpeg",
  "requestStatus": "PENDING_UPLOAD",
  "pendingDocTypes": ["GOVERNMENT_ID", "SELFIE"],
  "message": "Document uploaded. Front of GOVERNMENT_ID received; back of GOVERNMENT_ID still required."
}

Die Antwort zeigt Ihnen über pendingDocTypes stets, was noch fehlt. Ist dieses Array leer, sollte Ihr nächster Aufruf POST /requests/:id/submit sein.

Statuswerte der Dokumente

• pending — hochgeladen, noch nicht verarbeitet (tritt nur vor der Einreichung der Anfrage auf).
• verified — hat nach der Einreichung der Anfrage alle Echtheitsprüfungen bestanden.
• failed — hat eine Echtheitsprüfung nicht bestanden. Den konkreten Grund finden Sie in den verknüpften Prüfdatensätzen unter GET /requests/:id.
• corrupted — die Datei konnte nicht dekodiert werden. Erneut hochladen.

Fehler

• 400 BAD_REQUEST:
  • Datei größer als 10 MB.
  • Nicht unterstützter MIME-Typ.
  • side fehlt bei GOVERNMENT_ID.
  • documentType ist laut KYC-Einstellungen der Organisation nicht zulässig.
• 404 NOT_FOUND — die übergeordnete Anfrage existiert nicht in dieser Organisation.
• 409 CONFLICT — die Anfrage befindet sich nicht in PENDING_UPLOAD. Sie können einer bereits eingereichten Anfrage keine Dokumente mehr hinzufügen.

Eine Download-URL abrufen

GET /api/v1/kyc/requests/:requestId/documents/:docId/url    Berechtigungsbereich: kyc:read

Dokumente werden in privatem Objektspeicher abgelegt. Um eines anzusehen oder herunterzuladen, rufen Sie eine kurzlebige signierte URL ab.

Antwort

{
  "url": "https://storage.certivant.com/kyc/org_.../req_.../doc_....jpg?X-Amz-Signature=...",
  "expiresIn": 900
}

expiresIn wird in Sekunden angegeben — die URL ist 15 Minuten gültig. Erzeugen Sie bei Bedarf jedes Mal eine neue, wenn Sie ein Dokument anzeigen müssen; zwischenspeichern Sie sie nicht.

Die zurückgegebene url ist eine vorsignierte Speicher-URL (S3 / Azure Blob / GCS). Sie öffnet sich direkt in einem Browser-Tab und wird ohne Header Authorization dargestellt:

• Bilder (image/jpeg, image/png, image/webp) → <img src="{url}" />
• PDFs (application/pdf) → <iframe src="{url}" /> oder <object data="{url}" type="application/pdf" />

Prüfen Sie den mimeType jedes Dokuments (aus GET /requests/:id), um zu entscheiden, wie es dargestellt wird.

Die Rohbytes herunterladen

GET /api/v1/kyc/requests/:requestId/documents/:docId/download    Berechtigungsbereich: kyc:read

Streamt die Bytes der Dokumentdatei direkt zurück, mit dem gespeicherten Content-Type (image/jpeg, image/png, image/webp oder application/pdf) und Content-Disposition: inline. Keine signierte URL, keine Weiterleitung.

curl -L "https://app.certivant.com/api/v1/kyc/requests/req_01J.../documents/doc_01J.../download" \
  -H "Authorization: Bearer ck_live_..." \
  -o government_id_front.jpg

Bevorzugen Sie diesen Weg gegenüber der Route mit signierter URL, wenn Sie Dokumente in Ihrem eigenen Dashboard anzeigen:

• Er funktioniert mit jedem Speicher-Backend, einschließlich lokaler Festplatte — deren signierte URL /uploads/… ist nur vom Certivant-Host aus erreichbar und liefert von einem anderen Ursprung aus 404.
• Leiten Sie ihn über Ihr Backend weiter und liefern Sie ihn vom selben Ursprung aus (<img src="/your-proxy/doc"> für Bilder, <iframe> für PDFs). Der Schlüssel Authorization: Bearer bleibt serverseitig und erreicht nie den Browser.
• Es wird nie eine Speicher-URL offengelegt, daher gibt es nichts, was austreten oder ablaufen könnte.

Dokumente ersetzen

Sie können ein Dokument nicht direkt bearbeiten. Hat der Antragsteller ein unscharfes Foto hochgeladen und Sie möchten eine neue Aufnahme:

1. Die Anfrage muss sich in PENDING_UPLOAD befinden (oder Sie müssen zuerst eine abgelehnte Anfrage erneut einreichen, um die bisherigen Dokumente zu entfernen).
2. Laden Sie ein neues Dokument mit demselben documentType und side hoch. Das bisherige wird ersetzt — für die Verarbeitung wird nur die neueste Version verwendet.

Diese Regel dient der Integrität des Audit-Protokolls: Eine unveränderliche Historie jedes Uploads bleibt im Audit-Protokoll erhalten, auch wenn sich das aktive Dokument ändert.

Dokumente einer Anfrage auflisten

Es gibt keinen eigenen Listen-Endpunkt für Dokumente. Die vollständige Liste ist in der Antwort von GET /api/v1/kyc/requests/:id enthalten:

{
  "id": "req_...",
  "documents": [
    { "id": "doc_a", "documentType": "GOVERNMENT_ID", "side": "front", "status": "verified", ... },
    { "id": "doc_b", "documentType": "GOVERNMENT_ID", "side": "back", "status": "verified", ... },
    { "id": "doc_c", "documentType": "SELFIE", "status": "verified", ... }
  ]
}

Durchlaufen Sie documents und rufen Sie für das jeweilige Dokument, das Sie anzeigen möchten, /download (um die Bytes weiterzuleiten) oder /url (für einen signierten Link) auf.

Verwandte Themen

• KYC-Anfragen — der übergeordnete Endpunkt, dem Ihre Dokumente zugeordnet werden.
• Gehostete Sitzungen — lassen Sie Certivant die Dokumente direkt vom Antragsteller einsammeln.
• Schemas — vollständige Aufzählung von documentType, status und verwandten Werten.