Guia d'integració i avaluació de l'API de verificació d'identitat (CA)

Una API de verificació d'identitat permet a una aplicació recollir o enviar proves d'identitat i rebre resultats estructurats sobre una persona reclamada. Depenent del flux de treball, pot validar un document d'identitat, extreure atributs, comparar un sol·licitant en viu amb un retrat de referència, comprovar la vivacitat, corroborar dades o orquestrar diverses comprovacions en una sola sessió.

La resposta de l'API és una evidència, no una decisió comercial completa. Una integració de producció també ha de definir la captura de confiança, la propietat de l'estat del client, les transicions d'estat, els reintents, la revisió, la privadesa, el manteniment de registres i la política que converteix els resultats tècnics en aprovació, reintent, escalada, revisió o rebuig.

Punts clau

• Una API de verificació d'identitat és més que un punt final. El contracte real inclou la captura, els estats asíncrons, les evidències, els esdeveniments, la reconciliació, la revisió i l'eliminació.
• El backend és el propietari de la decisió. Una redirecció de client o una pantalla de “succés” visual no és autoritzada; l'estat final s'ha de confirmar al servidor.
• Els resultats necessiten abast i raons. L'autenticitat del document, la vinculació del titular, la vivacitat, la qualitat i el risc contextual haurien de romandre separables en lloc de col·lapsar-se en un booleà inexplicat.
• La fiabilitat apareix en els camins de fallada. La idempotència, la verificació de webhooks, la reproducció d'esdeveniments, els temps d'espera, els reintents, el versionat i la paritat de sandbox són tan importants com el camí feliç.
• L'avaluació ha d'utilitzar poblacions similars a les de producció. La cobertura, la resistència al frau, la finalització, els resultats falsos, la càrrega de revisió i la privadesa s'han de mesurar per document, dispositiu, geografia i segment d'usuari rellevant.

Què fa una API de verificació d'identitat?

Una API de verificació d'identitat proporciona una interfície llegible per màquina per a les capacitats de prova d'identitat. Una integració típica crea un intent de verificació, dirigeix el sol·licitant a través d'una experiència de captura segura, rep esdeveniments de progrés o finalització, recupera l'evidència final i aplica la política de l'organització que hi confia.

El model de prova d'identitat NIST SP 800-63A-4 separa tres funcions importants:

• Resolució: distingir la persona reclamada dins de la població rellevant.
• Validació: determinar si les proves d'identitat i els atributs són autèntics, precisos i acceptables.
• Verificació: establir que el sol·licitant és el subjecte associat a aquesta evidència.

Una API pot realitzar una, dues o totes tres. Els noms dels productes no garanteixen l'abast, de manera que els requisits haurien d'indicar la conclusió exacta esperada de cada resultat.

Comparació d'API de verificació d'identitat, API de documents, API de KYC i OCR

Interfície	Propòsit principal	Sortida útil	Què no prova per si mateixa
API OCR	Convertir píxels de documents en text o camps	Nom, data, número, adreça extrets	Autenticitat, possessió o risc del client
API de verificació de documents	Validar un document i les seves proves capturades	Comprovacions d'autenticitat, caducitat, coherència de camps, indicadors de manipulació	Que el sol·licitant actual en sigui el propietari
API de concordança facial	Comparar una cara enviada amb una de referència	Similitud o decisió de concordança a un llindar	Vivacitat, autenticitat del document o identitat legal
API de vivacitat	Estimar la presència en viu en la captura biomètrica	Evidència de bona fe, atac, reintent o puntuació	La identitat de la persona
API de verificació d'identitat	Combinar la validació d'evidències i la vinculació del sol·licitant	Resultats a nivell d'evidència i resultat del flux de treball	KYC complet o elegibilitat empresarial
API de KYC	Donar suport a un flux més ampli de diligència deguda del client	Identitat, filtratge, risc, flux de treball i registres	Compliment automàtic sense política de l'organització

Aquesta distinció evita errors arquitectònics. Per exemple, afegir OCR a un formulari de càrrega accelera l'entrada de dades, però no autentica el document. Afegir la concordança facial connecta dues imatges, però no pot establir si cap de les dues imatges va arribar a través d'una captura de confiança i en viu.

Per obtenir el context més ampli de política, filtratge, risc i revisió contínua al voltant d'aquestes interfícies, vegeu la guia del cicle de vida de KYC. Aquest article es manté en el límit de confiança del desenvolupador: captura, estat de l'API, evidències, esdeveniments, reconciliació i decisions de backend.

Models d'integració comuns

Sessió de verificació allotjada

El backend de l'aplicació crea una sessió i rep una URL o un testimoni de curta durada. L'usuari completa la captura en un viatge allotjat pel proveïdor i després torna a l'aplicació. Aquest model pot reduir la complexitat del frontend i del dispositiu, tot preservant el control del costat del servidor.

Les preguntes clau inclouen la marca, el traspàs de domini, l'accessibilitat, la localització, el suport del navegador mòbil, la caducitat de la sessió, el comportament de retorn i com l'aplicació es reprèn quan l'usuari canvia de dispositiu.

SDK web o mòbil incrustat

Un SDK executa l'experiència de captura dins de l'aplicació. Pot proporcionar un control més estricte de la interfície i accés a les capacitats del dispositiu, però la qualitat de la integració afecta la seguretat. El suport de versions, la integritat de l'aplicació, els permisos de la càmera, la gestió de la càmera virtual, la política d'actualització i la telemetria passen a formar part de la revisió.

Comprovació independent de servidor a servidor

El sistema del client envia dades estructurades o multimèdia directament a un punt final. Això és útil per a captures ja de confiança, operacions per lots o mòduls individuals. També trasllada la responsabilitat de la integritat de la captura, el consentiment, la qualitat, la seguretat de la càrrega útil i la prevenció de la reproducció cap a l'integrador.

Flux de treball orquestrat

Una sessió pot ramificar-se a través de la validació de documents, comprovacions de bases de dades, vivacitat, concordança facial, filtratge, senyals de dispositius i revisió manual. L'API hauria d'exposar el flux de treball i la versió de la política perquè el mateix estat es pugui interpretar més tard.

Una seqüència d'integració segura

1. Crear l'intent des del backend

El backend de confiança genera una referència interna del client i crida al proveïdor amb el flux de treball, la configuració regional i el context de política requerits. No exposeu credencials d'API permanents al navegador o al codi mòbil.

Utilitzeu una estratègia d'idempotència per a les operacions de creació. Un temps d'espera del client no hauria de crear un segon intent facturable ni desvincular el resultat del client original.

2. Emetre un traspàs de captura de curta durada

Doneu al frontend només el testimoni o l'URL amb abast necessari per a aquest intent. Vinculeu-lo a l'aplicació esperada, la referència del client, el flux de treball i la caducitat. Eviteu posar dades personals innecessàries en URL, esdeveniments analítics o registres de client.

3. Capturar i validar evidències

Guieu l'usuari a través de les evidències admeses i els requisits de qualitat. Separeu els problemes de qualitat recuperables dels atacs sospitosos. “Apropa't”, “document caducat” i “la integritat de la captura ha fallat” no haurien de convertir-se en un error genèric.

4. Rebre un esdeveniment autenticat

Tracteu els webhooks com a entrada no fiable fins que no es verifiquin. Valideu la signatura de l'esdeveniment o l'autenticació del missatge, el control de temps o frescor, la destinació esperada, el tipus de contingut i l'identificador de l'esdeveniment. La RFC 9421 defineix un mecanisme general per a les signatures de missatges HTTP, tot i que un proveïdor pot utilitzar un esquema de signatura documentat diferent.

Emmagatzemeu els identificadors d'esdeveniments i processeu-los de manera idempotent. Els sistemes de lliurament reintenten; els esdeveniments duplicats són normals. No suposeu l'ordre d'arribada i no deixeu que un esdeveniment antic faci retrocedir un client d'un estat terminal.

5. Recuperar el resultat canònic

Després d'un esdeveniment de finalització, obteniu l'intent final de l'API del proveïdor. Aquest pas de reconciliació redueix la dependència del contingut d'un sol webhook i es recupera d'un lliurament perdut o retardat.

6. Aplicar la política de l'organització

Mapeu les evidències estructurades als estats de decisió propis de l'organització. El proveïdor pot recomanar un resultat, però l'organització que hi confia coneix el producte, l'historial del client, la base legal, la tolerància al risc i els camins de recuperació disponibles.

7. Registrar la transició

Persistiu la referència interna del client, l'identificador d'intent del proveïdor, el flux de treball i la versió, les evidències o referències rellevants, els codis de motiu, l'historial d'esdeveniments, la versió de la política, l'acció del revisor i la justificació final. Minimitzeu les dades sensibles copiades quan una referència duradora sigui suficient.

El model d'estat que l'API hauria d'exposar

Un camp booleà verificat és massa petit per a un viatge real del client. Els estats útils solen incloure:

Estat	Significat	Acció típica de l'aplicació
Creat	L'intent existeix, però la captura no ha començat	Presentar o reenviar el traspàs segur
En curs	L'usuari o les comprovacions asíncrones estan actives	Espera; no concedir accés final
Esperant entrada	Es requereix més evidència o acció de l'usuari	Mostrar una guia de recuperació precisa
Reintent permès	La captura o la qualitat van fallar de manera recuperable	Iniciar un nou intent delimitat
En revisió	Un revisor format és el propietari del cas	Mantenir l'accés pendent i exposar el següent pas esperat
Aprovat	L'evidència requerida va complir el flux de treball configurat	Aplicar la política de l'organització i la transició d'estat
Rebutjat	L'evidència va fallar un control definit	Aplicar apel·lació, restricció o camí alternatiu
Caducat o abandonat	L'intent va finalitzar sense una decisió	Permetre un reinici controlat
Error tècnic	El sistema no va poder produir evidència	Reintentar o reconciliar sense tractar-ho com a frau

Cada estat terminal hauria de tenir raons estructurades. Els codis de màquina estables permeten la política i l'anàlisi; els missatges humans localitzats ajuden els usuaris i els revisors. La RFC 9457 proporciona un format estàndard per a detalls de problemes HTTP llegibles per màquina a nivell d'interfície.

Quina evidència hauria de contenir el resultat?

Evidència a nivell de document

Inclou el tipus d'evidència, el país emissor, la classe de document, la caducitat, la coherència dels camps, la qualitat i els indicadors de validació rellevants per al mètode. Aclariu si el resultat prové d'una inspecció òptica, dades de xip, corroboració de l'emissor o de la base de dades, o una altra font.

Evidència de vinculació del sol·licitant

Mantingueu la comparació facial, la vivacitat, la integritat de la captura i la vinculació d'atributs d'identitat separades. Registreu la referència utilitzada i el llindar o la versió de decisió necessaris per a una interpretació posterior sense exposar material biomètric innecessari a cada consumidor.

Evidència de risc i operativa

Els senyals de dispositiu, IP, velocitat, intent repetit o flux de treball poden guiar l'escalada i la revisió. No haurien de canviar silenciosament els atributs d'identitat. Preserveu quin subsistema va produir cada motiu.

Provinència i versió

Els resultats poden canviar quan els models, les plantilles de documents, les llistes de vigilància o la política canvien. Emmagatzemeu la versió del proveïdor, la versió del flux de treball, el temps de decisió, les referències de la font i si un humà va revisar el cas.

Requisits de seguretat de l'API

Les API d'identitat processen dades personals i biomètriques valuoses i exposen fluxos de negoci que els atacants poden automatitzar. L'OWASP API Security Top 10 destaca els riscos directament rellevants aquí: autorització d'objectes trencada, autenticació trencada, exposició excessiva de propietats, consum de recursos sense restriccions, automatització de fluxos sensibles, inventari d'API deficient i confiança insegura en API de tercers.

Autenticació i autorització

Utilitzeu credencials i aplicacions separades per a proves i producció. Apliqueu el principi de menor privilegi, rotació, revocació, aïllament de l'entorn i autorització a nivell d'objecte. Una organització autenticada no hauria de poder recuperar l'intent d'una altra organització canviant un identificador.

Controls de càrrega i recursos

Valideu el tipus de mitjà, la mida, les dimensions, l'estructura i la font esperada. Establir temps d'espera, límits de concurrència, controls de velocitat i límits d'intent. Les trucades de verificació consumeixen càlcul i poden comportar un cost per comprovació, fent que els punts finals il·limitats siguin un risc de denegació de servei i de cost.

Exposició de dades

Torneu només els camps que necessita un consumidor. Separeu els rols operatius perquè el suport, els analistes, els desenvolupadors i els administradors no rebin per defecte totes les proves d'identitat. Redacteu les càrregues útils sensibles dels registres i les eines d'observabilitat.

Controls de webhook i reproducció

Autentiqueu els esdeveniments, preserveu el cos brut necessari per a la verificació de la signatura, rebutgeu els lliuraments obsolets o mal formats, dedupliqueu els identificadors d'esdeveniments i obteniu l'estat canònic. Rotació de secrets de webhook sense interrompre el lliurament en curs.

Inventari i versionat

Documenteu cada punt final actiu, versió, host, credencial, callback, SDK i data de retirada. Un punt final de prova a l'ombra amb dades de producció o un SDK antic sense manteniment pot soscavar el camí revisat.

Com provar una API de verificació d'identitat

Proves de contracte i estat

Exerciteu cada estat, raó, reintent, temps d'espera i transició terminal documentats. Verifiqueu la paginació, el filtratge, els cossos d'error, la compatibilitat amb versions anteriors i el comportament de camps desconeguts. Simuleu webhooks duplicats i fora d'ordre.

Proves d'evidències

Utilitzeu mostres permeses i representatives dels tipus de documents, països, escriptures, condicions de caducitat, dispositius, càmeres i xarxes de la població esperada. Seguiu per separat les evidències no admeses, il·legibles, no coincidents, manipulades i genuïnes.

Proves de frau

Creeu un conjunt d'atacs autoritzats per a reproduccions, evidències impreses, documents alterats, càmeres virtuals, emuladors, mitjans injectats, identitats repetides i intents automatitzats. Els requisits de prova remota del NIST distingeixen la confiança del sensor de captura, l'anàlisi de mitjans falsificats, els canals protegits i la comparació biomètrica perquè cap mecanisme cobreix el camí complet.

Proves operatives

Mesureu la finalització, els reintents, l'abandonament, la taxa de revisió manual, el temps de resolució, els contactes de suport, el retard del webhook, la reconciliació i la disponibilitat. Desglosseu els resultats per document, dispositiu, xarxa, idioma i grup de clients rellevant.

Proves de qualitat de la decisió

No compareu proveïdors amb un sol número de "precisió". Reviseu els falsos positius i els falsos negatius al llindar previst, els resultats específics d'atac, els recomptes de mostres, la confiança, els casos sense resposta i els resultats confirmats posteriors.

Proves de privadesa i eliminació

Verifiqueu la configuració de retenció, l'exportació, l'eliminació, els registres d'accés, la gestió regional, els controls de subprocessadors i el comportament quan arriba una sol·licitud d'eliminació durant una revisió oberta o una retenció legalment requerida.

Com avaluar els proveïdors

Abast i assegurament

Quines funcions de prova s'inclouen? Quins models d'assegurament i proves independents s'apliquen? Quins components i versions es van provar? Pot el proveïdor explicar què significa i què no significa una aprovació?

Cobertura

Demaneu una matriu de país i document, no només un total. Proveu les evidències que presenten els vostres clients, inclosos dispositius antics, múltiples escriptures, càmeres de baixa qualitat i documents poc comuns però legítims.

Experiència de desenvolupador

Reviseu la coherència de l'API, la qualitat d'OpenAPI, el manteniment de l'SDK, els exemples, els escenaris de sandbox, les eines de webhook, la disciplina del registre de canvis, la política de migració, la pàgina d'estat i l'escalada de suport. Una mostra de cinc línies de "camí feliç" no és una guia d'integració de producció.

Operacions i explicabilitat

Inspeccioneu les cues de revisió, les vistes d'evidències, els permisos de rols, els registres d'auditoria, els codis de motiu, les apel·lacions i les exportacions. Confirmeu que els humans poden distingir les fallades tècniques, els reintents de qualitat, els atacs probables i les discrepàncies d'identitat.

Comercial i portabilitat

Enteneu la facturació basada en l'èxit versus la basada en intents, les tarifes de revisió, els mínims, els límits, l'emmagatzematge, les opcions regionals i els termes de sortida. Mantingueu la vostra referència interna del client i el límit de política portàtils perquè un canvi de proveïdor no requereixi reescriure l'estat del compte.

Errors d'integració comuns

Concedir accés des de l'URL de retorn

L'usuari controla el camí del navegador. Una redirecció d'èxit és un estat d'interfície, no una prova. Confirmeu l'estat final des del backend de confiança.

Tractar cada fallada com a frau

La denegació de permisos, el temps d'espera, les evidències no admeses, la borrositat i la manipulació sospitosa són diferents. Barrejar-les crea falsos rebuigs i anàlisis inutilitzables.

Processar webhooks exactament una vegada

Les xarxes no poden prometre un lliurament exactament una vegada. Dissenyar per a esdeveniments almenys una vegada amb deduplicació, transicions monotòniques i recuperació canònica.

Registrar càrregues útils completes

El registre de depuració convenient pot copiar documents i dades biomètriques en sistemes amb accés més ampli i retenció més llarga. Utilitzeu identificadors, raons estructurades i accés controlat a les evidències.

Provar només el cas d'èxit del sandbox

Les fallades de producció es produeixen en reintents, dispositius antics, documents marginals, retards d'esdeveniments, canvis de versió i revisió. Feu que els escenaris de fallada formin part del conjunt d'acceptació.

Externalitzar la decisió de política

El resultat d'un proveïdor no pot conèixer totes les jurisdiccions, tipus de client, riscos del producte o restriccions comercials. Preserveu la lògica de decisió i la responsabilitat de l'organització.

Una llista de control d'implementació

Abans de la producció, confirmeu que:

• Les credencials de l'API romanen al servidor i estan abastades per entorn i rol;
• les trucades de creació són idempotents i es mapegen a referències internes estables del client;
• els tokens de captura són de curta durada i estan vinculats a l'intent esperat;
• cada estat i raó té una acció explícita del client i del backend;
• les signatures de webhook, la frescor, els duplicats i l'ordre estan provats;
• la recuperació canònica reconcilia els esdeveniments perduts o retardats;
• les sortides a nivell d'evidència romanen separades de la decisió final del client;
• els controls de velocitat, càrrega, concurrència i intent resisteixen l'abús automatitzat;
• les proves de documents, dispositius, frau, privadesa, accessibilitat i revisió utilitzen mostres similars a les de producció;
• la retenció, l'eliminació, la resposta a incidents, el versionat i la migració tenen propietaris.

Ús de Didit per a la verificació d'identitat

Didit proporciona la verificació d'identitat com un mòdul componible i permet als equips afegir la detecció de vivacitat, l'anàlisi de dispositius i IP i camins condicionals a través de l'orquestrador de flux de treball. El preu publicat de la verificació d'identitat autònoma és de 0,15 dòlars, mentre que el paquet KYC publicat de 0,33 dòlars combina la verificació d'identitat, la vivacitat passiva, la concordança facial i l'anàlisi d'IP.

La pàgina de preus enumera les tarifes actuals dels mòduls, i el nivell gratuït és de 500 verificacions gratuïtes al mes. Aquests resultats del producte haurien d'alimentar una política i un estat del client propietat del backend en lloc de substituir-los.

Preguntes freqüents

Què és una API de verificació d'identitat?

És una interfície programàtica per recollir o enviar proves d'identitat i rebre resultats estructurats sobre la validesa de les proves i la vinculació del sol·licitant a una identitat reclamada.

Una API de verificació d'identitat és el mateix que una API de KYC?

No necessàriament. La verificació d'identitat se centra en les proves d'identitat i la vinculació del titular. Una API de KYC també pot incloure el filtratge, el risc del client, els fluxos de treball, la revisió, els registres i l'actualització contínua.

La verificació d'identitat s'hauria d'executar des del frontend?

La interfície de captura es pot executar al frontend, però les credencials permanents, la creació de sessions, la recuperació de resultats finals, les decisions de política i els canvis d'estat del client pertanyen a un backend de confiança.

Per què es necessiten els webhooks?

Moltes comprovacions i revisions són asíncrones. Els webhooks notifiquen a l'aplicació els canvis, mentre que un punt final de recuperació proporciona l'estat canònic per a la reconciliació.

Com s'han de gestionar els webhooks duplicats?

Verifiqueu cada esdeveniment, emmagatzemeu el seu identificador, processeu-lo de manera idempotent, eviteu que els estats antics sobrescriguin els estats terminals més nous i recupereu l'intent canònic quan sigui necessari.

Què hauria d'incloure un sandbox?

Hauria de reproduir el contracte de producció i proporcionar casos deterministes per a l'èxit, el reintent, el rebuig, la revisió, la caducitat, l'error tècnic, els esdeveniments duplicats, els esdeveniments retardats i els codis de motiu rellevants.

Una API pot fer que una empresa sigui compliant?

No. Una API pot subministrar evidències i resultats de flux de treball. L'organització continua sent responsable de l'anàlisi legal, la política, les decisions del client, les excepcions, els registres, la privadesa i els controls continuats.

Referències principals

• NIST SP 800-63A-4: Prova i registre d'identitat
• OWASP API Security Top 10 — 2023
• RFC 9110: Semàntica HTTP
• RFC 9421: Signatures de missatges HTTP
• RFC 9457: Detalls de problemes per a API HTTP

Una integració sòlida de verificació d'identitat fa explícit cada límit de confiança: qui crea l'intent, com es captura l'evidència, quin resultat és canònic, com s'autentiquen els esdeveniments, què significa cada raó i quin sistema és el propietari de la decisió final del client.