Skip to main content
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 encapsula autenticação, tipos e retentativas — veja a aba SDKs.

​
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:
PapelPrefixoUso típico
Chave públicapk_Identifica a organização em fluxos que exigem a chave “pública” (conforme cada endpoint na referência).
Chave secretask_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

1

Acesse o painel do Spark

Entre no dashboard com uma conta que tenha permissão de administrador da organização.
2

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 já autenticado.
3

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

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

​
Base URL e documentação viva

O gateway oficial da API pública está em gateway.crmspark.com.br (HTTPS).

​
Autenticação

Todas as requisições autenticadas devem enviar a chave no cabeçalho HTTP: 
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: 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).

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