# API Aprovei

Base URL: https://api.aproveicheckout.com.br/v1

Use esta referência para Lovable, Cursor, v0, Bolt.new, agentes LLM e automações externas.

Referências completas:
- Documentação canônica: https://app.aproveicheckout.com.br/docs
- Visão geral de integração com IA: https://app.aproveicheckout.com.br/docs/ia
- Guia para agentes via API REST: https://app.aproveicheckout.com.br/docs/ia-agents
- Contrato completo para LLMs: https://app.aproveicheckout.com.br/docs/llms-full.txt
- Spec OpenAPI 3.1: https://app.aproveicheckout.com.br/docs/openapi.json
- Pedidos por e-mail/CPF e detalhe por ID (GET /orders e /orders/{orderId}, orders:read): https://app.aproveicheckout.com.br/docs/v1/pedidos

Servidor MCP (para agentes operarem a loja direto no chat):
- Endpoint Streamable HTTP: https://api.aproveicheckout.com.br/mcp
- Auth: mesma API Key Bearer da API Aprovei, sem header de loja (loja via parâmetro storeSlug por tool call)
- MCP usa storeSlug; não envie storeId nas tool calls.
- Tools: list_stores, get_store, list_products, get_product, search_products, create_checkout, list_webhooks, create_webhook, update_webhook, delete_webhook
- Guia: https://app.aproveicheckout.com.br/docs/mcp

Autenticação obrigatória:
- Authorization: Bearer <APROVEI_API_KEY>
- X-Store-Slug: <APROVEI_STORE_SLUG>
- Content-Type: application/json em requisições POST
- Idempotency-Key em POST /cart/create-checkout

Segurança:
- Nunca exponha o token Bearer em frontend público.
- Guarde tokens em variáveis de ambiente ou backend/server function.
- Não envie credenciais, tokens, gateways, billing ou dados sensíveis para usuários finais.

Endpoints reais da v1:
- GET /store
- GET /products
- GET /products/{productId}
- GET /search?q=termo
- POST /cart/create-checkout
- POST /v1/pix
- GET /webhooks
- POST /webhooks

Identificadores:
- productId e variantId usam products.product_id; para produtos com variações, use o variantId da variante retornada pelo catálogo.
- O slug da loja é o identificador público da loja na API REST v1, enviado em X-Store-Slug.
- Slug de produto não é identificador público; use productId e variantId para produtos.
- ID interno products.id não deve ser usado por integrações externas.

Fluxo recomendado:
1. Consulte GET /store.
2. Liste produtos em GET /products.
3. Use GET /search?q=termo quando precisar buscar por nome, descrição, SKU ou barcode.
4. Monte items usando variantId retornado pela API, com quantity de 1 a 999.
5. Envie POST /cart/create-checkout com Idempotency-Key.
6. Redirecione o usuário para checkoutUrl ou checkout_direct_url.
7. Para cobrança PIX, envie POST /v1/pix com API Key que tenha pix:create.

POST /cart/create-checkout body:
{
  "items": [
    { "variantId": "101", "quantity": 1 }
  ]
}

POST /cart/create-checkout response:
{
  "active": true,
  "skip_cart": false,
  "checkout_direct_url": "https://loja.dominio.com/checkout/token",
  "checkoutUrl": "https://loja.dominio.com/checkout/token"
}

Erros comuns:
- AUTH_MISSING_BEARER_TOKEN
- AUTH_INVALID_BEARER_TOKEN
- AUTH_STORE_HEADER_MISSING
- AUTH_STORE_FORBIDDEN
- AUTH_IP_NOT_ALLOWED
- UNSUPPORTED_MEDIA_TYPE
- VALIDATION_ERROR
- IDEMPOTENCY_KEY_MISSING
- IDEMPOTENCY_KEY_CONFLICT
- CHECKOUT_DOMAIN_NOT_CONFIGURED
- PRODUCT_NOT_FOUND
- STOCK_UNAVAILABLE
- WEBHOOK_LIMIT_EXCEEDED
- PIX_GATEWAY_NOT_CONFIGURED
- RATE_LIMIT_EXCEEDED

Rate limits:
- Storefront e listagem de webhooks: 300 req/min por token+loja.
- Criação de checkout, PIX e criação de webhooks: 60 req/min por token+loja.
- Teto global: 600 req/min por IP.

Webhooks:
- GET /webhooks lista webhooks sem retornar secret puro.
- POST /webhooks cria webhook e retorna o secret somente na criação.
- Máximo de 10 webhooks por loja.
- Assinatura outbound: X-Aprovei-Signature: sha256=<hex_hmac>
- HMAC-SHA256 calculado sobre o body JSON bruto enviado.
- Entrega: timeout 5s, até 5 tentativas com backoff de 1min, 5min, 30min e 2h.
- Sucesso na entrega = qualquer resposta HTTP 2xx.

Eventos públicos:
- order.created
- payment.pix.created
- payment.boleto.created
- order.paid
- order.processing
- order.refused
- order.cancelled
- order.chargeback
- order.refunded
- order.expired
- cart.abandoned

Recursos não disponíveis nesta versão:
- APIs de coleções.
- Produtos recomendados.
- Busca de produto por slug.