Introdução

Este documento tem como objetivo apoiar o cliente a compreender a integração com o produto de Autenticação Biométrica. Nesse documento iremos explicar o Fluxo, a autenticação e os Endpoints da integração. Para utilização destes serviços é necessário realizar a contratação do produto.

Pré requisitos para implementação:

• Possuir uma chave API da Celcoin, essa chave API é enviada após contratar o serviço conosco. link.

• Ter familiaridade com APIs Rest usando o protocolo OAuth 2.0.

• Ter o produto/solução contratada, caso queira usar a funcionalidade em ambiente produtivo, por favor entre em contato com a nossa equipe comercial através do e-mail [email protected]. Para dúvidas técnicas, basta entrar em contato com o suporte através do link.

• Após finalizar a integração, realizar a homologação.

✅

Importante

Sugestões de uso

• Autenticação Transacional: Utilizar a solução em caso de tentativa de transação com valor diferente do costume ou valor maior que o habitual.
• Autenticação de Acesso: Utilizar a solução para autenticar novo acesso dispositivo diferente.
• **Validação de Dispositivos:**Utilizar para validar novo dispositivo.
• Alteração/Atualização de Dados: Utilizar em caso de alteração de dados da conta.
• Contratação de Produto/Serviço: Utilizar no momento de contratar produto/serviço.

Sandbox

No ambiente de sandbox, possuímos o seguinte comportamento: (Em Desenvolvimento Mock)
Utilize o campo DocumentNumber
Final documento terminando em:
• Par - Aprovado.
• Ímpar - Reprovado.

Informações importantes para o processo em produção nasConsiderações finais

Fluxo de integração

Antes de iniciar a integração, defina em quais momentos do seu processo a autenticação biométrica será utilizada. Sempre que for necessário iniciar uma verificação biométrica, faça uma requisição ao nosso endpoint, informando os dados obrigatórios exigidos no payload.
No response da requisição, você receberá uma URL de Webview. Essa URL deve ser disponibilizada ao seu cliente final, que irá acessá-la para realizar a captura da selfie.
Após a captura e análise biométrica, enviaremos a resposta do processo (autenticação aprovada ou reprovada) através do Webhook previamente configurado.

Criar Link para Autenticação

A criação da autenticação deve ser realizada através do endpoints

Link para Autenticação Biométrica

URL Sandbox: https://sandbox.openfinance.celcoin.com.br/onboarding/v1/biometric-auth

Exemplo Request:

form-data

{
		"flow": "BIOMETRIC_LIVENESS", //Tipo de flow ("BIOMETRIC_LIVENESS" ou "BIOMETRIC_DOC_LIVENESS"
    "clientCode": "a7e9ea3f-69e4-4599-92b4-6cb8a79c3512", //código único cliente
    "fullName": "José da Silva", //Nome Completo do usuário que será autenticado
    "documentNumber": "37167700002", // CPF do usuário
    "metadata":  { //Campo aberto para envio de dados adicionais, como finalidade para realizar a autenticação.
    			"type": "TRANSACAO PIX",
   				 "paymentId": "71996290076"
  								}, 
    "expiresIn": "100000", //tempo de expiração do webview em segundos
		"notificationWebview": {
    	"phoneNumber": "11998729212", //Número de telefone para recebimento de webview
    	"notificationsChannel": [ //Canais para recebimento de webview (SMS e/ou WHATSAPP)
      "SMS"
    ]
  },
  "redirectUrlWebview": "https://www.google.com" // Url para redirecionamento
}

Exemplo Response Sucesso:

{
    "body": {
        "biometricAuthId": "786cc58b-aea1-4b24-a3e5-602a5a2ebf02",
        "clientCode": "6521e0ef-fbe8-41af-b400-92a7b4bc6795",
        "documentNumber": "06239629502",
        "urlWebview": "https://cadastro.uat.unico.app/process/1b03cdf4-aed0-422b-8c2c-07bd8f746db1?collect-shield=true&new-loader=off",
        "urlExpirationAt": "2026-04-07T18:20:10.963Z",
        "metadata": {
            "type": "TRANSACAO PIX",
            "paymentId": "71996290076"
        }
    },
    "version": "1.0.0",
    "status": "SUCCESS"
}

Exemplo Response Error:

{
    "error": {
        "errorCode": "OBE034",
        "message": "Formato do JSON esta fora do padrão. Verifique a documentação."
    },
    "version": "1.0.0",
    "status": "ERROR"
}

Consultar Autenticação

É possível consultar as autenticações criadas e seus status utilizando o seguinte endpoint

É possível utilizar os seguintes filtros:
• Data início e data fim (Obrigatório caso não inclua o nº da autenticação)
• Status da autenticação
• DocumentNumber
• ClientCode
• BiometricID

Também é possível consultar os status das Propostas no Painel do Cliente através da opção Consultar Autenticação Biométrica

URL Sandbox: https://sandbox.openfinance.celcoin.com.br/onboarding/v1/biometric-auth

Exemplo Request:

biometric-auth?biometricAuthId=f773bb7f-599b-450b-93d0-0665c6d70581&clientCode=f83f55e8-77fb-4e48-a312-22a6c0f9e89a&status=PENDING &documentNumber=37138444028&dateFrom=2025-07-10T06:30:00&dateTo=2025-07-16T06:30:00

Exemplo Response:

{
    "body": {
        "limit": 1,
        "currentPage": 1,
        "limitPerPage": 200,
        "totalPages": 1,
        "totalItems": 1,
        "biometricAuthentications": [
            {
                "biometricAuthId": "786cc58b-aea1-4b24-a3e5-602a5a2ebf02",
                "clientCode": "6521e0ef-fbe8-41af-b400-92a7b4bc6795",
                "documentNumber": "06239629502",
                "status": "REPROVED",
                "createdAt": "2026-04-07T17:20:11.068Z",
                "updatedAt": "2026-04-07T18:20:16.035Z",
                "metadata": {
                    "type": "TRANSACAO PIX",
                    "paymentId": "71996290076"
                },
                "urlWebview": "https://cadastro.uat.unico.app/process/1b03cdf4-aed0-422b-8c2c-07bd8f746db1?collect-shield=true&new-loader=off",
                "urlExpirationAt": "2026-04-07T15:20:10.963Z"
            }
        ]
    },
    "version": "1.0.0",
    "status": "SUCCESS"
}

Buscar documentos: é possível buscar os documentos associados a uma autenticação biométrica endpoint

É possível utilizar os seguintes filtros:
• ClientCode
• biometricAuthId

Também é possível utilizar ambos os filtros, porém caso um dos parâmetros estejam errados não irá retornar nada.

Observação: As URLs retornadas possuem duração de 15minutos, após a expiração é necessário realizar uma nova chamada.

URL Sandbox: https://sandbox.openfinance.celcoin.com.br/onboarding/v1/biometric-auth

Exemplo Request:

biometric-auth/files?biometricAuthId=38672b6a-2440-4f5f-b3ca-fe9bf8c50017

Exemplo Response:

{
    "body": {
        "files": [
            {
                "type": "CONJUNTO_PROBATORIO",
                "url": "https://onboardingexterno.blob.core.windows.net/onboarding/biometricAuth/SANDBOX/972/06239629502/eefb6983-4f22-4904-8b34-95ad5bb84907/06239629502_eefb6983-4f22-4904-8b34-95ad5bb84907_CONJUNTO_PROBATORIO.pdf?sv=2025-05-05&se=2026-04-08T19%3A31%3A18Z&sr=b&sp=r&sig=96w2k83FssYHYFdWL4itmXQmMN2ZKLlYp82E9novfh4%3D",
                "expirationTime": "2026-04-08T16:31:18Z"
            },
            {
                "type": "SELFIE",
                "url": "https://onboardingexterno.blob.core.windows.net/onboarding/biometricAuth/SANDBOX/972/06239629502/eefb6983-4f22-4904-8b34-95ad5bb84907/06239629502_eefb6983-4f22-4904-8b34-95ad5bb84907_SELFIE.jpeg?sv=2025-05-05&se=2026-04-08T19%3A31%3A18Z&sr=b&sp=r&sig=ZrXJjZc03Ks1JGsblKwLgN0mifDPtn35VhwoRc8Vtn4%3D",
                "expirationTime": "2026-04-08T16:31:18Z"
            }
        ],
        "clientCode": "5af402e5-38ce-46f6-bcfa-94411c5fe489",
        "documentNumber": "06239629502",
        "biometricAuthId": "eefb6983-4f22-4904-8b34-95ad5bb84907"
    },
    "version": "1.0.0",
    "status": "SUCCESS"
}

Cadastrar Webhook

Nesta chamada você realizará a definição das rotas que receberão as notificações relacionados aos fluxos.

Passos para integrar

Realizar autenticação na API - [API Reference]
Cadastrar Webhook - [API Reference]

Disponibilizamos duas opções de autenticação nas notificações, Basic Auth ou OAuth 2.0. A definição será feita através da requisição, conforme os exemplos abaixo:

Utilizando Basic Authentication:

Neste formato o basic auth definido será enviado nas notificações.

cURL da Chamada

curl --location --request POST 'https://sandbox.openfinance.celcoin.dev/common/v1/webhook/subscription' \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--header 'Authorization: Bearer {{access_token}}' \
--data '
{
  "entity": "onboarding-biometric-auth", //Incluir evento que deseja cadastrar webhook
  "context": "ONBOARDING",
  "webhookUrl": "string",
  "auth": {
    "login": "string",
    "pwd": "string",
    "type": "string",
    "urlAuth": "string",
    "requestType": "string",
    "responsePathToken": "string",
    "requestAuth": [
      {
        "key": "string",
        "value": "string",
        "type": "string"
      }
    ]
  }
}

Eventos

Evento: onboarding-biometric-auth

Evento que informa a resposta da autenticação biométrica realizada.

{
  "biometricAuthId": "609f429b-3112-4938-bc6e-72658c89a7b8", //ID único gerado pela Celcoin
  "clientCode": "7affe105-1186-4534-a42d-7bd136b1c32d", //Código único cliente
  "documentNumber": "02147645087", //CPF do usuário autenticado
  "status": "REPROVED", //status
  "metadata": { //Campo aberto para envio de dados adicionais, como finalidade para realizar a autenticação.
    "type": "TRANSACAO PIX",
    "paymentId": "71996290076"
  },
  "webhookId": "b95f1c05-198a-452d-a0cb-7be24ff1924c" //ID do webhook
}

Evento: onboarding-biometric-auth-file

Evento que informa os documentos gerados por aquela autenticação biométrica realizada.

{
  "biometricAuthId": "609f429b-3112-4938-bc6e-72658c89a7b8", //ID único gerado pela Celcoin
  "clientCode": "7affe105-1186-4534-a42d-7bd136b1c32d", //Código único cliente
  "documentNumber": "02147645087", //CPF do usuário autenticado
  "files": [ //documentos
    {
      "type": "CONJUNTO_PROBATORIO", //documento tipo conjunto probatório
      "url": "https://onboardingexterno.blob.core.windows.net/onboarding/02147645087_609f429b-3112-4938-bc6e-72658c89a7b8_CONJUNTO_PROBATORIO?sv=2025-05-05&se=2025-05-27T21%3A15%3A22Z&sr=b&sp=r&sig=dDj5%2BAuu0KD3T5h2%2BwFU0Dah%2B2tFKxRO%2BO7H%2Bn1LBV0%3D", //URL onde está disponível o documento.
      "expirationTime": "2025-05-27T18:15:22Z" //tempo de expiração
    },
    {
      "type": "SELFIE", //documento tipo selfie
      "url": "https://onboardingexterno.blob.core.windows.net/onboarding/02147645087_609f429b-3112-4938-bc6e-72658c89a7b8_SELFIE?sv=2025-05-05&se=2025-05-27T21%3A15%3A22Z&sr=b&sp=r&sig=qY8vzDInSTFPg8WyWRHRRv%2FJv88lLC3Yo8d6fcMJl8o%3D", //URL onde está disponível o documento.
      "expirationTime": "2025-05-27T18:15:22Z" //tempo de expiração
    }
  ],
  "webhookId": "5f851e6f-6ea0-401a-8c48-e9c730968332" //ID do Webhook
}

Integração com o Webview

Esta seção oferecerá suporte à integração do WebView, a jornada que o seu cliente envia os documentos.

Recomendamos a utilização do Webview nos seguintes navegadores: Google Chrome, Mozilla Firefox e Safari.

Android

Para que as integrações para Android funcionem corretamente, é necessário que setDomStorageEnabled esteja definido como true. Exemplo abaixo:

myWebView.getSettings().setDomStorageEnabled(true);

iOS

Para que as integrações para iOS funcionem corretamente, é necessário customizar a configuração para permitir a reprodução de mídia sem solicitação de ação do usuário e para reproduzir a mídia. Exemplo abaixo:

let webView: WKWebView

init() {
    let audioVisualMediaType: WKAudiovisualMediaTypes = []
    let configuration = WKWebViewConfiguration()
    configuration.mediaTypesRequiringUserActionForPlayback = audioVisualMediaType
    configuration.allowsInlineMediaPlayback = true

    webView = WKWebView(frame: .zero, configuration: configuration)
}

Outras plataformas

Em outras plataformas, por exemplo, Flutter e React Native, você deve procurar as configurações do WebView para permitir a reprodução de mídia sem exigir gestos do usuário e para reproduzir o vídeo da câmera inline, não no controlador nativo de tela cheia.

Tabelas para apoio

Regras Campos

Tabela de erros

Customização

📚

Customização

O webview é passível de customização, permitindo alterar a logotipo, cor e formato do botão.

• Envie o logotipo preferencialmente no formato de logo ícone, devido à sua melhor legibilidade em tamanhos reduzidos.

• Certifique-se de que o logotipo seja quadrado, respeite o grid proporcional e garanta que seja exportado com no mínimo 192x192 pixels.

• Formatos aceitos: SVG, PNG e JPEG.

Entre em contato com nosso time para solicitar alteração.

Considerações finais

🚧

Quantidade de autenticação por documentos.

Quantidade de autenticação por documentos
Temos uma validação onde é permitido criar 1 autenticação por documento a cada 1 minuto.
Logo não é possível criar várias autenticações para o mesmo documento no mesmo instante.

Não temos um limitante de aberturas de autenticação, apenas se atente todas as regras e orientações descritas nessa documentação.

❗️

Responsabilidade

A responsabilidade sobre a tomada de decisão com base na resposta da autenticação biométrica é exclusivamente sua. Nossa solução fornece a análise técnica, mas a decisão final sobre aceitar ou recusar determinada operação é de sua responsabilidade.

📘

Resultados

Em produção, o resultado das análises, podem levar até 1 minuto após a conclusão do envio da selfie.

❗️

Testes em produção

Evite realizar testes repetitivos em ambiente de produção. A simulação de cenários negativos, especialmente quando envolve a utilização de um documento vinculado a outra face. Tal ação pode acionar alertas automáticos de fraude e impactar a integridade do sistema.

Recomendamos que todos os testes deste tipo sejam conduzidos em ambientes de sandbox.

👍

Importante

Webhooks

Para cadastrar os webhooks basta acessar a seguinte documentação aqui

Em caso de não receber o webhook é possível realizar uma chamada para receber o reenvio, para mais informações acesse a documentação de reenvio clicando aqui.

ClientCode e Biometric

ClientCode é um identificador único por transação criado por você.
biometricAuthId é um identificador único que geramos após a criação da autenticação, esse identificador será utilizado para realizar consultas.Recomendamos você guardar esses campos.

Consultar Autenticação no Painel do Cliente

É possível consultar os status no Painel do Cliente através da opção Consultar Autenticação Biométrica

Boas Práticas

Evite a criação de "polling" com períodos curtos nos endpoints de consulta, o fluxo de onboarding é todo via webhook orientando sempre as alterações de status e em qual etapa do processo a proposta se encontra.

Não utilize emuladores para realizar a jornada do Webview, caso utilize será bloqueado