> For the complete documentation index, see [llms.txt](https://docs.caf.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.caf.io/caf-api/caf-api-pt-br/api-core/transaction-details/services/verif-ai-smart-ocr.md). # VerifAI Smart OCR Análise com IA de documentos genéricos brasileiros que combina OCR (extração de texto) com um modelo generativo que classifica o documento, extrai campos estruturados e alimenta regras de validação dedicadas. O serviço foi projetado para documentos que o padrão [OCR de Documentos](/caf-api/caf-api-pt-br/api-core/transaction-details/services/document-ocr.md) não cobre (comprovante de residência, comprovante de renda, contrato social, procuração e documentos arbitrários) e é o único serviço no estilo OCR que expõe regras de validação prontas para uso. **Seção**: `smartOcr` **Arquivos obrigatórios:** qualquer arquivo de documento (`application/pdf`, `image/png`, `image/jpeg`, `image/bmp`, `image/webp`, `image/heic`, `image/heif`). {% hint style="info" %} O Verif AI Smart OCR só é executado quando o [modelo de transação](/caf-api/caf-api-pt-br/api-core/available-resources/transaction.md) o habilita explicitamente. A configuração das classes de documento suportadas, janelas de expiração e termos obrigatórios fica no modelo — o corpo da requisição carrega apenas os **tempo de execução** parâmetros listados abaixo. {% endhint %} ## Parâmetros da requisição Quando o serviço está habilitado, três campos opcionais podem ser passados dentro do `atributos` objeto de `POST /transactions`. Eles são encaminhados às regras de validação do Smart OCR; a extração em si ocorre independentemente desses valores. | Campo | Tipo | Usado por | Descrição | | ------------------------- | -------------------------------------- | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `attributes.holderName` | string | Titular do documento | Nome esperado do titular do documento. Comparado (sem diferenciar maiúsculas/minúsculas, sem diferenciar acentos, correspondência por substring) com o nome do titular extraído do documento (`customerName`, `employeeName`, `taxpayerName`, `shareholderName1`, etc., dependendo da classe do documento). | | `attributes.holderCpf` | string (apenas dígitos, 11 caracteres) | Titular do documento | CPF esperado do titular do documento. Comparado (somente dígitos) com o CPF extraído do documento (`customerPersonalTaxId`, `employeePersonalTaxId`, `taxpayerPersonalTaxId`, `shareholderPersonalTaxId1`). Quando omitido, recorre a `attributes.cpf`. | | `attributes.analysisDate` | string (`YYYY-MM-DD`) | Validade do documento | Data de referência usada para calcular a idade do documento. O padrão é a data da requisição quando omitida. Documentos com data de emissão futura em relação a esse valor são sempre considerados inválidos. | {% hint style="info" %} Todos os três campos são **opcionais**. A regra Titular do Documento precisa de pelo menos um de `holderName` / `holderCpf` (ou `cpf`) para ser informativa — quando nenhum deles é fornecido, a regra não pode ser avaliada e permanece `PENDENTE`. Campos CPF extraídos (por exemplo, `customerPersonalTaxId`) podem incluir caracteres de formatação (pontos e traços); as comparações usam apenas dígitos. Envie `attributes.holderCpf` com **apenas 11 dígitos**, sem pontuação. {% endhint %} **Exemplo de requisição:** ```json { "templateId": "your_template_id", "attributes": { "cpf": "12345678901", "holderName": "Maria Silva Santos", "holderCpf": "12345678901", "analysisDate": "2025-08-15" }, "files": [{ "data": "https://example.com/proof-of-residence.pdf" }] } ``` ### PDFs protegidos por senha Quando um PDF requer senha para ser aberto, envie a senha no campo `filePassword` do mesmo item em `files`. A senha é usada apenas para abrir o arquivo para processamento. | Campo | Tipo | Descrição | | ---------------------- | ------ | ----------------------------------------------------------------------------------------------- | | `files[].filePassword` | string | Senha necessária para abrir o PDF. Opcional; envie-a apenas para arquivos protegidos por senha. | {% hint style="warning" %} `filePassword` só é considerada para arquivos enviados com `"type": "ATTACHMENTS"`. Cada arquivo carrega sua própria senha, portanto uma requisição pode misturar arquivos protegidos e não protegidos. Quando um PDF protegido por senha é enviado sem `filePassword`, ou com uma incorreta, o arquivo não pode ser processado. {% endhint %} **Exemplo de requisição com um PDF protegido por senha:** ```json { "templateId": "your_template_id", "files": [ { "data": "https://example.com/bank-statement.pdf", "type": "ATTACHMENTS", "filePassword": "" } ] } ``` ## Classificação de documentos O Smart OCR classifica o documento enviado em uma das classes suportadas antes de extrair campos estruturados. A classificação combina recursos de texto (OCR) e visuais (o modelo generativo), portanto cada documento é processado apenas com o esquema relevante para sua classe. | Classe | Subclasse | Documentos típicos | | -------------------- | ------------------- | ------------------------------------------------------------------------------------------------------ | | `PROOF_OF_RESIDENCE` | — | Contas de consumo (energia, água, gás), faturas de telecom, extratos bancários, boletos de condomínio. | | `PROOF_OF_INCOME` | — | Holerites/contracheques, cartas de emprego com renda, extratos de benefícios previdenciários. | | `PROOF_OF_INCOME` | `INCOME_TAX_RETURN` | Recibos e declarações de entrega da declaração de imposto de renda (DIRPF / Recibo de Entrega). | | `SOCIAL_CONTRACT` | — | Contratos sociais de empresas, estatutos sociais e alterações consolidadas. | | `POWER_OF_ATTORNEY` | — | Procurações públicas, privadas e digitais. | | `GENERIC` | — | Documentos genéricos que não correspondem às categorias acima (notas fiscais, contratos, declarações). | O resultado da classificação e a subclasse (quando aplicável) são retornados dentro da `smartOcr` seção junto com os campos extraídos, para que os consumidores posteriores possam decidir como interpretar o payload. ## Atributos específicos (PROOF\_OF\_RESIDENCE) {% tabs %} {% tab title="Esquema" %} | Atributo | Tipo | Descrição | | --------------------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | relatedMonth | Inteiro | Mês de referência do comprovante de residência (1-12, sem zero à esquerda). | | relatedYear | Inteiro | Ano de referência do comprovante de residência (4 dígitos). | | issueDate | String | Data de emissão do documento (`DD/MM/AAAA`). | | dueDate | String | Data de vencimento do documento (`DD/MM/AAAA`). | | companyName | String | Nome legal/fantasia da empresa emissora (Razão Social). | | companyBusinessTaxId | String | CNPJ da empresa emissora (mantidos caracteres de formatação e máscara). | | companyAddress | String | Endereço da empresa emissora. | | customerName | String | Nome completo do titular do documento. | | customerPersonalTaxId | String | CPF do titular do documento (mantidos caracteres de formatação e máscara). | | customerBusinessTaxId | String | CNPJ do titular do documento, quando aplicável. | | customerCompleteAddress | String | Endereço completo do titular como impresso no documento. | | customerAddressStreet | String | Componente de rua do endereço do titular. | | customerAddressNumber | String | Componente número do endereço do titular. | | customerAddressNeighborhood | String | Componente bairro do endereço do titular. | | customerAddressCity | String | Componente cidade do endereço do titular. | | customerAddressState | String | Componente estado brasileiro (UF) do endereço do titular. | | customerAddressPostalCode | String | Componente CEP do endereço do titular. | | customerAddressExtraInfo | String | Informações extras/complemento do endereço. | | digitableLine | String | Linha digitável do boleto como impressa no documento, somente dígitos: 47 dígitos para boleto bancário, 48 para boleto de cobrança. Retornada como lida — os valores codificados são derivados do código de barras, não deste campo. | | amount | Ponto flutuante | Valor total a ser pago, como impresso no documento. Presente quando o documento exibe um valor. | | bankCode | String | Código do banco emissor como impresso no cabeçalho do boleto. Presente apenas em boletos bancários. | | barcode | String | Código de barras do boleto, decodificado das barras impressas: 44 dígitos. Presente quando o documento é um boleto e as barras puderam ser lidas. | | barcodeAmount | String | Valor codificado no código de barras, em centavos. Omitido quando o boleto traz um valor de referência em vez de um valor efetivo. | | barcodeAmountFormatted | String | Mesmo valor em notação decimal, sem símbolo de moeda. | | barcodeDueDate | String | Data de vencimento codificada no código de barras (`DD/MM/AAAA`). Apenas boletos bancários — boletos de cobrança não carregam uma data de vencimento no layout. | | barcodeBankCode | String | Código do banco codificado no código de barras. Apenas boletos bancários. | | {% endtab %} | | | {% tab title="Exemplo" %} ```json { "smartOcr": { "documentClass": "PROOF_OF_RESIDENCE", "subClass": null, "relatedMonth": 3, "relatedYear": 2025, "issueDate": "01/03/2025", "dueDate": "10/03/2025", "companyName": "ENEL DISTRIBUIDORA SP", "companyBusinessTaxId": "61.695.227/0001-93", "companyAddress": "AV PRES JUSCELINO KUBITSCHEK, 222 - SP", "customerName": "Maria Silva Santos", "customerPersonalTaxId": "123.456.789-01", "customerBusinessTaxId": "", "customerCompleteAddress": "RUA OSVALDO ARANHA, 123 BAIRRO CENTRO - SP 01310-000", "customerAddressStreet": "RUA OSVALDO ARANHA", "customerAddressNumber": "123", "customerAddressNeighborhood": "CENTRO", "customerAddressCity": "SAO PAULO", "customerAddressState": "SP", "customerAddressPostalCode": "01310000", "customerAddressExtraInfo": "APTO 501", "digitableLine": "836200000013234512340006000000000000000000000000", "amount": 123.45, "barcode": "83620000001234512340000000000000000000000000", "barcodeAmount": "12345", "barcodeAmountFormatted": "123.45" } } ``` {% endtab %} {% tab title="Regras de validação" %} | Regra de validação | Comportamento para `PROOF_OF_RESIDENCE` | | ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Validade do documento | Usa `issueDate` (ou `relatedMonth` + `relatedYear` quando a data de emissão está ausente) comparado a `attributes.analysisDate`. A janela padrão de expiração é de 180 dias; pode ser personalizada no modelo via `documentTypeRules` (`maxDays`, `maxMonths`, `lastMonth`, `lastYear`). | | Titular do documento | Compara `attributes.holderName` com `customerName` (substring, sem diferenciar caixa/acentos) e/ou `attributes.holderCpf` (ou `attributes.cpf`) com `customerPersonalTaxId` (somente dígitos). Pelo menos uma correspondência torna a regra válida. | | Campos obrigatórios | Valida que cada termo configurado no modelo (`requiredTerms`) esteja presente na extração. | | Completude do endereço | Valida cada componente individual (`customerAddressStreet`, `customerAddressNumber`, `customerAddressPostalCode`, `customerAddressNeighborhood`, `customerAddressCity`). Todos os cinco devem estar presentes e não vazios. | | Código de barras existe | Verifica se o código de barras impresso pôde ser decodificado e seu dígito verificador é válido nos 44 dígitos. Um comprovante de residência sem código de barras legível não é aprovado. Exclusivo para esta classe de documento. | | Código de barras corresponde | Verifica o boleto em três etapas: o código de barras é legível, seus 44 dígitos correspondem à linha digitável impressa e os valores codificados correspondem `amount`, `dueDate` e `bankCode`, nos campos selecionados em `fieldsToCompare`. Exclusivo para esta classe de documento. | | {% endtab %} | | | {% endtabs %} | | ## Atributos específicos (PROOF\_OF\_INCOME) {% tabs %} {% tab title="Esquema" %} | Atributo | Tipo | Descrição | | ---------------------------- | --------------- | -------------------------------------------------------------------------------- | | relatedMonth | Inteiro | Mês de referência (1-12). | | relatedYear | Inteiro | Ano de referência (4 dígitos). | | companyName | String | Nome legal/fantasia do empregador (Razão Social). | | companyBusinessTaxId | String | CNPJ do empregador. | | companyCompleteAddress | String | Endereço completo do empregador. | | companyAddressStreet | String | Componente rua do empregador. | | companyAddressNumber | String | Componente número do empregador. | | companyAddressNeighborhood | String | Componente bairro do empregador. | | companyAddressCity | String | Componente cidade do empregador. | | companyAddressState | String | Estado brasileiro (UF) do empregador. | | companyAddressPostalCode | String | CEP do empregador. | | companyAddressExtraInfo | String | Informações extras do endereço do empregador. | | employeeName | String | Nome completo do funcionário. | | employeePersonalTaxId | String | CPF do funcionário. | | employeeCompleteAddress | String | Endereço completo do funcionário. | | employeeRole | String | Cargo/função do funcionário. | | employeeContractType | String | Tipo de contrato (ex. `Prazo indeterminado`, `Temporário`, `Prazo determinado`). | | employeeHireDate | String | Data de admissão (`DD/MM/AAAA`). | | employeeEndDate | String | Data de término do contrato (vazia quando `employmentStatus` está `Aberto`). | | employeeBaseIncome | Ponto flutuante | Valor da renda base (sem `R$`/símbolos). | | employeeGrossIncome | Ponto flutuante | Valor da renda bruta. | | employeeTotalDeductions | Ponto flutuante | Valor total dos descontos. | | employeeNetIncome | Ponto flutuante | Renda líquida (`employeeGrossIncome` - `employeeTotalDeductions`). | | employeeBankNumber | String | Código/número do banco onde o salário é pago. | | employeeBankBranchNumber | String | Número da agência. | | employeeBankAccountNumber | String | Número da conta. | | employeeRetirementIndicative | String | Indicativo de situação de aposentadoria (ex. `Aposentado`, `Pensão`). | | employmentStatus | String | `Aberto` (ativo) ou `Encerrado` (rescindido). | | {% endtab %} | | | {% tab title="Exemplo" %} ```json { "smartOcr": { "documentClass": "PROOF_OF_INCOME", "subClass": null, "relatedMonth": 8, "relatedYear": 2025, "companyName": "EMPRESA EXEMPLO LTDA", "companyBusinessTaxId": "12.345.678/0001-90", "companyCompleteAddress": "AV PAULISTA, 1000 BELA VISTA - SP 01310-100", "companyAddressStreet": "AV PAULISTA", "companyAddressNumber": "1000", "companyAddressNeighborhood": "BELA VISTA", "companyAddressCity": "SAO PAULO", "companyAddressState": "SP", "companyAddressPostalCode": "01310100", "companyAddressExtraInfo": "", "employeeName": "Maria Silva Santos", "employeePersonalTaxId": "123.456.789-01", "employeeCompleteAddress": "RUA DAS FLORES, 50 - SP", "employeeRole": "Analista de Sistemas", "employeeContractType": "Prazo indeterminado", "employeeHireDate": "01/02/2020", "employeeEndDate": "", "employeeBaseIncome": 7500.0, "employeeGrossIncome": 8250.0, "employeeTotalDeductions": 1320.5, "employeeNetIncome": 6929.5, "employeeBankNumber": "341", "employeeBankBranchNumber": "1234-5", "employeeBankAccountNumber": "67890-1", "employeeRetirementIndicative": "", "employmentStatus": "Aberto" } } ``` {% endtab %} {% tab title="Regras de validação" %} | Regra de validação | Comportamento para `PROOF_OF_INCOME` | | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Validade do documento | Usa `relatedMonth` + `relatedYear` (fim do mês de referência) comparado a `attributes.analysisDate`. A janela padrão de expiração é de 180 dias; configurável no modelo. | | Titular do documento | Compara `attributes.holderName` com `employeeName` (substring, sem diferenciar caixa/acentos) e/ou `attributes.holderCpf` (reserva `attributes.cpf`) com `employeePersonalTaxId` (somente dígitos). | | Campos obrigatórios | Valida que cada termo configurado em `requiredTerms` esteja presente. | | Completude do endereço | Valida o **funcionário** endereço (`employeeCompleteAddress`). Quando o endereço do empregado não é extraído, o endereço da empresa é usado e um aviso é adicionado. | | {% endtab %} | | | {% endtabs %} | | ## Atributos específicos (PROOF\_OF\_INCOME · INCOME\_TAX\_RETURN) Quando o documento é classificado como `PROOF_OF_INCOME` com `subClass = INCOME_TAX_RETURN` (Recibo de Entrega da Declaração de Imposto de Renda), um conjunto diferente de campos é extraído. {% tabs %} {% tab title="Esquema" %} | Atributo | Tipo | Descrição | | -------------------------------------- | --------------- | ------------------------------------------------------------------------ | | anoFiscal | Inteiro | Ano fiscal da declaração (ex. `2024`). | | anoCalendario | Inteiro | Ano-calendário da renda informada (ex. `2023`). | | tipoContribuinte | String | Tipo de contribuinte (ex. `Titular`, `Dependente`). | | taxpayerName | String | Nome completo do contribuinte. | | taxpayerPersonalTaxId | String | CPF do contribuinte. | | cnpjDoContribuinte | String | CNPJ do contribuinte quando a declaração pertence a uma pessoa jurídica. | | dataDeNascimentoDoContribuinte | String | Data de nascimento do contribuinte (`DD/MM/AAAA`). | | enderecoCompletoDoContribuinte | String | Endereço completo do contribuinte. | | emailDoContribuinte | String | E-mail do contribuinte, quando presente. | | naturezaDaAtividadeDoContribuinte | String | Natureza da atividade (ex. `Empregado`, `Autônomo`). | | ocupacaoPrincipalDoContribuinte | String | Principal função/ocupação do contribuinte. | | rendaTributavelTotalDoContribuinte | Ponto flutuante | Renda tributável total. | | rendaNaoTributavelTotalDoContribuinte | Ponto flutuante | Renda não tributável total. | | rendaTributavelExclusivaDoContribuinte | Ponto flutuante | Renda tributável exclusiva. | | rendaMensalCalculadaDoContribuinte | Ponto flutuante | Renda mensal média calculada. | | {% endtab %} | | | {% tab title="Exemplo" %} ```json { "smartOcr": { "documentClass": "PROOF_OF_INCOME", "subClass": "INCOME_TAX_RETURN", "fiscalYear": 2024, "calendarYear": 2023, "taxpayerType": "Titular", "taxpayerName": "Maria Silva Santos", "taxpayerPersonalTaxId": "123.456.789-01", "taxpayerBusinessTaxId": "", "taxpayerBirthDate": "12/05/1985", "taxpayerCompleteAddress": "RUA OSVALDO ARANHA, 123 CENTRO - SP 01310-000", "taxpayerEmail": "maria.silva@example.com", "taxpayerRoleNature": "Empregado", "taxpayerMainRole": "Analista de Sistemas", "taxpayerTotalTaxableIncome": 99000.0, "taxpayerTotalNonTaxableIncome": 12000.0, "taxpayerExclusiveTaxableIncome": 1500.0, "taxpayerCalculatedMontlyIncome": 8250.0 } } ``` {% endtab %} {% tab title="Regras de validação" %} | Regra de validação | Comportamento para `INCOME_TAX_RETURN` | | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Validade do documento | Usa o fim de `anoFiscal` (ou `anoCalendario` quando o ano fiscal está ausente) comparado com `attributes.analysisDate`. A janela de expiração padrão é de 365 dias para declarações de imposto de renda; configurável no template. | | Titular do documento | Compara `attributes.holderName` com `taxpayerName` e/ou `attributes.holderCpf` (reserva `attributes.cpf`) com `taxpayerPersonalTaxId`. | | Campos obrigatórios | Valida o configurado `requiredTerms`. | | Completude do endereço | Valida `enderecoCompletoDoContribuinte` como uma única string (não componente por componente). | | {% endtab %} | | | {% endtabs %} | | ## Atributos específicos (SOCIAL\_CONTRACT) {% tabs %} {% tab title="Esquema" %} | Atributo | Tipo | Descrição | | ------------------------------- | ---------------- | ------------------------------------------------------------------------------------------- | | companyName | String | Nome empresarial/fantasia da empresa (Razão Social). | | companyBusinessTaxId | String | CNPJ da matriz. | | cnaeDaEmpresa | Array de strings | Códigos CNAE da atividade principal e descrições ("o objeto da sociedade"). | | tipoDaEmpresa | String | Tipo da empresa (ex. `Sociedade Empresária Limitada`, `Sociedade Simples Limitada`). | | companyCompleteAddress | String | Endereço completo da empresa. | | companyAddressStreet | String | Componente rua da empresa. | | companyAddressNumber | String | Componente número da empresa. | | companyAddressNeighborhood | String | Componente bairro da empresa. | | companyAddressCity | String | Componente cidade da empresa. | | companyAddressState | String | UF da empresa. | | companyAddressPostalCode | String | CEP da empresa. | | companyAddressExtraInfo | String | Informações complementares do endereço da empresa. | | dataDeConstituicaoDaEmpresa | String | Data de constituição da empresa (`DD/MM/AAAA`). | | empresaAtiva | Booleano | `true` quando o documento indica duração indeterminada (sem data de expiração). | | totalDeQuotasDaEmpresa | Inteiro | Quantidade total de quotas. | | moedaDasQuotasDaEmpresa | String | Moeda das quotas (ex. `BRL`). | | valorDaQuotaDaEmpresa | Ponto flutuante | Valor de uma quota. | | nomeDoSocio{N} | String | Nome do sócio N (1, 2, 3...). | | cpfDoSocio{N} | String | CPF do sócio N (quando o sócio é uma pessoa física). | | funcaoDoSocio{N} | String | Função do sócio N (ex. `Sócio Administrador`, `Procurador`, `Representante Legal`). | | poderesDoSocio{N} | Array de strings | Poderes concedidos ao sócio N. | | podeAssinarSozinho{N} | Booleano | `true` somente quando o documento declarar explicitamente que o sócio pode assinar sozinho. | | descricaoDeAssinaturaSozinho{N} | String | Descrição textual da regra de assinatura. | | restricoesDoSocio{N} | Array de strings | Restrições aplicáveis ao sócio N. | | quotasDoSocio{N} | Inteiro | Quotas de propriedade do sócio N. | | cnpjDoSocio{N} | String | CNPJ do sócio N (quando o sócio for uma empresa). | | enderecoDoSocio{N} | String | Endereço do sócio N (quando o sócio for uma empresa). | | dataInicioDoMandatoDoSocio{N} | String | Data de início do mandato (quando o sócio for uma empresa). | | dataFimDoMandatoDoSocio{N} | String | Data de fim do mandato (quando o sócio for uma empresa). | | tipoDeAssinaturaDoSocio{N} | String | `assinatura_digital` ou `assinatura_fisica`. | | assinaturaDoSocioEncontrada{N} | Booleano | `true` quando a assinatura foi encontrada no documento. | | {% endtab %} | | | {% tab title="Exemplo" %} ```json { "smartOcr": { "documentClass": "SOCIAL_CONTRACT", "subClass": null, "companyName": "EMPRESA EXEMPLO LTDA", "companyBusinessTaxId": "12.345.678/0001-90", "companyCnae": [ "62.01-5-01 - Desenvolvimento de programas de computador sob encomenda" ], "companyType": "Sociedade Empresária Limitada", "companyCompleteAddress": "AV PAULISTA, 1000 BELA VISTA - SP 01310-100", "companyAddressStreet": "AV PAULISTA", "companyAddressNumber": "1000", "companyAddressNeighborhood": "BELA VISTA", "companyAddressCity": "SAO PAULO", "companyAddressState": "SP", "companyAddressPostalCode": "01310100", "companyAddressExtraInfo": "", "companyIncorporationDate": "15/01/2018", "companyIsActive": true, "companyQuotasTotal": 100000, "companyQuotasCurrency": "BRL", "companyQuotasValue": 1.0, "shareholderName1": "Maria Silva Santos", "shareholderPersonalTaxId1": "123.456.789-01", "shareholderRole1": "Sócio Administrador", "shareholderPowers1": [ "Abertura e movimentação de contas bancárias", "Assinatura de contratos" ], "shareholderSignAlone1": true, "shareholderSignAloneDescription1": "Assina isoladamente", "shareholderRestrictions1": [], "shareholderQuotas1": 60000, "shareholderBusinessTaxId1": "", "shareholderAddress1": "", "shareholderMandateStartDate1": "", "shareholderMandateEndDate1": "", "shareholderSignatureType1": "digital_signature", "shareholderSignatureMet1": true, "shareholderName2": "João Oliveira", "shareholderPersonalTaxId2": "987.654.321-00", "shareholderRole2": "Sócio", "shareholderQuotas2": 40000, "shareholderSignAlone2": false, "shareholderSignAloneDescription2": "Assina em conjunto com Maria Silva Santos" } } ``` {% endtab %} {% tab title="Regras de validação" %} | Regra de validação | Comportamento para `SOCIAL_CONTRACT` | | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Validade do documento | Usa `dataDeConstituicaoDaEmpresa` comparado com `attributes.analysisDate`. A janela padrão é mais ampla (configurável). Documentos cuja data de constituição está no futuro são sempre inválidos. | | Titular do documento | Compara `attributes.holderName` com `shareholderName1` (e/ou a cada `nomeDoSocio{N}`) e `attributes.holderCpf` (reserva `attributes.cpf`) com `cpfDoSocio{N}`. | | Campos obrigatórios | Valida o configurado `requiredTerms` (uso típico: garantir que os poderes do sócio, as quotas e a data de constituição estejam presentes). | | Completude do endereço | Valida o **sede** endereço (`companyCompleteAddress`). Quando apenas endereços de filiais são extraídos, um aviso informativo é adicionado. | | {% endtab %} | | | {% endtabs %} | | ## Atributos específicos (PROCURAÇÃO) {% tabs %} {% tab title="Esquema" %} | Atributo | Tipo | Descrição | | ---------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------ | | companyName | String | Nome da empresa outorgante (quando aplicável). | | companyBusinessTaxId | String | CNPJ da empresa outorgante. | | companyCompleteAddress | String | Endereço completo da empresa. | | companyAddressStreet | String | Componente rua da empresa. | | companyAddressNumber | String | Componente número da empresa. | | companyAddressNeighborhood | String | Componente bairro da empresa. | | companyAddressCity | String | Componente cidade da empresa. | | companyAddressState | String | UF da empresa. | | companyAddressPostalCode | String | CEP da empresa. | | companyAddressExtraInfo | String | Informações complementares do endereço da empresa. | | nomeDoSocio{N} | String | Nome completo do outorgante. | | cpfDoSocio{N} | String | CPF do outorgante. | | funcaoDoSocio{N} | String | Função do outorgante (ex. `Outorgante`, `Sócio Administrador`). | | poderesDoSocio{N} | Array de strings | Poderes concedidos pelo outorgante N. | | podeAssinarSozinho{N} | Booleano | Se o outorgante N pode assinar sozinho. | | nomeDoOutorgado{N} | String | Nome completo do outorgado. | | outorgadoAssinaSozinho | Booleano | `true` quando o outorgado pode assinar sozinho após a procuração. | | observacaoDeAssinatura | String | Observações sobre a regra de assinatura. | | poderesConcedidos | Array de strings | Lista consolidada dos poderes concedidos na procuração. | | tipo | String | `público`, `privado` ou `inválido`. | | temDataDeExpiração | Booleano | `true` quando a procuração tem data de expiração. | | expirationDate | String | Data de expiração (vazia quando `temDataDeExpiração` está `false`). | | temSelosDeCartório | Booleano | `true` quando ao menos um selo de cartório foi encontrado. | | formaDeAutenticacaoDoSelo{N} | String | Forma de autenticação do selo N (`Assinado digitalmente via GOV.BR`, `Reconhecimento de Firma`, etc.). | | nomeNoSelo{N} | String | Nome no selo N (quando legível). | | seloCartorialValido{N} | Booleano | Se o selo N é considerado válido. | | tipoDoSeloCartorial{N} | String | `assinatura_digital` ou `assinatura_manuscrita`. | | válido | Booleano | Decisão final de validade calculada pelo modelo. | | decisaoTextual | String | Explicação textual de `válido`. | | {% endtab %} | | | {% tab title="Exemplo" %} ```json { "smartOcr": { "documentClass": "POWER_OF_ATTORNEY", "subClass": null, "companyName": "EMPRESA EXEMPLO LTDA", "companyBusinessTaxId": "12.345.678/0001-90", "companyCompleteAddress": "AV PAULISTA, 1000 BELA VISTA - SP 01310-100", "shareholderName1": "Maria Silva Santos", "shareholderPersonalTaxId1": "123.456.789-01", "shareholderRole1": "Outorgante", "shareholderPowers1": ["Abrir contas bancárias", "Assinar contratos"], "shareholderSignAlone1": true, "assigneeName1": "João Oliveira", "assigneeSignsAlone": true, "signObservation": "Outorgante com poderes para assinar isoladamente.", "powersGranted": [ "Abrir contas bancárias", "Movimentar contas bancárias", "Assinar contratos" ], "type": "public", "hasExpirationDate": true, "expirationDate": "31/12/2026", "hasNotaryStamps": true, "notaryStampAuthenticationForm1": "Reconhecimento de Firma", "notaryStampName1": "Maria Silva Santos", "isValidNotaryStamp1": true, "notaryStampType1": "handwritten_signature", "isValid": true, "textualDecision": "Procuração pública com firma reconhecida e poderes claros para movimentação bancária." } } ``` {% endtab %} {% tab title="Regras de validação" %} | Regra de validação | Comportamento para `POWER_OF_ATTORNEY` | | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Validade do documento | Usa `expirationDate` quando `hasExpirationDate = true`; caso contrário, compara `attributes.analysisDate` (ou a data da solicitação, quando omitida) em relação à janela de validade da procuração. Documentos vencidos `expirationDate` são sempre inválidos. | | Titular do documento | Compara `attributes.holderName` com `nomeDoSocio{N}` (outorgantes) e `attributes.holderCpf` (reserva `attributes.cpf`) com `cpfDoSocio{N}`. | | Campos obrigatórios | Valida o configurado `requiredTerms` (uso típico: garantir que poderes como `Abrir conta bancária` estejam explicitamente listados). | | Completude do endereço | Valida `companyCompleteAddress` como uma única string. | | {% endtab %} | | | {% endtabs %} | | ## Atributos específicos (GENERIC) Quando o documento não corresponde a nenhuma das categorias acima, o Smart OCR recorre ao `GENERIC` esquema com campos baseados em função. Os nomes dos campos seguem o padrão `{role}{Property}` (ex. `nomeDoPagador`, `cnpjDoRecebedor`). {% tabs %} {% tab title="Esquema" %} | Atributo | Tipo | Descrição | | ---------------------- | --------------- | ------------------------------------------------- | | issueDate | String | Data de emissão do documento, quando presente. | | dueDate | String | Data de vencimento do documento, quando presente. | | nomeDoPagador | String | Nome completo do pagador/devedor. | | cpfDoPagador | String | CPF do pagador. | | cnpjDoPagador | String | CNPJ do pagador. | | nomeDoRecebedor | String | Nome completo do recebedor/credor. | | cpfDoRecebedor | String | CPF do recebedor. | | cnpjDoRecebedor | String | CNPJ do recebedor. | | companyName | String | Nome da empresa, quando aplicável. | | companyBusinessTaxId | String | CNPJ da empresa, quando aplicável. | | companyAddress | String | Endereço da empresa, quando aplicável. | | companyCompleteAddress | String | Endereço completo da empresa, quando aplicável. | | valorLiquido | Ponto flutuante | Valor monetário líquido, quando presente. | | valorBruto | Ponto flutuante | Valor monetário bruto, quando presente. | | {% endtab %} | | | {% tab title="Exemplo" %} ```json { "smartOcr": { "documentClass": "GENERIC", "subClass": null, "issueDate": "15/08/2025", "dueDate": "26/09/2025", "payerName": "JOÃO DA SILVA", "payerPersonalTaxId": "486.884.452-13", "receiverName": "EMBALAGENS DO SUL LTDA", "receiverBusinessTaxId": "98.765.432/0001-10", "companyName": "EMBALAGENS DO SUL LTDA", "companyBusinessTaxId": "98.765.432/0001-10", "companyAddress": "RUA OSVALDO ARANHA, 123 BAIRRO CENTRO - RS 96800-215", "companyCompleteAddress": "RUA OSVALDO ARANHA, 123 BAIRRO CENTRO - RS 96800-215", "netAmount": 1850.0, "grossAmount": 2000.0 } } ``` {% endtab %} {% tab title="Regras de validação" %} | Regra de validação | Comportamento para `GENERIC` | | ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Validade do documento | Usa `issueDate` (ou `dueDate` como alternativa) comparado com `attributes.analysisDate`. Documentos que não tenham nenhum dos dois não podem ser validados e permanecem `PENDENTE`. | | Titular do documento | Compara `attributes.holderName` com `nomeDoPagador`/`nomeDoRecebedor` e `attributes.holderCpf` (reserva `attributes.cpf`) com `cpfDoPagador`/`cpfDoRecebedor`. | | Campos obrigatórios | Valida o configurado `requiredTerms` (uso típico: garantir que cláusulas contratuais estejam presentes). | | Completude do endereço | Valida `companyCompleteAddress` como uma única string quando presente. | | {% endtab %} | | | {% endtabs %} | | ## Regras de validação O `smart_ocr` as regras abaixo podem ser ativadas no [modelo de transação](/caf-api/caf-api-pt-br/api-core/transaction-details/validation-rules.md). As descrições abaixo documentam o comportamento exposto publicamente; controles de configuração apenas do template (como `documentTypeRules` ou `requiredTerms`) são gerenciados no Trust. | Chave da regra | Título | Parâmetros da requisição | Valores de status | | --------------------------------------------- | ----------------------------------------------------------- | -------------------------------------------------------------------------- | -------------------------------- | | `verifai_smart_ocr_document_validity` | Validade do documento | `attributes.analysisDate` | `VÁLIDO`, `INVÁLIDO`, `PENDENTE` | | `verifai_smart_ocr_document_holder` | Titular do documento | `attributes.holderName`, `attributes.holderCpf` (reserva `attributes.cpf`) | `VÁLIDO`, `INVÁLIDO`, `PENDENTE` | | `verifai_smart_ocr_required_fields` | Campos obrigatórios | — (configurado via `requiredTerms` no template) | `VÁLIDO`, `INVÁLIDO`, `PENDENTE` | | `verifai_smart_ocr_address_completeness` | Completude do endereço | — | `VÁLIDO`, `INVÁLIDO`, `PENDENTE` | | `smart_ocr_proof_of_residence_barcode_exists` | Código de barras no comprovante de residência | — | `VÁLIDO`, `INVÁLIDO`, `PENDENTE` | | `smart_ocr_proof_of_residence_barcode_match` | Comparação do código de barras do comprovante de residência | — (configurado via `fieldsToCompare` no template) | `VÁLIDO`, `INVÁLIDO`, `PENDENTE` | ### Validade do documento (`verifai_smart_ocr_document_validity`) Verifica se o documento foi emitido dentro da janela máxima configurada. A regra usa a data de emissão do documento, a data de vencimento ou o mês/ano de referência (o que estiver disponível para a classe do documento) para calcular quantos dias se passaram em relação à `dataDeAnalise` fornecida na solicitação — ou a data da solicitação quando omitida. A janela padrão é **180 dias** e pode ser personalizada por classe de documento via `documentTypeRules` no template (`maxDays`, `maxMonths`, `lastMonth`, `lastYear`). Documentos cuja data esteja no futuro em relação a `dataDeAnalise` são sempre considerados inválidos. ### Titular do documento (`verifai_smart_ocr_document_holder`) Verifica se o documento pertence ao titular esperado. A regra compara o nome do titular e/ou CPF extraídos do documento com os valores informados em `attributes.holderName` e `attributes.holderCpf`. A comparação de nome não diferencia maiúsculas de minúsculas nem acentos (correspondência por substring); a comparação de CPF usa apenas dígitos. Basta uma das correspondências — a regra é `VÁLIDO` quando pelo menos um dos valores fornecidos corresponde ao campo correspondente no documento. ### Campos obrigatórios (`verifai_smart_ocr_required_fields`) Verifica se os termos listados em `requiredTerms` (configurados por classe de documento no template) estão todos presentes na extração. Um termo é considerado encontrado quando pelo menos um campo extraído tem correspondência de rótulo/metadados e um valor não vazio. ### Completude do endereço (`verifai_smart_ocr_address_completeness`) Verifica se o endereço do documento está completo (logradouro, número, CEP, bairro e cidade). `PROOF_OF_RESIDENCE` valida cada componente individualmente usando os campos dedicados `customerAddress*` , enquanto outras classes de documento validam `companyCompleteAddress` / `enderecoCompletoDoContribuinte` como uma única string. Quando `PROOF_OF_INCOME` ou `SOCIAL_CONTRACT` documentos extraem apenas endereços secundários (endereço do funcionário, endereço da filial), um aviso informativo é adicionado à saída da regra sem alterar seu status. ### Código de barras no comprovante de residência (`smart_ocr_proof_of_residence_barcode_exists`) Verifica se o comprovante de residência é uma fatura, decodificando o código de barras impresso e conferindo o dígito verificador de seus 44 dígitos — o que comprova que a leitura está correta. Um comprovante de residência cujo código de barras não possa ser lido é **não aprovado**. O código de barras é a fonte da verdade e a linha digitável impressa não o substitui. Esta regra se aplica **somente** a documentos classificados como `PROOF_OF_RESIDENCE`. Um documento de qualquer outra classe não é avaliado e a regra permanece `VÁLIDO`. ### Comparação do código de barras do comprovante de residência (`smart_ocr_proof_of_residence_barcode_match`) Verifica a fatura em relação a ela mesma, em três etapas. A verificação para na primeira etapa que falhar, porque depois de uma falha a seguinte já não diz mais nada. | Etapa | Verifica | Uma falha significa | | ----- | -------------------------------------------------------------------------- | --------------------------------------------------------- | | 1 | o código de barras é legível e seu dígito verificador confere | o código de barras não pôde ser lido | | 2 | os 44 dígitos correspondem à linha digitável impressa | o código de barras ou a linha digitável foram adulterados | | 3 | os valores codificados correspondem aos campos lidos no corpo do documento | o código de barras ou o corpo da fatura foi adulterado | A Etapa 3 abrange os campos selecionados em `fieldsToCompare`: | Valor | Compara | | -------------------- | -------------------------------------------------------------------------- | | `VALOR` | o valor codificado no código de barras em relação a `amount` | | `DATA_DE_VENCIMENTO` | a data de vencimento codificada no código de barras em relação a `dueDate` | | `BANCO` | o código do banco codificado no código de barras em relação a `bankCode` | Um campo que o formato da fatura não carrega é ignorado, e os demais campos selecionados continuam sendo comparados: uma fatura de arrecadação — o formato usual em uma conta de serviço público — não carrega nem data de vencimento nem código do banco. Um campo que deveria existir e não foi lido falha na regra, assim como uma divergência. Sem `fieldsToCompare` configurado, a regra permanece `PENDENTE`. Assim como a regra acima, ela se aplica apenas a `PROOF_OF_RESIDENCE`. Para a configuração de quais regras estão habilitadas por template e de como `availableActions` são interpretadas, consulte [Regras de validação](/caf-api/caf-api-pt-br/api-core/transaction-details/validation-rules.md). --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.caf.io/caf-api/caf-api-pt-br/api-core/transaction-details/services/verif-ai-smart-ocr.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.