# Volta

> Volta é um sistema de reembolso de despesas pelo WhatsApp para empresas brasileiras: o colaborador manda a foto da nota, a IA lê, o gestor aprova e o financeiro paga. Esta API deixa outros sistemas (contabilidade, ERP, automações) lerem os reembolsos e receberem avisos em tempo real.

## Documentação
- [Guia para desenvolvedores](https://voltareembolso.com.br/desenvolvedores): autenticação, endpoints, paginação, webhooks e como conferir a assinatura.
- [Especificação OpenAPI 3.1](https://voltareembolso.com.br/openapi.json): todos os endpoints e formatos, em JSON.
- [Perguntas frequentes](https://voltareembolso.com.br/perguntas-frequentes)
- [Status do serviço](https://voltareembolso.com.br/status)

## Resumo da API (v1)
- Base: https://voltareembolso.com.br/api/v1
- Autenticação: cabeçalho `Authorization: Bearer vlt_live_<chave>`. As chaves são criadas pelo administrador da empresa no painel, em Integrações. Cada chave só enxerga a própria empresa.
- Somente leitura (GET). Respostas em JSON em português. Erros: `{"erro":{"codigo":"...","mensagem":"..."}}`.
- Limite: 120 pedidos por minuto por chave (HTTP 429 com Retry-After).
- GET /me · GET /reembolsos · GET /reembolsos/{id} · GET /colaboradores · GET /categorias · GET /centros-de-custo
- /reembolsos aceita: status (pendente, em_analise, aprovado, recusado, pago, cancelado), desde, ate, pago_desde, pago_ate (AAAA-MM-DD), centro_de_custo, categoria, colaborador (uuid), limite (1 a 200) e cursor. A resposta traz `dados` e `proximo_cursor` (null na última página).
- Dados pessoais (e-mail, WhatsApp, chave Pix) e links de comprovante só vêm em chaves criadas com essa permissão.

## Webhooks
- O administrador cadastra um endereço https em Integrações e escolhe os eventos: reembolso.criado, reembolso.em_analise, reembolso.aprovado, reembolso.recusado, reembolso.pago, reembolso.cancelado.
- O Volta envia POST com JSON `{ "id", "tipo", "criado_em", "dados": { "reembolso": {...} } }` e os cabeçalhos Volta-Event, Volta-Delivery e Volta-Signature.
- Assinatura: `Volta-Signature: t=<segundos>,v1=<hex>`, onde hex = HMAC-SHA256 de "<t>.<corpo bruto>" com o segredo do endereço (whsec_…). Recuse eventos com t a mais de 5 minutos do horário atual.
- Responda com status 2xx em até 8 segundos. Sem sucesso, o Volta tenta de novo depois de 1 min, 5 min, 30 min, 2 h e 12 h. Use o campo `id` para ignorar eventos repetidos.