# 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_default" \
-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 a análise não termine dentro do tempo limite da requisição síncrona, o status de retorno será `202 Accepted` e o resultado deve ser recuperado por uma requisição GET, conforme descrito abaixo . Nesse caso nenhum webhook é enviado: o webhook é exclusivo das análises assíncronas.
:::

## **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** |
| --- | --- | --- |
| `proof_of_address_default` | Comprovantes de residência (contas de luz, gás, internet, cartas do governo, declarações) | Extrai e valida nome, endereço estruturado, endereço bruto, data de emissão e tipo de documento. |
| `company_statute_default` | Contrato ou estatuto social | Extração e validação básica: dados da empresa, capital social, órgão de registro e quadro societário. |
| `company_statute_credit_right_assignment` | Contrato ou estatuto social | Extração avançada com validação de poderes para assinar cessão de direitos creditórios: grupos de assinantes, limites financeiros e necessidade de revisão. |
| `power_of_attorney_default` | Procuração | Extrai outorgantes, outorgados, poderes concedidos, escopo, validade, irrevogabilidade e dados do tabelionato. |
| `invoice_default` | Notas fiscais e DANFEs | Extrai emissor, tomador, tipo e tributação da nota, número, datas, itens e valores. |
| `bankslip_default` | Boletos bancários | Extrai beneficiário, CNPJ do beneficiário, código de barras, valor e data de vencimento. |
| `ccb_default` | Cédulas de Crédito Bancário (CCB) | Extrai número do contrato, dados do emissor, garantias, valor financiado, taxa de juros, parcelas e vencimentos. |
| `portability_retention_evidence_analysis` | Evidências de retenção de portabilidade | Valida a evidência: número do contrato, documento e telefone do emissor, número da portabilidade, presença de assinatura e se é uma confirmação válida. |

Expanda cada tipo abaixo para ver os campos que a análise devolve em `analysis_result`, com o tipo e o significado de cada um. Campos aninhados aparecem com o caminho completo (`address.street`) e listas são marcadas com `[]`.

**proof_of_address_default — campos retornados em `analysis_result`**

| Campo | Tipo | Descrição |
| --- | --- | --- |
| `name` | `string` | Nome completo do titular, conforme extraído do documento |
| `address` | `object` | Endereço residencial estruturado. Informação não encontrada vem como string vazia |
| `address.street` | `string` | Nome da rua |
| `address.number` | `string` | Número do imóvel |
| `address.complement` | `string` | Complemento, como apartamento, sala ou andar, quando houver |
| `address.neighborhood` | `string` | Bairro |
| `address.city` | `string` | Cidade |
| `address.state` | `string` | Estado ou Distrito Federal |
| `address.cep` | `string` | CEP |
| `raw_address` | `string` | Endereço residencial completo, em texto corrido |
| `issue_date` | `string` | Data de emissão do documento no formato AAAA-MM-DD |
| `document_type` | enum: `utility_bill`, `bank_statement`, `address_declaration`, `rental_agreement`, `government_letter` … | Tipo de documento enviado (ex.: 'utility_bill', 'address_declaration') |

**company_statute_default — campos retornados em `analysis_result`**

| Campo | Tipo | Descrição |
| --- | --- | --- |
| `company_name_official` | `string` | Razão social completa da empresa |
| `company_name_trade` | `string` | Nome fantasia |
| `cnpj` | `string` | CNPJ no formato XX.XXX.XXX/XXXX-XX |
| `nire` | `string` | NIRE — Número de Identificação do Registro de Empresas |
| `headquarters_address_full` | `string` | Endereço completo da sede |
| `incorporation_date` | `string` | Data de constituição da empresa |
| `last_consolidated_amendment_date` | `string` | Data da última alteração consolidada |
| `corporate_purpose_summary` | `string` | Objeto social principal |
| `share_capital_value` | `number` | Valor TOTAL do capital social |
| `share_capital_currency` | `string` | Moeda do capital social (ex.: 'BRL') |
| `registration_office_name` | `string` | Nome do órgão de registro (ex.: JUCESP) |
| `registration_office_number` | `string` | Número de registro no órgão competente |
| `registration_office_date` | `string` | Data do registro ou arquivamento no órgão competente |
| `requires_power_of_attorney_check` | `boolean` | Verdadeiro quando os poderes de assinatura não estão claros ou há menção a procuração, indicando necessidade de verificar um documento adicional |
| `partners_data[]` | `object` | Dados de um único sócio extraídos do contrato social |
| `partners_data[].name` | `string` | Nome completo do sócio |
| `partners_data[].cpf` | `string` | CPF do sócio no formato XXX.XXX.XXX-XX |
| `partners_data[].is_administrator` | `boolean` | Verdadeiro quando o sócio é nomeado administrador de forma explícita |
| `partners_data[].role_powers` | `string` | Cargo ou poderes, APENAS quando o sócio é administrador |
| `partners_data[].share_quantity` | `integer` | Quantidade de ações ou quotas detidas pelo sócio |
| `partners_data[].share_value` | `number` | Valor total em BRL das ações ou quotas |
| `partners_data[].participation_percentage` | `number` | Percentual de participação do sócio na empresa |
| `clauses_of_interest` | `object` | Cláusulas de interesse extraídas do documento |
| `clauses_of_interest.administration_clause_summary` | `string` | Resumo da cláusula que define quem representa e assina pela empresa |

**company_statute_credit_right_assignment — campos retornados em `analysis_result`**

| Campo | Tipo | Descrição |
| --- | --- | --- |
| `requires_review` | `boolean` | Indica se o documento é complexo, se inclui muitas cláusulas ou subcláusulas sobre a administração ou se requer outros documentos em conjunto (como atlas de assembleia ou de eleição). |
| `company_data` | `object` | Dados cadastrais e societários completos da entidade analisada. |
| `company_data.company_name_official` | `string` | Nome Oficial Completo da Empresa |
| `company_data.company_name_trade` | `string` | Nome Fantasia |
| `company_data.cnpj` | `string` | CNPJ (CNPJ/MF) no formato XX.XXX.XXX/XXXX-XX |
| `company_data.nire` | `string` | Número de Identificação do Registro de Empresas |
| `company_data.headquarters_address_full` | `string` | Endereço completo da sede |
| `company_data.incorporation_date` | `string` | Data de constituição/formação da empresa |
| `company_data.last_consolidated_amendment_date` | `string` | Data deste contrato social ou alteração |
| `company_data.corporate_purpose_summary` | `string` | Objeto social principal |
| `company_data.share_capital_value` | `number` | Valor TOTAL do Capital Social |
| `company_data.share_capital_currency` | `string` | Moeda do capital social (ex: 'BRL') |
| `company_data.registration_office_name` | `string` | Nome do órgão de registro (ex: JUCESP) |
| `company_data.partners_data[]` | `object` | Modelo que representa os dados de um único sócio extraídos do Contrato Social. |
| `company_data.partners_data[].name` | `string` | Nome completo do sócio |
| `company_data.partners_data[].cpf` | `string` | CPF do sócio no formato XXX.XXX.XXX-XX |
| `company_data.partners_data[].cnpj` | `string` | CNPJ (CNPJ/MF) da empresa sócio (caso sócio seja uma pessoa jurídica) no formato XX.XXX.XXX/XXXX-XX |
| `company_data.partners_data[].is_representative` | `boolean` | Verdadeiro se o sócio pode representar a empresa. |
| `company_data.partners_data[].role_powers` | enum: `president`, `partner`, `administrator`, `director`, `manager` … | Cargo ou poderes. Use 'other' caso se refira a uma empresa, organização ou similar. |
| `company_data.partners_data[].share_quantity` | `integer` | Número de ações/quotas detidas pelo sócio |
| `company_data.partners_data[].share_value` | `number` | Valor total das ações/quotas |
| `company_data.partners_data[].participation_percentage` | `number` | Percentual de participação do sócio na empresa |
| `analyzed_operation` | `string` | O ato ou negócio jurídico específico cuja representação está sendo analisada. |
| `source_documents[]` | `string` | Lista de documentos societários que fundamentam a análise (ex: 'Estatuto Social', 'Ata de Eleição'). |
| `allows_proxies` | `boolean` | Indica se o estatuto da entidade permite a representação por meio de procuradores. |
| `signer_groups[]` | `object` | Define os diferentes grupos e regras de assinatura válidos para a entidade. |
| `signer_groups[].group_id` | `integer` | Um identificador numérico único para o grupo de assinatura. |
| `signer_groups[].description` | `string` | Um resumo claro da regra de negócio que este grupo representa. |
| `signer_groups[].source_clause` | `string` | O texto completo da cláusula ou artigo que estabelece esta regra. |
| `signer_groups[].representation_type` | enum: `Conjunta`, `Individual`, `Conforme Mandato` | Descreve se a representação é feita de forma conjunta ou individual. Caso ambas sejam permitidas, use individual. |
| `signer_groups[].minimum_signers` | `integer` | O número mínimo de membros deste grupo que devem assinar. Se a assinatura for conjunta, esse valor deve ser maior que 1 |
| `signer_groups[].limitations` | `object` | Define as condições e restrições aplicáveis a esta regra de assinatura. |
| `signer_groups[].limitations.financial_limit` | `object` | Define a alçada financeira da regra de forma estruturada. |
| `signer_groups[].limitations.financial_limit.operator` | enum: `MENOR_IGUAL`, `MAIOR_QUE`, `MAIOR`, `MENOR`, `IGUAL` … | O operador de comparação para o limite financeiro. |
| `signer_groups[].limitations.financial_limit.value` | `number` | O valor monetário da alçada. |
| `signer_groups[].limitations.financial_limit.currency` | `string` | O código da moeda do valor (ex: BRL, USD). |
| `signer_groups[].limitations.observations` | `string` | Notas ou comentários adicionais sobre a interpretação ou aplicação da regra. |
| `signer_groups[].members[]` | `object` | Define os cargos que podem compor o grupo de assinatura. |
| `signer_groups[].members[].position` | enum: `president`, `partner`, `administrator`, `director`, `manager` … | Cargo ou poderes. Use 'other' caso se refira a uma empresa, organização ou similar. |
| `signer_groups[].members[].full_name` | `string` | O nome completo do indivíduo que ocupa o cargo, se identificado. |
| `signer_groups[].members[].cpf` | `string` | O CPF do indivíduo (Cadastro de Pessoa Física), se disponível. |
| `signer_groups[].members[].mandate_end_date` | `string` | A data de expiração do mandato (ex: 'AAAA-MM-DD'). |
| `signer_groups[].members[].is_qualified` | `boolean` | Indica se a pessoa que ocupa o cargo está identificada no documento. |
| `signer_groups[].members[].is_required` | `boolean` | Indica se a presença deste membro é obrigatória. |

**power_of_attorney_default — campos retornados em `analysis_result`**

| Campo | Tipo | Descrição |
| --- | --- | --- |
| `grantors[]` | `object` | Lista de outorgantes — ao menos um é obrigatório |
| `grantors[].name` | `string` | Nome completo do outorgante |
| `grantors[].cpf` | `string` | CPF do outorgante no formato XXX.XXX.XXX-XX (pessoa física) |
| `grantors[].cnpj` | `string` | CNPJ do outorgante no formato XX.XXX.XXX/XXXX-XX (pessoa jurídica) |
| `grantees[]` | `object` | Lista de outorgados — ao menos um é obrigatório |
| `grantees[].name` | `string` | Nome completo do outorgado |
| `grantees[].cpf` | `string` | CPF do outorgado no formato XXX.XXX.XXX-XX (pessoa física) |
| `grantees[].cnpj` | `string` | CNPJ do outorgado no formato XX.XXX.XXX/XXXX-XX (pessoa jurídica) |
| `powers_granted` | `string` | Descrição dos poderes concedidos pela procuração |
| `power_scope` | `string` | Escopo ou limitações dos poderes concedidos, quando especificados |
| `expiration_date` | `string` | Data em que os poderes expiram; nulo indica validade indeterminada |
| `is_irrevocable` | `boolean` | Verdadeiro quando a procuração é declarada irrevogável de forma explícita |
| `revocation_clause` | `string` | Texto da cláusula de revogação, quando presente |
| `notary_name` | `string` | Nome do cartório onde o documento foi registrado |
| `notary_registration_number` | `string` | Número de registro ou livro no cartório |
| `notary_date` | `string` | Data do reconhecimento em cartório |
| `document_date` | `string` | Data de assinatura da procuração |
| `purpose` | `string` | Finalidade declarada da procuração (ex.: representar em juízo, movimentar contas bancárias) |

**invoice_default — campos retornados em `analysis_result`**

| Campo | Tipo | Descrição |
| --- | --- | --- |
| `company_name` | `string` | Razão social da empresa |
| `cnpj` | `string` | CNPJ da empresa |
| `invoice_type` | enum: `Documento fiscal eletrônico de serviços`, `Documento fiscal eletrônico de produto` | Tipo de nota fiscal — produto ou serviço |
| `taxation_type` | `string` | Tipo de tributação |
| `invoice_issue_date` | `string` | Data de emissão da nota |
| `invoice_number` | `string` | Número da nota fiscal |
| `contracting_company` | `string` | Empresa contratante |
| `invoice_description` | `string` | Descrição da nota fiscal |
| `invoice_value` | `number` | Valor da nota fiscal |
| `items[]` | `object` | Lista de itens da nota fiscal |
| `items[].code` | `string` | Código do item (NCM/SH) |
| `items[].description` | `string` | Descrição do item |
| `items[].quantity` | `integer` | Quantidade do item |
| `items[].value` | `number` | Valor do item |
| `rps_code` | `string` | Código do RPS — Recibo Provisório de Serviços |
| `access_key` | `string` | Chave de acesso, para notas fiscais de produto |

**bankslip_default — campos retornados em `analysis_result`**

| Campo | Tipo | Descrição |
| --- | --- | --- |
| `beneficiary_cnpj` | `string` | CNPJ do beneficiário |
| `beneficiary_company_name` | `string` | Razão social do beneficiário |
| `boleto_barcode` | `string` | Código de barras do boleto |
| `due_date` | `string` | Data de vencimento |
| `value` | `number` | Valor do boleto |

**ccb_default — campos retornados em `analysis_result`**

| Campo | Tipo | Descrição |
| --- | --- | --- |
| `contract_number` | `string` | Número da CCB |
| `issuer_document` | `string` | CPF ou CNPJ do emitente da CCB |
| `issuer_cep` | `string` | CEP do emitente |
| `guarantee_chassis` | `string` | Chassi do veículo dado em garantia, se aplicável |
| `invoice_total_value` | `number` | Valor total da nota fiscal, se aplicável |
| `annual_interest_rate` | `number` | Taxa de juros anual prefixada, em percentual |
| `financed_amount` | `number` | Valor total financiado na CCB |
| `total_installments` | `integer` | Quantidade total de prestações |
| `first_due_date` | `string` | Vencimento da primeira parcela |
| `last_due_date` | `string` | Vencimento da última parcela (ver a fluxo de pagamento) |
| `has_signature` | `boolean` | Indica se o documento possui assinatura válida (física ou digital) |
| `is_valid_contract` | `boolean` | Indica se o documento enviado é uma cédula de crédito bancária |

**portability_retention_evidence_analysis — campos retornados em `analysis_result`**

| Campo | Tipo | Descrição |
| --- | --- | --- |
| `contract_number` | `string` | Número do contrato |
| `issuer_document_number` | `string` | CPF do tomador de crédito |
| `issuer_phone_number` | `string` | Número de telefone do tomador |
| `portability_number` | `number` | Número da portabilidade |
| `has_signature` | `boolean` | Indica se o documento (especialmente se for uma CCB) contém elementos de assinatura eletrônica, como um hash, código de verificação, QR Code ou uma página de autenticação. |
| `is_valid_evidence` | `boolean` | Indica se o documento é um tipo de evidência aceitável, como uma conversa de texto ou uma Cédula de Crédito Bancário (CCB). |
| `is_confirmation` | `boolean` | Indica se a evidência confirma o cancelamento da portabilidade. Deve ser TRUE se o cliente declarar explicitamente o cancelamento ou não reconhecimento do pedido de portabilidade OU se a evidência for uma CCB com assinatura (has_signature: true). Deve ser FALSE caso não seja uma conversa OU a conversa não indique um cancelamente ou não reconhecimento. As opções aqui devem sempre ser TRUE ou FALSE. |

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.

## **Formatos e Limites do Arquivo**

O campo `document_bytes` aceita os formatos abaixo. O tipo real do arquivo é verificado pelo conteúdo, não pela extensão nem pelo `Content-Type` declarado — enviar um `.jpg` rotulado como `application/pdf` resulta em `DOC00202`.

| Formato | Tamanho máximo | Observações |
| --- | --- | --- |
| PDF | 30 MB | Máximo de 350 páginas (`DOC00203`). PDFs protegidos por senha são rejeitados (`DOC00305`). |
| JPEG | 30 MB | |
| PNG | 10 MB | |

## **Respostas**

### Resposta de Sucesso (`200 OK`)

Em uma análise síncrona concluída com sucesso, a API retorna `HTTP 200 OK` com o corpo abaixo. Os campos do envelope são sempre os mesmos; o que varia por `document_analysis_type` é o conteúdo de `analysis_result`.

```json
{
  "id": "solicitacao-abc-12345",
  "document_analysis_type": "proof_of_address_default",
  "validation_status": "valid",
  "file_metadata": { "file_type": "pdf" },
  "analysis_result": { "...": "campos extraídos, variam por tipo de análise" },
  "feedback_data": null
}
```

| Campo | Descrição |
| --- | --- |
| `id` | O mesmo identificador que você enviou na requisição. |
| `document_analysis_type` | O tipo de análise aplicado. |
| `validation_status` | Resultado da validação. Veja os valores possíveis abaixo. |
| `file_metadata` | Metadados do arquivo recebido, como o tipo detectado. |
| `analysis_result` | Os dados extraídos. Vazio (`{}`) quando a análise não foi concluída. |
| `feedback_data` | Feedback que você tenha registrado para este documento, se houver. |

#### Valores de `validation_status`

| Valor | Significado |
| --- | --- |
| `valid` | Análise concluída com sucesso. |
| `pending` | Ainda em processamento. |
| `missing_information` | O documento não possui informações obrigatórias. |
| `bad_quality` | Qualidade do documento insuficiente para análise. |
| `invalid_data` | O documento contém dados inválidos ou inconsistentes. |
| `incorrect_document_type` | O conteúdo não corresponde ao tipo de análise solicitado. |
| `parsing_error` | O resultado da análise não pôde ser interpretado. |
| `analysis_failed` | A análise não pôde ser concluída pelo modelo. |

### 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 350 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. |

### **Categoria 4: Falhas de Serviço (DOC005xx)**

Estes erros indicam uma falha do nosso lado, não do seu documento nem da sua requisição. São retornados com status HTTP `5xx` e a ação recomendada é **repetir a requisição**.

| Código | Título | Status HTTP | Descrição |
| --- | --- | --- | --- |
| `DOC00500` | Analysis Failed | `503` | Não foi possível concluir a análise. Tente novamente; se o problema persistir, contate o suporte. |

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

# **Registrar feedback de uma análise**

Você pode registrar um retorno sobre a qualidade de uma análise, o que nos ajuda a melhorar os modelos. Envie um POST para o endpoint abaixo usando o mesmo `id` da requisição original.

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

```bash
curl -X POST "https://api.caas.qitech.app/document_analysis/document/solicitacao-abc-12345/feedback" \
-H "Authorization: SUA_CHAVE_API" \
-H "Content-Type: application/json" \
-d '{
  "event_date": "2026-09-02T14:30:00",
  "feedback_data": { "campo_incorreto": "issue_date", "valor_correto": "2026-07-20" }
}'
```

| Atributo | Descrição |
| --- | --- |
| `event_date` (obrigatório) | Data e hora do feedback. |
| `feedback_data` (obrigatório) | Objeto livre com o conteúdo do feedback. |

O feedback registrado passa a ser retornado no campo `feedback_data` ao recuperar a análise. Também é possível consultá-lo com um `GET` no mesmo endpoint.

---

# 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

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 do Webhook

## 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."}'
```

### Motivos de erro

Quando a análise não é concluída com sucesso, o campo `status_reason` indica o motivo:

| status_reason | Descrição |
| --- | --- |
| `missing_information` | O documento não possui informações obrigatórias. |
| `invalid_data` | O documento possui dados inválidos. |
| `bad_quality` | O documento enviado tem qualidade baixa e não pôde ser processado. |
| `parsing_error` | O resultado da análise não pôde ser interpretado como JSON. |
| `analysis_failed` | Falha do nosso lado: não foi possível concluir a análise. A ação recomendada é a sua integração **repetir a requisição**, sem envolver o usuário final — o documento está correto. |

### O campo `status`

O campo `status` classifica o resultado e tem três valores:

| status | Significado |
| --- | --- |
| `successful` | A análise foi concluída. O campo `document` traz o resultado. |
| `bad_request` | O documento enviado não permitiu concluir a análise. Veja `status_reason`. |
| `failed` | Falha nossa, não do documento. A ação recomendada é repetir a requisição. |

Numa análise **síncrona** essa mesma falha aparece como `HTTP 503` com o código `DOC00500`; no fluxo assíncrono ela chega por este webhook, porque não há requisição aberta para responder.