Introdução

Bem vindo à API de OCR (Optical Character Recognition) para leitura de documentos da Zaig. Você pode utilizar esta API para enviar uma imagem de um documento a ser reconhecido, como uma Carteira de Habilitação ou Cédula de identidade, e referência-lo através de uma chave nos demais produtos do sistema ZAIG.

Problemas?

Nós não somos uma companhia que se esconde atrás de uma API! Entre em contato com o nosso suporte e nós responderemos o mais rápido possível. Fique à vontade para nos ligar caso deseje uma resposta rápida!

Adoramos Feedback

Mesmo que você já tenha resolvido o seu problema ou que ele seja muito simples (Até mesmo um typo ou uma organização inadequada que você já entendeu), envie-nos um e-mail, assim nós tornamos a documentação cada vez mais prática e a próxima pessoa não vai precisar sofrer as dores que você sofreu!

Ambientes

Possuímos dois ambientes para os nossos clientes. A URL base das APIs são:

• Produção - https://api.caas.qitech.app/ocr/
• Sandbox - https://api.sandbox.caas.qitech.app/ocr/

Somente HTTPS

Por questão de segurança, toda a comunicação com as APIs da Zaig devem ser realizadas utilizando a comunicação HTTPS. Para garantir que, por desatenção ou qualquer outro motivo, não ocorram chamadas HTTP, este servidor somente disponibiliza a porta 443 com comunicação TLS 1.2. Chamadas realizadas utilizando outros protocolos serão automaticamente negadas.

Autenticação

Para autenticar uma chamada, utilize o código seguinte:

# No shell, você somente precisa adicionar o header adequado em cada requisição
curl "api_endpoint_here"
  -H "Authorization: TESTETESTETESTE"

Substitua a API key 'TESTETESTETESTE' com a sua chave adquirida com o nosso suporte.

Utilizamos uma API Key para permitir acesso a nossa API. Ela provavelmente já foi enviada por e-mail para você. Caso ainda não tenha recebido a sua chave, envie um e-mail para suporte.caas@qitech.com.br.

Nossa API espera receber a API Key em todas as requisições ao nosso servidor em um header como o abaixo:

Authorization: TESTETESTETESTE

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 ZAIG.

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

Exemplo de envio

  {
    "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

Templates disponíveis

Neste momento, a ZAIG 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.

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;
• O tamanho máximo da imagem deve ser de 3 MB (Com exceção à DANFE que pode ter até 10MB);
• 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.

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.

Exemplo de retorno

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

Descrição dos Atributos de Resposta

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

Exemplo de retorno em caso de imagem inválida

    {
        "title": "bad_quality",
        "description": "The uploaded image cannot be successfully processed."
    }

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 "bad_quality" são resultantes de uma validação de má qualidade da imagem e portanto devem ser repassados ao usuário.

Status HTTP

Todas as APIs da Zaig utilizam a seguinte padronização nos status HTTP de retorno, de acordo com o RFC 7231: