MapogosAPI Docs
/
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étodoUsoPermissão
POST /v1/{modulo}CriarCriar
PATCH /v1/{modulo}/{id}Atualizar só os campos enviadosAtualizar
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çãoResultado
Mesma chave e mesmo corpo em até 24hDevolve a resposta original, com o cabeçalho Idempotent-Replayed: true
Mesma chave e corpo diferente409 idempotencia_conflito
Chave novaExecuta 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 cliente
Testar ▸
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"}'

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çãoO que o Mapogos faz junto (igual ao painel)
Baixa de pagamentoCancela o PIX pendente correspondente, reinicia o ciclo de cobrança e envia o recibo ao cliente
Cancelar pagamentoRemove a cobrança e cancela o PIX no banco; registra o motivo na auditoria
Criar acordoCancela débitos/PIX pendentes do contrato e envia ao cliente o acordo e o PIX da 1ª parcela
Abrir/concluir OSColoca o veículo em manutenção / libera o veículo e notifica
Peça na OSBaixa do estoque, respeitando o intervalo mínimo de troca da peça
Registrar multaCalcula 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.