# VPN Pay — Documentação de integração (API pública v1)

Documento público e somente leitura. Nenhuma operação financeira é executada a partir
desta página: toda chamada real exige chave de API autenticada sobre o endereço base.

- Endereço base: `https://vpnpay.com.br/api/public/v1`
- Contrato legível por máquina: `https://vpnpay.com.br/api/public/v1/openapi.json`
- Modelos WhatsApp: `GET https://vpnpay.com.br/api/public/v1/connect/templates?accountId=UUID` (permissão `connect:templates:read`) `POST https://vpnpay.com.br/api/public/v1/connect/templates` e `DELETE https://vpnpay.com.br/api/public/v1/connect/templates/{name}?accountId=UUID` (`connect:templates:write`).
- Para criar: corpo `{ "accountId": "UUID", "template": { "name": "segunda_via", "language": "pt_BR", "category": "UTILITY", "components": [{ "type": "BODY", "text": "Sua segunda via está disponível para consulta." }] } }`, com `Idempotency-Key`. A WABA vem exclusivamente da conexão autorizada. Modelos são compartilhados entre números da mesma WABA, nunca entre WABAs distintas. Não informe WABA/token no pedido.
- Criação retorna `data.template.id/status/category`; aguarde `APPROVED` na lista antes de enviar. `data.ok=false` inclui `providerHttpStatus` e códigos seguros. HTTP 202/409 incerto: consulte a lista antes de outra tentativa. Não há repetição automática.
- Lista aceita `limit` (1–100) e `after`, retornando `data.templates` e `data.after`. São suportados UTILITY/MARKETING, HEADER TEXT, BODY com exemplos por variável, FOOTER e até 3 botões QUICK_REPLY/URL/PHONE_NUMBER/COPY_CODE. AUTHENTICATION (código de verificação): `category:"AUTHENTICATION"`, `components:[{type:"BODY",add_security_recommendation:true},{type:"FOOTER",code_expiration_minutes:10},{type:"BUTTONS",buttons:[{type:"OTP",otp_type:"COPY_CODE",text:"Copiar código"}]}]`; para enviar, use `message.otpCode` no POST /connect/messages. A chave existente não recebe novas permissões automaticamente: crie uma chave com as duas permissões de modelos.
- Esta versão em texto: `https://vpnpay.com.br/api/public/v1/docs.md`

---

## 1. Fundamentos

| Item | Valor |
| --- | --- |
| Formato | JSON em pedido e resposta (`application/json; charset=utf-8`) |
| Valores | Sempre inteiros em centavos. R$ 12,34 = `1234` |
| Moeda | `currency` com 3 letras, padrão `BRL` |
| Versão | No caminho (`/v1`). Campos novos podem surgir; ignore o que não conhecer |
| Rastreio | Toda resposta traz `request_id` |

Envelope de sucesso:

```json
{ "success": true, "data": { "id": "8f0c…", "object": "payment" }, "error": null, "code": null, "message": null, "request_id": "0f7f1a7c-…" }
```

Envelope de erro:

```json
{ "success": false, "data": null, "error": "invalid_request", "code": "invalid_request", "message": "Campo amount deve ser inteiro positivo em centavos", "request_id": "0f7f1a7c-…" }
```

Exceção única: `GET /openapi.json` devolve o documento OpenAPI puro, sem envelope.

## 2. Autenticação e permissões

```http
Authorization: Bearer vpnp_live_9f2a1c4d7b.5c1e…segredo
Content-Type: application/json
```

- O cliente (tenant) é sempre identificado pela chave. `tenant_id` enviado no corpo é ignorado.
- O segredo aparece uma única vez, na criação ou rotação da chave.
- Escopo por unidade: `merchant_scope = ALL` (todas as unidades) ou `SELECTED` (apenas as
  unidades listadas). `SELECTED` sem nenhuma unidade vinculada **bloqueia** a consulta —
  não existe acesso amplo por omissão.
- Recurso de outra unidade ou de outro cliente devolve **404 neutro** (anti-enumeração).

| Permissão (scope) | O que libera |
| --- | --- |
| `connect:send` | Enviar WhatsApp (VPN Connect) |
| `connect:read` | Consultar status de WhatsApp |
| `connect:templates:read` | Consultar modelos WhatsApp da WABA |
| `connect:templates:write` | Criar modelos WhatsApp na WABA |
| `fiscal:read` | Consultar notas fiscais e documentos recebidos |
| `fiscal:write` | Emitir notas fiscais e registrar eventos |
| `payments:read` | Consultar cobranças |
| `payments:write` | Criar cobranças |
| `recipients:read` | Consultar recebedores |
| `recipients:write` | Cadastrar recebedores |
| `payouts:read` | Consultar repasses |
| `payouts:write` | Solicitar repasses |
| `refunds:read` | Consultar devoluções |
| `refunds:write` | Criar devoluções |
| `balances:read` | Consultar saldos |
| `reconciliation:read` | Consultar conciliação |
| `webhooks:manage` | Gerenciar avisos (webhooks) |
| `delivery:read` | Consultar entregas |
| `delivery:write` | Solicitar entregas |
| `fleet:read` | Consultar entregas da frota própria |
| `fleet:write` | Registrar entregas da frota própria |
| `fleet_invoices:read` | Consultar faturas de repasse da frota |
| `merchants:read` | Consultar unidades |
| `merchants:write` | Cadastrar unidades e vincular recebedor |

| Situação | HTTP | code |
| --- | --- | --- |
| Chave ausente, inválida, revogada ou expirada | 401 | `unauthorized` |
| Chave válida sem o scope exigido | 403 | `forbidden` |
| Cliente inativo/arquivado tentando escrever | 403 | `forbidden` |

## 3. Idempotência

Obrigatória em todo POST. Cabeçalho `Idempotency-Key`, mínimo de 8 caracteres.

- Mesma chave + mesmo corpo: devolve a mesma resposta, sem criar nova operação.
- Mesma chave + corpo diferente: `409 idempotency_conflict`.
- Chave isolada por cliente e por endpoint. Derive-a do seu pedido, não de um valor
  aleatório por tentativa.

### VPN Connect — WhatsApp

- POST `/connect/messages` exige `connect:send`; GET `/connect/messages/{messageId}` exige `connect:read`.
- Autentique com Authorization: Bearer ou x-api-key, usando uma chave VPN Pay (nunca o token Meta).
- Envio exige Idempotency-Key com 8–100 caracteres, accountId e apenas um destinatário: to (E.164) ou recipientIndex (0–4).
- Exemplo de corpo: `{ "accountId": "UUID_DA_CONTA", "recipientIndex": 1, "message": { "type": "text", "text": "Teste de envio VPN Connect" } }`.
- Templates: message com type template, name, language e bodyParams opcionais; aprovação pela Meta é necessária.
- Modelos com imagem: crie com HEADER format IMAGE e example.header_url [link HTTPS JPG/PNG]; no envio informe message.headerImageUrl.
- Conta precisa pertencer ao cliente da chave e à unidade autorizada; conta sem unidade exige ALL. Nunca amplia o tenant.
- Para conta sem unidade, crie chave dedicada ALL apenas com connect:send/connect:read. Não amplie a chave financeira SELECTED da Tropical.
- TEST só envia a destinatários homologados; texto livre só dentro das 24h após a última mensagem recebida.
- Credencial real cifrada da conta é obrigatória. Não existe endpoint de exportação do token.
- HTTP 201 indica aceite Meta; 200 repetição sem envio; 202 indica queued/unknown (não repetir). 422 indica bloqueio ou falha.
- Confira data.ok, messageId, status, waMessageId e errorCode. A consulta traz o status atualizado pelo webhook Meta (sent/delivered/read/failed).
- Não há encaminhamento dos eventos WhatsApp ao webhook da Tropical nesta versão; use a consulta de status.
- Mesma chave com conteúdo diferente retorna 409. Resultado incerto nunca libera repetição automática.

## 4. Cadastro e mapeamento da sua base (obrigatório antes da primeira chamada)

| Método | Caminho | Scope | Observação |
| --- | --- | --- | --- |
| GET | `/merchants?external_reference=LOJA-001` | `merchants:read` | Só unidades autorizadas pela chave |
| GET | `/merchants/{id}` | `merchants:read` | 404 neutro fora do escopo |
| POST | `/merchants` | `merchants:write` | Exige chave `ALL`; `external_reference` único (409) |
| PATCH | `/merchants/{id}` | `merchants:write` | Só `name` e `recipient_id`; status nunca pela API |
| GET | `/recipients?external_reference=REC-001` | `recipients:read` | Busca pelo seu código |
| POST | `/recipients` | `recipients:write` | Idempotente; chave `SELECTED` exige `merchant_id` |

```json
POST /merchants            (Idempotency-Key: loja-LOJA-001)
{ "name": "Loja Centro (exemplo)", "external_reference": "LOJA-001" }

POST /recipients           (Idempotency-Key: rec-REC-001)
{ "type": "COMPANY", "legal_name": "Loja Centro Ltda (exemplo)", "document_type": "CNPJ",
  "document_number": "11222333000181", "external_reference": "REC-001",
  "merchant_id": "0b6f6a3e-1c2d-4e5f-8a9b-1234567890ab" }

PATCH /merchants/0b6f6a3e-1c2d-4e5f-8a9b-1234567890ab   (Idempotency-Key: link-LOJA-001)
{ "recipient_id": "5d1c…" }
```

1. Cada loja do seu sistema = uma **unidade** (`merchant_id`). Guarde o UUID ao lado do seu código
   (`external_reference`) ou consulte por ele a qualquer momento.
2. Correlacione cada pedido pelo `external_reference` da cobrança.
3. O recebedor (`recipient_id`) recebe o líquido. Ele nasce `PENDING`; **KYC e aprovação são
   feitos no painel** e não podem ser contornados pela API. Sem aprovação não há repasse.
4. Chave `SELECTED` só vê e altera recursos das suas unidades (cobranças, repasses,
   devoluções, recebedores ligados, entregas, frota). Saldo consolidado (`/balances`),
   conciliação e regras de frota para todas as unidades exigem chave `ALL` (403).

**Dependem do painel da VPN Pay (sem API de escrita):** criação/rotação de chaves e escolha das
unidades de cada chave (unidade nova criada pela API não entra sozinha em chave `SELECTED`);
ativação/suspensão de unidade; KYC e aprovação de recebedores; chaves Pix e contas bancárias;
conexões de provedores de pagamento e de logística; tetos de adiantamento do frete no cartão;
importação/conciliação/quitação da fatura mensal do parceiro logístico; endereço de webhook.

## 5. Gateway — cobranças Pix (Pix In)

| Método | Caminho | Scope |
| --- | --- | --- |
| POST | `/payments` | `payments:write` |
| GET | `/payments` | `payments:read` |
| GET | `/payments/{id}` | `payments:read` |

| Campo | Tipo | Obrigatório | Observação |
| --- | --- | --- | --- |
| `amount` | inteiro (centavos) | sim | Maior que zero |
| `currency` | string(3) | não | Padrão `BRL` |
| `payer.name` | string | sim | Nome de quem paga |
| `payer.document` | string | sim | CPF ou CNPJ válido |
| `payer.email` | string | não | |
| `merchant_id` | uuid | não | Unidade comercial |
| `recipient_id` | uuid | não | Recebedor do líquido |
| `external_reference` | string | não | Seu número de pedido |
| `metadata` | objeto | não | Devolvido na consulta |
| `provider_connection_id` | uuid | não | Ausente = Smart Routing escolhe |
| `expires_in_minutes` | inteiro ≥ 5 | não | Padrão 60 |

```bash
curl -X POST https://vpnpay.com.br/api/public/v1/payments \
  -H "Authorization: Bearer $VPNPAY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pedido-1042-pagamento-1" \
  -d '{"amount":4990,"external_reference":"pedido-1042","expires_in_minutes":30,
       "payer":{"name":"Maria Souza","document":"12345678909","email":"maria@exemplo.com"}}'
```

```json
{ "success": true,
  "data": { "id": "8f0c2f1e-…", "object": "payment", "status": "PENDING", "amount": 4990,
            "currency": "BRL", "external_reference": "pedido-1042",
            "br_code": "00020126…5802BR…", "qr_code": "data:image/png;base64,iVBORw0K…",
            "expires_at": "2026-10-01T22:30:00.000Z" },
  "error": null, "code": null, "message": null, "request_id": "…" }
```

Estados: `CREATED`, `PENDING`, `PROCESSING`, `PAID`, `FAILED`, `CANCELED`,
`EXPIRED`, `UNKNOWN`, `RECONCILIATION_REQUIRED`. Libere o pedido **somente** em `PAID`.
`UNKNOWN` nunca deve ser tratado como pago nem gerar nova cobrança.

### 5.1 Cobrança por cartão (checkout HOSTED)

O mesmo `POST /payments` com `method: "CARD"`. Sem `method`, a chamada continua Pix.

**Arquitetura do primeiro pagamento.** O cliente digita o cartão **somente na página
segura do provedor** (`checkout_url`). A API da VPN Pay recusa número, CVV, validade e
token de cartão com `400 CARD_DATA_NOT_ACCEPTED`; nem a VPN Pay nem o seu sistema recebem
esses dados. Isso não é declaração de conformidade PCI do seu ambiente: apenas o cartão
não passa por ele. Pagamentos recorrentes com token não fazem parte desta versão.

| Campo | Obrigatório | Observação |
| --- | --- | --- |
| `method` | sim | `CARD` |
| `checkout` | sim | `HOSTED` (único modo) |
| `amount`, `currency` | sim / não | Centavos; só `BRL` |
| `payer.name`, `payer.document`, `payer.email` | sim | Titular da cobrança |
| `installments` | não | Padrão 1; limitado pela política e pelo provedor |
| `merchant_id` | recomendado | Unidade; chave `SELECTED` só cria para unidade autorizada |
| `external_reference` | recomendado | Seu número de pedido |
| `success_url` | não | https; destino do navegador após pagar |
| `provider_connection_id` | não | Ausente = roteamento escolhe conexão com cartão |

```bash
curl -X POST https://vpnpay.com.br/api/public/v1/payments \
  -H "Authorization: Bearer $VPNPAY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pedido-1043-cartao-1" \
  -d '{"method":"CARD","checkout":"HOSTED","amount":5890,"installments":1,
       "merchant_id":"0f1e2d3c-…","external_reference":"pedido-1043",
       "success_url":"https://loja.exemplo.com/pedido/1043",
       "payer":{"name":"Maria Souza","document":"12345678909","email":"maria@exemplo.com"}}'
```

```json
{ "success": true,
  "data": { "id": "5b7c…", "object": "payment", "method": "CARD", "status": "PENDING",
            "amount": 5890, "currency": "BRL", "external_reference": "pedido-1043",
            "checkout": "HOSTED", "checkout_url": "https://<pagina-segura-do-provedor>/…",
            "provider_result": "CREATED",
            "card": { "installments": 1, "customer_charged_amount": 5890, "brand": null, "last4": null } },
  "error": null, "code": null, "message": null, "request_id": "…" }
```

**Estados e confirmação.** `PENDING` (página emitida) → `PROCESSING` (autorizado ou em
análise de risco — **pré-autorização não é pagamento**) → `PAID` (captura confirmada pelo
provedor; o líquido da loja fica **a receber**). A liquidação futura do adquirente libera
somente o líquido e gera `payment.settled`. Recusa: `FAILED`. O retorno do navegador
(`success_url`) **não** comprova pagamento — aguarde `payment.paid` ou consulte
`GET /payments/{id}`. "Recebido em dinheiro" declarado fora do provedor vira
`RECONCILIATION_REQUIRED` e nunca vale como pagamento.

**Timeout.** Se o provedor não responder, a resposta é `202` com `provider_result: "UNKNOWN"`
e `checkout_url: null`. Não crie outra cobrança: repita com a **mesma** `Idempotency-Key` ou
consulte `GET /payments/{id}`. Não há troca automática de conexão após resultado incerto.

**Entrega com cartão.** `POST /deliveries/quotes` (pré-checkout) → `POST /payments` CARD →
`payment.paid` → `POST /deliveries/{id}/funding` com `funding_source: ONLINE_ORDER_CARD` e
`payment_id` → `/dispatch`. A reserva sai apenas do recebível daquele pagamento, sem esperar
a compensação, dentro do teto de exposição definido pela VPN Pay (desligado até a liberação).

**Parcelas e total.** O número de parcelas pedido é conferido contra a regra de parcelamento
da VPN Pay (cliente e unidade) e o limite do provedor; o total cobrado é calculado pela VPN Pay.
Se o valor confirmado pelo provedor não bater com esse total, o pagamento **não** vira `PAID`:
fica em `RECONCILIATION_REQUIRED`, sem lançamento e sem liberação.

**Devolução e contestação.** `POST /refunds` sobre o `payment_id`. Com entrega custeada pelo
pedido, só é possível devolver até *pago − já devolvido − valor da entrega retido ou
reconhecido*; acima disso a resposta é recusada (o custo da entrega nunca volta por estorno).
Contestação (chargeback) avisada pelo provedor gera `payment.chargeback`
(`chargeback_status: OPENED`) e **congela a liberação** do recebível daquele pedido; só o
que esse recebível não cobre é bloqueado no saldo disponível da **mesma loja**, e qualquer
falta fica registrada na disputa. Reservas de entrega não são tocadas. A reversão gera
`payment.chargeback` com `REVERSED` e libera apenas o que aquela disputa bloqueou.

| HTTP | code (reason) | Quando |
| --- | --- | --- |
| 400 | `CARD_DATA_NOT_ACCEPTED` | Corpo com número, CVV, validade ou token de cartão |
| 400 | `CARD_CHECKOUT_REQUIRED` | `method: CARD` sem `checkout: HOSTED` |
| 400/422 | `INVALID_INSTALLMENTS` | Parcelas inválidas, acima da regra de parcelamento ou do limite do provedor |
| 422 | `CARD_CHECKOUT_UNSUPPORTED` | Nenhuma conexão elegível com checkout seguro de cartão |
| 422 | `CARD_CHARGE_REFUSED` | Provedor recusou a criação da cobrança |

**Provedores suportados.** Cartão: Asaas (página de pagamento do próprio Asaas), até 12x.
Woovi: somente Pix. Dependências habilitadas no painel: conexão Asaas ativa com cartão
verificado, aviso (webhook) do Asaas configurado, tarifa comercial de cartão vigente e
política de parcelas. Recebimento: na Tropical as cobranças entram na conta VPN e o
repasse semanal sai da conta VPN para a conta da loja.

## 6. Gateway — repasses Pix (Pix Out)

| Método | Caminho | Scope |
| --- | --- | --- |
| POST | `/payouts` | `payouts:write` |
| GET | `/payouts` / `/payouts/{id}` | `payouts:read` |

Campos: `recipient_id` (uuid, obrigatório), `pix_key_id` (uuid de chave Pix ativa,
obrigatório), `amount` (centavos, obrigatório), `currency`, `merchant_id`,
`provider_connection_id`.

- Só o saldo **AVAILABLE** do recebedor pode virar repasse; o valor é reservado no pedido e
  devolvido ao disponível se o repasse falhar.
- O monitoramento de risco é consultado antes do provedor. Recebedor bloqueado gera status
  `BLOCKED`, sem acionar provedor e sem reservar saldo — trate como pendência, não falha.

## 7. Gateway — devoluções

| Método | Caminho | Scope |
| --- | --- | --- |
| POST | `/refunds` | `refunds:write` |
| GET | `/refunds` / `/refunds/{id}` | `refunds:read` |

`payment_id`, `amount` (igual ao pago = total; menor = parcial), `reason` e
`liabilities[]` (quem assume; a soma precisa ser exatamente igual a `amount`).

```json
{ "payment_id": "8f0c2f1e-…", "amount": 1500, "reason": "MERCHANT_OUT_OF_STOCK",
  "liabilities": [ { "party": "MERCHANT", "amount": 1500, "recipient_id": "b3c1a2d4-…" } ] }
```

Motivos: `CUSTOMER_CANCEL_BEFORE_DISPATCH`, `CUSTOMER_CANCEL_AFTER_DISPATCH`,
`MERCHANT_OUT_OF_STOCK`, `MERCHANT_CANCEL_AFTER_PICKUP`, `DRIVER_NO_SHOW`,
`DRIVER_FAILURE`, `PLATFORM_ERROR`, `FRAUD`, `DUPLICATE_PAYMENT`.
Partes: `MERCHANT`, `DRIVER`, `PARTNER`, `OTHER`, `PLATFORM` (`recipient_id`
obrigatório quando a parte não é `PLATFORM`).

Divergência entre o registrado e o confirmado pelo provedor não conclui a devolução: ela
fica em `RECONCILIATION_REQUIRED` para conferência.

## 8. Gateway — recebedores e saldos

| Método | Caminho | Scope |
| --- | --- | --- |
| POST / GET | `/recipients` | `recipients:write` / `recipients:read` |
| GET | `/recipients/{id}` | `recipients:read` |
| GET | `/recipients/{id}/balance?currency=BRL` | `balances:read` |
| GET | `/balances` | `balances:read` |

| Estado do saldo | Significado |
| --- | --- |
| `AVAILABLE` | Disponível para repasse agora — único sacável |
| `PENDING` | Confirmado, aguardando liquidação/liberação |
| `BLOCKED` | Retido por risco, disputa, decisão operacional ou reserva de frete |
| `RECEIVABLE` | A receber; nunca sacável |

Chaves Pix e contas bancárias são cadastradas no painel e entram como pendentes até
conferência; a API nunca devolve a chave completa. O recebedor nasce `PENDING` e só recebe
repasse quando `ACTIVE`.

## 9. Entregas com parceiro logístico (Uber Direct — Fase 18)

Modelo financeiro: **o custo da entrega sai do dinheiro do próprio pedido daquela loja**.
Não existe carteira, saldo editável, adiantamento da VPN Pay nem uso de saldo de outro
pedido ou de outra unidade.

| Método | Caminho | Scope |
| --- | --- | --- |
| GET | `/deliveries?limit=20` | `delivery:read` |
| GET | `/deliveries/{id}` | `delivery:read` |
| POST | `/deliveries/quotes` | `delivery:write` |
| POST | `/deliveries/{id}/funding` | `delivery:write` |
| POST | `/deliveries/{id}/dispatch` | `delivery:write` |
| POST | `/deliveries/{id}/cancel` | `delivery:write` |

### 9.1 Cotar (cria a solicitação de entrega)

Dois modos. **Pré-checkout** — cote o frete antes de criar a cobrança, porque ele compõe o
total cobrado do cliente:

```text
cotação pré-checkout → total → POST /payments → payment.paid → funding (com payment_id) → dispatch
```

```http
POST /deliveries/quotes
Idempotency-Key: pedido-1043-cotacao-1

{
  "merchant_id": "3c1d2e4f-5a6b-4c7d-8e9f-0a1b2c3d4e5f",
  "external_reference": "pedido-1043",
  "dropoff": {
    "address": {
      "street": "Rua Cameron",
      "number": "66",
      "complement": "",
      "district": "Miguel Couto",
      "city": "Nova Iguaçu",
      "state": "RJ",
      "postalCode": "26070482",
      "latitude": -22.7089395,
      "longitude": -43.4347412
    },
    "contact": {
      "name": "Diogo",
      "phone": "+5521994977331",
      "instructions": ""
    }
  }
}
```

A cotação pré-checkout **não reserva saldo, não cria custeio e não permite despacho**. A unidade
precisa estar no escopo da chave (senão 404). Crie a cobrança com **o mesmo
`external_reference`** e o mesmo `merchant_id`, somando `data.quote.total` ao pedido, e
custeie antes de `data.quote.expires_at`.

**Legado** — o pedido já existe e define a unidade:

```http
POST /deliveries/quotes
Idempotency-Key: pedido-1042-cotacao-1

{
  "payment_id": "8f0c2f1e-6c1a-4f0b-9f71-1d0f2a3b4c5d",
  "external_reference": "pedido-1042",
  "dropoff": {
    "address": {
      "street": "Rua Cameron",
      "number": "66",
      "complement": "",
      "district": "Miguel Couto",
      "city": "Nova Iguaçu",
      "state": "RJ",
      "postalCode": "26070482",
      "latitude": -22.7089395,
      "longitude": -43.4347412
    },
    "contact": {
      "name": "Diogo",
      "phone": "+5521994977331",
      "instructions": ""
    }
  }
}
```

**Destino (`dropoff`)** — obrigatório nos dois modos: `address.street`, `address.number`,
`address.city`, `address.state` (UF brasileira, 2 letras), `address.postalCode` (8 dígitos sem máscara),
`contact.name` e `contact.phone`. Telefone somente com dígitos (DDD obrigatório), ou internacional
com prefixo `+`. `address.latitude`/`address.longitude` são opcionais, mas devem ser enviadas
juntas como números válidos (-90 a 90 / -180 a 180), nunca null. Complemento, bairro e instruções
são opcionais. Endereço textual/flat não é interpretado: entrada inválida retorna `400 invalid_request`
antes de criar a solicitação ou consultar o parceiro.

Resposta `201`: `data.delivery` (com `checkout_mode` `PRE_CHECKOUT` ou `PAYMENT_FIRST`)
e `data.quote` com `id`, `delivery_cost`, `service_fee`, `total`, `currency`,
`expires_at`. Guarde `data.quote.id` — é obrigatório no custeio.

**Local de retirada (`pickup`, opcional)** — precedência:

1. `pickup` enviado na requisição e válido → sempre usado;
2. `pickup` omitido → endereço padrão da configuração de entregas da unidade;
3. nenhum dos dois → `422 PICKUP_REQUIRED`;
4. `pickup` enviado e inválido → `422 PICKUP_INVALID` (nunca substituído pelo padrão).

```json
"pickup": { "address": { "street": "Av. Exemplo", "number": "100", "district": "Centro",
                         "city": "Nova Iguaçu", "state": "RJ", "postalCode": "26000-000" },
            "contact": { "name": "Loja", "phone": "+5521999990000" } }
```

O endereço resolvido fica congelado na cotação e é reutilizado no despacho.

**Conta de pagamento da entrega** — a configuração da unidade pode usar:

- **Pagamento do pedido (dinâmica)**: sem conta fixa. Entregas custeadas por
  `ONLINE_ORDER_PIX` / `ONLINE_ORDER_CARD` usam a conta da tentativa que
  efetivamente recebeu o pagamento, escolhida pelo roteamento (inclusive após
  failover) — nunca simplesmente a última tentativa. A cotação pré-checkout usa
  o ambiente configurado explicitamente; tarifas dependentes do provedor são
  revalidadas no custeio com a conta real (`409 QUOTE_CHANGED` se mudarem) e a
  conta é conferida de novo antes do despacho. Recusas: `PAYMENT_ATTEMPT_NOT_FOUND`,
  `PAYMENT_ATTEMPT_AMBIGUOUS`, `PAYMENT_CONNECTION_MISMATCH`, `PAYMENT_ENVIRONMENT_MISMATCH`.
- **Conta fixa**: obrigatória para a cobrança avulsa de entrega (Pix Out da conta
  da loja); sem ela a cobrança avulsa retorna `NO_PAYMENT_CONNECTION`.

### 9.2 Custear (reserva o valor no dinheiro do pedido)

```http
POST /deliveries/{id}/funding
Idempotency-Key: pedido-1043-custeio-1

{ "quote_id": "7b2f…", "payment_id": "9a8b…", "funding_source": "ONLINE_ORDER_PIX" }
```

`payment_id` é **obrigatório no pré-checkout** (opcional no legado; se enviado, deve ser o
pedido já vinculado). Antes de reservar qualquer valor, numa única transação, a VPN Pay confere:
cotação desta entrega e ainda válida; pagamento do mesmo tenant, da mesma unidade e com o mesmo
`external_reference`; estado financeiro exigido pela origem; fundos suficientes; nenhum custeio
conflitante. Só então vincula o pagamento e reserva. O vínculo fica **imutável** e um pagamento
custeia no máximo **uma entrega ativa**. Se qualquer verificação falhar, nada é vinculado.

| `code` | HTTP | Quando |
| --- | --- | --- |
| `QUOTE_EXPIRED` | 409 | Cotação vencida — cote de novo |
| `PAYMENT_MERCHANT_MISMATCH` | 422 | Pagamento de outra unidade |
| `PAYMENT_REFERENCE_MISMATCH` | 422 | `external_reference` do pagamento diferente da entrega |
| `DELIVERY_ALREADY_FUNDED` | 409 | Entrega já custeada com outro pagamento |
| `PAYMENT_ALREADY_BOUND` | 409 | Pagamento já custeia outra entrega ativa |
| `PAYMENT_REQUIRED` | 422 | Pré-checkout sem `payment_id` |

| `funding_source` | Origem do dinheiro | Pré-requisitos |
| --- | --- | --- |
| `ONLINE_ORDER_PIX` | Saldo **AVAILABLE** gerado por aquele pedido | Pedido `PAID` e liquidado |
| `ONLINE_ORDER_CARD` | **PENDING** daquele recebível de cartão | Captura comprovada pelo provedor **e** teto de adiantamento habilitado para a unidade |

Distinção essencial do cartão: **captura confirmada** autoriza contratar a entrega mesmo com
o recebível ainda `PENDING`, respeitando o teto de exposição. Pré-autorização isolada não
autoriza nada. A liquidação confirmada pelo adquirente encerra a exposição e libera apenas o
líquido da loja — o frete já foi descontado uma única vez, sem desconto duplicado.

Outros motivos (campo `code` do envelope): `PAYMENT_NOT_CONFIRMED`, `CAPTURE_NOT_CONFIRMED`,
`PROVIDER_CAPTURE_EVIDENCE_MISSING`, `FUNDING_SOURCE_MISMATCH` (422);
`EXPOSURE_NOT_ENABLED`, `EXPOSURE_SINGLE_LIMIT`, `EXPOSURE_LIMIT_REACHED`,
`INSUFFICIENT_BALANCE` (402). Sem custeio válido, `/dispatch` devolve 409.

### 9.3 Despachar (contrata a corrida no parceiro)

```http
POST /deliveries/{id}/dispatch
Idempotency-Key: pedido-1042-despacho-1
{}
```

Resposta `202`. Timeout ou resposta inconclusiva do parceiro **mantêm a reserva** e
devolvem estado de despacho `TIMEOUT` com o aviso `delivery.dispatch_pending`; nunca
trate como falha nem repita com outra chave de idempotência. A reserva só é devolvida
quando há falha definitiva, sem corrida criada e sem custo devido.

### 9.4 Cancelar

```http
POST /deliveries/{id}/cancel
Idempotency-Key: pedido-1042-cancelamento-1

{ "reason": "customer_canceled" }
```

Sem custo do parceiro, a reserva volta integralmente (para `AVAILABLE` se o recebível já
foi liquidado, senão para `PENDING`). Havendo taxa do parceiro, a entrega fica com
`financial_adjustment: "PENDING_PARTNER_COST"` e o ajuste é concluído no painel mediante
evidência da taxa. Taxa maior que o reservado é recusada (`FEE_EXCEEDS_RESERVATION`) —
nada é debitado em silêncio.

### 9.5 Estados financeiros da entrega

`GET /deliveries/{id}` devolve:

```json
{ "id": "…", "object": "delivery", "merchant_id": "…", "payment_id": "…",
  "checkout_mode": "PRE_CHECKOUT",
  "external_reference": "pedido-1042", "status": "DISPATCHED", "message": null,
  "funding": { "source": "ONLINE_ORDER_CARD", "status": "RESERVED", "amount": 1800,
               "delivery_cost": 1500, "service_fee": 300, "refunded_amount": 0,
               "cancellation_fee": null, "dispatch": "DISPATCHED", "currency": "BRL" } }
```

### 9.6 Obrigação com o parceiro e fatura mensal

O custo vira obrigação (`PAYABLE:LOGISTICS`) **uma única vez**, quando a corrida existe —
não na liquidação do cartão. A fatura mensal do parceiro é importada, conciliada (entrega
cobrada em duas faturas é sinalizada e a segunda quitação é bloqueada) e quitada com
comprovante; diferenças vão para `ADJUSTMENT:LOGISTICS_VARIANCE`. Todo esse ciclo é
executado no painel, não pela API.

## 10. Frota própria — faturas do complemento

| Método | Caminho | Scope |
| --- | --- | --- |
| GET | `/fleet/invoices` | `fleet_invoices:read` |
| GET | `/fleet/invoices/{id_or_number}` | `fleet_invoices:read` |

Paginação estável por cursor: `limit` (1–100, padrão 20) e `starting_after`
(`pagination.next_cursor` da página anterior), ordem fixa `period_end desc, id desc`.
Filtros: `status` (`OPEN`, `OVERDUE`, `IN_REVIEW`, `PAID`, `FUNDED`, `PAYING`,
`SETTLED`) e `merchant_id`. O detalhe aceita o UUID do ciclo ou o número da fatura
(`FAT-2026-00002`). A chave só enxerga as unidades autorizadas nela.

Avisos da fatura: `fleet_invoice.created`, `fleet_invoice.charge_available`,
`fleet_invoice.paid` — um por tipo. Fechamento do ciclo, emissão do complemento e repasse
aos entregadores são operações do painel.

## 11. Avisos automáticos (webhooks)

| Evento | Quando |
| --- | --- |
| `payment.created` | Cobrança criada |
| `payment.paid` | Cobrança paga |
| `payment.failed` | Cobrança falhou |
| `payment.settled` | Recebível liquidado (líquido disponível) |
| `payment.chargeback` | Contestação de cartão aberta ou revertida |
| `refund.created` | Devolução criada |
| `refund.completed` | Devolução concluída |
| `refund.failed` | Devolução falhou |
| `payout.created` | Repasse criado |
| `payout.completed` | Repasse concluído |
| `payout.failed` | Repasse falhou |
| `payout.blocked` | Repasse bloqueado |
| `recipient.updated` | Recebedor atualizado |
| `delivery.requested` | Entrega solicitada |
| `delivery.quoted` | Entrega cotada |
| `delivery.charge_pending` | Cobrança da entrega em processamento |
| `delivery.authorized` | Entrega autorizada |
| `delivery.failed` | Entrega não autorizada |
| `delivery.dispatched` | Corrida criada no parceiro |
| `delivery.dispatch_pending` | Corrida em confirmação com o parceiro |
| `delivery.status_changed` | Situação da corrida atualizada |
| `delivery.canceled` | Entrega cancelada |
| `fleet_invoice.created` | Fatura da frota criada |
| `fleet_invoice.charge_available` | Cobrança da fatura disponível |
| `fleet_invoice.paid` | Pagamento da fatura confirmado |
| `connect.message.received` | WhatsApp: mensagem recebida |
| `connect.message.status` | WhatsApp: enviada, entregue ou lida |
| `connect.message.failed` | WhatsApp: falha no envio |

Corpo enviado:

```json
{ "id": "3c9a4b5c-…", "type": "payment.paid", "created_at": "2026-10-01T22:10:04.000Z",
  "delivery_id": "a71f…",
  "data": { "id": "8f0c2f1e-…", "object": "payment", "status": "PAID", "amount": 4990,
            "currency": "BRL", "external_reference": "pedido-1042" } }
```

Cabeçalhos:

```http
X-VPNPay-Event: payment.paid
X-VPNPay-Delivery: a71f…
X-VPNPay-Timestamp: 1789245004
X-VPNPay-Signature: sha256=9b1d…
```

Assinatura: HMAC SHA-256 de `timestamp + "." + corpo bruto`, com o segredo do endereço de
aviso, em hexadecimal. Compare sempre com o corpo **bruto**, antes de qualquer parse.
Tolerância de 300 segundos. Entrega *at-least-once*: deduplique pelo `id` do evento.
Responda 2xx em até 10s. Novas tentativas: 30s, 2min, 10min, 1h, 6h e 24h. Apenas https.

```ts
const expected = "sha256=" + crypto
  .createHmac("sha256", process.env.VPNPAY_WEBHOOK_SECRET!)
  .update(`${timestamp}.${raw}`)
  .digest("hex");
```

Webhooks **do parceiro logístico para a VPN Pay** são cadastrados no painel da Uber Direct
apontando para `/api/public/webhooks/uber/{connectionId}`; a assinatura é conferida e o
evento é registrado uma única vez antes de virar aviso para o seu sistema.

## 12. Erros

| HTTP | code | Quando |
| --- | --- | --- |
| 400 | `invalid_request` | Campo ausente, tipo errado, JSON inválido, valor não inteiro |
| 401 | `unauthorized` | Chave ausente, inválida, revogada ou expirada |
| 403 | `forbidden` | Sem o scope exigido, ou cliente inativo tentando escrever |
| 404 | `not_found` | Recurso inexistente, de outra unidade ou de outro cliente |
| 409 | `idempotency_conflict` | Mesma `Idempotency-Key` com corpo diferente |
| 409 | `conflict` | Estado atual do recurso impede a operação |
| 422 | `unprocessable` | Regra de negócio recusou (saldo, risco, provedor, exposição) |
| 429 | `rate_limited` | Limite por minuto excedido |
| 500 | `internal_error` | Falha inesperada da VPN Pay |

Indisponibilidade de provedor chega como `422`, nunca `503`.

## 13. Listagens e limite de uso

As listagens devolvem os registros mais recentes, sem paginação por cursor nem filtro por
período (teto: pagamentos 50, repasses 100, devoluções 100, recebedores 200, conciliação 50,
entregas 100). Exceção: `/fleet/invoices` tem paginação por cursor.

Limites por chave, janela de 60s: leitura 240/min, escrita 60/min. Cabeçalhos
`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` e `Retry-After`.

## 14. Sequência recomendada de integração

1. Com uma chave `ALL` de cadastro: `POST /merchants` e `POST /recipients` com seus códigos;
   aguardar KYC no painel; depois criar no painel a chave operacional `SELECTED` por unidade.
2. Cadastrar o endereço de aviso e validar a assinatura com um evento de teste.
3. Pedido pago: `POST /payments` → Pix (exibir QR) ou cartão (redirecionar a `checkout_url`)
   → aguardar `payment.paid`. Liquidação do cartão chega depois em `payment.settled`.
4. Entrega: `POST /deliveries/quotes` → `/funding` → `/dispatch` → acompanhar
   `delivery.status_changed` até `delivery.completed` ou `delivery.canceled`.
5. Contingência: timeout mantém a reserva; consulte `GET /deliveries/{id}`.
6. Conferência financeira: `GET /balances` e, na frota própria, `GET /fleet/invoices`.

## 15. Situação de homologação

Gateway (Pix In, Pix Out, devoluções, recebedores, saldos, conciliação) e frota própria
estão em produção. O fluxo de entregas com parceiro logístico (Fase 18) está implantado e
validado em simulação automatizada; a homologação externa ponta a ponta com o parceiro —
corridas reais, webhooks do parceiro em produção e liquidação no adquirente — é executada
pelo cliente integrador no ambiente de teste do parceiro antes da virada.

## 16. Conta centralizadora e SaaS integrador

- Cada lojista financeiramente independente é um cliente (tenant) próprio; filiais são unidades dentro dele.
- O SaaS integrador (tipo de integração `SAAS_INTEGRATOR`) usa **uma chave de API e um segredo de webhook por cliente**. O cliente vem sempre da chave; nunca de campo enviado.
- Os recebimentos podem entrar numa conta PSP centralizadora da VPN Pay. Cada cliente só a usa com **autorização explícita** da VPN Pay, por operação (recebimento, consulta, estorno, repasse) e com validade (máx. 12 meses). Sem autorização vigente a chamada é recusada (`TENANT_MISMATCH` / `GRANT_EXPIRED`).
- Toda operação grava o cliente beneficiário, o pagamento original e a conta usada; isso não muda depois. Estornos e consultas usam sempre a conta do pagamento original.
- Saldo físico único, parcelas contábeis separadas: repasse só sai se o saldo físico cobrir o pedido **mais** o que pertence aos outros clientes (`SHARED_BALANCE_INSUFFICIENT`). Repasses concorrentes na mesma conta são serializados.
- Avisos do provedor identificam o cliente pela operação registrada (conta + id externo). Aviso de recurso desconhecido ou de outra conta é guardado sem efeito.
- O integrador nunca vê as credenciais da conta centralizadora.
- A autorização usada é gravada pela VPN Pay em cada cobrança, tentativa, transação, estorno e repasse. O integrador não informa autorização; qualquer valor enviado é ignorado. Registros anteriores à autorização não recebem uma.
- Estorno em conta centralizadora sai obrigatoriamente pela conta do pagamento original (`REFUND_CONNECTION_MUST_MATCH_PAYMENT`).
- Repasse em conta compartilhada, no envio: autorização revalidada (vencida ou revogada → falha `GRANT_EXPIRED` e a reserva volta ao saldo disponível), saldo físico consultado no provedor (indisponível → `SHARED_BALANCE_UNKNOWN`, nada enviado) e coberto o disponível + bloqueado de todos os clientes da conta, incluindo reservas e repasses em andamento.
- Timeout do provedor: o repasse fica em andamento, a reserva continua bloqueada e não há novo envio até a conciliação.
