Skip to main content
A API pública do Spark permite que sistemas externos, como ERPs, sites e automações, leiam e enviem dados do CRM. Ela usa HTTP e JSON, tem a versão na URL (/v1) e autentica cada requisição com uma chave no cabeçalho. Esta página explica como habilitar a API, obter as chaves e fazer a primeira chamada. Os detalhes de cada endpoint estão na referência interativa, no menu lateral. Se o seu servidor usa TypeScript ou JavaScript, o cliente oficial sparkcrm cuida da autenticação, dos tipos e das retentativas. Veja SDKs.

​
Antes de começar

  • As chaves pertencem à organização, não a um usuário.
  • Só administradores da organização podem habilitar a API e criar ou revogar chaves. Se você integra para outra empresa, peça a chave ao administrador do Spark dela.

​
Chaves de API

Se você usar a chave pública num endpoint que exige a secreta, a API responde 401 com o código API_KEY_WRONG_TYPE.
Trate a chave secreta como uma senha: use-a só no servidor e não a coloque em repositórios, tickets ou capturas de tela.

​
Habilitar a API e obter as chaves

1

Abra as configurações de desenvolvedores

Entre no Spark com uma conta de administrador e abra Configurações → Desenvolvedores.
2

Habilite o ambiente

Ative o ambiente de API. Na primeira vez, o Spark cria a chave pública e a primeira chave secreta e mostra os valores para você copiar.
3

Guarde as chaves

Guarde as chaves num cofre de senhas ou em variáveis de ambiente. Você pode criar outras chaves secretas, desativar uma chave ou desligar o ambiente inteiro sem apagar as chaves.
Se você desligar e religar o ambiente, as chaves continuam as mesmas. Mais detalhes em Modo Desenvolvedores.

​
URL base e especificação

Todas as rotas ficam em https://gateway.crmspark.com.br, com o prefixo /v1. A especificação OpenAPI está em /swagger-json. Use-a para gerar clientes ou tipos na sua linguagem.

​
Autenticação

Envie a chave no cabeçalho X-API-Key de toda requisição:

​
Erros

Toda resposta de erro tem o mesmo formato:
Use code na lógica do seu código. O texto de message pode mudar. Erros que qualquer endpoint pode devolver: Os códigos específicos de cada recurso estão nas páginas de campanhas, modelos de mensagem e na referência de cada endpoint.

​
Limites de uso

Os limites valem por chave de API: Ao passar de um limite, a API responde 429 com o código RATE_LIMIT_EXCEEDED. Espere alguns segundos e tente de novo, aumentando o intervalo a cada nova falha.

​
Webhooks

Com o ambiente de desenvolvedores ativo, o Spark pode avisar o seu sistema quando algo acontece na organização, como uma mensagem recebida, um chat criado ou um número de WhatsApp conectado. A entrega usa o Svix, que assina as requisições e repete as que falharem. Veja os eventos e como verificar a assinatura em Webhooks.

​
Boas práticas

  • Use uma chave secreta por sistema integrado. Assim você revoga uma sem afetar as outras.
  • Troque as chaves quando mudar de fornecedor ou de equipe e remova as que não são mais usadas.
  • Trate 429 e erros 5xx com novas tentativas e espera crescente, para que uma falha temporária não derrube o seu sistema.