Get Reusable Documents

Utilisez ce endpoint pour vérifier si un utilisateur dispose déjà d'un document disponible pour réutilisation avant de démarrer un nouveau flux de capture de document. Si un document est trouvé, son documentId peut être transmis directement à POST /processes/v1 (type Document) pour ignorer l'étape de capture.

Endpoint

Environnement	URL
Production	GET https://api.id.unico.app/documents/v1
Sandbox	GET https://api.id.uat.unico.app/documents/v1

Requête

En-têtes

En-tête	Valeur
Authorization	Bearer <access_token> (voir Authentification)
APIKEY	Clé API provisionnée avec la Capture de documents et réutilisation activée.

Paramètres de requête

Paramètre	Type	Requis	Description
code	string	oui	Identifiant de l'utilisateur (CPF ou CURP, sans formatage).
type	string	oui	Type de document à rechercher. Valeurs acceptées : BR_RG, BR_CNH, BR_CIN, BR_PASSPORT.

remarque

Les valeurs de type ci-dessus sont spécifiques à ce endpoint. Ne les confondez pas avec :

• subject.duiType dans les requêtes POST -- utilise le préfixe DUI_TYPE_* et identifie la personne, pas le type de document (ex. : DUI_TYPE_BR_CPF).
• documentType dans la réponse -- utilise le chemin complet du registre (ex. : unico.moja.dictionary.br.cnh.v2.Cnh).

Exemple

cURL

curl -X GET "https://api.id.unico.app/documents/v1?code=12345678909&type=BR_CNH" \
  -H "Authorization: Bearer $TOKEN" \
  -H "APIKEY: $API_KEY"

Node.js

import fetch from 'node-fetch';

const params = new URLSearchParams({ code: '12345678909', type: 'BR_CNH' });
const res = await fetch(
  `https://api.id.unico.app/documents/v1?${params}`,
  {
    headers: {
      Authorization: `Bearer ${accessToken}`,
      APIKEY: apiKey
    }
  }
);
const data = await res.json();
// data.items[0].documentId → pass to POST /processes/v1 for reuse

Réponses

200 OK

{
  "items": [
    {
      "documentType": "unico.moja.dictionary.br.cnh.v2.Cnh",
      "documentId": "doc-abc-123"
    }
  ]
}

Champ	Type	Description
items	array	Liste des documents réutilisables trouvés pour l'utilisateur. Tableau vide si aucun document réutilisable n'a été trouvé pour le code et le type donnés.
items[].documentType	string	Identifiant du type de document. Valeurs possibles : unico.moja.dictionary.br.rg.v2.Rg, unico.moja.dictionary.br.cnh.v2.Cnh, unico.moja.dictionary.br.cin.v1.Cin, unico.moja.dictionary.br.passaporte.v1.Passaporte.
items[].documentId	string	Identifiant du document. Transmettez cette valeur dans document.documentId lors de POST /processes/v1 pour réutiliser le document.

403 Forbidden

Le Bearer token ou l'APIKEY est manquant, expiré ou invalide.

429 Too Many Requests

Limite de débit atteinte. Lorsque votre système reçoit une erreur HTTP 429, vous devez implémenter des mécanismes pour prévenir les défaillances en cascade et éviter d'aggraver la restriction.

Bonnes pratiques :

• Période de refroidissement (backoff) : Arrêtez ou limitez immédiatement les requêtes suivantes de votre système. Ne réessayez pas continuellement les requêtes échouées en boucle serrée.
• Mise en file d'attente et limitation : Mettez en tampon ou en file d'attente les requêtes sortantes de votre côté pour contrôler le flux de trafic avant de les renvoyer.
• Backoff exponentiel avec jitter : Lors des nouvelles tentatives, augmentez le temps d'attente de manière exponentielle entre les tentatives (ex. : 1 s, 2 s, 4 s, 8 s) et ajoutez un petit délai aléatoire (« jitter ») pour éviter un effet de troupeau où toutes les requêtes en file d'attente réessaient exactement à la même milliseconde.

avertissement

Frapper continuellement un endpoint limité en débit sans faire de backoff peut prolonger la période de restriction et impacter sévèrement le débit opérationnel de votre système. Limiter correctement les requêtes de votre côté assure une intégration plus fluide et plus résiliente.

Pour les limites par défaut, l'augmentation des requêtes et des détails supplémentaires, voir Limites de débit.

Utilisation du documentId pour la réutilisation

Une fois que vous avez un documentId, transmettez-le dans la requête de processus Document pour ignorer la capture :

{
  "subject": {
    "code": "12345678909",
    "name": "Luke Skywalker"
  },
  "document": {
    "purpose": "onboarding",
    "authProcessId": "<biometric-process-id>",
    "documentId": "doc-abc-123"
  }
}

Champ	Description
document.purpose	Objectif commercial de ce processus de document. Valeurs acceptées : creditprocess, carpurchase, paybypaycheck, onboarding, fgts. Ces valeurs sont spécifiques à l'API Document et diffèrent de l'enum purpose du SDK biométrique.
document.authProcessId	ID du processus biométrique précédemment créé pour cet utilisateur (issu de POST /processes/v1).
document.documentId	ID du document obtenu à partir de la réponse de ce endpoint. Lorsqu'il est fourni, document.files peut être omis -- la plateforme récupère automatiquement le document précédemment capturé.

Pour le schéma complet de la requête de processus Document, voir Créer un processus Document.

Codes d'erreur

400 Bad Request

Code	Message	Description
20507	O parâmetro subject.code é inválido.	Valeur d'identifiant malformée ou inexistante (CPF ou CURP).
20002	O parâmetro APIKey não foi informado.	En-tête APIKEY manquant.
20001	O parâmetro authtoken não foi informado.	En-tête de jeton d'authentification manquant.

403 Forbidden

Code	Message	Description
30020	The provided authorization token does not have permission to perform this action.	Le jeton n'a pas la permission d'accéder au selfie du document.
30017	User does not have permission to perform this action.	JWT malformé ou utilisateur sans permission pour effectuer cette opération.
10502	O token informado está expirado.	Jeton d'accès expiré.
10501	O token informado é inválido.	Jeton d'authentification invalide.
10201	O AppKey informado é inválido.	APIKEY manquante ou inexistante.

404 Not Found

Code	Message	Description
99987	Attachment not found.	La pièce jointe associée au document n'a pas été trouvée.
50001	The process is not found.	Aucun document trouvé pour les paramètres fournis.

500 Internal Server Error

Code	Message	Description
99999	Internal failure! Try again later.	Erreur de traitement côté serveur.