> For the complete documentation index, see [llms.txt](https://docs.adapta.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.adapta.org/skip/comece-aqui/conectando-seu-app-ao-mundo-integracoes-via-api.md).

# Conectando seu App ao Mundo: Integrações via API

Integrar é conectar o seu app do Skip a outros serviços para que eles conversem entre si. Um exemplo clássico: o app recebe uma venda, avisa o **Stripe** para cobrar o cliente, dispara um e-mail de confirmação pelo **Resend** e registra a venda no banco do **Skip Cloud: Banco de Dados, Autenticação e Segredos** — tudo automaticamente, em segundos.

Esta página explica os conceitos básicos, como configurar chaves com segurança e quais são as integrações mais usadas.

### Conceitos básicos (sem jargão)

Antes de configurar qualquer coisa, entenda os termos:

* **API** (*Application Programming Interface*): A "ponte" que permite que dois sistemas conversem. É o idioma universal da internet.
* **Endpoint:** O "endereço" específico dentro de uma API para enviar um pedido. Ex: `/clientes`, `/pagamentos`.
* **API Key:** Uma senha secreta que autoriza seu app a usar um serviço externo. Tratada como um segredo.
* **Webhook:** Uma notificação automática enviada por um serviço externo quando algo acontece. Exemplo: o Stripe avisa seu app no momento exato em que o cliente pagou.
* **Edge Function:** Uma função que roda em servidor, próxima do usuário. Ideal para **esconder chaves secretas** e executar lógica segura fora do frontend.

### Onde ficam os segredos

No Skip Cloud, todos os segredos (API Keys, tokens, senhas) ficam em um único lugar seguro:

**Painel do projeto → Skip Cloud → Segredos**

{% hint style="danger" %}
**Nunca** cole uma API Key diretamente no prompt do chat — ela ficaria exposta no histórico da conversa, podendo ser lida por qualquer pessoa com acesso ao projeto.
{% endhint %}

### Passo a passo para configurar uma chave

1. Abra o painel do **Skip Cloud: Banco de Dados, Autenticação e Segredos** no seu projeto.
2. Vá para a aba **Segredos**.
3. Clique em **adicionar** e informe:
   * **Nome** da variável (ex.: `STRIPE_SECRET_KEY`, `OPENAI_API_KEY`).
   * **Valor** — a chave em si.
4. Salve.
5. No chat, peça à IA para usar esse segredo na integração, **referenciando pelo nome** (nunca pelo valor).

> 💬 Exemplo de prompt: *"Crie a integração com o Stripe usando a chave `STRIPE_SECRET_KEY` que está nos Segredos."*

### Exemplos práticos de integração

#### 💳 Pagamentos (Stripe)

Assinaturas recorrentes, checkouts pontuais e verificação automática do status da transação. Webhooks do Stripe atualizam o banco assim que o pagamento é confirmado.

#### ✉️ E-mail (Resend)

Mensagens transacionais de boas-vindas, confirmação de cadastro, recuperação de senha ou notificações de compra.

#### 🤖 Inteligência Artificial (OpenAI / Gemini)

Chatbots especialistas, analistas de documentos, geração de conteúdo baseado em dados do usuário. A chave da IA fica protegida no Segredos, nunca exposta no frontend.

#### 💬 WhatsApp (Evolution API)

Atendimento em tempo real com cada conversa virando um lead rastreável no seu CRM.

### Boas práticas

* **Desenvolvimento incremental:** Antes de automatizar tudo, crie um **botão manual** para testar se a API está respondendo. Depois automatize.
* **Verifique o status code:** Use o **Bug Scanner** ou as DevTools (F12 → aba Rede) para ver o que a API retornou:
  * **200** → sucesso.
  * **401** → chave inválida ou sem permissão.
  * **429** → muitas requisições em pouco tempo.
  * **500** → erro do servidor remoto.
* **Analise os logs:** Se algo falhar, olhe os **Logs** do Skip Cloud — a mensagem real de erro costuma estar ali, mesmo quando o app só mostra "algo deu errado".

### Fluxo recomendado para qualquer integração

1. Cadastre a chave nos **Segredos** do Skip Cloud.
2. Peça à IA para criar uma **Edge Function** que usa essa chave.
3. Teste manualmente com um botão simples no app.
4. Confira no **Bug Scanner** (aba Rede) se a resposta foi 200.
5. Só então automatize o fluxo completo (webhooks, triggers, etc.).

### Alternativa avançada: Supabase

Se você optou por usar **Supabase como backend externo**, a configuração de segredos e edge functions é feita **no painel do Supabase**, em `Edge Functions > Secrets`. O fluxo é parecido, mas acontece fora da interface do Skip.

{% hint style="info" %}
**Para novos projetos**, recomendamos usar o **Skip Cloud nativo** — é mais simples, e toda a interface de Segredos, APIs e Logs fica no mesmo lugar.
{% endhint %}

### Resumo rápido

| Você quer...                               | O que usar                                          |
| ------------------------------------------ | --------------------------------------------------- |
| Guardar uma chave de API com segurança     | Skip Cloud → **Segredos**                           |
| Criar lógica que chama uma API externa     | Skip Cloud → **APIs e Gatilhos** (Edge Function)    |
| Receber notificações de um serviço externo | **Webhook** apontando para uma Edge Function        |
| Diagnosticar uma integração quebrada       | **Bug Scanner** (aba Rede) + **Logs** do Skip Cloud |