Enviando um Documento

Envie um documento utilizando o endpoint /image conforme indicado abaixo. Este endpoint retornará um identificador GUID (Globally Unique Identifier) para o documento, que poderá então ser referenciado nos demais serviços do sistema QI Tech.

Envio

Para enviar um documento, basta realizar via método POST o envio do código base64 da imagem em formato json para o seguinte endereço:

https://api.caas.qitech.app/ocr/image

Request Body

  {
    "document_b64": "\<BASE64_IMAGE\>",
    "template": "cnh",
    "file_type": "jpeg"
  }

Substitua o código base64 de seu documento documento no lugar do placeholder.

Descrição dos Atributos de Envio

Atributo	Descrição
document_b64	Campo obrigatório. Imagem do documento a ser análisado em formato base64.
template	Campo obrigatório. Declara o template que deve ser aplicado para análise da imagem.
file_type	Campo facultativo. Identifica o formato do arquivo enviado, jpeg ou pdf. Caso não seja enviado, o valor jpeg é assumido.

Templates disponíveis

Neste momento, a QI Tech apresenta os seguintes templates disponíveis para análise OCR. Caso o seu documento necessário não esteja incluso nesta lista, envie um e-mail para suporte.caas@qitech.com.br e informe-se dos detalhes quanto a implementação desta feature.

Template	Descrição
cnh	Carteira Nacional de Habilitação brasileira completa.
cnh_front	Carteira Nacional de Habilitação brasileira frente (Lado da foto).
cnh_back	Carteira Nacional de Habilitação brasileira frente (Lado da assinatura).
cnh_digital	PDF da Carteira Nacional de Habilitação brasileira digital.
rg_front	Carteira de Identidade brasileira frente (Lado da foto).
rg_back	Carteira de Identidade brasileira verso (Lado dos dados).
danfe	Documento Auxiliar da Nota Fiscal Eletrônica (NF-e).
proof_of_address	Comprovante de residência.
letter_of_attorney	Procuração que concede poderem com relação a uma empresa.
company_statute	Contrato social ou estatudo de uma empresa.

Imagem

Visando garantir uma maior confiabilidade das análises executadas, é necessário que o cliente siga algumas regras na hora de tirar a foto:

• Remova o documento do plástico;
• Garanta que o documento encontra-se centralizado na foto;
• Garanta que o documento esteja iluminado;
• Garanta que todos os dados do documento estejam nítidos, visíveis e legíveis;
• Garanta que a foto esteja visível e nítida.

Requisitos da Imagem

Para o funcionamento adequado da API, atente-se aos seguintes parâmetros.

• A imagem deve estar em formato JPEG ou PDF;
• A imagem deve possuir, ao menos, 500 pixels de altura e 500 pixels de largura;
• A API não suporta a leitura de documentos escritos à mão;
• O tamanho máximo da imagem varia de acordo com o formato escolhido, seguindo os limites a seguir:

Formato	Tamanho máximo suportado
.JPEG	3MB
.PNG	10MB
.PDF	30MB

Resposta

Caso sua requisição de leitura de documento seja processada com sucesso, será retornado um HTTP status 200 e um objeto JSON com o identificador que aponta para o documento que foi enviada.

Response Body

    {
        "ocr_key": "f1c0d2e1-f950-4360-896d-36588e443fc9"
    }   

Descrição dos Atributos de Resposta

Atributo	Descrição
ocr_key	Chave de identificação da imagem fornecida que pode ser utilizada em qualquer outro serviço do sistema QI Tech.

Recuperação de um documento

Recuperação de imagem

    curl "https://api.caas.qitech.app/ocr/image/f4b5337a-7b50-406e-8c8e-7d0e77b5aa02/file" \
         -H "Authorization: EXAMPLE_API_KEY"

Em qualquer momento é possível recuperar as imagens enviadas. Para isso, basta enviar uma requisição GET adequadamente autenticada no endpoint:

https://api.caas.qitech.app/ocr/image/{image_key}/file

Onde image_key é o valor retornado durante o envio da imagem.

Validação de qualidade da imagem

Response Body: Caso de imagem inválida

    {
        "title": "document_quality",
        "description": "A imagem enviada não pode ser processada com êxito."
    }

Ao realizar um post no endpoint de imagem, caso a imagem não seja suficiente para validação, um HTTP Status Code 400 será retornado, como pode ser visto no exemplo ao lado. O Status Code 400 também é retornado quando o documento não atende aos requisitos de imagem, citados anteriormente.

Atenção - Existem outros motivos pelos quais retornamos 400 (Todos relacionados a dados inválidos). Somente os retornos com o title "document_quality" são resultantes de uma validação de má qualidade da imagem e portanto devem ser repassados ao usuário.

Validação de qualidade do rosto

A validação de qualidade da imagem é aplicada exclusivamente a documentos que contêm rostos, como RG, CNH e passaportes. Quando uma imagem é enviada ao sistema, se ela for identificada como um dos tipos abaixo, uma análise de face é realizada automaticamente:

• national_migration_registry_front
• passport_front
• ctps_front
• regional_nursing_council_registry_front
• regional_nursing_council_registry
• national_registry_of_foreigners_back
• passport
• national_migration_registry
• national_registry_of_foreigners
• cnh_digital
• rg_front
• rg
• cnh_front
• cnh

Durante essa análise, o sistema verifica se há um rosto visível na imagem e avalia aspectos como:

• Iluminação adequada (brilho);
• Presença de acessórios como óculos escuros;
• Proximidade ou distância excessiva do rosto;
• Ausência total de rostos na imagem.

Se algum desses critérios indicar que a imagem não está adequada, será retornado um erro com title: "face_validation" e o respectivo description, conforme detalhado abaixo.

{
    "title": "face_validation",
    "description": "<código_de_erro>"
}

Exemplo de retorno:

Nenhum rosto detectado

{
    "title": "face_validation",
    "description": "no_faces"
}

---

Tabela de tradução de mensagens para exibição ao usuário

Código de erro (description)	Mensagem amigável
close_face	A imagem foi capturada muito próxima do rosto. Reposicione o documento.
distant_face	A imagem foi capturada muito distante do rosto. Reposicione o documento.
wearing_acessories	A pessoa na imagem está usando óculos escuros ou acessórios que cobrem os olhos.
brightness_problem	A imagem está muito escura. Reenvie com mais iluminação.
no_faces	Não foi possível detectar um rosto na imagem. Verifique se o rosto está visível.