Enviando um documento

Enviando um Documento para uma análise padrão

Para iniciar a análise de um documento, envie uma requisição POST para o endpoint /document utilizando o formato multipart/form-data.

Endpoint: https://api.caas.qitech.app/document_analysis/document

Formato da Requisição

A requisição deve ser enviada como multipart/form-data e incluir campos de dados e um campo de arquivo. Os campos obrigatórios para uma análise são id, document_analysis_type, document_bytes.

Exemplo de requisição:

curl -X POST "https://api.caas.qitech.app/document_analysis/document" \
-H "Authorization: SUA_CHAVE_API" \
-H "Content-Type: multipart/form-data" \
-F "id=solicitacao-abc-12345" \
-F "document_analysis_type=proof_of_address" \
-F "document_bytes=@/caminho/para/seu/comprovante.pdf"

Descrição dos Atributos de Envio

Atributo	Descrição
id (obrigatório)	Um identificador único para a requisição, fornecido por você. Este ID pode ser usado posteriormente para recuperar os resultados da análise.
document_analysis_type (obrigatório)	Uma string que especifica o tipo de análise a ser realizada no documento. Veja a tabela abaixo para os tipos suportados.
document_bytes (obrigatório)	O arquivo do documento a ser analisado. Deve ser enviado como um arquivo no corpo da requisição multipart. Atenção: Não envie este campo como uma string codificada em base64.
async (opcional, default=false)	Um booleano (true ou false) que define o modo de processamento. - false (síncrono): A API tentará processar o documento e retornar o resultado na mesma requisição. - true (assíncrono): A API confirmará o recebimento e processará em segundo plano. O resultado será enviado via webhook para um url configurado previamente (veja mais na sessão sobre webhooks).

Atenção

O campo async deve ser utilizado para indicar uma requisição assíncrona. As requisições síncronas devem ser feitas apenas para documentos pequenos e análises rápidas em que uma resposta imediata é crucial. Caso uma requisição demore mais de 30 segundos ela será automaticamente redirecionada para uma fila, o status de retorno será 202 Accepted e o resultado da análise será enviado para o url de webhook previamente configurado (veja mais na sessão sobre webhooks).

Tipos de Análise Suportadas

O campo document_analysis_type determina qual modelo de extração de dados será aplicado ao seu documento. Abaixo estão os tipos atualmente suportados.

Tipo de Análise	Tipo de Documento	Descrição
company_statute_default	Contrato/Estatuto Social	Realiza a extração e validação básica de contratos sociais. Extrai informações gerais da empresa e dos sócios.
company_statute_credit_assignment	Contrato/Estatuto Social	Realiza a extração avançada de contratos sociais, incluindo a validação de poderes para assinatura de contratos de cessão de crédito.
proof_of_address_default	Comprovantes de Residência (contas de luz, gás, internet, cartas do governo, declarações, entre outros)	Extrai e valida informações de comprovantes de residência, como CEP, endereço completo, nome e data.
invoice	Notas fiscais, DANFEs.	Extrai informações chave de notas fiscais, incluindo detalhes do fornecedor/cliente, totais e itens.
bankslip	Boletos Bancários	Extrai informações de boletos bancários, como o beneficiário, o valor e a data de vencimento.
ccb_default	Cédulas de Crédito Bancárias (CCBs)	Extrai dados de Cédulas de Crédito Bancárias.

Para tipos de análise não listados aqui, entre em contato com nossa equipe de suporte em suporte.caas@qitech.com.br para consultar sobre implementações personalizadas.

Respostas

Resposta de Sucesso (200 OK)

Se o documento em uma análise síncrona for processado com sucesso, a API retornará um status HTTP 200 OK e um objeto JSON contendo os dados extraídos. A estrutura deste objeto JSON irá variar dependendo do document_analysis_type solicitado. Se a requisição tiver um timeout a API retornará um status HTTP 202 Accepted e a requisição será processada de maneira assíncrona. Depois de alguns instantes é possível recuperar a análise do documento usando uma requisição GET, conforme descrito abaixo.

Resposta de Aceito (202 OK)

Se o documento for processado de forma assíncrona, a API retornará um status HTTP 202 Accepted e a requisição será processada de maneira assíncrona. Depois de alguns instantes é possível recuperar a análise do documento usando uma requisição GET, conforme descrito abaixo.

Resposta de Erro (4xx)

Se houver um problema com a requisição ou com o documento, a API retornará um código de status 4xx com um corpo JSON descrevendo o erro.

Referência de Códigos de Erro

As tabelas a seguir listam todos os códigos de erro possíveis retornados pela API. Você pode usar esses códigos para implementar um tratamento de erros robusto em sua aplicação.

Categoria 1: Erros de Requisição (DOC001xx)

Código	Título	Descrição
DOC00100	Missing required field	A requisição não contém um campo obrigatório no corpo multipart/form-data.
DOC00101	Invalid field length	O comprimento de um valor em um campo form-data é inválido.
DOC00102	Invalid content type at request	O cabeçalho Content-Type da requisição não é multipart/form-data.
DOC00103	Invalid field at request	A requisição contém um campo inesperado ou inválido no corpo form-data.

Categoria 2: Erros no Processamento do Arquivo (DOC002xx)

Estes erros ocorrem quando o próprio arquivo enviado possui problemas que impedem seu processamento.

Código	Título	Descrição
DOC00200	Invalid Document Analysis Type	O document_analysis_type não é válido para o documento enviado. (ex: uma análise company_statute_default apartir de uma conta de luz.)
DOC00201	Invalid File Size	O tamanho do documento enviado excede o limite máximo permitido.
DOC00202	Invalid File Type	O arquivo não pôde ser processado devido a inconsistências em seu tipo ou formato (ex: um arquivo .jpg foi enviado com o tipo application/pdf).
DOC00203	PDF exceeds page limit	O arquivo PDF fornecido contém mais páginas do que o limite máximo permitido para processamento (o limite atual é de 200 páginas).
DOC00204	Invalid PDF File	O arquivo fornecido não é um PDF válido ou bem-formado e não pôde ser aberto.
DOC00205	Password Protected PDF	O PDF enviado está criptografado com uma senha e não pode ser processado.

Categoria 3: Erros na Análise do Documento (DOC003xx)

Estes erros ocorrem durante a fase de extração e análise de dados, após o arquivo ter sido aberto com sucesso.

Código	Título	Descrição
DOC00300	Missing Information	O documento não contém informações essenciais necessárias para que a análise seja concluída.
DOC00301	Bad Quality	A qualidade do documento (ex: resolução, legibilidade, nitidez) é muito baixa para ser analisada com precisão.
DOC00302	Invalid Data	O documento contém dados inconsistentes ou inválidos (ex: checksums incorretos, campos contraditórios).
DOC00303	Incorrect Document Type	O conteúdo do documento não corresponde ao tipo de documento esperado para o document_analysis_type selecionado.

Recuperar a Análise de um documento

Você pode recuperar os resultados de uma análise de documento enviada anteriormente a qualquer momento, usando seu id exclusivo.

https://api.caas.qitech.app/document_analysis/document/{document_id}

Substitua document_id pelo mesmo valor que você usou para fazer a requisição POST.