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

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

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.