{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-parceiros/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["admonition"]},"type":"markdown"},"seo":{"title":"Quickstart","description":"APIs públicas da Movvia para parceiros, estabelecimentos comerciais e clientes de dados veiculares.","meta":[{"name":"theme-color","content":"#7E3DEE"},{"name":"apple-mobile-web-app-title","content":"Movvia Docs"},{"name":"application-name","content":"Movvia Docs"}],"llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"quickstart","__idx":0},"children":["Quickstart"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Tempo estimado:"]}," 20 minutos."," ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Pré-requisito:"]}," credenciais de sandbox. Solicite em ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"mailto:comercial@movvia.com.br"},"children":["comercial@movvia.com.br"]}," com nome, empresa e caso de uso — resposta em minutos úteis."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"passo-1--configurar-o-ambiente","__idx":1},"children":["Passo 1 — Configurar o ambiente"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Exporte as credenciais no terminal:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"export MV_KEY=\"<seu_client_id_base64:client_secret>\"\nexport MV_PARCEIRO_ID=\"\"   # preencher no próximo passo\nexport BASE_URL=\"https://hml.api.pedagioeletronico.com.br/gestao-webhooks-api/v1\"\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"success","name":"Codificar credenciais"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Se recebeu ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["client_id"]}," e ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["client_secret"]}," separados:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"export MV_KEY=$(echo -n \"client_id:client_secret\" | base64)\n","lang":"bash"},"children":[]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"passo-2--descobrir-o-parceiroid","__idx":2},"children":["Passo 2 — Descobrir o parceiroId"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl \"$BASE_URL/me\" \\\n  -H \"Authorization: Basic $MV_KEY\"\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Resposta esperada:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"parceiroId\": \"par_7f3a1b2c\",\n  \"nome\": \"Sua Empresa Ltda\",\n  \"modo\": \"FILTRADO\",\n  \"status\": \"ativo\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Exporte o ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["parceiroId"]},":"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"export MV_PARCEIRO_ID=\"par_7f3a1b2c\"\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"passo-3--cadastrar-uma-placa","__idx":3},"children":["Passo 3 — Cadastrar uma placa"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -X POST \"$BASE_URL/placas\" \\\n  -H \"Authorization: Basic $MV_KEY\" \\\n  -H \"x-parceiro-id: $MV_PARCEIRO_ID\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"placa\":\"ABC1D23\",\"metadata\":{\"cliente_id\":\"teste_001\"}}'\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Resposta esperada:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"success\": true,\n  \"data\": {\n    \"placaId\": \"plc_9f2c7e1a\",\n    \"placa\": \"ABC1D23\",\n    \"criadoEm\": \"2026-04-24T14:32:10Z\"\n  }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"passo-4--expor-um-endpoint-de-webhook-local","__idx":4},"children":["Passo 4 — Expor um endpoint de webhook local"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://ngrok.com"},"children":["ngrok"]}," ou ferramenta equivalente para expor um endpoint local:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"# Em um terminal separado\nngrok http 3000\n# Copie a URL HTTPS exibida, ex: https://abc123.ngrok.io\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Crie um servidor mínimo para receber o webhook:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"typescript","header":{"controls":{"copy":{}}},"source":"import express from 'express';\nimport crypto from 'crypto';\n\nconst app = express();\napp.use(express.json());\n\napp.post('/webhook', (req, res) => {\n  const sig = req.headers['x-movvia-signature'] as string;\n  const payload = JSON.stringify(req.body);\n  const expected = crypto\n    .createHmac('sha256', process.env.MV_WEBHOOK_SECRET!)\n    .update(payload, 'utf8')\n    .digest('hex');\n\n  if (!crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected))) {\n    return res.status(401).send('Assinatura inválida');\n  }\n\n  console.log('Evento recebido:', JSON.stringify(req.body, null, 2));\n  res.status(200).send('OK');\n});\n\napp.listen(3000, () => console.log('Webhook ouvindo na porta 3000'));\n","lang":"typescript"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Informe a URL do webhook no onboarding ou via ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"mailto:comercial@movvia.com.br"},"children":["comercial@movvia.com.br"]},"."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"passo-5--disparar-um-evento-de-teste","__idx":5},"children":["Passo 5 — Disparar um evento de teste"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["No sandbox, use o endpoint de simulação para gerar uma passagem sintética:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -X POST \"$BASE_URL/sandbox/simular-passagem\" \\\n  -H \"Authorization: Basic $MV_KEY\" \\\n  -H \"x-parceiro-id: $MV_PARCEIRO_ID\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"placa\":\"ABC1D23\",\"valor\":12.50,\"praca\":\"KM 245 — Imigrantes\"}'\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Em segundos, seu servidor local deve logar:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"evento\": \"pe.transacao.recebida\",\n  \"versao\": \"2\",\n  \"id\": \"evt_8f3a1b2c\",\n  \"dados\": {\n    \"placa\": \"ABC1D23\",\n    \"valor\": 12.50,\n    \"praca\": \"KM 245 — Imigrantes\"\n  }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"próximos-passos","__idx":6},"children":["Próximos passos"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/parceiros/tutorials/validar-hmac"},"children":["Validar HMAC em detalhes"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/parceiros/tutorials/confirmar-pedido"},"children":["Confirmar um pedido"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/apis/parceiros/openapi"},"children":["Referência da API"]}]}]}]},"headings":[{"value":"Quickstart","id":"quickstart","depth":1},{"value":"Passo 1 — Configurar o ambiente","id":"passo-1--configurar-o-ambiente","depth":2},{"value":"Passo 2 — Descobrir o parceiroId","id":"passo-2--descobrir-o-parceiroid","depth":2},{"value":"Passo 3 — Cadastrar uma placa","id":"passo-3--cadastrar-uma-placa","depth":2},{"value":"Passo 4 — Expor um endpoint de webhook local","id":"passo-4--expor-um-endpoint-de-webhook-local","depth":2},{"value":"Passo 5 — Disparar um evento de teste","id":"passo-5--disparar-um-evento-de-teste","depth":2},{"value":"Próximos passos","id":"próximos-passos","depth":2}],"frontmatter":{"title":"Quickstart — Parceiros Movvia","description":"Do zero ao primeiro webhook recebido em 20 minutos. Sandbox, primeira placa e evento de passagem.","seo":{"title":"Quickstart"}},"lastModified":"2026-04-25T15:17:56.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/parceiros/tutorials/quickstart","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}