Integração via llms.txt e OpenAPI

Guia para conectar Lovable, Cursor, v0, Bolt.new, agentes LLM e automações externas com a API Aprovei. Aqui o agente gera código que roda na sua stack, guiado por llms.txt e pela spec OpenAPI.

Servidor MCP: para que o agente opere a loja direto no chat (consultar catálogo, gerar link de pagamento) sem escrever código, conecte o servidor MCP do Aprovei Checkout no Claude, ChatGPT, Cursor ou Lovable. Esta página cobre o caminho de código: gerar uma integração REST. Em dúvida entre os dois, veja a visão geral da integração com IA.

Comece pelo checkout: consulte produtos, monte o carrinho com variantId e crie o link em POST /cart/create-checkout.

Dados de conexão

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

Headers

Authorization: Bearer SEU_TOKEN
X-Store-Slug: SLUG_DA_LOJA
Content-Type: application/json
Idempotency-Key: CHAVE_UNICA_DO_CHECKOUT

Use Content-Type e Idempotency-Key em POST /cart/create-checkout. Para consultas, envie sempre Authorization e X-Store-Slug.

Fluxo recomendado

1. Consultar a loja

Dados públicos da loja em GET /store

2. Listar produtos

Catálogo paginado em GET /products

3. Buscar por termo

Use GET /search quando necessário

4. Criar o checkout

Monte o carrinho com variantId e gere o link

Importante: use o slug da loja no header X-Store-Slug. Para produtos, a API Aprovei Checkout v1 não usa slug como identificador público e não oferece APIs de coleções ou produtos recomendados nesta versão. Use productId e variantId retornados pela própria API (ambos usam products.product_id).

Prompt para Lovable, Cursor e LLMs

Prompt

Integre com a API Aprovei.

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

Contrato completo (endpoints, parâmetros, respostas, erros, webhooks):
https://app.aproveicheckout.com.br/docs/llms-full.txt
Leia antes de implementar.

Sempre envie:
- 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

Fluxo:
1. Consulte GET /store.
2. Liste produtos em GET /products.
3. Busque produtos em GET /search quando necessário.
4. Use productId/variantId retornados pela API.
5. Crie checkout com POST /cart/create-checkout.
6. Para PIX, use POST /v1/pix com a permissão pix:create.

Não use APIs de coleções, produtos recomendados ou slug como identificador de produto.
Não exponha o token no frontend público.

Os valores de APROVEI_API_KEY e APROVEI_STORE_SLUG não estão neste prompt.
Nunca invente, gere ou peça esses valores no meio do código.
Trate-os sempre como variáveis de ambiente já existentes.
Ao terminar, liste exatamente onde eu devo definir APROVEI_API_KEY e
APROVEI_STORE_SLUG antes de rodar (arquivo .env na raiz para Node/local,
aba Secrets/Environment Variables na Lovable, ou painel de Environment
Variables no deploy) e informe que a API Key é obtida no painel da Aprovei
pelo avatar/menu do usuário no topo direito > API Keys.

Exemplo mínimo

cURL

curl -X POST "https://api.aproveicheckout.com.br/v1/cart/create-checkout" \
  -H "Authorization: Bearer ${APROVEI_API_KEY}" \
  -H "X-Store-Slug: ${APROVEI_STORE_SLUG}" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: checkout-${UNIQUE_ID}" \
  -d '{
    "items": [
      { "variantId": "101", "quantity": 1 }
    ]
  }'

Tutorial: Lovable

No painel da Aprovei, clique no avatar/menu do usuário no topo direito, acesse API Keys e crie uma API Key com as permissões necessárias.
Anote também o slug da loja (retornado em GET /store e exibido no painel).
No projeto da Lovable, abra Settings → Secrets e cadastre APROVEI_API_KEY e APROVEI_STORE_SLUG. Assim a key nunca aparece no código gerado.
Cole o prompt desta página no chat da Lovable junto com o pedido da sua tela (ex.: "crie uma vitrine com botão de comprar").
Revise o código gerado: as chamadas devem sair de server function ou backend (nunca do navegador) e usar os headers documentados acima.

Tutorial: Cursor

Crie a API Key no painel da Aprovei pelo avatar/menu do usuário no topo direito → API Keys (mesmo passo do tutorial da Lovable).
Na raiz do projeto, crie um arquivo .env com APROVEI_API_KEY e APROVEI_STORE_SLUG e garanta que ele está no .gitignore.
Abra o chat do Cursor (Ctrl+L ou Cmd+L), cole o prompt desta página e descreva a integração que você quer gerar.
Valide a integração executando o cURL de exemplo com as suas credenciais antes de subir para produção.

Contexto para IA

Aponte seu assistente para um destes recursos:

https://app.aproveicheckout.com.br/docs/llms.txt — resumo curto do contrato v1 para LLMs.
https://app.aproveicheckout.com.br/docs/llms-full.txt — contrato completo (endpoints, parâmetros, respostas, erros e webhooks).
https://app.aproveicheckout.com.br/docs/openapi.json — spec OpenAPI 3.1 para ferramentas que consomem specs (Custom GPTs, geradores de SDK).

Segurança

Nunca salve o token Bearer no repositório.
Não embuta o token em frontend público; use backend, server function ou proxy seguro.
Use variáveis de ambiente como APROVEI_API_KEY e APROVEI_STORE_SLUG.
Em apps de navegador, confirme CORS e headers permitidos antes de publicar.

Webhooks e recuperação

Automações externas podem registrar endpoints em POST /webhooks. A lista completa de eventos, os headers de entrega e a validação da assinatura X-Aprovei-Signature estão no Guia de Webhooks.