Skip to content
/
Quickstart
Last updated

Quickstart

Tempo estimado: 20 minutos. Pré-requisito: credenciais de sandbox. Solicite em comercial@movvia.com.br com nome, empresa e caso de uso — resposta em minutos úteis.

Passo 1 — Configurar o ambiente

Exporte as credenciais no terminal:

export MV_KEY="<seu_client_id_base64:client_secret>"
export MV_PARCEIRO_ID=""   # preencher no próximo passo
export BASE_URL="https://hml.api.pedagioeletronico.com.br/gestao-webhooks-api/v1"
Codificar credenciais

Se recebeu client_id e client_secret separados:

export MV_KEY=$(echo -n "client_id:client_secret" | base64)

Passo 2 — Descobrir o parceiroId

curl "$BASE_URL/me" \
  -H "Authorization: Basic $MV_KEY"

Resposta esperada:

{
  "parceiroId": "par_7f3a1b2c",
  "nome": "Sua Empresa Ltda",
  "modo": "FILTRADO",
  "status": "ativo"
}

Exporte o parceiroId:

export MV_PARCEIRO_ID="par_7f3a1b2c"

Passo 3 — Cadastrar uma placa

curl -X POST "$BASE_URL/placas" \
  -H "Authorization: Basic $MV_KEY" \
  -H "x-parceiro-id: $MV_PARCEIRO_ID" \
  -H "Content-Type: application/json" \
  -d '{"placa":"ABC1D23","metadata":{"cliente_id":"teste_001"}}'

Resposta esperada:

{
  "success": true,
  "data": {
    "placaId": "plc_9f2c7e1a",
    "placa": "ABC1D23",
    "criadoEm": "2026-04-24T14:32:10Z"
  }
}

Passo 4 — Expor um endpoint de webhook local

Use ngrok ou ferramenta equivalente para expor um endpoint local:

# Em um terminal separado
ngrok http 3000
# Copie a URL HTTPS exibida, ex: https://abc123.ngrok.io

Crie um servidor mínimo para receber o webhook:

import express from 'express';
import crypto from 'crypto';

const app = express();
app.use(express.json());

app.post('/webhook', (req, res) => {
  const sig = req.headers['x-movvia-signature'] as string;
  const payload = JSON.stringify(req.body);
  const expected = crypto
    .createHmac('sha256', process.env.MV_WEBHOOK_SECRET!)
    .update(payload, 'utf8')
    .digest('hex');

  if (!crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected))) {
    return res.status(401).send('Assinatura inválida');
  }

  console.log('Evento recebido:', JSON.stringify(req.body, null, 2));
  res.status(200).send('OK');
});

app.listen(3000, () => console.log('Webhook ouvindo na porta 3000'));

Informe a URL do webhook no onboarding ou via comercial@movvia.com.br.

Passo 5 — Disparar um evento de teste

No sandbox, use o endpoint de simulação para gerar uma passagem sintética:

curl -X POST "$BASE_URL/sandbox/simular-passagem" \
  -H "Authorization: Basic $MV_KEY" \
  -H "x-parceiro-id: $MV_PARCEIRO_ID" \
  -H "Content-Type: application/json" \
  -d '{"placa":"ABC1D23","valor":12.50,"praca":"KM 245 — Imigrantes"}'

Em segundos, seu servidor local deve logar:

{
  "evento": "pe.transacao.recebida",
  "versao": "2",
  "id": "evt_8f3a1b2c",
  "dados": {
    "placa": "ABC1D23",
    "valor": 12.50,
    "praca": "KM 245 — Imigrantes"
  }
}

Próximos passos

Previous page
Next page