Referência de API
Escolhendo um contrato
A escolha do contrato é uma consequência de onde a captura biométrica acontece — não uma decisão independente. Use a tabela abaixo como guia.
| Contrato | Use quando… | Captura | Fluxo |
|---|---|---|---|
| Web & SDK | A jornada de captura é hospedada pela Unico (Web iFrame, Redirect ou SDK nativo) | Unico controla | O processo é criado antes da captura → usuário passa pela jornada → resultado retorna via callback ou polling |
| API | Sua aplicação controla a captura (com ou sem o SDK da Unico) e envia a imagem diretamente na chamada | Cliente controla | Imagem é enviada junto com a criação do processo → resultado retorna de forma síncrona |
| Magic Link (Mexico) | KYC onboarding no México (INE + selfie + liveness) | Magic Link | Backend cria o link → usuário acessa via WhatsApp / SMS → resultado retorna via webhook |
Contratos coexistentes
Os três contratos são APIs distintas com hosts, autenticação e payloads diferentes. Não existe um único endpoint que atenda aos três casos.
Hosts e ambientes
| Contrato | Host sandbox | Host produção |
|---|---|---|
| Web & SDK | https://api.idcloud.uat.unico.app | https://api.idcloud.unico.app |
| API | https://api.id.uat.unico.app | https://api.id.unico.app |
| Magic Link (Mexico) | https://sandbox.trully.ai | https://api.trully.ai |
| OAuth2 / Token | https://identityhomolog.acesso.io | https://identity.acesso.io |
Detalhes completos em Ambientes.
Autenticação
Todos os contratos Unico (Web & SDK e API) usam Bearer token (JWT) obtido via OAuth2 com urn:ietf:params:oauth:grant-type:jwt-bearer. A integração Magic Link do México usa uma API Key no header x-api-key.
Detalhes completos em Autenticação.
Diferenças de payload entre contratos
A mesma operação conceitual ("criar um processo de verificação de identidade") tem aparência diferente em cada contrato. Use as tabelas abaixo como referência rápida ao migrar entre integrações.
Criação de processo
| Aspecto | Web & SDK | API | Magic Link (Mexico) |
|---|---|---|---|
| Endpoint | POST /client/v1/process | POST /processes/v1 | POST /v2/magic-link |
| Auth | Authorization: Bearer <jwt> | Authorization: Bearer <jwt> + APIKEY | x-api-key: <key> |
| Imagem | Não enviada (capturada pela jornada da Unico) | Enviada como imageBase64 | Não enviada (capturada via Trully) |
| Identificação do usuário | person.duiType + person.duiValue | subject.code (CPF / CURP) | external_id |
| Tipos de documento | CPF, CURP, SSN, NIN, DNI, NIK | Somente CPF, CURP | Somente INE (México) |
| Definição do pipeline | flow (enum, 30+ valores) | Implícito na APIKEY (capacidades) | Implícito (KYC fixo) |
| Callback | callbackUri (redirecionamento do usuário) | Nenhum (síncrono) | metadata.redirect_url |
| Webhook | Webhook v1 (resultado final) | Webhook v1 (opcional) | Webhook v2 (eventos por etapa) |
| Retorna URL da jornada | Sim (userRedirectUrl) | Não | Sim (magic_link_url) |
| Resultado | Assíncrono (polling via GET ou webhook) | Síncrono (na resposta) | Assíncrono (webhook + GET) |
| Token SDK | Sim (token, webAppToken) | Não | Não |
Recuperação do resultado
| Aspecto | Web & SDK | API | Magic Link (Mexico) |
|---|---|---|---|
| Endpoint | GET /client/v1/process/\{id\} | GET /processes/v1/\{id\} (também na resposta de criação) | GET /v2/history/request?magic_link_token={token} |
| Status | state + result (enums com prefixo) | status (1, 3, 5) | status ("ok", etc.) |
| Estrutura do resultado | Aninhada em process.authenticationInfo.{capability}Result. No México, idGov dentro de authenticationInfo. | Plana: unicoId, liveness, government, identityFraudsters, idGov (apenas México) | data.result (específico Trully) |
| Documento | services[].documents[] (RG/CNH com OCR) | Endpoint separado (GET /processes/v1/\{id\}/document) | INE retornado em data |
Próximos passos
- Autenticação — fluxo OAuth2 e geração de JWT
- Ambientes — sandbox vs produção
- Coleção Postman — coleções prontas para uso
- Webhooks e Eventos — entrega assíncrona de resultados
- SDKs e Ferramentas — Web SDK, Android, iOS, Flutter