# Quickstart

**Tempo estimado:** 20 minutos.
**Pré-requisito:** credenciais de sandbox. Solicite em [comercial@movvia.com.br](mailto: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:


```bash
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:


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

## Passo 2 — Descobrir o parceiroId


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

Resposta esperada:


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

Exporte o `parceiroId`:


```bash
export MV_PARCEIRO_ID="par_7f3a1b2c"
```

## Passo 3 — Cadastrar uma placa


```bash
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:


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

## Passo 4 — Expor um endpoint de webhook local

Use [ngrok](https://ngrok.com) ou ferramenta equivalente para expor um endpoint local:


```bash
# 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:


```typescript
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](mailto: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:


```bash
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:


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

## Próximos passos

- [Validar HMAC em detalhes](/parceiros/tutorials/validar-hmac)
- [Confirmar um pedido](/parceiros/tutorials/confirmar-pedido)
- [Referência da API](/apis/parceiros/openapi)