Validação cadastral

curl --request POST \
  --url https://localapi.lazydata.com.br/v1/validation/registration \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "model": "<string>",
  "document": "<string>",
  "name": "<string>",
  "birthdate": "<string>",
  "opening_date": "<string>",
  "mother_name": "<string>",
  "father_name": "<string>",
  "trade_name": "<string>",
  "email": "<string>",
  "phone": "<string>",
  "address": {}
}
'

{
  "code": 200,
  "message": "Validação cadastral concluída com sucesso.",
  "result": {
    "id": "9fcb573b-7f62-4774-978b-07e89dfef5f2",
    "status": "completed",
    "test": false,
    "validation": {
      "id": "registration_validation",
      "name": "Validação cadastral",
      "type": "registration"
    },
    "cost": {
      "total": 0.08,
      "charged": 0.08,
      "refunded": 0
    },
    "timing": {
      "total": 2.31
    },
    "registration": {
      "model": "pf",
      "status": "approved",
      "score": 92.5,
      "identity_score": 88,
      "evidence_bonus": 4.5,
      "recommended_action": "approve",
      "summary": "Identidade principal compatível; evidências auxiliares confirmadas parcialmente.",
      "critical_errors": [],
      "compared_data": {
        "document": "00000000000",
        "name": "PESSOA EXEMPLO DOS SANTOS",
        "birth_or_opening_date": "1990-01-01"
      },
      "field_results": {
        "document": {
          "status": "confirmed",
          "impact": "positive",
          "score": 100,
          "message": "Documento confirmado na base."
        },
        "name": {
          "status": "confirmed",
          "impact": "positive",
          "score": 91.2,
          "message": "Nome compatível com a base."
        },
        "address": {
          "status": "partial",
          "impact": "positive",
          "score": 78.5,
          "message": "Endereço parcialmente confirmado na base."
        }
      }
    }
  }
}

POST

https://localapi.lazydata.com.br

validation

registration

Validação cadastral

curl --request POST \
  --url https://localapi.lazydata.com.br/v1/validation/registration \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "model": "<string>",
  "document": "<string>",
  "name": "<string>",
  "birthdate": "<string>",
  "opening_date": "<string>",
  "mother_name": "<string>",
  "father_name": "<string>",
  "trade_name": "<string>",
  "email": "<string>",
  "phone": "<string>",
  "address": {}
}
'

{
  "code": 200,
  "message": "Validação cadastral concluída com sucesso.",
  "result": {
    "id": "9fcb573b-7f62-4774-978b-07e89dfef5f2",
    "status": "completed",
    "test": false,
    "validation": {
      "id": "registration_validation",
      "name": "Validação cadastral",
      "type": "registration"
    },
    "cost": {
      "total": 0.08,
      "charged": 0.08,
      "refunded": 0
    },
    "timing": {
      "total": 2.31
    },
    "registration": {
      "model": "pf",
      "status": "approved",
      "score": 92.5,
      "identity_score": 88,
      "evidence_bonus": 4.5,
      "recommended_action": "approve",
      "summary": "Identidade principal compatível; evidências auxiliares confirmadas parcialmente.",
      "critical_errors": [],
      "compared_data": {
        "document": "00000000000",
        "name": "PESSOA EXEMPLO DOS SANTOS",
        "birth_or_opening_date": "1990-01-01"
      },
      "field_results": {
        "document": {
          "status": "confirmed",
          "impact": "positive",
          "score": 100,
          "message": "Documento confirmado na base."
        },
        "name": {
          "status": "confirmed",
          "impact": "positive",
          "score": 91.2,
          "message": "Nome compatível com a base."
        },
        "address": {
          "status": "partial",
          "impact": "positive",
          "score": 78.5,
          "message": "Endereço parcialmente confirmado na base."
        }
      }
    }
  }
}

Executa uma validação cadastral de pessoa física ou pessoa jurídica, comparando os dados informados com dados disponíveis na base. Use esta rota para validar cadastros, identificar divergências, apoiar onboarding, análise antifraude, revisão manual e regras internas de aprovação.

{
  "code": 200,
  "message": "Validação cadastral concluída com sucesso.",
  "result": {
    "id": "9fcb573b-7f62-4774-978b-07e89dfef5f2",
    "status": "completed",
    "test": false,
    "validation": {
      "id": "registration_validation",
      "name": "Validação cadastral",
      "type": "registration"
    },
    "cost": {
      "total": 0.08,
      "charged": 0.08,
      "refunded": 0
    },
    "timing": {
      "total": 2.31
    },
    "registration": {
      "model": "pf",
      "status": "approved",
      "score": 92.5,
      "identity_score": 88,
      "evidence_bonus": 4.5,
      "recommended_action": "approve",
      "summary": "Identidade principal compatível; evidências auxiliares confirmadas parcialmente.",
      "critical_errors": [],
      "compared_data": {
        "document": "00000000000",
        "name": "PESSOA EXEMPLO DOS SANTOS",
        "birth_or_opening_date": "1990-01-01"
      },
      "field_results": {
        "document": {
          "status": "confirmed",
          "impact": "positive",
          "score": 100,
          "message": "Documento confirmado na base."
        },
        "name": {
          "status": "confirmed",
          "impact": "positive",
          "score": 91.2,
          "message": "Nome compatível com a base."
        },
        "address": {
          "status": "partial",
          "impact": "positive",
          "score": 78.5,
          "message": "Endereço parcialmente confirmado na base."
        }
      }
    }
  }
}

Corpo da requisição

model

string

required

Modelo cadastral analisado. Use pf para pessoa física ou pj para pessoa jurídica.

document

string

required

CPF ou CNPJ do cadastro. Pontuação é aceita e removida automaticamente.

name

string

Nome da pessoa ou razão social.

birthdate

string

Data de nascimento em validações PF. Recomenda-se o formato yyyy-mm-dd.

opening_date

string

Data de abertura em validações PJ. Recomenda-se o formato yyyy-mm-dd.

mother_name

string

Nome da mãe em validações PF.

father_name

string

Nome do pai em validações PF.

trade_name

string

Nome fantasia em validações PJ.

string

E-mail informado como evidência auxiliar.

phone

string

Telefone informado como evidência auxiliar. Pontuação e prefixos são normalizados.

address

object

Endereço informado como evidência auxiliar.

x-ambient

string

Use sandbox para executar uma chamada de teste sem consumo de saldo.

Para detalhes sobre chamadas de teste, consulte Ambiente de teste.

Estrutura de `address`

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

Exemplo de corpo PF

{
  "model": "pf",
  "document": "00000000000",
  "name": "PESSOA EXEMPLO DOS SANTOS",
  "birthdate": "1990-01-01",
  "mother_name": "MARIA EXEMPLO DOS SANTOS",
  "email": "contato@example.com",
  "phone": "11999990000",
  "address": {
    "zipcode": "01001000",
    "street": "Rua Exemplo",
    "number": "100",
    "city": "São Paulo",
    "state": "SP"
  }
}

Exemplo de corpo PJ

{
  "model": "pj",
  "document": "00000000000000",
  "name": "EMPRESA EXEMPLO LTDA",
  "trade_name": "EMPRESA EXEMPLO",
  "opening_date": "2020-01-01",
  "email": "contato@example.com",
  "phone": "1130000000",
  "address": {
    "zipcode": "01001000",
    "street": "Rua Exemplo",
    "number": "100",
    "city": "São Paulo",
    "state": "SP"
  }
}

Os documentos acima são fictícios e servem apenas para demonstrar a estrutura da requisição.

Resposta

code

integer

required

Código da resposta da API.

message

string

required

Mensagem descritiva da resposta.

result

object

required

Objeto principal com o identificador da validação, cobrança, tempo de execução e resultado cadastral.

Estrutura de `result`

Campo	Tipo	Descrição
`id`	`string`	Identificador único da validação.
`status`	`string`	Status da execução. Para esta rota, normalmente `completed`.
`test`	`boolean`	Indica se a chamada foi executada em ambiente de teste.
`validation`	`object`	Metadados da validação executada.
`cost`	`object`	Valores cobrados ou estornados.
`timing`	`object`	Tempo de execução em segundos.
`registration`	`object`	Resultado consolidado da validação cadastral.

Estrutura de `result.validation`

Campo	Tipo	Descrição
`id`	`string`	Identificador da validação executada.
`name`	`string`	Nome amigável da validação.
`type`	`string`	Tipo da validação. Para esta rota, retorna `registration`.

Estrutura de `result.cost`

Campo	Tipo	Descrição
`total`	`number`	Valor total da validação.
`charged`	`number`	Valor debitado nesta chamada. Em sandbox, retorna `0`.
`refunded`	`number`	Valor estornado, quando houver.

Estrutura de `result.timing`

Campo	Tipo	Descrição
`total`	`number`	Tempo total de execução em segundos.

Estrutura de `result.registration`

Campo	Tipo	Descrição
`model`	`string`	Modelo analisado: `pf` ou `pj`.
`status`	`string`	Status consolidado da validação.
`score`	`number`	Pontuação final da validação, de `0` a `100`.
`identity_score`	`number`	Pontuação calculada apenas com campos de identidade verificáveis.
`evidence_bonus`	`number`	Bônus agregado por evidências auxiliares confirmadas, como endereço, telefone ou e-mail.
`recommended_action`	`string`	Ação recomendada para o cadastro.
`summary`	`string`	Resumo objetivo dos principais pontos encontrados.
`critical_errors`	`array<string>`	Divergências críticas que impedem aprovação automática.
`compared_data`	`object`	Dados da base usados na comparação para os campos informados.
`field_results`	`object`	Resultado detalhado da comparação por campo.

Valores de `status`

Valor	Descrição
`approved`	Dados compatíveis com a base.
`manual_review`	Dados parcialmente compatíveis ou evidências insuficientes para aprovação automática.
`rejected`	Foram encontradas divergências críticas.

Valores de `recommended_action`

Valor	Descrição
`approve`	O cadastro pode seguir automaticamente, conforme a política da sua aplicação.
`manual_review`	Revisão manual recomendada.
`reject`	Rejeição recomendada por divergência crítica.
`insufficient_data`	Dados insuficientes para aprovação automática.

Estrutura de `field_results`

O objeto field_results é indexado pelo nome do campo comparado. Campos comuns:

Campo	Quando aparece
`document`	CPF ou CNPJ.
`name`	Nome da pessoa ou razão social.
`birth_or_opening_date`	Data de nascimento ou abertura.
`trade_name`	Nome fantasia em validações PJ.
`mother_name`	Nome da mãe em validações PF.
`father_name`	Nome do pai em validações PF.
`address`	Endereço informado como evidência auxiliar.
`phone`	Telefone informado como evidência auxiliar.
`email`	E-mail informado como evidência auxiliar.

Cada campo comparado pode retornar:

Campo	Tipo	Descrição
`status`	`string`	Resultado individual do campo.
`impact`	`string`	Impacto do campo na decisão.
`score`	`number`	Pontuação individual do campo, de `0` a `100` quando aplicável.
`message`	`string`	Explicação objetiva do resultado.
`similarity`	`number`	Similaridade textual, quando aplicável.

Valores de `field_results.*.status`

Valor	Descrição
`confirmed`	Campo confirmado na base.
`partial`	Campo parcialmente compatível.
`mismatch`	Campo divergente.
`not_available`	Campo não disponível na base para comparação.
`not_provided`	Campo não informado na requisição.
`not_applicable`	Campo não aplicável ao modelo analisado.

Valores de `field_results.*.impact`

Valor	Descrição
`positive`	Evidência favorável.
`negative`	Evidência desfavorável.
`critical`	Divergência crítica.
`neutral`	Sem impacto relevante na decisão.

Estrutura de `compared_data`

O campo compared_data retorna apenas dados usados na comparação e pode variar conforme o modelo e os campos informados.

Campo	Descrição
`document`	CPF ou CNPJ encontrado na base e usado na comparação.
`name`	Nome da pessoa ou razão social encontrada na base.
`birth_or_opening_date`	Data de nascimento ou abertura encontrada na base.
`trade_name`	Nome fantasia encontrado na base, quando aplicável.
`mother_name`	Nome da mãe encontrado na base, quando aplicável.
`father_name`	Nome do pai encontrado na base, quando aplicável.
`email`	E-mail confirmado na base, retornado apenas quando corresponde ao e-mail informado.

Campos de compared_data e field_results podem não aparecer em todas as validações. A disponibilidade depende do modelo, dos dados informados e das informações existentes na base.

Ambiente de teste

Para executar uma chamada sem consumo de saldo, envie o header:

x-ambient: sandbox

Em chamadas de teste, test retorna true e charged retorna 0.

Respostas esperadas

As respostas possíveis estão exemplificadas no painel lateral da página.

Status	Quando ocorre
`200`	Validação cadastral concluída com sucesso.
`400`	Documento inválido, modelo inválido ou dados insuficientes para validação.
`401`	A chave da API está ausente, inválida ou não pôde ser autenticada.
`403`	A credencial não possui escopo de validação, o plano não permite acesso ou há bloqueio financeiro.
`422`	Validação do corpo da requisição falhou no schema da API reference.
`502`	Falha ao consultar o provedor da validação.

Regras importantes

A credencial usada precisa possuir o escopo de validação.
O plano da conta precisa permitir API e validações.
model deve ser pf ou pj.
Para pf, document deve ser um CPF válido.
Para pj, document deve ser um CNPJ válido.
Envie ao menos um campo útil além do documento para obter uma validação mais conclusiva.
Chamadas reais debitam o valor da validação conforme o preço vigente da conta.
A decisão final da sua aplicação deve considerar recommended_action, score, critical_errors e sua regra de negócio interna.

Comparação facial Visão geral

​Corpo da requisição

​Estrutura de address

​Exemplo de corpo PF

​Exemplo de corpo PJ

​Resposta

​Estrutura de result

​Estrutura de result.validation

​Estrutura de result.cost

​Estrutura de result.timing

​Estrutura de result.registration

​Valores de status

​Valores de recommended_action

​Estrutura de field_results

​Valores de field_results.*.status

​Valores de field_results.*.impact

​Estrutura de compared_data

​Ambiente de teste

​Respostas esperadas

​Regras importantes

Corpo da requisição

Estrutura de `address`

Exemplo de corpo PF

Exemplo de corpo PJ

Resposta

Estrutura de `result`

Estrutura de `result.validation`

Estrutura de `result.cost`

Estrutura de `result.timing`

Estrutura de `result.registration`

Valores de `status`

Valores de `recommended_action`

Estrutura de `field_results`

Valores de `field_results.*.status`

Valores de `field_results.*.impact`

Estrutura de `compared_data`

Ambiente de teste

Respostas esperadas

Regras importantes