# QI Tech — Risk Solutions › Análise de Documentos

Documentação da QI Tech em texto corrido, para colar em um LLM.
Fonte: https://docs.qitech.com.br
4 página(s).

Índice:
- Enviando um documento (/documentation/caas/document_analysis/document_submission)
- Status HTTP (/documentation/caas/document_analysis/http_status)
- Introdução (/documentation/caas/document_analysis/introduction)
- Webhook (/documentation/caas/document_analysis/webhook)

---

# Enviando um documento

URL: /documentation/caas/document_analysis/document_submission

## **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:

``` bash
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. <br/>- false (síncrono): A API tentará processar o documento e retornar o resultado na mesma requisição. <br/>- 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). |

:::info **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). |

### **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. |
| `DOC00304` | Invalid PDF File | O arquivo fornecido não é um PDF válido ou bem-formado e não pôde ser aberto. |
| `DOC00305` | Password Protected PDF | O PDF enviado está criptografado com uma senha e não pode ser processado. |
| `DOC00306` | Parsing Error | A análise do documento não pôde ser processada. |

# **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`.

---

# Status HTTP

URL: /documentation/caas/document_analysis/http_status

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

Status HTTP | Significado | Descrição
---------- | ------- | ---------------------------------
400 | Bad Request | A requisição enviada possui algum erro de formatação. Na maioria dos casos, retornamos no corpo da mensagem uma explicação de onde está o erro. Nesta API implementamos uma série de códigos de erro específicos para ajudar a entender o que pode estar errado.
401 | Unauthorized | Houve algum problema na autenticação, verifique se a API Key está correta e no header correto, de acordo com a seção Autenticação .
403 | Forbidden | O endpoint acessado é de uso interno e não está disponível para esta API Key.
404 | Not Found | O dado requisitado não foi encontrado usando a chave utilizada. Este status também é retornado quando um endpoint inválido é requisitado.
405 | Method Not Allowed | O método HTTP utilizado (POST, GET, PUT, ...) não se aplica ao endpoint utilizado.
406 | Not Acceptable | Os dados enviados no corpo da requisição são inválidos. Em geral, isso significa que os dados enviados não são um JSON válido.
409 | Conflict | O id do documento enviado corresponde a um id já processado anteriormente. Este status é retornado no caso de requisições duplicadas enviadas ao servidor, ou requisições e dois documentos com o mesmo id.
500 | Internal Server Error | Tivemos um problema para processar esta requisição. Quando este erro acontece nosso time é automaticamente notificado e inicia a análise e solução imediatamente.
503 | Service Unavailable | Você se deparou com uma indisponibilidade, planejada ou não, de infraestrutura dos nossos servidores.

---

# Introdução

URL: /documentation/caas/document_analysis/introduction

Bem vindo à API de Análise de Documentos da QI Tech. Está API foi especialmente feita para analisar documentos complexos que não seguem um formato padrão, como comprovantes de residencia, contratos, notas fiscais, CCBs, boletos e outros.

## **Suporte e Feedback**

Caso encontre qualquer problema técnico ou necessite de assistência, entre em contato com nossa equipe de suporte através do e-mail suporte.caas@qitech.com.br. Estamos comprometidos em fornecer uma resposta em tempo hábil.

## **Adoramos Feedback**

Valorizamos muito o feedback de nossos clientes! Se identificar quaisquer imprecisões, seções pouco claras ou tiver sugestões de melhoria, encorajamos que as compartilhe com nossa equipe. Sua contribuição nos ajuda a aprimorar a experiência de todos os usuários!

## **Ambientes**

A API está disponível em dois ambientes distintos para uso dos clientes. As URLs base para as APIs são as seguintes:

- Produção - `https://api.caas.qitech.app/document_analysis/`
- Sandbox - `https://api.sandbox.caas.qitech.app/document_analysis/`

**Aviso Importante!**

O uso de dados reais de pessoas físicas e/ou jurídicas é estritamente proibido no ambiente de Sandbox da QI Tech.

## **Somente HTTPS**

Por questão de segurança, toda a comunicação com as APIs da QI Tech deve ser realizada utilizando a comunicação HTTPS. Para garantir a conformidade e prevenir a transmissão insegura de dados, o servidor está configurado para aceitar exclusivamente conexões na porta 443 com o protocolo TLS 1.2. Chamadas realizadas utilizando outros protocolos serão automaticamente rejeitadas.

## **Autenticação**

O acesso à API é concedido através do uso de uma Chave de API (API Key). A sua chave de acesso foi ou será enviada para o seu e-mail. Caso ainda não a tenha recebido, por favor, entre em contato com nossa equipe de suporte em suporte.caas@qitech.com.br.

A API espera que a chave seja incluída no cabeçalho (header) `Authorization` de cada requisição enviada ao servidor.

**Exemplo de Requisição:**

```bash
# A flag -H adiciona o cabeçalho de autorização necessário à requisição.
curl "endpoint_da_api_aqui" \
  -H "Authorization: EXAMPLE_API_KEY"
```

:::info **Atenção**

Você deve substituir EXAMPLE-OF-API-KEY com a API Key recebida do suporte.
:::

---

# Webhook

URL: /documentation/caas/document_analysis/webhook

Quando uma análise assíncrona é finalizada, um webhook é enviado com o resultado da análise. Para isso, é necessário configurar um endereço onde vamos notificar as atualizações e também uma *signature_key* que será utilizada para assinar a requisição. Caso ainda não tenha um webhook configurado, fale com a equipe de [suporte](mailto:suporte.caas@qitech.com.br).

## Assinatura

Para garantir que a requisição recebida no endpoint do webhook parte dos nossos servidores, uma assinatura HMAC é enviada junto com o webhook. É possível usar essa assinatura, para verificar que o webhook partiu de nossos servidores.

> Exemplo de cálculo de assinatura em Python
```python
    hmac_obj = hmac.new(signature_key.encode('utf-8'), (endpoint + method + payload).encode('utf-8'), hashlib.sha1)
    return hmac_obj.hexdigest()
```

## Requisição

A requisição possui o formato abaixo e notifica que a análise foi finalizada. A requisição utiliza o método HTTP POST e o corpo da requisição é enviado como texto codificado em UTF-8.

### Webhook de Sucesso

```bash
curl --location 'YOUR-ENDPOINT-HERE' \
--header 'Signature: CALCULATED-HASH-HMAC' \
--data '{"id": "e314ffci-14f3-41a1-ad5d-c9c18782jhfe", "document": {"analysis_result": {...},  "validation_status": "valid"}, "status": "successful", "status_reason": "", "status_description": "Sucessfull Analysis"}'
```

### Webhook de Erro 
```bash
curl --location 'YOUR-ENDPOINT-HERE' \
--header 'Signature: CALCULATED-HASH-HMAC' \
--data '{"id": "e314ffci-14f3-41a1-ad5d-c9c18782jhfe", "status": "bad_request", "status_reason": "missing_information
", "status_description": "The document is missing required information."}'
```