Operação · Referência

Locações

Contratos de locação (aluguel normal/particular) e de venda, com ciclo de cobrança e situação.

Permissão: locacoesAções: ler · exportar1 campo(s) LGPD

O objeto locações

Campo	Tipo	Descrição
`id`	inteiro	Identificador	ordenar
`description`	texto	Descrição
`client_id`	inteiro	ID do cliente	filtro
`vehicle_id`	inteiro	ID do veículo	filtro
`contract_type`	texto (enum)	aluguel_normal \| aluguel_particular \| aluguel \| venda `aluguel` `aluguel_normal` `aluguel_particular` `venda`	filtro
`status`	texto (enum)	Situação `aberta` `ativa` `finalizada` `cancelada` `atrasada` `encerrado` `pendente`	filtro
`active`	booleano	Ativo (1/0)	filtro
`fleet_type`	texto (enum)	Carteira (mapogos \| premium) `mapogos` `premium`	filtro
`start_datetime`	data-hora	start datetime	ordenar
`expected_return`	data-hora	expected return	ordenar
`actual_return`	data-hora	actual return
`km_start`	inteiro	km start
`km_end`	inteiro	km end
`payment_type`	texto (enum)	payment type `mensal` `semanal` `diario`	filtro
`recurring_value`	decimal (string)	recurring value
`recurring_amount`	decimal (string)	Valor da parcela recorrente
`daily_rate`	decimal (string)	daily rate
`deposit`	decimal (string)	deposit
`deposit_value`	decimal (string)	deposit value
`deposit_amount`	decimal (string)	deposit amount
`total`	decimal (string)	total
`num_installments`	inteiro	num installments
`pay_weekday`	inteiro	pay weekday
`pay_monthday`	inteiro	pay monthday
`payment_day_week`	inteiro	payment day week
`payment_day_month`	inteiro	payment day month
`bridge_days`	inteiro	bridge days
`bridge_charged`	booleano	bridge charged
`auto_charge`	booleano	auto charge
`charge_step`	inteiro	Etapa do ciclo de cobrança (1–3)	filtro
`next_charge_at`	data-hora	next charge at	ordenar
`last_charge_at`	data-hora	last charge at
`blocked`	booleano	blocked
`autoblock_immune_until`	data-hora	Imune ao bloqueio automático até esta data
`revenue_hidden`	inteiro	1 = receita oculta dos relatórios
`contact_phone`	texto	contact phone	LGPD
`notes`	texto	Observações
`created_at`	data-hora	Criado em	ordenar
`log_origem`	texto	Origem do registro (sistema novo/antigo)

Exemplo do objeto200 OK

{
    "id": 1024,
    "description": "Aluguel semanal",
    "client_id": 512,
    "vehicle_id": 512,
    "contract_type": "aluguel",
    "status": "aberta",
    "active": false,
    "fleet_type": "mapogos",
    "start_datetime": "2026-10-08T14:30:00-03:00",
    "expected_return": "2026-10-08T14:30:00-03:00",
    "actual_return": "2026-10-08T14:30:00-03:00",
    "km_start": 45210,
    "km_end": 45210,
    "payment_type": "mensal",
    "recurring_value": "150.00",
    "recurring_amount": "150.00",
    "daily_rate": "150.00",
    "deposit": "150.00",
    "deposit_value": "150.00",
    "deposit_amount": "150.00",
    "total": "450.00",
    "num_installments": 1,
    "pay_weekday": 1,
    "pay_monthday": 1,
    "payment_day_week": 1,
    "payment_day_month": 1,
    "bridge_days": 1,
    "bridge_charged": false,
    "auto_charge": false,
    "charge_step": 1,
    "next_charge_at": "2026-10-08T14:30:00-03:00",
    "last_charge_at": "2026-10-08T14:30:00-03:00",
    "blocked": false,
    "autoblock_immune_until": "2026-10-08T14:30:00-03:00",
    "revenue_hidden": 1,
    "contact_phone": "91998765432",
    "notes": "Cliente pediu boleto",
    "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`, `start_datetime`, `expected_return`, `created_at`, `next_charge_at` — prefixo `-` para decrescente
`campos`	texto	Lista de campos do objeto, separados por vírgula
`q`	texto	Busca em: `description`
`status`	texto (enum)	Situação — valor exato ou lista separada por vírgula `aberta` `ativa` `finalizada` `cancelada` `atrasada` `encerrado` `pendente`
`active`	booleano	Ativo (1/0) — valor exato ou lista separada por vírgula
`contract_type`	texto (enum)	aluguel_normal \| aluguel_particular \| aluguel \| venda — valor exato ou lista separada por vírgula `aluguel` `aluguel_normal` `aluguel_particular` `venda`
`payment_type`	texto (enum)	payment type — valor exato ou lista separada por vírgula `mensal` `semanal` `diario`
`fleet_type`	texto (enum)	Carteira (mapogos \| premium) — valor exato ou lista separada por vírgula `mapogos` `premium`
`client_id`	inteiro	ID do cliente — valor exato ou lista separada por vírgula
`vehicle_id`	inteiro	ID do veículo — valor exato ou lista separada por vírgula
`charge_step`	inteiro	Etapa do ciclo de cobrança (1–3) — 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: `cliente`, `veiculo`, `pagamentos`, `acordos`, `multas`, `vistorias`, `encerramento`, `contatos`, `contratos`, `cobrancas_pix`

Requisição

Testar ▸

curl -X GET "https://apimapogos.sixinformatica.com/v1/locacoes?por_pagina=20" \
  -H "Authorization: Bearer $MAPOGOS_API_KEY"

<?php
$ch = curl_init('https://apimapogos.sixinformatica.com/v1/locacoes?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/locacoes?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/locacoes?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,
            "description": "Aluguel semanal",
            "client_id": 512,
            "vehicle_id": 512,
            "contract_type": "aluguel",
            "status": "aberta",
            "active": false,
            "fleet_type": "mapogos"
        }
    ],
    "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ção

Testar ▸

curl -X GET "https://apimapogos.sixinformatica.com/v1/locacoes/1024?incluir=cliente" \
  -H "Authorization: Bearer $MAPOGOS_API_KEY"

<?php
$ch = curl_init('https://apimapogos.sixinformatica.com/v1/locacoes/1024?incluir=cliente');
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/locacoes/1024?incluir=cliente', {
  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/locacoes/1024?incluir=cliente",
    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,
        "description": "Aluguel semanal",
        "client_id": 512,
        "vehicle_id": 512,
        "contract_type": "aluguel",
        "status": "aberta",
        "active": false,
        "fleet_type": "mapogos"
    },
    "request_id": "req_1d2c3b4a5f6e7d8c9b0a"
}

Relações

Nome	Módulo	Retorno	Rota
`cliente`	Clientes	um registro	`/v1/locacoes/{id}/cliente`
`veiculo`	Veículos	um registro	`/v1/locacoes/{id}/veiculo`
`pagamentos`	Pagamentos	lista paginada	`/v1/locacoes/{id}/pagamentos`
`acordos`	Acordos	lista paginada	`/v1/locacoes/{id}/acordos`
`multas`	Multas	lista paginada	`/v1/locacoes/{id}/multas`
`vistorias`	Vistorias	lista paginada	`/v1/locacoes/{id}/vistorias`
`encerramento`	Encerramento & Pós-Encerramento	lista paginada	`/v1/locacoes/{id}/encerramento`
`contatos`	Contatos de referência da locação	lista paginada	`/v1/locacoes/{id}/contatos`
`contratos`	Documentos de contrato	lista paginada	`/v1/locacoes/{id}/contratos`
`cobrancas_pix`	Cobranças PIX	lista paginada	`/v1/locacoes/{id}/cobrancas_pix`

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ção

Testar ▸

curl -X GET "https://apimapogos.sixinformatica.com/v1/locacoes/exportar?limite=1000" \
  -H "Authorization: Bearer $MAPOGOS_API_KEY"

<?php
$ch = curl_init('https://apimapogos.sixinformatica.com/v1/locacoes/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/locacoes/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/locacoes/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"])

Recursos incluídos neste módulo

Estes recursos usam a mesma permissão de Locações:

Rota	Recurso	Descrição	Campos
`/v1/locacoes_contatos`	Contatos de referência da locação	Familiares/referências informados no contrato.	`id`, `rental_id`, `client_id`, `position`, `name`, `phone`, `relation`, `created_at`
`/v1/locacoes_contratos`	Documentos de contrato	Contratos gerados para assinatura (situação e datas). O link/token de assinatura e a assinatura em si nunca são expostos.	`id`, `rental_id`, `contract_type`, `status`, `client_name`, `client_cpf`, `client_phone`, `signed_at` …

Eventos de webhook

locacao.criada locacao.encerrada — veja Webhooks.