> 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/core-api/transaction-details/services/verif-ai-smart-ocr.md). # VerifAI Smart OCR Análise com IA de documentos brasileiros genéricos 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/core-api/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 logo de saída. **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 [template da transação](/caf-api/caf-api-pt-br/core-api/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 template — o corpo da requisição carrega apenas os parâmetros de **runtime** listados abaixo. {% endhint %} ## Parâmetros da requisição Quando o serviço está habilitado, três campos opcionais podem ser enviados dentro do objeto `attributes` de `POST /transactions`. Eles são encaminhados para as regras de validação do Smart OCR; a extração em si é executada 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 (apenas 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. Por padrão, usa a data da requisição quando omitida. Documentos com data de emissão no futuro em relação a esse valor são sempre considerados inválidos. | {% hint style="info" %} 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 dos dois é fornecido, a regra não pode ser avaliada e permanece `PENDENTE`. Campos de CPF extraídos (ex. `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" }] } ``` ## Classificação do documento 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 recursos visuais (o modelo generativo), de modo que cada documento é processado apenas com o esquema relevante à 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 comprovantes da declaração de imposto de renda (DIRPF / Recibo de Entrega). | | `SOCIAL_CONTRACT` | — | Contratos sociais, estatutos sociais e alterações consolidadas. | | `POWER_OF_ATTORNEY` | — | Procurações públicas, particulares e digitais (procurações). | | `GENERIC` | — | Documentos genéricos que não se encaixam nas categorias acima (faturas, contratos, declarações). | O resultado da classificação e a subclasse (quando aplicável) são retornados dentro da `smartOcr` seção, juntamente com os campos extraídos, para que os consumidores downstream 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/YYYY`). | | dueDate | String | Data de vencimento do documento (`DD/MM/YYYY`). | | companyName | String | Nome empresarial/fantasia da empresa emissora (Razão Social). | | companyBusinessTaxId | String | CNPJ da empresa emissora (caracteres de formatação e mascaramento preservados). | | companyAddress | String | Endereço da empresa emissora. | | customerName | String | Nome completo do titular do documento. | | customerPersonalTaxId | String | CPF do titular do documento (caracteres de formatação e mascaramento preservados). | | customerBusinessTaxId | String | CNPJ do titular do documento, quando aplicável. | | customerCompleteAddress | String | Endereço completo do titular conforme impresso no documento. | | customerAddressStreet | String | Componente de rua do endereço do titular. | | customerAddressNumber | String | Componente do número do endereço do titular. | | customerAddressNeighborhood | String | Componente de bairro do endereço do titular. | | customerAddressCity | String | Componente de cidade do endereço do titular. | | customerAddressState | String | Componente do estado brasileiro (UF) do endereço do titular. | | customerAddressPostalCode | String | Componente do CEP do endereço do titular. | | customerAddressExtraInfo | String | Informação adicional do endereço / complemento. | | {% 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" } } ``` {% endtab %} {% tab title="Regras de validação" %} | Regra de validação | Comportamento para `PROOF_OF_RESIDENCE` | | ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Validade do Documento | Usos `issueDate` (ou `relatedMonth` + `relatedYear` quando a data de emissão está ausente) comparado com `attributes.analysisDate`. A janela padrão de expiração é de 180 dias; pode ser personalizada no template por meio de `documentTypeRules` (`maxDays`, `maxMonths`, `lastMonth`, `lastYear`). | | Titular do Documento | Compara `attributes.holderName` com `customerName` (substring, sem diferenciar maiúsculas/minúsculas e acentos) e/ou `attributes.holderCpf` (ou `attributes.cpf`) com `customerPersonalTaxId` (apenas dígitos). Pelo menos uma correspondência torna a regra válida. | | Campos Obrigatórios | Valida que cada termo configurado no template (`requiredTerms`) está presente na extração. | | Completude do Endereço | Valida cada componente individual (`customerAddressStreet`, `customerAddressNumber`, `customerAddressPostalCode`, `customerAddressNeighborhood`, `customerAddressCity`). Os cinco devem estar presentes e não vazios. | | {% 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 empresarial/fantasia do empregador (Razão Social). | | companyBusinessTaxId | String | CNPJ do empregador. | | companyCompleteAddress | String | Endereço completo do empregador. | | companyAddressStreet | String | Componente de rua do empregador. | | companyAddressNumber | String | Componente do número do empregador. | | companyAddressNeighborhood | String | Componente de bairro do empregador. | | companyAddressCity | String | Componente de cidade do empregador. | | companyAddressState | String | UF do estado brasileiro do empregador. | | companyAddressPostalCode | String | CEP do empregador. | | companyAddressExtraInfo | String | Informação adicional do endereço do empregador. | | employeeName | String | Nome completo do empregado. | | employeePersonalTaxId | String | CPF do empregado. | | employeeCompleteAddress | String | Endereço completo do empregado. | | employeeRole | String | Cargo/função do empregado. | | employeeContractType | String | Tipo de contrato (ex. `Prazo indeterminado`, `Temporário`, `Prazo determinado`). | | employeeHireDate | String | Data de admissão (`DD/MM/YYYY`). | | employeeEndDate | String | Data de término do contrato (vazio quando `employmentStatus` for `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 em que o salário é pago. | | employeeBankBranchNumber | String | Número da agência/filial. | | employeeBankAccountNumber | String | Número da conta. | | employeeRetirementIndicative | String | Indicativo de situação de aposentadoria (ex. `Aposentado`, `Pensão`). | | employmentStatus | String | `Aberto` (ativo) ou `Encerrado` (encerrado). | | {% 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 | Usos `relatedMonth` + `relatedYear` (fim do mês de referência) comparado com `attributes.analysisDate`. A janela padrão de expiração é de 180 dias; configurável no template. | | Titular do Documento | Compara `attributes.holderName` com `employeeName` (substring, sem diferenciar maiúsculas/minúsculas e acentos) e/ou `attributes.holderCpf` (fallback `attributes.cpf`) com `employeePersonalTaxId` (apenas dígitos). | | Campos Obrigatórios | Valida que cada termo configurado em `requiredTerms` está presente. | | Completude do Endereço | Valida o **empregado** 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 | | ------------------------------ | --------------- | ------------------------------------------------------------------------ | | fiscalYear | Inteiro | Ano fiscal da declaração (ex. `2024`). | | calendarYear | Inteiro | Ano-calendário da renda informada (ex. `2023`). | | taxpayerType | String | Tipo de contribuinte (ex. `Titular`, `Dependente`). | | taxpayerName | String | Nome completo do contribuinte. | | taxpayerPersonalTaxId | String | CPF do contribuinte. | | taxpayerBusinessTaxId | String | CNPJ do contribuinte quando a declaração pertence a uma pessoa jurídica. | | taxpayerBirthDate | String | Data de nascimento do contribuinte (`DD/MM/YYYY`). | | taxpayerCompleteAddress | String | Endereço completo do contribuinte. | | taxpayerEmail | String | E-mail do contribuinte, quando presente. | | taxpayerRoleNature | String | Natureza da função (ex. `Empregado`, `Autônomo`). | | taxpayerMainRole | String | Função/ocupação principal do contribuinte. | | taxpayerTotalTaxableIncome | Ponto flutuante | Renda tributável total. | | taxpayerTotalNonTaxableIncome | Ponto flutuante | Renda total isenta. | | taxpayerExclusiveTaxableIncome | Ponto flutuante | Renda tributável exclusiva. | | taxpayerCalculatedMontlyIncome | Ponto flutuante | Renda média mensal 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 `fiscalYear` (ou `calendarYear` quando o exercício fiscal está ausente) comparado com `attributes.analysisDate`. A janela de expiração padrão é de 365 dias para declarações de imposto; configurável no template. | | Titular do Documento | Compara `attributes.holderName` com `taxpayerName` e/ou `attributes.holderCpf` (fallback `attributes.cpf`) com `taxpayerPersonalTaxId`. | | Campos Obrigatórios | Valida os configurados `requiredTerms`. | | Completude do Endereço | Valida `taxpayerCompleteAddress` 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 empresa-mãe. | | companyCnae | Array de String | Códigos CNAE e descrições da atividade principal ("o objeto da sociedade"). | | companyType | 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ção complementar do endereço da empresa. | | companyIncorporationDate | String | Data de constituição da empresa (`DD/MM/YYYY`). | | companyIsActive | Booleano | `true` quando o documento indica duração indeterminada (sem data de expiração). | | companyQuotasTotal | Inteiro | Quantidade total de quotas. | | companyQuotasCurrency | String | Moeda das quotas (ex. `BRL`). | | companyQuotasValue | Ponto flutuante | Valor de uma quota. | | shareholderName{N} | String | Nome do sócio N (1, 2, 3...). | | shareholderPersonalTaxId{N} | String | CPF do sócio N (quando o sócio for uma pessoa física). | | shareholderRole{N} | String | Cargo/função do sócio N (ex. `Sócio Administrador`, `Procurador`, `Representante Legal`). | | shareholderPowers{N} | Array de String | Poderes concedidos ao sócio N. | | shareholderSignAlone{N} | Booleano | `true` somente quando o documento declarar explicitamente que o sócio pode assinar sozinho. | | shareholderSignAloneDescription{N} | String | Descrição textual da regra de assinatura. | | shareholderRestrictions{N} | Array de String | Restrições aplicáveis ao sócio N. | | shareholderQuotas{N} | Inteiro | Quotas detidas pelo sócio N. | | shareholderBusinessTaxId{N} | String | CNPJ do sócio N (quando o sócio for uma empresa). | | shareholderAddress{N} | String | Endereço do sócio N (quando o sócio for uma empresa). | | shareholderMandateStartDate{N} | String | Data de início do mandato (quando o sócio for uma empresa). | | shareholderMandateEndDate{N} | String | Data de término do mandato (quando o sócio for uma empresa). | | shareholderSignatureType{N} | String | `digital_signature` ou `physical_signature`. | | shareholderSignatureMet{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 | Usos `companyIncorporationDate` 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 cada `shareholderName{N}`) e `attributes.holderCpf` (fallback `attributes.cpf`) com `shareholderPersonalTaxId{N}`. | | Campos Obrigatórios | Valida os configurados `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 filial são extraídos, um aviso informativo é adicionado. | | {% endtab %} | | | {% endtabs %} | | ## Atributos específicos (POWER\_OF\_ATTORNEY) {% 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ção complementar do endereço da empresa. | | shareholderName{N} | String | Nome completo do outorgante. | | shareholderPersonalTaxId{N} | String | CPF do outorgante. | | shareholderRole{N} | String | Cargo/função do outorgante (ex. `Outorgante`, `Sócio Administrador`). | | shareholderPowers{N} | Array de String | Poderes concedidos pelo outorgante N. | | shareholderSignAlone{N} | Booleano | Se o outorgante N pode assinar sozinho. | | assigneeName{N} | String | Nome completo do outorgado. | | assigneeSignsAlone | Booleano | `true` quando o outorgado pode assinar sozinho após a procuração. | | signObservation | String | Observações sobre a regra de assinatura. | | powersGranted | Array de String | Lista consolidada de poderes concedidos na procuração. | | tipo | String | `public`, `private` ou `invalid`. | | hasExpirationDate | Booleano | `true` quando a procuração tem uma data de expiração. | | expirationDate | String | Data de expiração (vazio quando `hasExpirationDate` for `falso`). | | hasNotaryStamps | Booleano | `true` quando pelo menos um selo de cartório foi encontrado. | | notaryStampAuthenticationForm{N} | String | Forma de autenticação do selo N (`Assinado digitalmente via GOV.BR`, `Reconhecimento de Firma`, etc.). | | notaryStampName{N} | String | Nome no selo N (quando legível). | | isValidNotaryStamp{N} | Booleano | Se o selo N é considerado válido. | | notaryStampType{N} | String | `digital_signature` ou `handwritten_signature`. | | isValid | Booleano | Decisão final de validade calculada pelo modelo. | | textualDecision | String | Explicação textual de `isValid`. | | {% 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 | Usos `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 com data passada `expirationDate` são sempre inválidos. | | Titular do Documento | Compara `attributes.holderName` com `shareholderName{N}` (outorgantes) e `attributes.holderCpf` (fallback `attributes.cpf`) com `shareholderPersonalTaxId{N}`. | | Campos Obrigatórios | Valida os configurados `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 corresponder a nenhuma das categorias acima, o Smart OCR recorre ao `GENERIC` esquema com campos baseados em papéis. Os nomes dos campos seguem o padrão `{role}{Property}` (ex. `payerName`, `receiverBusinessTaxId`). {% 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. | | payerName | String | Nome completo do pagador/devedor. | | payerPersonalTaxId | String | CPF do pagador. | | payerBusinessTaxId | String | CNPJ do pagador. | | receiverName | String | Nome completo do recebedor/credor. | | receiverPersonalTaxId | String | CPF do recebedor. | | receiverBusinessTaxId | 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. | | netAmount | Ponto flutuante | Valor monetário líquido quando presente. | | grossAmount | 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 | Usos `issueDate` (ou `dueDate` como fallback) 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 `payerName`/`receiverName` e `attributes.holderCpf` (fallback `attributes.cpf`) com `payerPersonalTaxId`/`receiverPersonalTaxId`. | | Campos Obrigatórios | Valida os configurados `requiredTerms` (uso típico: garantir que as cláusulas contratuais estejam presentes). | | Completude do Endereço | Valida `companyCompleteAddress` como uma única string quando presente. | | {% endtab %} | | | {% endtabs %} | | ## Regras de validação Os quatro `smart_ocr` as regras abaixo podem ser habilitadas no [template da transação](/caf-api/caf-api-pt-br/core-api/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_validez_do_documento` | Validade do Documento | `attributes.analysisDate` | `VALID`, `INVÁLIDO`, `PENDENTE` | | `verifai_smart_ocr_titular_do_documento` | Titular do Documento | `attributes.holderName`, `attributes.holderCpf` (fallback `attributes.cpf`) | `VALID`, `INVÁLIDO`, `PENDENTE` | | `verifai_smart_ocr_campos_obrigatorios` | Campos Obrigatórios | — (configurado via `requiredTerms` no template) | `VALID`, `INVÁLIDO`, `PENDENTE` | | `verifai_smart_ocr_completude_do_endereco` | Completude do Endereço | — | `VALID`, `INVÁLIDO`, `PENDENTE` | ### Validade do documento (`verifai_smart_ocr_validez_do_documento`) Verifica se o documento foi emitido dentro da janela máxima configurada. A regra usa a data de emissão, a data de vencimento ou o mês/ano de referência do documento (o que estiver disponível para a classe do documento) para calcular quantos dias se passaram em comparação com a `analysisDate` 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 `analysisDate` são sempre considerados inválidos. ### Titular do documento (`verifai_smart_ocr_titular_do_documento`) 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 nomes não diferencia maiúsculas e minúsculas nem acentos (correspondência por substring); a comparação de CPF usa apenas dígitos. Qualquer uma das correspondências é suficiente — a regra é `VALID` quando pelo menos um dos valores fornecidos corresponde ao campo correspondente no documento. ### Campos obrigatórios (`verifai_smart_ocr_campos_obrigatorios`) 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_completude_do_endereco`) Verifica se o endereço do documento está completo (rua, número, CEP, bairro e cidade). `PROOF_OF_RESIDENCE` valida cada componente individualmente usando os dedicados `customerAddress*` campos, enquanto outras classes de documento validam `companyCompleteAddress` / `taxpayerCompleteAddress` 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. Para a configuração de quais regras estão habilitadas por template e como `availableActions` são interpretadas, veja [Regras de validação](/caf-api/caf-api-pt-br/core-api/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 dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.caf.io/caf-api/caf-api-pt-br/core-api/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 optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. 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.