Validação cadastral

A validação cadastral compara os dados informados na requisição com dados cadastrais de referência e retorna um resultado estruturado com score, status, campos comparados e ação recomendada. Ela pode ser usada em cadastros, onboarding, revisão de clientes, atualização cadastral e fluxos de prevenção a inconsistências.

Endpoint

POST /v1/validation/registration

Modelos disponíveis

Modelo	Descrição
`pf`	Validação cadastral de pessoa física.
`pj`	Validação cadastral de pessoa jurídica.

Validação de pessoa física

{
  "model": "pf",
  "document": "00000000000",
  "name": "Carlos Santos Silva",
  "birthdate": "1990-05-10",
  "mother_name": "Maria Santos Silva",
  "father_name": "João Santos Silva",
  "email": "cliente@example.com",
  "phone": "11999999999",
  "address": {
    "zipcode": "01001000",
    "street": "Rua Exemplo",
    "number": "100",
    "complement": "Apto 10",
    "district": "Centro",
    "city": "São Paulo",
    "state": "SP"
  }
}

Validação de pessoa jurídica

{
  "model": "pj",
  "document": "00000000000100",
  "name": "Empresa Exemplo LTDA",
  "trade_name": "Empresa Exemplo",
  "opening_date": "2018-03-15",
  "email": "contato@example.com",
  "phone": "1133334444",
  "address": {
    "zipcode": "01001000",
    "street": "Rua Exemplo",
    "number": "100",
    "complement": "Sala 20",
    "district": "Centro",
    "city": "São Paulo",
    "state": "SP"
  }
}

Campos da requisição

Campo	Tipo	Obrigatório	Descrição
`model`	`string`	Sim	Modelo da validação. Aceita `pf` ou `pj`.
`document`	`string`	Sim	CPF ou CNPJ que será validado.
`name`	`string`	Não	Nome da pessoa física ou razão social da pessoa jurídica.
`birthdate`	`string`	Não	Data de nascimento para pessoa física, no formato `YYYY-MM-DD`.
`opening_date`	`string`	Não	Data de abertura para pessoa jurídica, no formato `YYYY-MM-DD`.
`mother_name`	`string`	Não	Nome da mãe para pessoa física.
`father_name`	`string`	Não	Nome do pai para pessoa física.
`trade_name`	`string`	Não	Nome fantasia para pessoa jurídica.
`email`	`string`	Não	E-mail informado pelo usuário.
`phone`	`string`	Não	Telefone informado pelo usuário.
`address`	`object`	Não	Endereço informado pelo usuário.

Campos do endereço

Campo	Tipo	Descrição
`zipcode`	`string`	CEP.
`street`	`string`	Logradouro.
`number`	`string`	Número.
`complement`	`string`	Complemento.
`district`	`string`	Bairro.
`city`	`string`	Cidade.
`state`	`string`	UF.

Regras importantes

É necessário informar ao menos um dado cadastral além do CPF ou CNPJ. Exemplos válidos:

CPF + nome.
CPF + data de nascimento.
CPF + nome da mãe.
CNPJ + razão social.
CNPJ + data de abertura.
CNPJ + nome fantasia.

Dados como e-mail, telefone e endereço podem agregar evidência ao score, mas não substituem os dados cadastrais principais.

Tratamento de dados complementares

E-mail, telefone e endereço são tratados como evidências adicionais. Quando esses dados forem encontrados e compatíveis, eles podem aumentar a pontuação. Quando não forem encontrados ou divergirem da base, isso não necessariamente reduz o score principal, pois esses dados podem estar desatualizados ou ausentes na referência.

Exemplo de resposta aprovada

{
  "code": 200,
  "message": "Validação cadastral concluída com sucesso.",
  "result": {
    "id": "98f1c2b0-5c7e-4b64-9d9d-40dd3b2a1111",
    "status": "completed",
    "test": false,
    "validation": {
      "id": "registration_validation",
      "name": "Validação cadastral",
      "type": "registration"
    },
    "cost": {
      "total": 0.08,
      "charged": 0.08,
      "refunded": 0.0
    },
    "timing": {
      "total": 1.84
    },
    "registration": {
      "model": "pf",
      "status": "approved",
      "recommended_action": "approve",
      "score": 94.6,
      "summary": "Os dados informados são compatíveis com a referência cadastral.",
      "fields": {
        "document": {
          "status": "match",
          "impact": "positive",
          "score": 100,
          "message": "CPF compatível."
        },
        "name": {
          "status": "match",
          "impact": "positive",
          "score": 96.8,
          "similarity": 96.8,
          "message": "Nome compatível com a referência."
        },
        "birth_or_opening_date": {
          "status": "match",
          "impact": "positive",
          "score": 100,
          "message": "Data de nascimento compatível."
        },
        "mother_name": {
          "status": "match",
          "impact": "positive",
          "score": 95.3,
          "similarity": 95.3,
          "message": "Nome da mãe compatível."
        },
        "email": {
          "status": "match",
          "impact": "evidence",
          "score": 100,
          "message": "E-mail encontrado entre as evidências."
        },
        "phone": {
          "status": "not_available",
          "impact": "neutral",
          "score": 0,
          "message": "Telefone não disponível para comparação."
        },
        "address": {
          "status": "partial_match",
          "impact": "evidence",
          "score": 82.4,
          "message": "Endereço parcialmente compatível."
        }
      },
      "compared_data": {
        "document": "000.000.000-00",
        "name": "Carlos Santos Silva",
        "birth_or_opening_date": "1990-05-10",
        "mother_name": "Maria Santos Silva",
        "father_name": "João Santos Silva"
      }
    }
  }
}

Exemplo de resposta para revisão

{
  "code": 200,
  "message": "Validação cadastral concluída com sucesso.",
  "result": {
    "id": "4a7a91b1-9d0a-48f2-a05e-1ab8ad8b1111",
    "status": "completed",
    "test": false,
    "validation": {
      "id": "registration_validation",
      "name": "Validação cadastral",
      "type": "registration"
    },
    "cost": {
      "total": 0.08,
      "charged": 0.08,
      "refunded": 0.0
    },
    "timing": {
      "total": 1.92
    },
    "registration": {
      "model": "pf",
      "status": "review",
      "recommended_action": "review",
      "score": 72.4,
      "summary": "Os dados possuem compatibilidade parcial e exigem revisão.",
      "fields": {
        "document": {
          "status": "match",
          "impact": "positive",
          "score": 100,
          "message": "CPF compatível."
        },
        "name": {
          "status": "partial_match",
          "impact": "moderate",
          "score": 83.5,
          "similarity": 83.5,
          "message": "Nome parcialmente compatível."
        },
        "birth_or_opening_date": {
          "status": "not_provided",
          "impact": "neutral",
          "score": 0,
          "message": "Data de nascimento não informada."
        },
        "mother_name": {
          "status": "not_available",
          "impact": "neutral",
          "score": 0,
          "message": "Nome da mãe não disponível na referência."
        }
      },
      "compared_data": {
        "document": "000.000.000-00",
        "name": "Carlos Santos Silva"
      }
    }
  }
}

Exemplo de resposta reprovada

{
  "code": 200,
  "message": "Validação cadastral concluída com sucesso.",
  "result": {
    "id": "b31735d7-93e4-4011-9e74-50193fb81111",
    "status": "completed",
    "test": false,
    "validation": {
      "id": "registration_validation",
      "name": "Validação cadastral",
      "type": "registration"
    },
    "cost": {
      "total": 0.08,
      "charged": 0.08,
      "refunded": 0.0
    },
    "timing": {
      "total": 1.76
    },
    "registration": {
      "model": "pj",
      "status": "rejected",
      "recommended_action": "reject",
      "score": 38.2,
      "summary": "Foram encontradas divergências críticas nos dados identitários.",
      "fields": {
        "document": {
          "status": "match",
          "impact": "positive",
          "score": 100,
          "message": "CNPJ compatível."
        },
        "name": {
          "status": "mismatch",
          "impact": "critical",
          "score": 12.4,
          "similarity": 12.4,
          "message": "Razão social divergente da referência."
        },
        "birth_or_opening_date": {
          "status": "mismatch",
          "impact": "critical",
          "score": 0,
          "message": "Data de abertura divergente da referência."
        },
        "trade_name": {
          "status": "not_provided",
          "impact": "neutral",
          "score": 0,
          "message": "Nome fantasia não informado."
        }
      },
      "compared_data": {
        "document": "00.000.000/0001-00",
        "name": "Empresa Exemplo LTDA",
        "birth_or_opening_date": "2018-03-15"
      }
    }
  }
}

Campos da resposta

Campo	Tipo	Descrição
`result.id`	`string`	Identificador da validação.
`result.status`	`string`	Status da execução.
`result.test`	`boolean`	Indica se a validação foi feita em ambiente de teste.
`result.validation.id`	`string`	Identificador da validação executada.
`result.cost.total`	`number`	Valor total da validação.
`result.cost.charged`	`number`	Valor debitado.
`result.cost.refunded`	`number`	Valor estornado, quando aplicável.
`result.timing.total`	`number`	Tempo total da validação em segundos.
`result.registration.model`	`string`	Modelo validado: `pf` ou `pj`.
`result.registration.status`	`string`	Status final da validação.
`result.registration.recommended_action`	`string`	Ação recomendada.
`result.registration.score`	`number`	Score final da validação.
`result.registration.summary`	`string`	Resumo da análise.
`result.registration.fields`	`object`	Resultado por campo comparado.
`result.registration.compared_data`	`object`	Dados cadastrais de referência correspondentes aos campos enviados.

Status da validação cadastral

Status	Descrição
`approved`	Dados compatíveis com a referência.
`review`	Dados parcialmente compatíveis ou insuficientes para aprovação automática.
`rejected`	Dados com divergências críticas.
`not_found`	Documento não localizado na referência cadastral.

Ações recomendadas

Ação	Descrição
`approve`	Cadastro pode ser aprovado automaticamente.
`review`	Cadastro deve passar por revisão manual.
`reject`	Cadastro deve ser reprovado ou bloqueado.

Chamada de teste

A validação cadastral pode ser executada em ambiente de teste sem consumir saldo. Consulte a página de ambiente de teste:

Ambiente de teste

Veja como habilitar chamadas de teste usando o header correto.

Erros comuns

CPF inválido

{
  "code": 400,
  "message": "CPF inválido."
}

CNPJ inválido

{
  "code": 400,
  "message": "CNPJ inválido."
}

Modelo inválido

{
  "code": 400,
  "message": "Modelo cadastral inválido."
}

Dados insuficientes

{
  "code": 400,
  "message": "Informe ao menos um dado cadastral além do CPF para validar o cadastro."
}

Dados protegidos

{
  "code": 403,
  "message": "Não foi possível consultar dados protegidos por restrição de privacidade."
}

Menor de idade

{
  "code": 400,
  "message": "Não é permitido validar dados de menores de idade."
}

Observações

A validação cadastral calcula compatibilidade com base nos dados disponíveis. Campos ausentes na referência não reduzem o score por si só. Dados complementares como telefone, e-mail e endereço funcionam como evidências adicionais e podem aumentar a confiança quando compatíveis.

​Endpoint

​Modelos disponíveis

​Validação de pessoa física

​Validação de pessoa jurídica

​Campos da requisição

​Campos do endereço

​Regras importantes

​Tratamento de dados complementares

​Exemplo de resposta aprovada

​Exemplo de resposta para revisão

​Exemplo de resposta reprovada

​Campos da resposta

​Status da validação cadastral

​Ações recomendadas

​Chamada de teste