> ## Documentation Index
> Fetch the complete documentation index at: https://docs.crmspark.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Introdução

> Visão geral da API do Spark, ambiente de desenvolvedores, chaves, autenticação no gateway e link para webhooks de saída (Svix).

A API pública do Spark é o ponto de entrada estável para integrar sistemas externos ao CRM: automações, ERPs, webhooks e qualquer aplicação que precise ler ou enviar dados de forma programática.

Esta página resume o fluxo de desenvolvedor: ativar o ambiente no painel, obter e usar as chaves, e fazer a primeira autenticação. Detalhes de cada endpoint ficam na referência interativa ao lado.

Se você integra em **TypeScript ou JavaScript no servidor**, o cliente oficial [`sparkcrm`](https://www.npmjs.com/package/sparkcrm) encapsula autenticação, tipos e retentativas — veja a aba [SDKs](/sdks/index).

## O que você precisa saber de antemão

* A API é por organização: as chaves identificam a sua instância do Spark, não um usuário individual.
* Só administradores da organização podem habilitar o ambiente e criar ou revogar chaves. Se você é integrador, alinhe com o responsável pelo Spark na empresa.
* O modelo é deliberadamente simples: HTTP + JSON, versão na URL e uma chave por requisição no cabeçalho, familiar para quem já integrou APIs REST modernas.

## Ambiente de desenvolvedores e chaves

No Spark, “modo desenvolvedores” significa ativar o ambiente de API para a sua organização. Até lá, não há chaves válidas para o gateway público.

Depois de habilitado, você passa a ter:

| Papel         | Prefixo | Uso típico                                                                                                                                    |
| ------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| Chave pública | `pk_`   | Identifica a organização em fluxos que exigem a chave “pública” (conforme cada endpoint na referência).                                       |
| Chave secreta | `sk_`   | Autentica chamadas que exigem a chave “privada”, em geral operações mais sensíveis; você pode ter várias, com nomes como “Produção” ou “ERP”. |

Alguns endpoints aceitam apenas um tipo de chave; o playground e a especificação OpenAPI indicam o que cada operação espera. **Nunca** trate a chave secreta como dado público (repositórios, tickets abertos, capturas de tela).

### Como habilitar e obter as chaves

<Steps>
  <Step title="Acesse o painel do Spark">
    Entre no [dashboard](https://crmspark.com.br/dash) com uma conta que tenha permissão de administrador da organização.
  </Step>

  <Step title="Abra Desenvolvedores">
    Vá em Configurações e abra a seção Desenvolvedores (ambiente de API e gerenciamento de chaves), ou abra diretamente [Configurações → Desenvolvedores](https://crmspark.com.br/dash/settings/developers) já autenticado.
  </Step>

  <Step title="Habilite o ambiente">
    Use a opção para habilitar o ambiente de API. Na primeira vez, o sistema cria a chave pública e a primeira chave secreta e oferece um momento para copiar e guardar os valores com segurança.
  </Step>

  <Step title="Organize e proteja as credenciais">
    Guarde as chaves em um cofre ou variáveis de ambiente. Você pode criar chaves secretas adicionais, desativar uma chave ou desligar o ambiente sem apagar as chaves armazenadas — útil para pausar integrações rapidamente.
  </Step>
</Steps>

<Tip>
  Se o ambiente for desativado e depois reativado, as chaves existentes continuam as mesmas no sistema; siga as orientações na própria tela para copiar valores quando necessário.
</Tip>

## Base URL e documentação viva

O gateway oficial da API pública está em [gateway.crmspark.com.br](https://gateway.crmspark.com.br) (HTTPS).

## Autenticação

Todas as requisições autenticadas devem enviar a chave no cabeçalho HTTP:

```http theme={null}
X-API-Key: pk_… ou sk_…
```

## Webhooks de saída (eventos para o seu sistema)

Quando o ambiente de desenvolvedores está ativo, a organização pode receber **notificações HTTP** disparadas pelo Spark (mensagens recebidas ou enviadas, chats criados). A entrega usa o [Svix](https://www.svix.com/): assinatura, retentativas e configuração de URLs pelo **Consumer App Portal** integrado ao painel.

Conceitos, lista de eventos, verificação de assinatura e como obter **tipagem a partir do OpenAPI** (`x-webhooks` e schemas) estão na página dedicada [Webhooks (Saída)](/api-reference/webhooks).

## Boas práticas em poucas linhas

* Rotacione chaves ao mudar fornecedores ou equipes; remova chaves que não são mais usadas.
* Trate erros HTTP e limites de uso como parte normal da integração — clientes resilientes evitam falhas em cascata nos sistemas ligados ao CRM.