Envio de imagens para Onboarding (Document)

Os eventos de envio de imagens caracterizam-se por mensagens que comunicam ao destinatário o recebimento e o processamento de imagens para Onboarding.

Para mais informações sobre quando estes eventos são disparados e sobre o seu conteúdo, consulte a documentação Envio de documentos pessoais.

Pré-requisitos

Para receber esses eventos, o parceiro deverá:

Configurar previamente o recebedor de eventos do webhook;
Conhecer a estrutura básica dos eventos que acompanha o objeto data.

Informações sobre os eventos

Contexto e nome do evento

Os campos context e name poderão variar de acordo com a tabela a seguir:

`context`	`name`	Descrição
`Document`	`DOCUMENT_WAS_RECEIVED`	A imagem do documento foi recebida, porém ela pode ainda não ter sido completamente analisada.
`Document`	`DOCUMENT_WAS_PROCESSED`	A imagem do documento foi recebida e analisada.

Fluxo dos eventos

O fluxograma a seguir descreve a sequência em que os eventos ocorrem. Clique na imagem para ampliá-la:

Identificador (`entityId`)

O campo entityId é o identificador da entidade emissora do evento e seu valor depende do contexto de sua emissão.

No contexto de documento, o entityId é o token.

Dados dos eventos

DOCUMENT_WAS_RECEIVED

Esse evento sinaliza que imagem do documento foi recebida, porém ela pode ainda não ter sido completamente analisada.

Descrição do objeto `data` do evento

O objeto data traz detalhes específicos do contexto em que o evento ocorre. Neste caso, o objeto trará os campos de acordo com a tabela:

Nome	Tipo	Descrição
`token`	`string`	Token retornado no envio do documento.
`documentType`	`string`	Tipo de documento, o qual pode ser: “RG”, “CNH”, “SELFIE”, "CRNM", "RNE" ou "DNI".
`documentSide`	`string`	Lado do documento (”FRONT” ou “BACK”). Esse campo não é enviado em caso de selfie.
`status`	`string`	Situação da análise da imagem, a qual pode ser: “ANALYZING”, “PARTIALLY_ANALYZED”, "ANALYSIS_COMPLETED" ou "UNEXPECTED_ERROR".
`analyzedAt`	`string`	Data e hora em que a análise foi realizada, no formato ISO 8601 - UTC.

Payload do evento

O payload abaixo exemplifica a estrutura do evento que deverá ser recebido pelo parceiro. Clique na seta para expandi-lo:

Exemplos de payloads

{
      "entityId": "Wx07Wf3sdqqFat6KKicHs_8_8THcVHfJ",
      "companyKey": "company_key",
      "idempotencyKey": "d3a2e330-b42b-46b7-ae8e-f0942b5271fd",
      "context": "Document",
      "name": "DOCUMENT_WAS_RECEIVED",
      "timestamp": "2022-06-29T15:10:21.0585476+00:00",
      "correlationId": "d3a2e330-b42b-46b7-ae8e-f0942b5271fd",
      "metadata": {
         "customerDocument": "47742663023"
      },
      "data": {
         "token": "sjfdhsjakfgKKGIFGLkjbkjasgdklh",
         "documentType": "RG",
         "documentSide": "FRONT",
         "status": "ANALYZING"
      }
   }

[
   {
      "entityId": "VL2xeaa2TQzmqbaX32FaRvujBQfAqcb_",
      "companyKey": "company_key ",
      "idempotencyKey": "e5a2ae6a-e7fc-446d-983e-fb51338c6310",
      "context": "Document",
      "name": "DOCUMENT_WAS_RECEIVED",
      "timestamp": "2022-06-29T15:10:15.6697797+00:00",
      "correlationId": "e5a2ae6a-e7fc-446d-983e-fb51338c6310",
      "metadata": {
         "customerDocument": "47742663023"
      },
      "data": {
         "token": "VL2xeaa2TQzmqbaX32FaRvujBQfAqcb_",
         "documentType": "RG",
         "documentSide": "BACK",
         "status": "ANALYZING"
      }
   }
]

[
   {
      "entityId": "YR5GMNH.D3HMQKa2SfPjUwwlhx.kypcx",
      "companyKey": "company_key ",
      "idempotencyKey": "5d3b2bb2-dcd1-4398-8c02-8456fb26d65d",
      "context": "Document",
      "name": "DOCUMENT_WAS_RECEIVED",
      "timestamp": "2022-06-29T15:10:18.386868+00:00",
      "correlationId": "5d3b2bb2-dcd1-4398-8c02-8456fb26d65d",
      "metadata": {
         "customerDocument": "47742663023"
      },
      "data": {
         "token": "YR5GMNH.D3HMQKa2SfPjUwwlhx.kypcx",
         "documentType": "CNH",
         "documentSide": "FRONT",
         "status": "ANALYZING"
      }
   }
]

[
   {
      "entityId": "g.Ryjg0PyjLHwisjNCMKgweiABLY0u3w",
      "companyKey": "company_key",
      "idempotencyKey": "0f2c87a2-a65d-4fa8-a110-62f8dbc9398a",
      "context": "Document",
      "name": "DOCUMENT_WAS_RECEIVED",
      "timestamp": "2022-06-29T15:10:17.8142959+00:00",
      "correlationId": "0f2c87a2-a65d-4fa8-a110-62f8dbc9398a",
      "metadata": {
         "customerDocument": "47742663023"
      },
      "data": {
         "token": "g.Ryjg0PyjLHwisjNCMKgweiABLY0u3w",
         "documentType": "CNH",
         "documentSide": "BACK",
         "status": "ANALYZING"
      }
   }
]

[
   {
      "entityId": "xw6qQ7hTO96qOpFV9MGGYh2iIZPhf76V",
      "companyKey": "company_key",
      "idempotencyKey": "67e07769-e18b-448c-926d-a4c477e22e0a",
      "context": "Document",
      "name": "DOCUMENT_WAS_RECEIVED",
      "timestamp": "2022-06-29T15:10:17.0274218+00:00",
      "correlationId": "67e07769-e18b-448c-926d-a4c477e22e0a",
      "metadata": {
         "customerDocument": "47742663023"
      },
      "data": {
         "token": "xw6qQ7hTO96qOpFV9MGGYh2iIZPhf76V",
         "documentType": "SELFIE",
         "status": "ANALYZING"
      }
   }
]

DOCUMENT_WAS_PROCESSED

Esse evento sinaliza que a imagem do documento foi recebida e analisada.

Descrição do objeto `data` do evento

O objeto data traz detalhes específicos do contexto em que o evento ocorre. Neste caso, o objeto trará os campos de acordo com a tabela:

Nome	Tipo	Descrição
`token`	`string`	Token retornado no envio do documento.
`documentType`	`string`	Tipo de documento, o qual pode ser: “RG”, “CNH”, “SELFIE”, "CRNM", "RNE" ou "DNI".
`documentSide`	`string`	Lado do documento (”FRONT” ou “BACK”). Esse campo não é enviado em caso de selfie.
`status`	`string`	Situação da análise da imagem, a qual pode ser: “ANALYZING”, “PARTIALLY_ANALYZED”, "ANALYSIS_COMPLETED" ou "UNEXPECTED_ERROR".
`analyzedAt`	`string`	Data e hora em que a análise foi realizada, no formato ISO 8601 - UTC.

Campos exclusivos para RG (frente)

Nome	Tipo	Descrição
`faceMatch`	`object`	Objeto que contém os dados referentes à comparação da foto da pessoa no documento com a selfie enviada previamente.
`faceMatch.status`	`string`	Resultado da análise que identifica a correspondência entre a face do titular do documento (target) e a da selfie previamente analisada (source). Os possíveis status são: “HAS_FACE_MATCH” (há coincidência entre as faces), “UNMATCHED_DOCUMENT” (a foto do documento não corresponde à imagem da selfie) ou “MANY_FACES_DETECTED” (mais de uma face detectada).
`faceMatch.similarity`	`number`	Percentual de correspondência da selfie com a face do titular do documento.
`faceMatch.confidence`	`number`	Percentual de confiabilidade da análise realizada.
`documentDetails`	`object`	Objeto que contém informações referentes ao documento analisado.
`documentDetails.status`	`string`	Resultado da análise do texto extraído do documento. Essa análise determina se o tipo de documento enviado é o mesmo informado pelo cliente. Os possíveis status são: "DETECTED_DOCUMENT" (documento detectado), "NO_DOCUMENT_FOUND" (documento não encontrado) e "NO_INFO_FOUND" (informações não encontradas).
`documentDetails.federativeUnit`	`string`	Unidade federativa em que o documento foi emitido.
`documentDetails.side`	`string`	Lado do documento, sendo “A” para a frente e “B” para o verso.
`documentDetails.placeOfBirth`	`string`	Local de nascimento do cliente.

Campos exclusivos para RG (verso)

Nome	Tipo	Descrição
`documentDetails`	`object`	Objeto que contém informações referentes ao documento analisado.
`documentDetails.status`	`string`	Resultado da análise do texto extraído do documento. Essa análise determina se o tipo de documento enviado é o mesmo informado pelo cliente. Os possíveis status são: "DETECTED_DOCUMENT" (documento detectado), NO_DOCUMENT_FOUND (documento não encontrado) e NO_INFO_FOUND (informações não encontradas).
`documentDetails.idnumber`	`string`	Número do documento de identidade.
`documentDetails.registerName`	`string`	Nome do cliente como consta no documento.
`documentDetails.issueDate`	`string`	Data em que o documento foi emitido.
`documentDetails.birthDate`	`string`	Data de nascimento do cliente.
`documentDetails.motherName`	`string`	Nome da mãe do cliente como consta no documento.
`documentDetails.side`	`string`	Lado do documento, sendo “A” para a frente e “B” para o verso.

Campos exclusivos para CNH (frente)

Nome	Tipo	Descrição
`faceMatch`	`object`	Objeto que contém os dados referentes à comparação da foto da pessoa no documento com a selfie enviada previamente.
`faceMatch.status`	`string`	Resultado da análise que identifica a correspondência entre a face do titular do documento (target) e a da selfie previamente analisada (source). Os possíveis status são: “HAS_FACE_MATCH” (há coincidência entre as faces), “UNMATCHED_DOCUMENT” (a foto do documento não corresponde à imagem da selfie) ou “MANY_FACES_DETECTED” (mais de uma face detectada).
`faceMatch.similarity`	`number`	Percentual de correspondência da selfie com a face do titular do documento.
`faceMatch.confidence`	`number`	Percentual de confiabilidade da análise realizada.
`documentDetails`	`object`	Objeto que contém informações referentes ao documento analisado.
`documentDetails.status`	`string`	Resultado da análise do texto extraído do documento. Essa análise determina se o tipo de documento enviado é o mesmo informado pelo cliente. Os possíveis status são: "DETECTED_DOCUMENT" (documento detectado), NO_DOCUMENT_FOUND (documento não encontrado) e NO_INFO_FOUND (informações não encontradas).
`documentDetails.idnumber`	`string`	Número do documento.
`documentDetails.cpfNumber`	`string`	Número do documento CPF.
`documentDetails.registerName`	`string`	Nome do cliente como consta no documento.
`documentDetails.driveLicenseCategory`	`string`	Categoria da carteira de motorista, podendo ser “ACC”, “A”, “B” ou “C”.
`documentDetails.driveLicensenumber`		Número da carteira de motorista.
`documentDetails.federativeUnit`	`string`	Unidade federativa em que o documento foi emitido.
`documentDetails.issuedBy`	`string`	Entidade que emitiu o documento.
`documentDetails.issueDate`	`string`	Data de emissão do documento.
`documentDetails.birthDate`	`string`	Data de nascimento do cliente.
`documentDetails.fatherName`	`string`	Nome do pai do cliente como consta no documento.
`documentDetails.motherName`	`string`	Nome da mãe do cliente como consta no documento.
`documentDetails.validate`	`string`	Data de expiração do documento.
`documentDetails.side`	`string`	Lado do documento, sendo “A” para a frente e “B” para o verso.

Campos exclusivos para CNH (verso)

Nome	Tipo	Descrição
`documentDetails`	`object`	Objeto que contém informações referentes ao documento analisado.
`documentDetails.status`	`string`	Resultado da análise do texto extraído do documento. Essa análise determina se o tipo de documento enviado é o mesmo informado pelo cliente. Os possíveis status são: "DETECTED_DOCUMENT" (documento detectado), NO_DOCUMENT_FOUND (documento não encontrado) e NO_INFO_FOUND (informações não encontradas).
`documentDetails.issueDate`		Data de emissão do documento.
`documentDetails.issuedPlace`		Local de emissão do documento.
`documentDetails.side`	`string`	Lado do documento, sendo “A” para a frente e “B” para o verso.

Campos exclusivos para selfie

Nome	Tipo	Descrição
`faceDetails`	`object`	Objeto que contém informações referentes à análise do rosto exibido no documento.
`faceDetails.status`	`string`	Situação da análise das características do rosto da pessoa. Os possíveis status são: “DETECTED_FACE” (face detectada), “MANY_FACES_DETECTED” (mais de uma face detectada) e “COULD_NOT_DETECT_FACE” (não se detectou nenhuma face).
`faceDetails.confidence`	`number`	Percentual de confiabilidade da análise realizada.
`faceDetails.ageRange`	`object`	Objeto que contém informações sobre o intervalo de idade da pessoa de acordo com a imagem analisada.
`faceDetails.ageRange.low`	`number`	Mínima idade possível.
`faceDetails.ageRange.high`	`number`	Máxima idade possível.
`faceDetails.sunglasses`	`object`	Objeto que contém informações da análise que identifica se o cliente está usando óculos de sol.
`faceDetails.sunglasses.value`	`boolean`	Resultado da análise, o qual pode ser “true” ou “false”.
`faceDetails.sunglasses.confidence`	`number`	Percentual de confiabilidade da análise realizada.
`faceDetails.eyesOpen`	`object`	Objeto que contém informações da análise que identifica se o cliente está com os olhos abertos.
`faceDetails.eyesOpen.value`	`boolean`	Resultado da análise, o qual pode ser “true” ou “false”.
`faceDetails.eyesOpen.confidence`	`number`	Percentual de confiabilidade da análise realizada.
`liveness`	`object`	Objeto que contém informações referentes à prova de vida.
`liveness.status`	`string`	Resultado da análise da prova de vida, o qual pode ser: “LIVENESS_FOUND” (prova de vida encontrada) ou “NO_LIVENESS” (prova de vida não encontrada).
`liveness.analysisDetails`	`array of strings`	Esse campo é retornado em caso de reprovação de selfie, contendo uma lista com mensagens que indicam os motivos de recusa da selfie.
`liveness.analysisDetails.messages`	`string`	Mensagem que indica o motivo da recusa da selfie enviada.

🚧
Importante
Recomendamos que o parceiro não desenvolva uma regra de negócio com base nos motivos de recusa de selfie, pois eles podem sofrer alteração.

Payload do evento

O payload abaixo exemplifica a estrutura do evento que deverá ser recebido pelo parceiro. Clique na seta para expandi-lo:

Exemplos de payloads

{
      "entityId": "Wx07Wf3sdqqFat6KKicHs_8_8THcVHfJ",
      "companyKey": "FLORESTA_ED",
      "idempotencyKey": "e02272ae-897b-45bc-917c-749fb56006f4",
      "context": "Document",
      "name": "DOCUMENT_WAS_PROCESSED",
      "timestamp": "2022-06-29T15:10:24.1631484Z",
      "correlationId": "e02272ae-897b-45bc-917c-749fb56006f4",
      "metadata": {
         "customerDocument": "47742663023"
      },
      "data": {
         "token": "Wx07Wf3sdqqFat6KKicHs_8_8THcVHfJ",
         "documentType": "RG",
         "documentSide": "FRONT",
         "status": "ANALYSIS_COMPLETED",
         "analyzedAt": "2022-06-29T15:10:24.1631484Z",
         "faceMatch": {
            "status": "HAS_FACE_MATCH",
            "similarity": 99.9763,
            "confidence": 99.97799
         },
         "documentDetails": {
            "status": "DETECTED_DOCUMENT",
            "federativeUnit": "PARÁ",
            "side": "A",
            "placeOfBirth": "Santarém"
         }
      }
   }

{
      "entityId": "VL2xeaa2TQzmqbaX32FaRvujBQfAqcb_",
      "companyKey": "company_key",
      "idempotencyKey": "c16695e2-3369-4694-b4f7-a657a839fc6c",
      "context": "Document",
      "name": "DOCUMENT_WAS_PROCESSED",
      "timestamp": "2022-06-29T15:10:18.9419179Z",
      "correlationId": "c16695e2-3369-4694-b4f7-a657a839fc6c",
      "metadata": {
         "customerDocument": "47742663023"
      },
      "data": {
         "token": "VL2xeaa2TQzmqbaX32FaRvujBQfAqcb_",
         "documentType": "RG",
         "documentSide": "BACK",
         "status": "ANALYSIS_COMPLETED",
         "analyzedAt": "2022-06-29T15:10:18.9419179Z",
         "documentDetails": {
            "status": "DETECTED_DOCUMENT",
            "idNumber": "47742663023",
            "registerName": "Nísia Floresta",
            "issueDate": "22/09/2014",
            "birthDate": "12/10/1810",
            "motherName": "Dionísia Gonçalves Pinto",
            "side": "B"
         }
      }
   }

{
      "entityId": "YR5GMNH.D3HMQKa2SfPjUwwlhx.kypcx",
      "companyKey": "company_key",
      "idempotencyKey": "3cfbaff6-0a14-4db7-b855-6bf4cd3b59fb",
      "context": "Document",
      "name": "DOCUMENT_WAS_PROCESSED",
      "timestamp": "2022-06-29T15:10:20.9297677Z",
      "correlationId": "3cfbaff6-0a14-4db7-b855-6bf4cd3b59fb",
      "metadata": {
         "customerDocument": "47742663023"
      },
      "data": {
         "token": "YR5GMNH.D3HMQKa2SfPjUwwlhx.kypcx",
         "documentType": "CNH",
         "documentSide": "FRONT",
         "status": "ANALYSIS_COMPLETED",
         "analyzedAt": "2022-06-29T15:10:20.9297677Z",
         "faceMatch": {
            "status": "HAS_FACE_MATCH",
            "similarity": 99.794975,
            "confidence": 99.993004
         },
         "documentDetails": {
            "status": "DETECTED_DOCUMENT",
            "idNumber": "123456789",
            "cpfNumber": "47742663023",
            "registerName": "Nísia Floresta",
            "driveLicenseCategory": "B",
            "driveLicenseNumber": "12345678900",
            "federativeUnit": "PA",
            "issuedBy": "SSP",
            "issueDate": "12/04/2019",
            "birthDate": "12/10/1810",
            "fatherName": "",
            "motherName": "Dionísia Gonçalves Pinto",
            "validDate": "18/01/2024",
            "category": "B",
            "side": "A"
         }
      }
   }

{
      "entityId": "g.Ryjg0PyjLHwisjNCMKgweiABLY0u3w",
      "companyKey": "company_key",
      "idempotencyKey": "5de5b5aa-9502-4d15-a167-90d625566ab2",
      "context": "Document",
      "name": "DOCUMENT_WAS_PROCESSED",
      "timestamp": "2022-06-29T15:10:22.6694109Z",
      "correlationId": "5de5b5aa-9502-4d15-a167-90d625566ab2",
      "metadata": {
         "customerDocument": "47742663023"
      },
      "data": {
         "token": "g.Ryjg0PyjLHwisjNCMKgweiABLY0u3w",
         "documentType": "CNH",
         "documentSide": "BACK",
         "status": "ANALYSIS_COMPLETED",
         "analyzedAt": "2022-06-29T15:10:22.6694109Z",
         "documentDetails": {
            "status": "DETECTED_DOCUMENT",
            "issuePlace": "Santarém, PA",
            "issueDate": "28/09/2020",
            "side": "B"
         }
      }
   }

{
      "entityId": "xw6qQ7hTO96qOpFV9MGGYh2iIZPhf76V",
      "companyKey": "company_key",
      "idempotencyKey": "cbf1e957-6b77-4a64-9f9b-c3c452cb77c6",
      "context": "Document",
      "name": "DOCUMENT_WAS_PROCESSED",
      "timestamp": "2022-06-29T15:10:18.0122463Z",
      "correlationId": "cbf1e957-6b77-4a64-9f9b-c3c452cb77c6",
      "metadata": {
         "customerDocument": "47742663023"
      },
      "data": {
         "token": "xw6qQ7hTO96qOpFV9MGGYh2iIZPhf76V",
         "documentType": "SELFIE",
         "status": "ANALYSIS_COMPLETED",
         "analyzedAt": "2022-06-29T15:10:18.0122463Z",
         "faceDetails": {
            "status": "DETECTED_FACE",
            "confidence": 99.999275,
            "ageRange": {
               "low": 25,
               "high": 35
            },
            "sunglasses": {
               "value": false,
               "confidence": 99.99592
            },
            "eyesOpen": {
               "value": true,
               "confidence": 92.05033
            }
         },
         "liveness": {
            "status": "LIVENESS_FOUND"
         }
      }
   }

{
      "entityId": "xw6qQ7hTO96qOpFV9MGGYh2iIZPhf76V",
      "companyKey": "company_key",
      "idempotencyKey": "cbf1e957-6b77-4a64-9f9b-c3c452cb77c6",
      "context": "Document",
      "name": "DOCUMENT_WAS_PROCESSED",
      "timestamp": "2022-06-29T15:10:18.0122463Z",
      "correlationId": "cbf1e957-6b77-4a64-9f9b-c3c452cb77c6",
      "metadata": {
         "customerDocument": "47742663023"
      },
      "data": {
         "token": "xw6qQ7hTO96qOpFV9MGGYh2iIZPhf76V",
         "documentType": "SELFIE",
         "status": "ANALYSIS_COMPLETED",
         "analyzedAt": "2022-06-29T15:10:18.0122463Z",
         "faceDetails": {
            "status": "MANY_FACES_DETECTED",
            "confidence": 99.999275,
            "ageRange": {
               "low": 25,
               "high": 35
            },
            "sunglasses": {
               "value": false,
               "confidence": 99.99592
            },
            "eyesOpen": {
               "value": true,
               "confidence": 92.05033
            }
         },
         "liveness": {
            "status": "NO_LIVENESS",
            "analysisDetails": [
               {
                  "message": "The face is too far."
               }
            ]
         }
      }
   }

Motivos de recusa da selfie

Mensagem	Descrição
The image is in wrong orientation. Must be portrait.	A imagem está com orientação errada. Ela deve estar em modo retrato.
The image is not enough centralized.	A imagem não está suficientemente centralizada.
The image is too far.	A imagem do rosto está muito distante. Realize a captura da imagem com a câmera um pouco mais próxima do rosto.
The image is too close.	A imagem do rosto está muito próxima, o que compromete a nitidez. Realize a captura da imagem com a câmera um pouco mais distante do rosto.
Could not detect a face. Try another image.	Não foi possível detectar um rosto na imagem. Tente enviar outra imagem.
Traces of image injection detected.	É possível que essa imagem seja proveniente de um upload. Somente serão aceitas fotos capturadas no momento do registro do cliente.

❗
Atenção
Se as imagens não forem aprovadas, não será possível prosseguir com o registro do cliente e nem criar uma conta. Consulte as recomendações contidas na página Orientações para envio de fotos.

Envio de imagens para Onboarding (Document)

Pré-requisitos

Informações sobre os eventos

Contexto e nome do evento

Fluxo dos eventos

Identificador (`entityId`)

Dados dos eventos

DOCUMENT_WAS_RECEIVED

Descrição do objeto `data` do evento

Payload do evento

DOCUMENT_WAS_PROCESSED

Descrição do objeto `data` do evento

🚧
Importante

Payload do evento

❗
Atenção

Pré-requisitos

Informações sobre os eventos

Contexto e nome do evento

Fluxo dos eventos

Identificador (entityId)

Dados dos eventos

DOCUMENT_WAS_RECEIVED

Descrição do objeto data do evento

Payload do evento

DOCUMENT_WAS_PROCESSED

Descrição do objeto data do evento

🚧Importante

Payload do evento

❗Atenção

Identificador (`entityId`)

Descrição do objeto `data` do evento

Descrição do objeto `data` do evento

🚧
Importante

❗
Atenção