Teste da credencial, consulta de CEP e de localidade, validação cadastral de CPF/CNPJ e observações livres ligadas a registros.
Autenticação em todos os exemplos: veja Autenticação. Teste no navegador pelo Swagger ou importe a coleção do Postman.
| Endpoint | Métodos | Para que serve |
|---|---|---|
status |
GET | Teste de conexão e credencial do terceiro |
consultarCep |
GET | Endereço pelo CEP |
localizarLocalidade |
GET | Busca de cidades pelo nome |
validarPessoaFisica |
GET | Validação cadastral de CPF (bureau BigDataCorp) |
validarPessoaJuridica |
GET | Validação cadastral de CNPJ (bureau BigDataCorp) |
txObservacao |
GET, POST, PUT, DELETE | Observações livres ligadas a qualquer registro |
Teste de conexão e credencial do terceiro. Não consulta nada: só confirma que a autenticação (APP/REDE/CNPJ/CPF + SENHA + A) e a permissão do terceiro estão corretas. Útil para testar a conexão da integração. Vale para todos os perfis.
/v1/terceiro/statusResponde ok se a credencial é válida
Perfis: App, Rede, Estabelecimento, Cliente, Pessoa
curl -s -X GET "$BASE/v1/terceiro/status?$AUTH"
Resposta:
{
"status": "ok"
}
Erros específicos: 401 — credencial inválida.; 403 — sem permissão..
Endereço pelo CEP. Consulta o CEP na base do ZP (atualizada por serviço externo quando preciso). Só GET.
/v1/terceiro/consultarCepEndereço do CEP
Perfis: App, Rede, Estabelecimento, Cliente, Pessoa
Parâmetros (query)
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
cep |
string | sim | CEP, 8 dígitos (pontuação é ignorada). |
curl -s -X GET "$BASE/v1/terceiro/consultarCep?$AUTH&cep=80000000"
Resposta:
{
"status": "ok",
"cep": "80000000",
"cliente": "",
"logradouro": "RUA EXEMPLO",
"complemento": "",
"bairro": "CENTRO",
"localidade": "CURITIBA",
"estado": "PR",
"codigo_ibge": "4106902"
}
Erros específicos: 200 — só {"status":"ok"} quando o CEP é inválido ou não foi encontrado..
Busca de cidades pelo nome. Até 10 cidades cujo nome contém o texto (sem acentos). Só GET.
/v1/terceiro/localizarLocalidadeCidades
Perfis: App, Rede, Estabelecimento, Cliente, Pessoa
Parâmetros (query)
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
q |
string | sim | Parte do nome da cidade. |
curl -s -X GET "$BASE/v1/terceiro/localizarLocalidade?$AUTH&q=curitiba"
Resposta:
{
"status": "ok",
"data": [
{
"value": "CURITIBA;PR;4106902",
"text": "CURITIBA/PR"
}
]
}
Validação cadastral de CPF (bureau BigDataCorp). Compara os dados informados com a base do bureau e devolve o grau de semelhança de cada bloco, a situação do CPF e se há indicação de óbito. Cada chamada consulta o bureau (serviço pago) e fica registrada. Só GET. Os parâmetros vão na query (ou no corpo como application/x-www-form-urlencoded); corpo JSON não é lido.
/v1/terceiro/validarPessoaFisicaSemelhança dos dados com o bureau
Perfis: App, Rede, Estabelecimento, Cliente, Pessoa
Parâmetros (query)
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
documento |
string | sim | CPF. |
nome |
string | não | Nome completo. |
data_nascimento |
date | não | AAAA-MM-DD. |
nome_mae |
string | não | Nome da mãe. |
cep |
string | não | CEP informado pelo cliente. |
logradouro |
string | não | |
numero |
integer | não | |
complemento |
string | não | |
bairro |
string | não | |
localidade |
string | não | Cidade. |
estado |
string | não | UF. |
telefone |
string | não | Com DDD. |
celular |
string | não | Com DDD. |
email |
string | não |
curl -s -X GET "$BASE/v1/terceiro/validarPessoaFisica?$AUTH&documento=12345678909"
Resposta:
{
"status": "ok",
"documento": "12345678909",
"dados_basicos": 0.95,
"endereco": 0.8,
"telefone": 0.0,
"celular": 1.0,
"email": 1.0,
"cpf_status": "REGULAR",
"falecida": false,
"pergunta1": {
"Quais destes e-mails você reconhece?": [
{
"0": "Nenhum"
},
{
"1": "cliente@exemplo.com.br"
},
{
"2": "cliente123@exemplo.com"
}
]
},
"pergunta2": {
"Quais destes telefones você reconhece?": [
{
"0": "Nenhum"
},
{
"1": "…"
}
]
},
"pergunta3": {
"Quais destes endereços você reconhece?": [
{
"0": "Nenhum"
},
{
"1": "…"
}
]
},
"token": "0123456789abcdef0123456789abcdef"
}
Erros específicos: 200 — só {"status":"ok","documento":""} quando o CPF é inválido (não consulta o bureau)..
Validação cadastral de CNPJ (bureau BigDataCorp). Como validarPessoaFisica, para CNPJ: semelhança dos dados informados com o bureau, situação do CNPJ e se está inativo. Cada chamada consulta o bureau (serviço pago) e fica registrada. Só GET. Os parâmetros vão na query (ou no corpo como application/x-www-form-urlencoded); corpo JSON não é lido.
/v1/terceiro/validarPessoaJuridicaSemelhança dos dados com o bureau
Perfis: App, Rede, Estabelecimento, Cliente, Pessoa
Parâmetros (query)
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
documento |
string | sim | CNPJ. |
razao_social |
string | não | |
nome_fantasia |
string | não | |
data_fundacao |
date | não | AAAA-MM-DD. |
cep |
string | não | CEP informado pelo cliente. |
logradouro |
string | não | |
numero |
integer | não | |
complemento |
string | não | |
bairro |
string | não | |
localidade |
string | não | Cidade. |
estado |
string | não | UF. |
telefone |
string | não | Com DDD. |
celular |
string | não | Com DDD. |
email |
string | não |
curl -s -X GET "$BASE/v1/terceiro/validarPessoaJuridica?$AUTH&documento=11222333000181"
Resposta:
{
"status": "ok",
"documento": "11222333000181",
"dados_basicos": 0.9,
"endereco": 1.0,
"telefone": 1.0,
"celular": 0.0,
"email": 0.5,
"cnpj_status": "ATIVA",
"inativa": false,
"pergunta1": {
"Quais destes e-mails você reconhece?": [
{
"0": "Nenhum"
},
{
"1": "financeiro@exemplo.com.br"
}
]
},
"pergunta2": {
"Quais destes telefones você reconhece?": [
{
"0": "Nenhum"
},
{
"1": "…"
}
]
},
"pergunta3": {
"Quais destes endereços você reconhece?": [
{
"0": "Nenhum"
},
{
"1": "…"
}
]
},
"token": "0123456789abcdef0123456789abcdef"
}
Erros específicos: 200 — só {"status":"ok","documento":""} quando o CNPJ é inválido..
Observações livres ligadas a qualquer registro. Grava e consulta observações (texto) ligadas a qualquer registro do sistema, identificado por tabela + id. GET por id_tx_observacao devolve uma; por tabela + id devolve a lista. DELETE desativa (ativo = N). A API não verifica se a tabela e o id existem e não restringe pelo escopo do acesso (só pelo app).
/v1/terceiro/txObservacaoConsulta uma observação ou as de um registro
Por id_tx_observacao a resposta é um objeto plano (sem data[] e, no ZP, sem data_hora): {status, id_tx_observacao, tabela, id, observacao, ativo}.
Perfis: App, Rede, Estabelecimento, Cliente, Pessoa
Parâmetros (query)
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
id_tx_observacao |
integer | não | Id da observação (tem prioridade). |
tabela |
string | não | Tabela (usar junto com id quando não houver id_tx_observacao). |
id |
integer | não | Id do registro na tabela. |
curl -s -X GET "$BASE/v1/terceiro/txObservacao?$AUTH"
Resposta:
{
"status": "ok",
"data": [
{
"id_tx_observacao": 15,
"observacao": "Cliente pediu segunda via",
"data_hora": "2026-11-10 09:30:00",
"ativo": true
}
]
}
Erros específicos: 400 — {"errors":{"params":"Você deve passar o id_tx_observacao ou o conjunto (tabela, id)"}}.; 400 — {"errors":{"registro":"Falha ao localizar"}}: o id não existe no app..
/v1/terceiro/txObservacaoCria uma observação
Perfis: App, Rede, Estabelecimento, Cliente, Pessoa
Corpo (JSON objeto)
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
tabela |
string | sim | Nome da tabela do sistema a que a observação se refere (ex.: cob_cobranca). |
id |
integer | sim | Id do registro nessa tabela. |
observacao |
string | sim | Texto |
ativo |
boolean | não | true/false |
curl -s -X POST "$BASE/v1/terceiro/txObservacao?$AUTH" \
-H 'Content-Type: application/json' \
-d '{"tabela": "cob_cobranca", "id": 5001, "observacao": "Cliente pediu segunda via"}'
Resposta:
{
"status": "ok",
"id_tx_observacao": 15
}
Erros específicos: 400 — {"errors":{"body":"O conteúdo não é um JSON válido"}}.; 400 — {"errors":{"exception":""}}: erro de validação ao gravar (ex.: "Dados já cadastrados (id)")..
/v1/terceiro/txObservacaoAltera uma observação (parcial)
Perfis: App, Rede, Estabelecimento, Cliente, Pessoa
Parâmetros (query)
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
id_tx_observacao |
integer | sim | Id da observação |
Corpo (JSON objeto)
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
tabela |
string | não | Nome da tabela do sistema a que a observação se refere (ex.: cob_cobranca). |
id |
integer | não | Id do registro nessa tabela. |
observacao |
string | não | Texto |
ativo |
boolean | não | true/false |
curl -s -X PUT "$BASE/v1/terceiro/txObservacao?$AUTH&id_tx_observacao=" \
-H 'Content-Type: application/json' \
-d '{"observacao": "Texto corrigido"}'
Resposta:
{
"status": "ok"
}
Erros específicos: 400 — {"errors":{"id_tx_observacao":"Inválido"}}.; 400 — {"errors":{"body":"O conteúdo não é um JSON válido"}}.; 400 — {"errors":{"registro":"Falha ao localizar"}}: o id não existe no app.; 400 — {"errors":{"exception":""}}: erro de validação ao gravar (ex.: "Dados já cadastrados (id)")..
/v1/terceiro/txObservacaoDesativa uma observação
Perfis: App, Rede, Estabelecimento, Cliente, Pessoa
Parâmetros (query)
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
id_tx_observacao |
integer | sim | Id da observação |
curl -s -X DELETE "$BASE/v1/terceiro/txObservacao?$AUTH&id_tx_observacao="
Resposta:
{
"status": "ok"
}
Erros específicos: 400 — {"errors":{"id_tx_observacao":"Inválido"}}.; 400 — {"errors":{"registro":"Falha ao localizar"}}: o id não existe no app.; 400 — {"errors":{"registro":"Falha ao desativar"}}: por exemplo, registro já inativo..