Guia
Gravar dados e idempotência
Criar, atualizar e executar ações (como dar baixa em um pagamento) seguindo as mesmas regras das telas do Mapogos.
Métodos
| Método | Uso | Permissão |
|---|---|---|
POST /v1/{modulo} | Criar | Criar |
PATCH /v1/{modulo}/{id} | Atualizar só os campos enviados | Atualizar |
POST /v1/{modulo}/{id}/{acao} | Ações (baixa, concluir OS…) | conforme a ação |
DELETE /v1/{modulo}/{id} | Excluir/cancelar (quando o módulo permite) | Excluir |
Idempotência: reenvie sem medo
Envie em todo POST/PATCH/DELETE o cabeçalho Idempotency-Key com um valor único por operação (ex.: um UUID ou o id do pedido no seu sistema).
| Situação | Resultado |
|---|---|
| Mesma chave e mesmo corpo em até 24h | Devolve a resposta original, com o cabeçalho Idempotent-Replayed: true |
| Mesma chave e corpo diferente | 409 idempotencia_conflito |
| Chave nova | Executa normalmente |
✓
Por que isso importa
Se a rede cair depois que o Mapogos gravou mas antes de você receber a resposta, o reenvio não duplica cobrança, cliente ou OS.
Atualizar o telefone de um clienteTestar ▸
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"}'<?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',
]),
]);
$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"
}),
});
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"
},
timeout=30,
)
json = resposta.json()
print(json["dados"] if json["sucesso"] else json["erro"]["mensagem"])Validação
Campos são validados por tipo, tamanho, formato (CPF/CNPJ com dígito verificador, placa, e-mail, telefone, CEP, datas) e existência de registros relacionados. Erros voltam todos juntos em 422. Campos que não existem na operação também são apontados.
Regras de negócio
| Operação | O que o Mapogos faz junto (igual ao painel) |
|---|---|
| Baixa de pagamento | Cancela o PIX pendente correspondente, reinicia o ciclo de cobrança e envia o recibo ao cliente |
| Cancelar pagamento | Remove a cobrança e cancela o PIX no banco; registra o motivo na auditoria |
| Criar acordo | Cancela débitos/PIX pendentes do contrato e envia ao cliente o acordo e o PIX da 1ª parcela |
| Abrir/concluir OS | Coloca o veículo em manutenção / libera o veículo e notifica |
| Peça na OS | Baixa do estoque, respeitando o intervalo mínimo de troca da peça |
| Registrar multa | Calcula taxa administrativa e roda a automação de multas |
i
Auditoria
Toda gravação feita pela API fica registrada no histórico do Mapogos com o nome da chave que a fez.