Skip to content
/
Liquidação
Last updated

Liquidação

Liquidação é o processo de associar passagens a um pedido, cobrar seu cliente e confirmar o pagamento à Movvia. Os três endpoints principais são POST /pedidos, POST /pedidos/{id}/confirmar e POST /pedidos/{id}/cancelar.

Criar um pedido

Agrupe as passagens que deseja liquidar em um pedido. Use sempre uma idempotencyKey única por operação.

curl -X POST https://hml.api.pedagioeletronico.com.br/gestao-webhooks-api/v1/pedidos \
  -H "Authorization: Basic $MV_KEY" \
  -H "x-parceiro-id: $MV_PARCEIRO_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "transacoes": ["t_9f2c7e1a", "t_3b8d4f2e"],
    "idempotencyKey": "ord_20260424_001"
  }'

Resposta:

{
  "pedidoId": "ped_a1b2c3d4",
  "status": "pendente",
  "valor": 25.00,
  "transacoes": ["t_9f2c7e1a", "t_3b8d4f2e"],
  "criadoEm": "2026-04-24T10:00:00Z"
}

Confirmar um pedido

Após cobrar seu cliente com sucesso, confirme o pagamento:

curl -X POST https://hml.api.pedagioeletronico.com.br/gestao-webhooks-api/v1/pedidos/ped_a1b2c3d4/confirmar \
  -H "Authorization: Basic $MV_KEY" \
  -H "x-parceiro-id: $MV_PARCEIRO_ID" \
  -H "Content-Type: application/json" \
  -d '{"idempotencyKey": "conf_20260424_001"}'

Resposta:

{
  "pedidoId": "ped_a1b2c3d4",
  "status": "confirmado",
  "confirnadoEm": "2026-04-24T10:05:00Z"
}

Cancelar um pedido

Cancele se não conseguir cobrar o cliente ou se houver erro no seu fluxo:

curl -X POST https://hml.api.pedagioeletronico.com.br/gestao-webhooks-api/v1/pedidos/ped_a1b2c3d4/cancelar \
  -H "Authorization: Basic $MV_KEY" \
  -H "x-parceiro-id: $MV_PARCEIRO_ID" \
  -H "Content-Type: application/json" \
  -d '{"motivo": "falha_cobranca", "idempotencyKey": "canc_20260424_001"}'

Máquina de estados

pendente → confirmado
pendente → cancelado
confirmado → (terminal, sem transição)
cancelado → (terminal, sem transição)

Pedidos em estado terminal não aceitam novas transições. Tentar confirmar ou cancelar um pedido já confirmado retorna 409 Conflict.

Prazo para confirmação

Pedidos não confirmados ou cancelados em até 48h são automaticamente cancelados pela plataforma. Um webhook pe.pedidos.expirado é emitido antes da expiração.

Boas práticas
  • Confirme o pedido no mesmo fluxo em que cobra o cliente, não em um job assíncrono.
  • Sempre use idempotencyKey distinta para criação e confirmação do mesmo pedido.
  • Armazene o pedidoId para reconciliação antes de confirmar.
Previous page
Next page