Integrations API Routes
Documentação de todas as rotas em /api/integrations/**.
Plataformas: Shopify, Yampi, Nuvemshop, WooCommerce, Hotmart, Kiwify.
Integrações - Base
Seção intitulada “Integrações - Base”GET /api/integrations
Seção intitulada “GET /api/integrations”Descrição: Lista todas as integrações e-commerce da conta, opcionalmente filtradas por plataforma. Auth: Required
Request:
- Query params:
platform(string, opcional)
Response:
- 200: Array de integrações (sem
access_token_encryptednemwebhook_secret)
GET /api/integrations/[id]
Seção intitulada “GET /api/integrations/[id]”Descrição: Retorna detalhes de uma integração específica.
Response:
- 200: Integração
- 404: Integração não encontrada
PATCH /api/integrations/[id]
Seção intitulada “PATCH /api/integrations/[id]”Descrição: Atualiza settings e/ou status de uma integração.
Request:
- Body:
{ settings?: object, status?: string }
DELETE /api/integrations/[id]
Seção intitulada “DELETE /api/integrations/[id]”Descrição: Remove uma integração e limpa webhooks remotos na plataforma de origem.
Notas: Para Hotmart e Kiwify, não há cleanup de webhooks (gerenciados pelo lado da plataforma).
GET /api/integrations/[id]/webhook-status
Seção intitulada “GET /api/integrations/[id]/webhook-status”Descrição: Retorna status dos webhooks cruzando tópicos esperados com eventos recebidos.
Notas: Verifica 13 tópicos de webhook mapeados para métricas correspondentes.
Shopify
Seção intitulada “Shopify”POST /api/integrations/shopify/connect
Seção intitulada “POST /api/integrations/shopify/connect”Descrição: Inicia o fluxo OAuth do Shopify a partir do frontend x17. Retorna URL de autorização.
Request:
- Body:
{ shop: string }
Response:
- 200:
{ data: { auth_url: string } }
POST /api/integrations/shopify/connect-webhook
Seção intitulada “POST /api/integrations/shopify/connect-webhook”Descrição: Conecta uma loja Shopify via webhook-only (sem OAuth).
Request:
- Body:
{ store_name: string, webhook_secret?: string }
Response:
- 200:
{ data: { webhook_url, webhook_url_token, events: [{ topic, label }] } }
GET /api/integrations/shopify/callback
Seção intitulada “GET /api/integrations/shopify/callback”Descrição: Callback do OAuth Shopify. Valida HMAC, troca code por access_token, salva integração e registra 13 tópicos de webhook.
Response:
- 302: Redirect para
/app/settings/integrations?success=shopify
POST /api/integrations/shopify/webhook
Seção intitulada “POST /api/integrations/shopify/webhook”Descrição: Recebé webhooks do Shopify. Dois modos: por token (webhook-only) ou por shopDomain (OAuth).
Notas: Topicos tratados: orders/create, orders/updated, orders/cancelled, orders/fulfilled, orders/paid, checkouts/create, checkouts/update, refunds/create, fulfillments/create, fulfillments/update, customers/create, customers/update, carts/create.
POST /api/integrations/shopify/compliance
Seção intitulada “POST /api/integrations/shopify/compliance”Descrição: Webhooks obrigatórios de compliance GDPR do Shopify.
Notas: Topicos: customers/data_request, customers/redact, shop/redact. Apenas loga (obrigatório pelo Shopify App Review).
POST /api/integrations/yampi/connect
Seção intitulada “POST /api/integrations/yampi/connect”Descrição: Conecta uma loja Yampi via API Key ou inicia fluxo OAuth PKCE.
Request (OAuth):
- Body:
{ method: "oauth", alias: string }
Request (API Key):
- Body:
{ alias, user_token, user_secret_key }
GET /api/integrations/yampi/callback
Seção intitulada “GET /api/integrations/yampi/callback”Descrição: Callback do OAuth PKCE Yampi. Troca code por tokens com code_verifier.
Notas: Salva access_token_encrypted, refresh_token_encrypted, token_expires_at.
POST /api/integrations/yampi/webhook
Seção intitulada “POST /api/integrations/yampi/webhook”Descrição: Recebé webhooks da Yampi. Resolve integração por alias.
Notas: Alias resolvido em ordem: query param store > merchant.alias > resource.merchant.alias. Eventos tratados: order.created, order.paid, order.status.updated, cart.reminder, e mais.
Nuvemshop
Seção intitulada “Nuvemshop”POST /api/integrations/nuvemshop/connect
Seção intitulada “POST /api/integrations/nuvemshop/connect”Descrição: Inicia fluxo OAuth da Nuvemshop.
Response:
- 200:
{ data: { auth_url: string } }
GET /api/integrations/nuvemshop/callback
Seção intitulada “GET /api/integrations/nuvemshop/callback”Descrição: Callback do OAuth Nuvemshop.
Notas: Registra 3 webhooks: order/created, order/paid, checkout/created.
POST /api/integrations/nuvemshop/webhook
Seção intitulada “POST /api/integrations/nuvemshop/webhook”Descrição: Recebé webhooks da Nuvemshop. Resolve por store ID.
WooCommerce
Seção intitulada “WooCommerce”POST /api/integrations/woocommerce/connect
Seção intitulada “POST /api/integrations/woocommerce/connect”Descrição: Conecta via REST API (consumer key/secret). Valida credenciais e registra webhooks.
Request:
- Body:
{ store_url, consumer_key, consumer_secret }
POST /api/integrations/woocommerce/webhook
Seção intitulada “POST /api/integrations/woocommerce/webhook”Descrição: Recebé webhooks do WooCommerce. Resolve por hostname.
Hotmart
Seção intitulada “Hotmart”POST /api/integrations/hotmart/connect
Seção intitulada “POST /api/integrations/hotmart/connect”Descrição: Conecta via credenciais de API (client_id, client_secret, hottok).
Notas: Webhooks configurados manualmente na Hotmart.
POST /api/integrations/hotmart/webhook
Seção intitulada “POST /api/integrations/hotmart/webhook”Descrição: Recebé webhooks da Hotmart. Identifica integração pelo hottok.
Notas: Busca TODAS as integrações Hotmart ativas e itera para encontrar a que tem o hottok correspondente.
POST /api/integrations/kiwify/connect
Seção intitulada “POST /api/integrations/kiwify/connect”Descrição: Conecta via credenciais de API (account_id, api_key).
Notas: Webhooks configurados manualmente na Kiwify.
POST /api/integrations/kiwify/webhook
Seção intitulada “POST /api/integrations/kiwify/webhook”Descrição: Recebé webhooks da Kiwify. Identifica integração pela signature.
Notas: Pattern similar ao Hotmart: matching por iteração em todas as integrações ativas.