Operação · Referência
Clientes
Locatários e compradores: identificação, CNH, contato e endereço.
GET
/v1/clientesListarGET/v1/clientes/{id}DetalharGET/v1/clientes/{id}/locacoesRelação: LocaçõesGET/v1/clientes/{id}/pagamentosRelação: PagamentosGET/v1/clientes/{id}/acordosRelação: AcordosGET/v1/clientes/{id}/multasRelação: MultasGET/v1/clientes/{id}/documentosRelação: Documentos do clienteGET/v1/clientes/exportarExportar em lotePOST/v1/clientesCadastrar clientePATCH/v1/clientes/{id}Atualizar clienteO objeto clientes
| Campo | Tipo | Descrição | |
|---|---|---|---|
id | inteiro | Identificador | ordenar |
name | texto | Nome completo / razão social | ordenar |
cpf_cnpj | texto | CPF ou CNPJ | LGPD |
cpf | texto | cpf | LGPD |
rg | texto | rg | LGPD |
birth_date | data | birth date | LGPD |
civil_status | texto | civil status | |
profession | texto | profession | |
phone | texto | Telefone | LGPD |
email | texto | LGPD | |
cnh | texto | cnh | LGPD |
cnh_registro | texto | cnh registro | LGPD |
cnh_categoria | texto | cnh categoria | filtro |
cnh_validade | data | cnh validade | ordenar |
cnh_emissao | data | cnh emissao | |
cnh_primeira_habilitacao | data | cnh primeira habilitacao | |
cep | texto | cep | LGPD |
street | texto | street | LGPD |
number | texto | number | LGPD |
complement | texto | complement | LGPD |
neighborhood | texto | neighborhood | LGPD |
city | texto | city | filtro |
uf | texto | uf | filtro |
address | texto | address | LGPD |
reference_point | texto | reference point | LGPD |
neighbors | objeto | Vizinhos de referência (JSON) | LGPD |
witness_neighbors | objeto | Testemunhas (JSON) | LGPD |
billing_day | inteiro | Dia de cobrança preferido | |
billing_start_date | data | billing start date | |
created_at | data-hora | Criado em | ordenar |
log_origem | texto | Origem do registro (sistema novo/antigo) | filtro |
Exemplo do objeto200 OK
{
"id": 1024,
"name": "Maria Fernanda Souza",
"cpf_cnpj": "52998224725",
"cpf": "52998224725",
"rg": "1234567",
"birth_date": "2026-10-15",
"civil_status": "texto",
"profession": "texto",
"phone": "91998765432",
"email": "maria@exemplo.com.br",
"cnh": "01234567890",
"cnh_registro": "01234567890",
"cnh_categoria": "texto",
"cnh_validade": "2026-10-15",
"cnh_emissao": "2026-10-15",
"cnh_primeira_habilitacao": "2026-10-15",
"cep": "66010000",
"street": "Av. Nazaré",
"number": "1000",
"complement": "Sala 2",
"neighborhood": "Nazaré",
"city": "Belém",
"uf": "PA",
"address": "texto",
"reference_point": "texto",
"neighbors": {},
"witness_neighbors": {},
"billing_day": 1,
"billing_start_date": "2026-10-15",
"created_at": "2026-10-08T14:30:00-03:00",
"log_origem": "sistema_novo"
}GET Listar
Retorna os registros paginados, do mais recente para o mais antigo (padrão). Requer Ler.
Parâmetros de consulta
| Parâmetro | Tipo | Descrição |
|---|---|---|
pagina | inteiro | Página (padrão 1) |
por_pagina | inteiro | 1 a 200 (padrão 50) |
ordenar | texto | Aceita: id, name, created_at, cnh_validade — prefixo - para decrescente |
campos | texto | Lista de campos do objeto, separados por vírgula |
q | texto | Busca em: name (e documento/telefone, com permissão LGPD) |
city | texto | city — valor exato ou lista separada por vírgula |
uf | texto | uf — valor exato ou lista separada por vírgula |
cnh_categoria | texto | cnh categoria — valor exato ou lista separada por vírgula |
log_origem | texto | Origem do registro (sistema novo/antigo) — valor exato ou lista separada por vírgula |
criado_desde / criado_ate | data | Período de criação |
atualizado_desde | data-hora | Criados ou alterados desde (pelo registro de alterações do Mapogos) |
incluir | texto | Só no detalhe. Relações: locacoes, pagamentos, acordos, multas, documentos |
RequisiçãoTestar ▸
curl -X GET "https://apimapogos.sixinformatica.com/v1/clientes?por_pagina=20" \
-H "Authorization: Bearer $MAPOGOS_API_KEY"<?php
$ch = curl_init('https://apimapogos.sixinformatica.com/v1/clientes?por_pagina=20');
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . getenv('MAPOGOS_API_KEY'),
],
]);
$resposta = json_decode(curl_exec($ch), true);
$http = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
if ($resposta['sucesso']) {
print_r($resposta['dados']);
} else {
echo $resposta['erro']['mensagem'];
}const resposta = await fetch('https://apimapogos.sixinformatica.com/v1/clientes?por_pagina=20', {
method: 'GET',
headers: {
Authorization: `Bearer ${process.env.MAPOGOS_API_KEY}`,
},
});
const json = await resposta.json();
if (json.sucesso) console.log(json.dados);
else console.error(json.erro.mensagem);import os, uuid, requests
resposta = requests.request(
"GET",
"https://apimapogos.sixinformatica.com/v1/clientes?por_pagina=20",
headers={"Authorization": f"Bearer {os.environ['MAPOGOS_API_KEY']}"},
timeout=30,
)
json = resposta.json()
print(json["dados"] if json["sucesso"] else json["erro"]["mensagem"])Resposta200 OK
{
"sucesso": true,
"dados": [
{
"id": 1024,
"name": "Maria Fernanda Souza",
"cpf_cnpj": "52998224725",
"cpf": "52998224725",
"rg": "1234567",
"birth_date": "2026-10-15",
"civil_status": "texto",
"profession": "texto"
}
],
"meta": {
"total": 1,
"pagina": 1,
"por_pagina": 20,
"paginas": 1
},
"request_id": "req_0f1e2d3c4b5a69788796"
}GET Detalhar
Retorna um registro pelo id. Requer Ler.
Use incluir para embutir relações (cada uma exige Ler no módulo relacionado).
| Erro | Quando |
|---|---|
404 nao_encontrado | Não existe ou está fora das carteiras da chave |
403 permissao_negada | Sem Ler no módulo (ou numa relação pedida) |
RequisiçãoTestar ▸
curl -X GET "https://apimapogos.sixinformatica.com/v1/clientes/1024?incluir=locacoes" \
-H "Authorization: Bearer $MAPOGOS_API_KEY"<?php
$ch = curl_init('https://apimapogos.sixinformatica.com/v1/clientes/1024?incluir=locacoes');
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . getenv('MAPOGOS_API_KEY'),
],
]);
$resposta = json_decode(curl_exec($ch), true);
$http = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
if ($resposta['sucesso']) {
print_r($resposta['dados']);
} else {
echo $resposta['erro']['mensagem'];
}const resposta = await fetch('https://apimapogos.sixinformatica.com/v1/clientes/1024?incluir=locacoes', {
method: 'GET',
headers: {
Authorization: `Bearer ${process.env.MAPOGOS_API_KEY}`,
},
});
const json = await resposta.json();
if (json.sucesso) console.log(json.dados);
else console.error(json.erro.mensagem);import os, uuid, requests
resposta = requests.request(
"GET",
"https://apimapogos.sixinformatica.com/v1/clientes/1024?incluir=locacoes",
headers={"Authorization": f"Bearer {os.environ['MAPOGOS_API_KEY']}"},
timeout=30,
)
json = resposta.json()
print(json["dados"] if json["sucesso"] else json["erro"]["mensagem"])Resposta200 OK
{
"sucesso": true,
"dados": {
"id": 1024,
"name": "Maria Fernanda Souza",
"cpf_cnpj": "52998224725",
"cpf": "52998224725",
"rg": "1234567",
"birth_date": "2026-10-15",
"civil_status": "texto",
"profession": "texto"
},
"request_id": "req_1d2c3b4a5f6e7d8c9b0a"
}Relações
| Nome | Módulo | Retorno | Rota |
|---|---|---|---|
locacoes | Locações | lista paginada | /v1/clientes/{id}/locacoes |
pagamentos | Pagamentos | lista paginada | /v1/clientes/{id}/pagamentos |
acordos | Acordos | lista paginada | /v1/clientes/{id}/acordos |
multas | Multas | lista paginada | /v1/clientes/{id}/multas |
documentos | Documentos do cliente | lista paginada | /v1/clientes/{id}/documentos |
GET Exportar em lote
Até 1000 registros por chamada, paginando por cursor. Requer Ler e Exportar. Aceita os mesmos filtros da listagem e formato=csv. Detalhes no guia Exportação em lote.
RequisiçãoTestar ▸
curl -X GET "https://apimapogos.sixinformatica.com/v1/clientes/exportar?limite=1000" \
-H "Authorization: Bearer $MAPOGOS_API_KEY"<?php
$ch = curl_init('https://apimapogos.sixinformatica.com/v1/clientes/exportar?limite=1000');
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . getenv('MAPOGOS_API_KEY'),
],
]);
$resposta = json_decode(curl_exec($ch), true);
$http = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
if ($resposta['sucesso']) {
print_r($resposta['dados']);
} else {
echo $resposta['erro']['mensagem'];
}const resposta = await fetch('https://apimapogos.sixinformatica.com/v1/clientes/exportar?limite=1000', {
method: 'GET',
headers: {
Authorization: `Bearer ${process.env.MAPOGOS_API_KEY}`,
},
});
const json = await resposta.json();
if (json.sucesso) console.log(json.dados);
else console.error(json.erro.mensagem);import os, uuid, requests
resposta = requests.request(
"GET",
"https://apimapogos.sixinformatica.com/v1/clientes/exportar?limite=1000",
headers={"Authorization": f"Bearer {os.environ['MAPOGOS_API_KEY']}"},
timeout=30,
)
json = resposta.json()
print(json["dados"] if json["sucesso"] else json["erro"]["mensagem"])POST Cadastrar cliente
Cadastrar cliente. Requer criar.
Corpo da requisição (JSON)
| Campo | Tipo | Regras | |
|---|---|---|---|
name | texto | obrigatório | Nome completo / razão social (até 120 caracteres) |
cpf_cnpj | texto | opcional | CPF ou CNPJ válido (com ou sem máscara; gravado só com dígitos). Duplicado → 409 (até 20 caracteres) |
email | texto | opcional | E-mail válido (até 150 caracteres) |
phone | texto | opcional | DDD + número (gravado só com dígitos) (até 30 caracteres) |
telefones_extras | lista | opcional | Lista de telefones auxiliares (substitui os atuais) |
cep | texto | opcional | 8 dígitos (até 12 caracteres) |
street | texto | opcional | (até 160 caracteres) |
number | texto | opcional | (até 20 caracteres) |
complement | texto | opcional | (até 120 caracteres) |
neighborhood | texto | opcional | (até 120 caracteres) |
city | texto | opcional | (até 80 caracteres) |
uf | texto | opcional | Sigla do estado (até 2 caracteres) |
cnh_registro | texto | opcional | (até 30 caracteres) |
cnh_categoria | texto | opcional | Ex.: AB (até 5 caracteres) |
cnh_validade | data | opcional | |
cnh_emissao | data | opcional | |
cnh_primeira_habilitacao | data | opcional | |
rg | texto | opcional | (até 30 caracteres) |
birth_date | data | opcional | |
civil_status | texto | opcional | (até 40 caracteres) |
profession | texto | opcional | (até 120 caracteres) |
reference_point | texto | opcional | (até 255 caracteres) |
neighbors | lista | opcional | Até 3 vizinhos [{"name":"…","phone":"…"}] |
witness_neighbors | lista | opcional | Até 3 testemunhas [{"name":"…","phone":"…"}] |
Erros possíveis: 422 validacao (lista todos os campos), 409 conflito (estado não permite), 403, 404, 415.
RequisiçãoTestar ▸
curl -X POST "https://apimapogos.sixinformatica.com/v1/clientes" \
-H "Authorization: Bearer $MAPOGOS_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"name":"Maria Fernanda Souza","cpf_cnpj":"529.982.247-25","phone":"(91) 99876-5432","email":"maria@exemplo.com.br","cep":"66000-000","city":"Belém","uf":"PA"}'<?php
$ch = curl_init('https://apimapogos.sixinformatica.com/v1/clientes');
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . getenv('MAPOGOS_API_KEY'),
'Content-Type: application/json',
'Idempotency-Key: ' . bin2hex(random_bytes(16)),
],
CURLOPT_POSTFIELDS => json_encode([
'name' => 'Maria Fernanda Souza',
'cpf_cnpj' => '529.982.247-25',
'phone' => '(91) 99876-5432',
'email' => 'maria@exemplo.com.br',
'cep' => '66000-000',
'city' => 'Belém',
'uf' => 'PA',
]),
]);
$resposta = json_decode(curl_exec($ch), true);
$http = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
if ($resposta['sucesso']) {
print_r($resposta['dados']);
} else {
echo $resposta['erro']['mensagem'];
}const resposta = await fetch('https://apimapogos.sixinformatica.com/v1/clientes', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.MAPOGOS_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"name": "Maria Fernanda Souza",
"cpf_cnpj": "529.982.247-25",
"phone": "(91) 99876-5432",
"email": "maria@exemplo.com.br",
"cep": "66000-000",
"city": "Belém",
"uf": "PA"
}),
});
const json = await resposta.json();
if (json.sucesso) console.log(json.dados);
else console.error(json.erro.mensagem);import os, uuid, requests
resposta = requests.request(
"POST",
"https://apimapogos.sixinformatica.com/v1/clientes",
headers={"Authorization": f"Bearer {os.environ['MAPOGOS_API_KEY']}",
"Idempotency-Key": str(uuid.uuid4())},
json={
"name": "Maria Fernanda Souza",
"cpf_cnpj": "529.982.247-25",
"phone": "(91) 99876-5432",
"email": "maria@exemplo.com.br",
"cep": "66000-000",
"city": "Belém",
"uf": "PA"
},
timeout=30,
)
json = resposta.json()
print(json["dados"] if json["sucesso"] else json["erro"]["mensagem"])Resposta201 Created
{
"sucesso": true,
"dados": {
"id": 1024,
"name": "Maria Fernanda Souza",
"cpf_cnpj": "52998224725",
"cpf": "52998224725",
"rg": "1234567",
"birth_date": "2026-10-15",
"civil_status": "texto",
"profession": "texto"
},
"request_id": "req_6c5b4a3f2e1d0c9b8a7f"
}PATCH Atualizar cliente
Atualizar cliente (parcial). Requer atualizar.
Corpo da requisição (JSON)
| Campo | Tipo | Regras | |
|---|---|---|---|
name | texto | opcional | Nome completo / razão social (até 120 caracteres) |
cpf_cnpj | texto | opcional | CPF ou CNPJ válido (com ou sem máscara; gravado só com dígitos). Duplicado → 409 (até 20 caracteres) |
email | texto | opcional | E-mail válido (até 150 caracteres) |
phone | texto | opcional | DDD + número (gravado só com dígitos) (até 30 caracteres) |
telefones_extras | lista | opcional | Lista de telefones auxiliares (substitui os atuais) |
cep | texto | opcional | 8 dígitos (até 12 caracteres) |
street | texto | opcional | (até 160 caracteres) |
number | texto | opcional | (até 20 caracteres) |
complement | texto | opcional | (até 120 caracteres) |
neighborhood | texto | opcional | (até 120 caracteres) |
city | texto | opcional | (até 80 caracteres) |
uf | texto | opcional | Sigla do estado (até 2 caracteres) |
cnh_registro | texto | opcional | (até 30 caracteres) |
cnh_categoria | texto | opcional | Ex.: AB (até 5 caracteres) |
cnh_validade | data | opcional | |
cnh_emissao | data | opcional | |
cnh_primeira_habilitacao | data | opcional | |
rg | texto | opcional | (até 30 caracteres) |
birth_date | data | opcional | |
civil_status | texto | opcional | (até 40 caracteres) |
profession | texto | opcional | (até 120 caracteres) |
reference_point | texto | opcional | (até 255 caracteres) |
neighbors | lista | opcional | Até 3 vizinhos [{"name":"…","phone":"…"}] |
witness_neighbors | lista | opcional | Até 3 testemunhas [{"name":"…","phone":"…"}] |
Erros possíveis: 422 validacao (lista todos os campos), 409 conflito (estado não permite), 403, 404, 415.
RequisiçãoTestar ▸
curl -X PATCH "https://apimapogos.sixinformatica.com/v1/clientes/1024" \
-H "Authorization: Bearer $MAPOGOS_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"phone":"(91) 98888-7777","city":"Ananindeua"}'<?php
$ch = curl_init('https://apimapogos.sixinformatica.com/v1/clientes/1024');
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'PATCH',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . getenv('MAPOGOS_API_KEY'),
'Content-Type: application/json',
'Idempotency-Key: ' . bin2hex(random_bytes(16)),
],
CURLOPT_POSTFIELDS => json_encode([
'phone' => '(91) 98888-7777',
'city' => 'Ananindeua',
]),
]);
$resposta = json_decode(curl_exec($ch), true);
$http = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
if ($resposta['sucesso']) {
print_r($resposta['dados']);
} else {
echo $resposta['erro']['mensagem'];
}const resposta = await fetch('https://apimapogos.sixinformatica.com/v1/clientes/1024', {
method: 'PATCH',
headers: {
Authorization: `Bearer ${process.env.MAPOGOS_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"phone": "(91) 98888-7777",
"city": "Ananindeua"
}),
});
const json = await resposta.json();
if (json.sucesso) console.log(json.dados);
else console.error(json.erro.mensagem);import os, uuid, requests
resposta = requests.request(
"PATCH",
"https://apimapogos.sixinformatica.com/v1/clientes/1024",
headers={"Authorization": f"Bearer {os.environ['MAPOGOS_API_KEY']}",
"Idempotency-Key": str(uuid.uuid4())},
json={
"phone": "(91) 98888-7777",
"city": "Ananindeua"
},
timeout=30,
)
json = resposta.json()
print(json["dados"] if json["sucesso"] else json["erro"]["mensagem"])Resposta200 OK
{
"sucesso": true,
"dados": {
"id": 1024,
"name": "Maria Fernanda Souza",
"cpf_cnpj": "52998224725",
"cpf": "52998224725",
"rg": "1234567",
"birth_date": "2026-10-15",
"civil_status": "texto",
"profession": "texto"
},
"request_id": "req_6c5b4a3f2e1d0c9b8a7f"
}Recursos incluídos neste módulo
Estes recursos usam a mesma permissão de Clientes:
| Rota | Recurso | Descrição | Campos |
|---|---|---|---|
/v1/clientes_documentos | Documentos do cliente | Metadados de documentos anexados ao cliente (CNH, comprovantes). | id, client_id, doc_type, file_name, mime_type, size_bytes, match_status, match_score … |
Eventos de webhook
cliente.criado cliente.atualizado — veja Webhooks.