Documenti

I documenti sono collegati a una richiesta, non direttamente a un richiedente. Ogni caricamento avvicina la richiesta madre allo stato "pronta per l'invio" — quando pendingDocTypes è vuoto, si può inviare la richiesta per l'elaborazione.

Carica un documento

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

Caricamento multipart. Passi documentType (e side, se applicabile) come parametri di query, e il file in un campo di modulo file.

Parametri di query

Corpo del modulo

Tipi di documento

Esempio

# 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"

Risposta (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."
}

La risposta indica sempre ciò che manca ancora tramite pendingDocTypes. Quando quell'array è vuoto, la chiamata successiva deve essere POST /requests/:id/submit.

Valori di stato del documento

• pending — caricato, non ancora elaborato (accade solo prima dell'invio della richiesta).
• verified — ha superato tutti i controlli di autenticità dopo l'invio della richiesta.
• failed — non ha superato un controllo di autenticità. Consulti i record dei controlli collegati in GET /requests/:id per il motivo specifico.
• corrupted — il file non può essere decodificato. Lo carichi di nuovo.

Errori

• 400 BAD_REQUEST:
  • Il file supera i 10 MB.
  • Tipo MIME non supportato.
  • side mancante per GOVERNMENT_ID.
  • documentType non consentito dalle impostazioni KYC dell'organizzazione.
• 404 NOT_FOUND — la richiesta madre non esiste in questa organizzazione.
• 409 CONFLICT — la richiesta non è in PENDING_UPLOAD. Non si possono aggiungere documenti a una richiesta già inviata.

Ottieni un URL di download

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

I documenti sono archiviati in uno storage privato di oggetti. Per visualizzarne o scaricarne uno, recuperi un URL firmato a breve scadenza.

Risposta

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

expiresIn è espresso in secondi — l'URL è valido per 15 minuti. Ne generi uno nuovo ogni volta che deve visualizzare un documento; non memorizzarli nella cache.

L'url restituito è un URL di storage prefirmato (S3 / Azure Blob / GCS). Si apre direttamente in una scheda del browser e viene visualizzato senza intestazione Authorization:

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

Controlli il mimeType di ciascun documento (da GET /requests/:id) per decidere cosa visualizzare.

Scarica i byte grezzi

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

Trasmette direttamente i byte del file del documento, con il Content-Type memorizzato (image/jpeg, image/png, image/webp oppure application/pdf) e Content-Disposition: inline. Nessun URL firmato, nessun reindirizzamento.

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

Preferisca questo percorso rispetto alla route con URL firmato quando visualizza i documenti all'interno della propria dashboard:

• Funziona con qualsiasi backend di storage, incluso il disco locale — il cui URL firmato /uploads/… è raggiungibile solo dall'interno dell'host di Certivant e darà 404 da un'altra origine.
• Lo faccia passare dal proprio backend e lo serva nella stessa origine (<img src="/your-proxy/doc"> per le immagini, <iframe> per i PDF). La chiave Authorization: Bearer resta lato server e non raggiunge mai il browser.
• Nessun URL di storage viene mai esposto, quindi non c'è nulla da far trapelare o che possa scadere.

Sostituzione dei documenti

Non è possibile modificare un documento sul posto. Se il richiedente ha caricato una foto sfocata e si desidera una nuova acquisizione:

1. La richiesta deve essere in PENDING_UPLOAD (oppure va prima reinviata una richiesta rifiutata, per cancellare i documenti precedenti).
2. Carichi un nuovo documento con lo stesso documentType e side. Il precedente viene sostituito — per l'elaborazione viene usata solo l'ultima versione.

Questa regola serve all'integrità dell'audit: una cronologia immutabile di ogni caricamento sopravvive nel registro di audit, anche quando cambia il documento attivo.

Elencare i documenti di una richiesta

Non esiste un endpoint separato per l'elenco dei documenti. L'elenco completo è incluso nella risposta di GET /api/v1/kyc/requests/:id:

{
  "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", ... }
  ]
}

Scorra documents e richiami /download (per trasmettere i byte tramite il proprio server) oppure /url (per un link firmato) su qualsiasi documento specifico che desidera visualizzare.

Correlati

• Richieste KYC — la richiesta madre a cui si collegano i documenti.
• Sessioni ospitate — lasci che sia Certivant a raccogliere direttamente i documenti dal richiedente.
• Schemi — elenco completo di documentType, status e valori correlati.