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 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).
O Verif AI Smart OCR só é executado quando o template da transação 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.
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.
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.
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.
Exemplo de requisição:
{
"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.
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)
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.
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.
Atributos específicos (PROOF_OF_INCOME)
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).
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.
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.
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.
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).
Atributos específicos (SOCIAL_CONTRACT)
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.
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.
Atributos específicos (POWER_OF_ATTORNEY)
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.
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.
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).
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.
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.
Regras de validação
Os quatro smart_ocr as regras abaixo podem ser habilitadas no template da transação. 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.
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.
Atualizado