Operação · Referência

Vistorias

Vistorias 360° de entrada/saída: KM, avarias por área, fotos e análise de IA.

Permissão: vistoriasAções: ler · criar · atualizar · exportar2 campo(s) LGPD

GET/v1/vistoriasListar GET/v1/vistorias/{id}Detalhar GET/v1/vistorias/{id}/avariasRelação: Avarias da vistoria GET/v1/vistorias/{id}/fotosRelação: Fotos da vistoria GET/v1/vistorias/{id}/veiculoRelação: Veículos GET/v1/vistorias/{id}/locacaoRelação: Locações GET/v1/vistorias/exportarExportar em lote POST/v1/vistoriasAbrir vistoria PATCH/v1/vistorias/{id}Atualizar vistoria / validar

O objeto vistorias

Campo	Tipo	Descrição
`id`	inteiro	Identificador	ordenar
`vehicle_id`	inteiro	ID do veículo	filtro
`rental_id`	inteiro	ID da locação	filtro
`client_id`	inteiro	ID do cliente	filtro
`client_cpf`	texto	client cpf	LGPD
`client_name`	texto	client name	LGPD
`plate`	texto	Placa	filtro
`km_atual`	inteiro	km atual
`km_ultima_troca_oleo`	inteiro	km ultima troca oleo
`km_excedente`	inteiro	km excedente
`multa_km_alerta`	decimal (string)	multa km alerta
`inspector_user_id`	inteiro	inspector user id
`inspector_name`	texto	inspector name
`observacoes`	texto	observacoes
`ia_summary_json`	objeto	ia summary json
`ia_custo_total`	decimal (string)	ia custo total
`ia_processed_at`	data-hora	ia processed at
`has_avarias`	booleano	has avarias	filtro
`status`	texto (enum)	Situação `rascunho` `aberta` `validada` `arquivada`	filtro
`validada_por`	inteiro	validada por
`validada_em`	data-hora	validada em
`created_at`	data-hora	Criado em	ordenar
`updated_at`	data-hora	Atualizado em	ordenar

Exemplo do objeto200 OK

{
    "id": 1024,
    "vehicle_id": 512,
    "rental_id": 512,
    "client_id": 512,
    "client_cpf": "52998224725",
    "client_name": "Maria Fernanda Souza",
    "plate": "ABC1D23",
    "km_atual": 45210,
    "km_ultima_troca_oleo": 45210,
    "km_excedente": 45210,
    "multa_km_alerta": "150.00",
    "inspector_user_id": 512,
    "inspector_name": "Carlos",
    "observacoes": "Entrega sem avarias",
    "ia_summary_json": {},
    "ia_custo_total": "450.00",
    "ia_processed_at": "2026-10-08T14:30:00-03:00",
    "has_avarias": false,
    "status": "rascunho",
    "validada_por": 1,
    "validada_em": "2026-10-08T14:30:00-03:00",
    "created_at": "2026-10-08T14:30:00-03:00",
    "updated_at": "2026-10-08T14:30:00-03:00"
}

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`, `created_at`, `updated_at` — prefixo `-` para decrescente
`campos`	texto	Lista de campos do objeto, separados por vírgula
`status`	texto (enum)	Situação — valor exato ou lista separada por vírgula `rascunho` `aberta` `validada` `arquivada`
`vehicle_id`	inteiro	ID do veículo — valor exato ou lista separada por vírgula
`rental_id`	inteiro	ID da locação — valor exato ou lista separada por vírgula
`client_id`	inteiro	ID do cliente — valor exato ou lista separada por vírgula
`plate`	texto	Placa — valor exato ou lista separada por vírgula
`has_avarias`	booleano	has avarias — 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 (pela coluna de atualização)
`incluir`	texto	Só no detalhe. Relações: `avarias`, `fotos`, `veiculo`, `locacao`

Requisição

Testar ▸

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

<?php
$ch = curl_init('https://apimapogos.sixinformatica.com/v1/vistorias?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/vistorias?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/vistorias?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,
            "vehicle_id": 512,
            "rental_id": 512,
            "client_id": 512,
            "client_cpf": "52998224725",
            "client_name": "Maria Fernanda Souza",
            "plate": "ABC1D23",
            "km_atual": 45210
        }
    ],
    "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/vistorias/1024?incluir=avarias" \
  -H "Authorization: Bearer $MAPOGOS_API_KEY"

<?php
$ch = curl_init('https://apimapogos.sixinformatica.com/v1/vistorias/1024?incluir=avarias');
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/vistorias/1024?incluir=avarias', {
  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/vistorias/1024?incluir=avarias",
    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,
        "vehicle_id": 512,
        "rental_id": 512,
        "client_id": 512,
        "client_cpf": "52998224725",
        "client_name": "Maria Fernanda Souza",
        "plate": "ABC1D23",
        "km_atual": 45210
    },
    "request_id": "req_1d2c3b4a5f6e7d8c9b0a"
}

Relações

Nome	Módulo	Retorno	Rota
`avarias`	Avarias da vistoria	lista paginada	`/v1/vistorias/{id}/avarias`
`fotos`	Fotos da vistoria	lista paginada	`/v1/vistorias/{id}/fotos`
`veiculo`	Veículos	um registro	`/v1/vistorias/{id}/veiculo`
`locacao`	Locações	um registro	`/v1/vistorias/{id}/locacao`

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/vistorias/exportar?limite=1000" \
  -H "Authorization: Bearer $MAPOGOS_API_KEY"

<?php
$ch = curl_init('https://apimapogos.sixinformatica.com/v1/vistorias/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/vistorias/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/vistorias/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 Abrir vistoria

Abrir vistoria (dados e avarias; fotos pelo painel). Requer criar.

Corpo da requisição (JSON)

Campo	Tipo		Regras
`vehicle_id`	inteiro	obrigatório
`rental_id`	inteiro	opcional
`km_atual`	inteiro	obrigatório
`km_ultima_troca_oleo`	inteiro	opcional
`inspector_name`	texto	opcional	(até 120 caracteres)
`observacoes`	texto	opcional	(até 5000 caracteres)
`status`	enum	opcional	`rascunho` `aberta` `validada` `arquivada`
`avarias`	lista	opcional	[{area, area_label, descricao}] — substitui a lista atual

Erros possíveis: 422 validacao (lista todos os campos), 409 conflito (estado não permite), 403, 404, 415.

Requisição

Testar ▸

curl -X POST "https://apimapogos.sixinformatica.com/v1/vistorias" \
  -H "Authorization: Bearer $MAPOGOS_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"vehicle_id":512,"km_atual":45310,"observacoes":"Entrega ao cliente","avarias":[{"area":"para_choque_dianteiro","area_label":"Para-choque dianteiro","descricao":"Risco leve"}]}'

<?php
$ch = curl_init('https://apimapogos.sixinformatica.com/v1/vistorias');
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([
    'vehicle_id' => 512,
    'km_atual' => 45310,
    'observacoes' => 'Entrega ao cliente',
    'avarias' => [
      [
        'area' => 'para_choque_dianteiro',
        'area_label' => 'Para-choque dianteiro',
        'descricao' => 'Risco leve',
      ],
    ],
  ]),
]);
$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/vistorias', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.MAPOGOS_API_KEY}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': crypto.randomUUID(),
  },
  body: JSON.stringify({
      "vehicle_id": 512,
      "km_atual": 45310,
      "observacoes": "Entrega ao cliente",
      "avarias": [
          {
              "area": "para_choque_dianteiro",
              "area_label": "Para-choque dianteiro",
              "descricao": "Risco leve"
          }
      ]
  }),
});
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/vistorias",
    headers={"Authorization": f"Bearer {os.environ['MAPOGOS_API_KEY']}",
             "Idempotency-Key": str(uuid.uuid4())},
    json={
        "vehicle_id": 512,
        "km_atual": 45310,
        "observacoes": "Entrega ao cliente",
        "avarias": [
            {
                "area": "para_choque_dianteiro",
                "area_label": "Para-choque dianteiro",
                "descricao": "Risco leve"
            }
        ]
    },
    timeout=30,
)
json = resposta.json()
print(json["dados"] if json["sucesso"] else json["erro"]["mensagem"])

Resposta201 Created

{
    "sucesso": true,
    "dados": {
        "id": 1024,
        "vehicle_id": 512,
        "rental_id": 512,
        "client_id": 512,
        "client_cpf": "52998224725",
        "client_name": "Maria Fernanda Souza",
        "plate": "ABC1D23",
        "km_atual": 45210
    },
    "request_id": "req_6c5b4a3f2e1d0c9b8a7f"
}

PATCH Atualizar vistoria / validar

Atualizar vistoria / validar. Requer atualizar.

Corpo da requisição (JSON)

Campo	Tipo		Regras
`vehicle_id`	inteiro	opcional
`rental_id`	inteiro	opcional
`km_atual`	inteiro	opcional
`km_ultima_troca_oleo`	inteiro	opcional
`inspector_name`	texto	opcional	(até 120 caracteres)
`observacoes`	texto	opcional	(até 5000 caracteres)
`status`	enum	opcional	`rascunho` `aberta` `validada` `arquivada`
`avarias`	lista	opcional	[{area, area_label, descricao}] — substitui a lista atual

Erros possíveis: 422 validacao (lista todos os campos), 409 conflito (estado não permite), 403, 404, 415.

Requisição

Testar ▸

curl -X PATCH "https://apimapogos.sixinformatica.com/v1/vistorias/1024" \
  -H "Authorization: Bearer $MAPOGOS_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"status":"validada"}'

<?php
$ch = curl_init('https://apimapogos.sixinformatica.com/v1/vistorias/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([
    'status' => 'validada',
  ]),
]);
$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/vistorias/1024', {
  method: 'PATCH',
  headers: {
    Authorization: `Bearer ${process.env.MAPOGOS_API_KEY}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': crypto.randomUUID(),
  },
  body: JSON.stringify({
      "status": "validada"
  }),
});
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/vistorias/1024",
    headers={"Authorization": f"Bearer {os.environ['MAPOGOS_API_KEY']}",
             "Idempotency-Key": str(uuid.uuid4())},
    json={
        "status": "validada"
    },
    timeout=30,
)
json = resposta.json()
print(json["dados"] if json["sucesso"] else json["erro"]["mensagem"])

Resposta200 OK

{
    "sucesso": true,
    "dados": {
        "id": 1024,
        "vehicle_id": 512,
        "rental_id": 512,
        "client_id": 512,
        "client_cpf": "52998224725",
        "client_name": "Maria Fernanda Souza",
        "plate": "ABC1D23",
        "km_atual": 45210
    },
    "request_id": "req_6c5b4a3f2e1d0c9b8a7f"
}

Recursos incluídos neste módulo

Estes recursos usam a mesma permissão de Vistorias:

Rota	Recurso	Descrição	Campos
`/v1/vistorias_avarias`	Avarias da vistoria	Áreas do veículo verificadas e avarias encontradas.	`id`, `vistoria_id`, `area`, `area_label`, `tem_avaria`, `descricao`, `created_at`
`/v1/vistorias_fotos`	Fotos da vistoria	Metadados das fotos da vistoria.	`id`, `vistoria_id`, `categoria`, `file_size`, `uploaded_at`
`/v1/vistorias_entrada_saida`	Vistorias simples (legado)	Vistorias de entrada/saída do formulário antigo.	`id`, `rental_id`, `vehicle_id`, `plate`, `inspection_type`, `inspection_mode`, `status`, `fuel_level` …

Eventos de webhook

vistoria.concluida — veja Webhooks.