> ## 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.

# Modo Desenvolvedores (API)

> Ambiente de API por organização: chave pública e chaves secretas, quem gerencia, ligar e desligar acesso e boas práticas de credenciais.

No Spark, **Desenvolvedores** é a área em [Configurações → Desenvolvedores](https://crmspark.com.br/dash/settings/developers) onde a organização **liga o acesso programático** ao CRM e **administra as credenciais** usadas pelo [gateway público](https://gateway.crmspark.com.br). Não é um “modo” que muda a interface do dia a dia do time de atendimento: é um **interruptor de API** e um **cofre de chaves** para integrações, formulários públicos, ERPs e scripts.

## Para que serve

* Permitir que sistemas externos chamem endpoints oficiais (REST + JSON) em nome da **organização**, não de um usuário específico.
* **Pausar** todas as integrações de uma vez desligando o ambiente, sem apagar as chaves já criadas.
* **Separar credenciais** por projeto (produção, homologação, parceiro) usando várias chaves secretas com nomes claros.

## Ambiente habilitado x desabilitado

| Estado           | Efeito                                                                                                                                                                                                        |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Desabilitado** | Não há uso válido das chaves contra o gateway até você habilitar de novo. As chaves **permanecem armazenadas** no sistema.                                                                                    |
| **Habilitado**   | As chaves passam a autenticar requisições conforme as regras de cada endpoint. Na primeira ativação, o Spark cria a **chave pública** e a **primeira chave secreta** e oferece um momento seguro para copiar. |

Desligar o ambiente é útil em incidentes ou migrações: você corta o acesso programático imediato sem precisar revogar chave por chave.

<Tip title="Reativar depois de desligar">
  Ao habilitar novamente, as chaves existentes **continuam as mesmas**; a interface pode lembrar que valores completos não são “reexpostos” como na primeira criação — use copiar na lista quando precisar do texto integral.
</Tip>

## Chave pública e chaves secretas

| Tipo              | Prefixo típico | Papel                                                                                         |
| ----------------- | -------------- | --------------------------------------------------------------------------------------------- |
| **Chave pública** | `pk_`          | Identifica a organização em fluxos que a documentação da API marca como uso de chave pública. |
| **Chave secreta** | `sk_`          | Autentica operações que exigem chave privada; é a credencial **sensível** — trate como senha. |

Você pode ter **várias chaves secretas**, cada uma com um **nome** (ex.: “Produção”, “Staging”, “ERP”). Isso ajuda a saber qual sistema revogar quando alguém sai do projeto ou quando uma integração vaza.

### Ativar ou desativar uma chave secreta

Na lista de chaves secretas existe controle de **chave ativa na API**. Desativar uma chave específica interrompe só os clientes que usam aquela credencial, **sem** desligar o ambiente inteiro nem as outras chaves.

### Remover uma chave

É possível **remover** uma chave secreta da lista. Enquanto houver **apenas uma** chave secreta, a interface **não permite excluí-la** (evita deixar o ambiente sem credencial secreta útil). Para trocar a última chave de forma segura, crie uma nova, atualize as integrações e só então remova a antiga — ou use desativar temporariamente.

<Warning title="Impacto na operação">
  Remover ou desativar uma chave quebra qualquer sistema que ainda a use até você atualizar a credencial. O mesmo vale para **desabilitar o ambiente** inteiro.
</Warning>

## Onde isso aparece no produto

* **Formulários de captação** públicos (link ou iframe) carregam o fluxo com a chave na URL — o mesmo tipo de credencial gerenciada aqui; veja [Formulários de captação](/conceitos/formularios-de-captacao).
* **Envio de modelos de mensagem** para um chat (`POST` em `chats/{chatId}/templates` no gateway): veja abaixo.
* Demais integrações server-to-server seguem o cabeçalho e o tipo de chave descritos na referência da API.

## Enviar modelo com variáveis pela API

O endpoint de envio de template aceita o ID do modelo cadastrado no Spark. Variáveis funcionam como no painel:

* **Manuais** — envie em `commonVariables`, com chaves `var1`, `var2`, … (cada número corresponde a `{{1}}`, `{{2}}` no texto do modelo).
* **Automáticas (dados do chat)** — não envie no body; o Spark resolve com base no `chatId` da URL (nome, contato, aniversário ou campo personalizado configurado no modelo).

Exemplo mínimo:

```json theme={null}
{
  "templateId": "seu_template_id",
  "commonVariables": {
    "var1": "Promoção de maio",
    "var2": "15OFF"
  }
}
```

Se faltar valor para alguma variável manual obrigatória, a API responde com erro pedindo o preenchimento. Detalhes dos tipos de variável e configuração no modelo estão em [Modelos de mensagem](/conceitos/modelos-de-mensagem).

## Disparos de campanha pela API

Além de mensagens individuais, é possível criar e iniciar **campanhas em massa** com filtros de público-alvo, plataforma, template e cadência — o mesmo conjunto de opções do painel de [Disparos](/conceitos/disparos).

### Fluxo em duas etapas

A API espelha o painel: primeiro você **cria um rascunho** com template, plataforma, cadência e filtros; depois **inicia** informando as variáveis manuais do modelo (se houver). Isso permite estimar o público antes de confirmar o envio.

| Etapa           | Endpoint                                          | Resultado                              |
| --------------- | ------------------------------------------------- | -------------------------------------- |
| Escolher modelo | `GET /v1/message-templates/{id}`                  | Ver `commonVariables` exigidas         |
| Estimar público | `POST /v1/campaigns/audience-preview`             | `estimatedCount` de chats              |
| Criar rascunho  | `POST /v1/campaigns`                              | `campaignId` com status `draft`        |
| Iniciar         | `POST /v1/campaigns/{id}/start`                   | `executionId` com status `processing`  |
| Acompanhar      | `GET /v1/campaigns/{id}/executions/{executionId}` | `progress`, `sentCount`, `failedCount` |

### Variáveis no disparo

Funcionam como no envio individual de template (seção acima):

* **Manuais** — envie em `commonVariables` no start (`var1` → `{{1}}`, `var2` → `{{2}}`, …). O mesmo valor vale para todos os destinatários.
* **Automáticas** — resolvidas pelo Spark por chat (nome, contato, aniversário, campo personalizado). Não envie no body.

Consulte `GET /v1/message-templates/{id}` para saber quais variáveis manuais são obrigatórias antes de chamar o start.

### Filtros de público-alvo

Segmente chats por tags, plataforma, funil, canal de entrada, datas e dezenas de outros critérios. A estrutura usa grupos combinados com AND entre grupos e AND/OR dentro de cada grupo.

Consulte o catálogo completo em `GET /v1/campaigns/filters/schema` ou veja exemplos prontos no guia da API.

<Warning title="platform da campanha ≠ filtro de chats">
  O campo `platform` no body define o **canal de envio**. Para restringir quais chats entram no público, inclua explicitamente um filtro `chat.platform` (ou outros campos como `chat.tagIds`, `chat.funnelStepId`, etc.).
</Warning>

Guia completo com tutorial passo a passo, tabela de filtros, exemplos JSON e SDK: [Disparos pela API](/api-reference/campaigns).

## SDK oficial (TypeScript)

Para Node, Bun, Deno e runtimes compatíveis, use o pacote [`sparkcrm`](https://www.npmjs.com/package/sparkcrm) em vez de montar `fetch` manualmente. A documentação na aba [SDKs](/sdks/index) cobre instalação, referência de métodos, tipos de webhook e tratamento de erros.

## Referência técnica

Passo a passo de habilitação, cabeçalho `X-API-Key`, base URL e boas práticas de integração estão na [Introdução à API](/api-reference/introduction) (aba Referência da API).