# Vero API — superfície pública

> Escrow-as-a-Service para o comércio digital. A Vero segura o pagamento em custódia, verifica a condição combinada e libera no momento certo. Esta é a superfície PÚBLICA — a que marketplaces, plataformas e agentes/MCP usam.

Especificação completa (OpenAPI 3.1, legível por máquina): openapi.json
Referência navegável: api.html

## Autenticação
- Partner API: `Authorization: Bearer vero_...` + escopo por endpoint (ex.: `transactions:read`).
- Público (links/checkout): token opaco no caminho; sem credencial de conta.
- Webhooks de entrada: `X-Webhook-Secret` ou `X-Carrier-Signature`.

Base URLs: produção https://api.vero.com · sandbox https://sandbox.api.vero.com · local http://localhost:8080
Dinheiro = string decimal + `currency` ISO-4217. Datas = ISO-8601 UTC. Todo erro traz um `code` estável.

## Endpoints

### Partner API
- GET /api/v1/whoami — Identity of the calling API key
- GET /api/v1/transactions — List transactions (demonstration surface)
- GET /api/v1/merchants — List my sub-merchants
- POST /api/v1/merchants — Register a sub-merchant (seller)
- GET /api/v1/merchants/{merchantId} — Get a sub-merchant
- PATCH /api/v1/merchants/{merchantId} — Update a sub-merchant
- POST /api/v1/merchants/{merchantId}/block — Block a sub-merchant
- POST /api/v1/merchants/{merchantId}/unblock — Unblock a sub-merchant
- GET /api/v1/merchants/{merchantId}/payment-links — List a seller's payment links
- POST /api/v1/merchants/{merchantId}/payment-links — Create a payment link for a seller
- GET /api/v1/merchants/{merchantId}/payment-links/{linkId} — Get a payment link
- PATCH /api/v1/merchants/{merchantId}/payment-links/{linkId} — Update a payment link
- POST /api/v1/merchants/{merchantId}/payment-links/{linkId}/activate — Activate a payment link
- POST /api/v1/merchants/{merchantId}/payment-links/{linkId}/cancel — Cancel (deactivate) a payment link

### Links & checkout público
- GET /v1/payment-links/{token} — Resolve a public link (buyer-safe)
- POST /v1/payment-links/{token}/fund — Fund a link (create the escrow agreement)
- GET /v1/status/{accessToken} — Public transaction status

### Webhooks de entrada
- POST /v1/integrations/payments/{provider}/webhook — Inbound payment provider webhook
- POST /v1/integrations/tracking/{provider}/webhook — Inbound tracking webhook (normalized)
- POST /v1/logistics/carriers/{carrierId}/webhook — Inbound carrier webhook (signed)