--- updatedAt: 2026-10-02T12:48:20.000Z agentTools: projectIndex: https://devcenter.certiface.io/llms.txt --- # Integração Bureau Fluxo de integração com o Bureau de Faces da Certiface, que permite validar identidades de forma rápida e segura, combinando biometria facial e análises de risco para prevenir fraudes. # Certiface REST API ## Sumário * [Introdução](#introdução) * [Visão geral](#visão-geral) * [Método Autenticação](#método-autenticação) * [Gerar hash MD5 em Linux](#gerar-hash-md5-em-linux) * [Response](#response) * [Método Certiface](#método-certiface) * [Headers](#headers) * [Body](#body) * [Response](#response-certiface) *** ## Introdução A finalidade da API Certiface/Bureau de Faces é identificar biometricamente o cliente na base do Certiface, informando os dados: **foto, CPF, nome e data de nascimento**. Para isso, é necessário que seja feita a **autenticação do operador** que irá executar a validação e, em seguida, a identificação dele. O Certiface REST API possui os seguintes métodos: 1. Autenticação 2. Certiface *** ## Visão geral Fluxo base para validação biométrica. ![](https://files.readme.io/3019efcd9c54559491b785175d849881b61bb3e59c1a655e5c563bb10ede65df-image.png) *** ## Método Autenticação O objetivo do método é autenticar o usuário do sistema e obter o **token** que será utilizado como chave criptográfica para acessar a chamada biométrica (método Certiface). A resposta retorna em JSON com o token e a data/hora de expiração. **O token expira em 30 minutos.** ## Request **request:** POST **content-Type:** application/x-www-form-urlencoded **body:** ```text login=login senha=md5Password ``` *** ### Parâmetros | Parâmetro | Descrição | | --------- | ------------------------------ | | login | Login do operador do Certiface | | senha | Senha criptografada em MD5 | Por segurança, não utilize encoders MD5 online. *** ## Gerar hash MD5 em Linux ```bash echo -n "suasenha" | md5sum fb8da69afd458b1b3b4dec5194c564d6 ``` [Site de apoio](https://suporte.certiface.com.br/md5-crypt) ## Response **Retorno 200 OK** **content-type:** application/json body: ```json { "token": "WdCFs9ytXJC52RWV5jmynEIKVd0xpKH6JSi7HVeoMz8", "expires": "01/01/2021 11:11:01" } ``` | Parâmetro | Descrição | | --------- | -------------------------------------- | | token | Token para gerar o hash de autorização | | expires | Data de expiração do Token | **Retorno 400** Requisição mal formada ou dados incorretos. **Retorno 401** Não autorizado. **Retorno 403** Sem permissão > **É bom saber!** > O endereço deverá ser utilizado apenas > para o **desenvolvimento** e **homologação** da integração. > Para acessar o ambiente de produção, esse endereço deverá ser substituído por: > *** > **Método Certiface** > O objetivo é validar biometricamente o cliente, podendo ocorrer o cadastro quando o cliente não > estiver na base de dados do Certiface ou se a sua validação estiver nessa base. Além da validação > biométrica, também estão disponíveis (sob demanda) validações em outras bases de dados. > O retorno é composto pelo **status da transação** e o **score de risco** para melhor recomendar se o > cliente será **aprovado, revisado** ou **reprovado** na transação corrente. ## Request **Request:** POST **Content-Type:** multipart/form-data **Authorization:** login; UUTKyf8qcxvvHs6M\_ueOmoEFwYxvXE4DAeULKeoHr3o; **Date:** 01/01/2021 11:01:19 01/01/2021 10:31:51 **Body:** ```text cpf: "00000014141" nome: "nome e sobrenome" nascimento: "01/01/2001" imagem: "/9j/4AAQSkZJRgABAg .....VDc4DGpaKuf/9k=" ``` **Headers** | Parâmetro | Descrição | | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Authorization | Login
Hash de autorização (gerado utilizando SHA256)
Data e hora de expiração (retornado pelo método Autenticação como expires)
**Exemplo:** login;dBCOXryPKKnsHid9d6JZpNP8W0946PL5ymOxypX88NU;01/01/2021
11:01:01 | | Date | Data e Hora da requisição, no formato: dd/MM/yyyy HH:mm:ss | **Atenção especial ao cabeçalho da requisição, header Authorization:** * Este header é composto do **login do usuário, hash de autorização e data/hora de
expiração** (separados pelo caractere ";"). * A data e hora de expiração são retornados pelo método **Autorização.** * O hash de autorização deve ser gerado utilizando o algoritmo **SHA256** a partir do tipo do método (POST) + URL + **data\_e\_hora\_de\_expiração** como texto base e o token criptográfico gerado no método Autorização como chave. **Body:** | Parâmetro | Descrição | | ------------------------- | ------------------------------------------------------------------------------------------------------------- | | cpf | Identificador único do cliente | | nome **(Opcional)** | Nome do cliente (deve conter no mínimo dois nomes, ex: "**Felipe Augusto**") | | nascimento **(Opcional)** | Data de nascimento do cliente, no formato "**dd/mm/yyyy**" | | imagem | Imagem contendo a face do cliente (a imagem pode ser enviada em **base64** ou em formato binário, "**file**") | **Exemplo da chamada do método Certiface:** ```text POST /CertiFaceWS/rs/certiface HTTP/1.1 Host: certiface.com.br Authorization: usuario;5S9wfiTrbvFQfCgSLy7tMN_EUHzAiQAE9ENcMTvX9Y;11/06/2015 18:24:35 Date: 11/06/2015 17:55:13 Cache-Control: no-cache Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW ----WebKitFormBoundary7MA4YWxkTrZu0gW Content-Disposition: form-data; name="imagem" /9j/4AAQSkZJRgABAQEBKwErAAD/2wBDAAMCAgMCAgMDAwMEAwMEBQgFBQQEBQoHBwYID…… ----WebKitFormBoundary7MA4YWxkTrZu0gW Content-Disposition: form-data; name="cpf" 00000014141 ----WebKitFormBoundary7MA4YWxkTrZu0gW Content-Disposition: form-data; name="nome" NOME SOBRENOMES ----WebKitFormBoundary7MA4YWxkTrZu0gW Content-Disposition: form-data; name="nascimento" 01/01/1991 ----WebKitFormBoundary7MA4YWxkTrZu0gW ``` **[Site de Apoio](https://suporte.certiface.com.br/certifaceApoio)** ## Response **Retorno 200 OK** **Exemplo 1:** Transação efetuada com sucesso (codigo = 200) **content-type:** application/json **body:** ```json { "certifaceID": { "protocolo": "209901234567", "codigo": 200, "score": 400 } } ``` **Exemplo 2:** Imagem recusada (codigo = 401) **content-type:** application/json **body:** ```json { "certifaceID": { "protocolo": "209901234567", "codigo": 401, "score": 0 } } ``` **Exemplo 3:** Erro interno (codigo = 501) **content-type:** application/json **body:** ```json { "certifaceID": { "protocolo": "209901234567", "codigo": 501, "score": 0 } } ``` **Detalhamento da resposta: Tabela "certifaceID"** | Parâmetro | Tipo | Descrição | | --------- | -------------- | :-------------------------------------------------------------------------------- | | protocolo | texto | Protocolo de identificação da transação | | codigo | Número inteiro | Código de status. Consulte tabela "certifaceID.codigo" | | score | Número inteiro | Score de risco, de 0 (sem informação), 100 (baixo risco)
a 1000 (alto risco) | **Tabela "certifaceID.codigo"** | Valor | Descrição | | ----- | ---------------------------------------------------------------------------- | | 200 | Transação efetuada com sucesso | | 401 | Erro de imagem recusada (face não encontrada ou erro de qualidade da imagem) | | 501 | Erro interno, falha ao processar transação | **Retorno** **200 OK** - Erros de validação Observação: O formato do JSON de retorno para erros de validação é diferente. **Exemplo 4:** Erro de validação de dados de entrada **content-type:** application/json **body:** ```json { "status": "ERR", "resultado": "ERR", "protocolo": "209901234567", "msg": "INVALID" } ``` **Exemplo 5:** Erro de usuário menor de idade > **NOTA:** Quando o bloqueio por idade estiver habilitado, conforme configuração definida pelo cliente, usuários menores de idade terão a solicitação bloqueada, retornando o erro abaixo. Por padrão, esse tratamento não está habilitado. **content-type:** application/json **body:** ```json { "status": "ERR", "resultado": "BMI", "protocolo": "209901234567", "msg": "USER IS UNDER 13: [12]" } ``` **Tabela "certifaceErro"** | Parâmetro | Tipo | Descrição | | --------- | ----- | :-------------------------------------------------------------------- | | protocolo | texto | Protocolo de identificação da transação | | status | texto | Status da transação, consulte tabela "**certifaceErro.status**" | | resultado | texto | Sigla do resultado, consulte tabela "**certifaceErro.resultados**" | | msg | texto | *Mensagem de detalhamento da transação - pode não ser
retornado* | | similares | lista | Não utilizado neste cenário - pode não ser retornado | **Tabela "certifaceErro.status"** | Parâmetro | Descrição | | --------- | :------------------------- | | ERR | Erro ao realizar transação | | | | **Tabela "certifaceErro.resultados"** | Parâmetro | Descrição | | --------- | :---------------------------------------------------------------------------------------------- | | ERR | Erro no processamento. Consulte
mensagem (quando disponível) para
maiores informações | | BMI | Bloqueio de menor de idade (configurável) | **Retorno 400 BAD REQUEST** Requisição form-data mal formada. **Retorno 401 UNAUTHORIZED** Não autorizado (credencial de acesso não informada, inválida ou expirada).