Aller au contenu principal

Créer un processus

Ce endpoint gère trois produits qui partagent le même chemin mais diffèrent par les paramètres du corps, les capacités et les champs de réponse :

  • Intégration -- valide l'identité de l'utilisateur en comparant son visage à la base d'identité Unico (subject.duiType + subject.code requis).
  • Transactionnel -- vérifie que c'est la même personne qu'un processus précédent en comparant face à face (referenceProcessId OU tableau references avec selfie / ID de processus requis).
  • Cardholder Verification -- confirme qu'une carte appartient à son titulaire déclaré, sans aucune capture de selfie (subject.code + card requis). Réutilise éventuellement un processus déjà validé via referenceProcessId pour activer le déclencheur de réutilisation ; sans lui, la réponse revient par défaut à unsure. Voir la capacité Cardholder Verification.

Le produit actif est déterminé par l'APIKEY envoyée dans l'en-tête de la requête.

Pour le flux d'intégration complet, voir Vue d'ensemble de l'API.

Endpoint​

EnvironnementURL
ProductionPOST https://api.id.unico.app/processes/v1
SandboxPOST https://api.id.uat.unico.app/processes/v1

Requête​

En-têtes
En-têteValeur
AuthorizationBearer <access_token> (voir Authentification)
APIKEYClé API provisionnée -- définit le produit actif et les capacités activées.
Content-Typeapplication/json
Paramètres du corps
ChampTypeRequisDescription
subject.duiTypeintegerouiIdentifiant du type de document. Voir valeurs de duiType ci-dessous.
subject.codestringouiValeur de l'identifiant telle que définie par subject.duiType. Sans points ni tirets.
subject.namestringnonNom complet.
subject.genderstringnonM ou F.
subject.birthDatestring (ISO 8601)nonDate de naissance (AAAA-MM-JJ).
subject.emailstringnonAdresse e-mail.
subject.phonestringnonNuméro de téléphone au format E.164.
subject.clientReferencestringconditionnelIdentifiant unique de l'utilisateur dans votre système. Requis pour la capacité Multi-comptes. Unique dans votre base, maximum de 256 caractères, sans espaces.
useCasestringnonContexte de l'opération, ex. Onboarding.
subsidiaryIdstringnonID de la filiale — requis uniquement si plusieurs filiales existent.
imageBase64stringouiSelfie capturé par votre front-end, en base64.
Valeurs de duiType
PaysCodeDescription
BR1CPF brésilien
MX2CURP mexicain
US4SSN américain
BR5Passeport brésilien
AR6Passeport argentin
AR7DNI argentin
NG8NIN nigérian
CL9RUN chilien
EC10NI équatorien
US11Passeport américain
GT12CUI guatémaltèque
UY13CI uruguayen
BR14CNPJ brésilien
ZZ15Adresse e-mail
ID16NIK indonésien
ZZ17Numéro de téléphone
US18Permis de conduire américain
NG20Numéro de vérification bancaire nigérian (BVN)
US21Carte de passeport américaine
US22Passeport américain en polycarbonate
US23Carte d'identité américaine
TR24Numéro d'identification turc (TCKN)
MX25RFC mexicain (Personne physique)
CO26NIT colombien
PE27RUC péruvien
CA28Numéro d'assurance sociale canadien (NAS)
DK29CPR danois
GB30Numéro d'assurance nationale britannique (NINO)
PL31PESEL polonais
SE32Numéro personnel suédois (PNR)
CH33Numéro AVS/AHV suisse
AT34Numéro fiscal autrichien (STNR)
FI35Code d'identité personnelle finlandais (HETU)
BE36Numéro national belge (NN)
IT37Codice Fiscale italien (CF)
SE38Numéro de coordination suédois (Samordningsnummer)
NO39Numéro d'identité national norvégien (Fødselsnummer)
PE40DNI péruvien
DE41Numéro d'identification fiscale allemand (IdNr)
NL42Numéro de service citoyen néerlandais (BSN)
NG43Jeton BVN nigérian (haché)
NG44Jeton NIN nigérian (haché)
PT45Numéro d'identification fiscale portugais (NIF)
FR46Numéro de référence fiscale français (SPI)
IE47Numéro personnel de service public irlandais (PPSN)
LU48Numéro d'identification national luxembourgeois (Matricule)
AR49Permis de conduire argentin (Licencia Nacional de Conducir)
ES50Numéro d'identité d'étranger espagnol (NIE)
ES51Document national d'identité espagnol (DNI)
CL52Passeport chilien
CO53Passeport colombien
PE54Passeport péruvien
CO55Permis de conduire colombien (Licencia de Conducción)
CO56Carte de citoyenneté colombienne (Cédula de Ciudadanía)
CL57Permis de conduire chilien (Licencia de Conducir)
MX58Permis de conduire mexicain (Licencia de Conducir)
—0Non spécifié
—3Identifiant interne Unico
Exigences d'image
  • Résolution minimale : 640 x 480 (standard HD)
  • Taille maximale du fichier : 800 Ko (compression JPEG92 recommandée)
  • Formats acceptés : PNG, JPEG, WebP
  • Les jetons JWT du SDK expirent après 10 minutes et ne peuvent être utilisés qu'une seule fois

Exemple​

curl -X POST https://api.id.unico.app/processes/v1 \
  -H "Authorization: Bearer $TOKEN" \
  -H "APIKEY: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": {
      "duiType": 1,
      "code": "12345678909",
      "name": "Luke Skywalker",
      "gender": "M",
      "birthDate": "2000-05-20",
      "email": "[email protected]",
      "phone": "5519725570707"
    },
    "useCase": "Onboarding",
    "imageBase64": "/9j/4AAQSkZJR..."
  }'

Réponses​

200 OK

Le contrat est unique — le champ idCloud.result porte le verdict consolidé des capacités utilisées.

Unico consolide les résultats des capacités exécutées en un seul idCloud.result, prêt à décider de la prochaine étape de votre flux — sans besoin d'orchestrer les résultats individuels.

{
  "id": "80371b2a-3ac7-432e-866d-57fe37896ac6",
  "status": 3,
  "idCloud": {
    "result": "approved"
  }
}
ChampTypeDescription
idstring (UUID)Identifiant du processus. Utilisez-le avec Get Process pour les re-requêtes.
statusinteger1 (en traitement), 3 (terminé avec succès), 5 (erreur).
Valeurs possibles du résultat
idCloud.resultMeaningRecommended action
approvedReal person and validated identity.Proceed with the flow.
deniedIdentity not validated, liveness check failed, or extreme risk identified.End the flow or redirect to an alternative flow.
critical-riskCritical risk level identified.End the flow or route to manual review.
high-riskHigh risk level identified.Route to manual review or an alternative flow.
retryInsufficient capture or score to evaluate.Ask the user for a new capture.
inconclusiveNot enough evidence for a verdict.Route to manual review or an alternative flow.

Les valeurs retournées dépendent de la recette configurée dans votre APIKey. Consultez Flux pour connaître les valeurs de résultat que chaque recette peut retourner.

BrazilLes clients au Brésil peuvent recevoir la réponse par capacité

La structure globale de la réponse reste la même — le résultat unique est la valeur par défaut.

Les intégrations au Brésil peuvent recevoir les résultats ouverts, par capacité. Chaque capacité activée dans l'APIKey ajoute son propre bloc à la réponse — les champs des capacités désactivées sont omis.

{
  "id": "80371b2a-3ac7-432e-866d-57fe37896ac6",
  "status": 3,
  "unicoId": {
    "result": "yes"
  },
  "riskLevel": {
    "result": "inconclusive"
  },
  "idFace": {
    "personId": "a1b2c3d4e5f67890a1b2c3d4e5f67890a1b2c3d4e5f67890a1b2c3d4e5f67890",
    "result": "FOUND"
  },
  "government": {
    "serpro": 87
  },
  "liveness": 1
}
Les champs de réponse dépendent de votre APIKey

L'exemple ci-dessus présente tous les champs de capacité possibles. Votre réponse réelle n'inclura que les champs correspondant aux capacités activées dans votre configuration APIKey — les champs des capacités désactivées sont entièrement omis. Contactez votre chef de projet Unico pour activer ou ajuster des capacités.

ChampTypeDescription
unicoId.resultstringyes, no, inconclusive -- voir Vérification d'identité.
riskLevel.resultstringapproved, reproved, risk-critical, risk-high, inconclusive -- voir les valeurs possibles ci-dessous ou la Classification du risque de fraude.
idFace.resultstringFOUND — voir Identifiant Facial.
idFace.personIdstringIdentifiant opaque stable pour le visage, retourné conjointement à idFace.result = FOUND. Lorsqu'aucun visage ne peut être identifié dans l'image, la requête échoue avec l'erreur 20532 au lieu de retourner un bloc idFace.
identityFraudsters.resultstringObsolète. Utilisez riskLevel à la place. Les clients dont les intégrations sont en cours peuvent continuer à l'utiliser pendant qu'ils coordonnent la migration avec l'équipe responsable du projet.
government.serprointegerScore de similarité Serpro (0-100, -1, -2). Disponible au Brésil uniquement. Voir Retour de similarité Serpro.
livenessinteger1 (réussi), 2 (échoué) -- voir Détection de Vie.
riskLevel.result — valeurs possibles
ValeurSignification
approvedIl s'agit du visage du titulaire de la pièce d'identité et aucun indice lié à une fraude n'a été détecté.
reprovedLe rejet est recommandé, car plusieurs indicateurs de fraude ont été détectés.
risk-criticalLe rejet est recommandé, mais la décision finale appartient à votre appréciation. Le risque critique indique qu'au moins 2 preuves solides de fraude ont été trouvées.
risk-highLe rejet est également recommandé, mais la décision vous appartient. Le risque élevé indique qu'au moins une preuve solide de fraude a été trouvée.
inconclusiveAucune preuve solide de fraude n'a été trouvée. Il n'est donc pas possible de conclure s'il existe un risque pertinent ou non.
info

Lorsque unicoId.result = inconclusive et que l'orchestration du Score de Risque est active, le processus peut retourner status: 1 (en traitement). Interrogez Get Process ou utilisez les webhooks pour récupérer le résultat final.

Codes d'erreur​

CodeMessageDescription
40221This flow does not support reusing a prior process (referenceProcessId or bioTokenId) without an image; send an image (imageBase64, or references[0] with type IMAGE_BASE64) instead.Le flux de réutilisation (referenceProcessId/bioTokenId, sans image) a été rejeté car la réutilisation de processus n'est pas activée pour cette clé API.
20900O base64 informado não é válido.Le paramètre base64 est invalide. Causes possibles : ce n'est pas une image ou c'est une tentative d'injection.
20807A imagem precisa estar no padrão HD ou possuir uma resolução superior a 640 x 480.La résolution de l'image téléchargée est trop faible.
20532No face detected in image.Aucun visage n'a pu être détecté dans l'image envoyée.
20513The referenced process was not found.Le referenceProcessId pointe vers un processus qui n'existe pas ou n'est plus accessible.
20512The referenced process is not available for reuse.Le processus référencé existe mais n'est pas disponible pour réutilisation.
20509The subject.name field is invalid.subject.name contient des caractères invalides.
20508The subject.gender field is invalid.subject.gender doit être M ou F.
20507O parâmetro subject.code é inválido.CPF non standard ou inexistant.
20506O base64 informado é muito grande. O tamanho máximo suportado é até 800kb.La taille de l'image dépasse 800 Ko ; compressez en JPEG92.
20505O base64 informado não é suportado. Os formatos aceitos são png, jpeg e webp.Le format base64 est invalide ou non pris en charge.
20065The referenceProcessId field is invalid.Le referenceProcessId n'est pas un UUID valide.
20062The useCase field is invalid.Valeur non reconnue dans le champ useCase.
20024The referenceProcessId field is missing.Le paramètre referenceProcessId n'a pas été fourni et references n'a pas été envoyé comme alternative. Ne s'applique pas à Cardholder Verification -- son referenceProcessId n'est jamais validé comme requis ; une condition de réutilisation non satisfaite répond unsure à la place.
20533The card field is missing.Cardholder Verification : l'objet card n'a pas été fourni.
20534The card.bin field is missing.Cardholder Verification : card.bin n'a pas été fourni.
20535The card.last4 field is missing.Cardholder Verification : card.last4 n'a pas été fourni.
20536The card data is invalid.Cardholder Verification : les données de la carte ont été rejetées comme invalides.
20021The subject.phone field is invalid.Le format de subject.phone est invalide (IDD + indicatif régional + numéro, 13 caractères).
20019The subject.birthDate field is invalid.subject.birthDate n'est pas au format ISO 8601 (AAAA-MM-JJ).
20009O parâmetro imagebase64 não foi informado.Le paramètre d'image selfie est manquant.
20008The subject.email field is invalid.Format d'e-mail invalide dans subject.email.
20006O parâmetro subject.name não foi informado.Le paramètre subject.name est manquant.
20005O parâmetro subject.code não foi informado.Le paramètre subject.code est manquant.
20004O parâmetro subject não foi informado.Le paramètre subject est manquant.
20003The request body is missing or invalid.Payload nul ou invalide.
20002O parâmetro APIKey não foi informado.Le paramètre APIKEY est manquant dans l'en-tête de la requête.
20001O parâmetro authtoken não foi informado.Le paramètre de jeton d'intégration est manquant dans l'en-tête de la requête.
10508The JWT with the captured face has already been used.Le JWT ne peut être utilisé qu'une seule fois.
10507The JWT with the captured face is expired.Le JWT a expiré ; il doit être envoyé dans les 10 minutes.
10506The imageBase64 field is not a valid JWT from SDK.Le champ imageBase64 n'est pas un JWT valide généré par le SDK.

Prochaines étapes​

  • Pour interroger le résultat d'un processus d'Intégration, voir Get Process.
  • Pour voir toutes les combinaisons de recettes et leurs valeurs de résultat possibles, voir Flux.
  • Pour les opérations de Document et de Vérification de l'âge, voir les pages respectives dans cette section.
Dernière mise à jour le