{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-parceiros/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["admonition"]},"type":"markdown"},"seo":{"title":"Confirmar um pedido","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":"confirmar-um-pedido","__idx":0},"children":["Confirmar um pedido"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Este tutorial cobre o fluxo de liquidação do início ao fim: receber o evento de passagem, criar um pedido, cobrar o cliente e confirmar o pagamento."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Pré-requisito:"]}," ambiente configurado conforme o ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/parceiros/tutorials/quickstart"},"children":["Quickstart"]},"."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"passo-1--receber-o-evento-de-passagem","__idx":1},"children":["Passo 1 — Receber o evento de passagem"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Quando uma passagem é capturada, a Movvia entrega um webhook no seu endpoint:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"evento\": \"pe.transacao.recebida\",\n  \"id\": \"evt_8f3a1b2c\",\n  \"dados\": {\n    \"transacaoId\": \"t_9f2c7e1a\",\n    \"placa\": \"ABC1D23\",\n    \"valor\": 12.50,\n    \"praca\": \"KM 245 — Imigrantes\",\n    \"criadoEm\": \"2026-04-24T09:58:00Z\"\n  }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Armazene o ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["transacaoId"]}," para usar na criação do pedido."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"passo-2--criar-o-pedido","__idx":2},"children":["Passo 2 — Criar o pedido"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Agrupe uma ou mais transações em um pedido. Use uma ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["idempotencyKey"]}," única:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -X POST \"$BASE_URL/pedidos\" \\\n  -H \"Authorization: Basic $MV_KEY\" \\\n  -H \"x-parceiro-id: $MV_PARCEIRO_ID\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"transacoes\": [\"t_9f2c7e1a\"],\n    \"idempotencyKey\": \"ord_20260424_ABC1D23_001\"\n  }'\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Resposta:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"pedidoId\": \"ped_a1b2c3d4\",\n  \"status\": \"pendente\",\n  \"valor\": 12.50,\n  \"transacoes\": [\"t_9f2c7e1a\"],\n  \"criadoEm\": \"2026-04-24T10:00:00Z\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Armazene o ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["pedidoId"]}," antes de prosseguir."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"passo-3--cobrar-o-cliente","__idx":3},"children":["Passo 3 — Cobrar o cliente"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Execute o débito no seu sistema (saldo, pontos, PIX, cartão). Este passo é interno ao seu produto — a Movvia não participa."]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"success","name":"Sequência crítica"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Crie o pedido ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["apenas após"]}," receber o evento confirmado. Confirme o pedido ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["somente quando"]}," a cobrança for bem-sucedida no seu lado."]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"passo-4--confirmar-o-pagamento","__idx":4},"children":["Passo 4 — Confirmar o pagamento"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Após débito bem-sucedido, confirme o pedido:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -X POST \"$BASE_URL/pedidos/ped_a1b2c3d4/confirmar\" \\\n  -H \"Authorization: Basic $MV_KEY\" \\\n  -H \"x-parceiro-id: $MV_PARCEIRO_ID\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"idempotencyKey\": \"conf_ped_a1b2c3d4\"}'\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Resposta:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"pedidoId\": \"ped_a1b2c3d4\",\n  \"status\": \"confirmado\",\n  \"confirmadoEm\": \"2026-04-24T10:05:00Z\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"passo-5--tratar-falha-na-cobrança","__idx":5},"children":["Passo 5 — Tratar falha na cobrança"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Se não conseguir cobrar o cliente, cancele o pedido:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -X POST \"$BASE_URL/pedidos/ped_a1b2c3d4/cancelar\" \\\n  -H \"Authorization: Basic $MV_KEY\" \\\n  -H \"x-parceiro-id: $MV_PARCEIRO_ID\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"motivo\": \"falha_cobranca\", \"idempotencyKey\": \"canc_ped_a1b2c3d4\"}'\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"fluxo-completo-em-código","__idx":6},"children":["Fluxo completo em código"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"typescript","header":{"controls":{"copy":{}}},"source":"async function liquidarTransacao(transacaoId: string, placa: string) {\n  const idempotencyKey = `ord_${Date.now()}_${placa}`;\n\n  // Criar pedido\n  const pedidoRes = await fetch(`${BASE_URL}/pedidos`, {\n    method: 'POST',\n    headers: {\n      'Authorization': `Basic ${process.env.MV_KEY}`,\n      'x-parceiro-id': process.env.MV_PARCEIRO_ID!,\n      'Content-Type': 'application/json',\n    },\n    body: JSON.stringify({ transacoes: [transacaoId], idempotencyKey }),\n  });\n  const pedido = await pedidoRes.json();\n\n  // Cobrar cliente (lógica interna do seu produto)\n  const cobrado = await cobrarCliente(placa, pedido.valor);\n\n  if (cobrado) {\n    // Confirmar\n    await fetch(`${BASE_URL}/pedidos/${pedido.pedidoId}/confirmar`, {\n      method: 'POST',\n      headers: {\n        'Authorization': `Basic ${process.env.MV_KEY}`,\n        'x-parceiro-id': process.env.MV_PARCEIRO_ID!,\n        'Content-Type': 'application/json',\n      },\n      body: JSON.stringify({ idempotencyKey: `conf_${pedido.pedidoId}` }),\n    });\n  } else {\n    // Cancelar\n    await fetch(`${BASE_URL}/pedidos/${pedido.pedidoId}/cancelar`, {\n      method: 'POST',\n      headers: {\n        'Authorization': `Basic ${process.env.MV_KEY}`,\n        'x-parceiro-id': process.env.MV_PARCEIRO_ID!,\n        'Content-Type': 'application/json',\n      },\n      body: JSON.stringify({\n        motivo: 'falha_cobranca',\n        idempotencyKey: `canc_${pedido.pedidoId}`,\n      }),\n    });\n  }\n}\n","lang":"typescript"},"children":[]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"próximos-passos","__idx":7},"children":["Próximos passos"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/parceiros/tutorials/lidar-com-erros"},"children":["Lidar com erros"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/parceiros/guides/idempotencia"},"children":["Guia de idempotência"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/apis/parceiros/openapi"},"children":["Referência da API"]}]}]}]},"headings":[{"value":"Confirmar um pedido","id":"confirmar-um-pedido","depth":1},{"value":"Passo 1 — Receber o evento de passagem","id":"passo-1--receber-o-evento-de-passagem","depth":2},{"value":"Passo 2 — Criar o pedido","id":"passo-2--criar-o-pedido","depth":2},{"value":"Passo 3 — Cobrar o cliente","id":"passo-3--cobrar-o-cliente","depth":2},{"value":"Passo 4 — Confirmar o pagamento","id":"passo-4--confirmar-o-pagamento","depth":2},{"value":"Passo 5 — Tratar falha na cobrança","id":"passo-5--tratar-falha-na-cobrança","depth":2},{"value":"Fluxo completo em código","id":"fluxo-completo-em-código","depth":2},{"value":"Próximos passos","id":"próximos-passos","depth":2}],"frontmatter":{"title":"Confirmar um pedido — Parceiros Movvia","description":"Fluxo completo de criação e confirmação de pedido de liquidação com idempotência na API de Parceiros Movvia.","seo":{"title":"Confirmar um pedido"}},"lastModified":"2026-04-25T15:17:56.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/parceiros/tutorials/confirmar-pedido","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}