API para desenvolvedores

Envie uma DM com um único POST.

Uma API REST para o seu CRM no plano Business: contatos, conversas, negócios, tarefas, campanhas e mensagens no Telegram, no X e na caixa de entrada social. Autenticação Bearer, chaves com escopo, idempotência, cabeçalhos de limite de taxa e webhooks de saída. Sem precisar de SDK.

  • JSON sobre HTTPS
  • Respostas de baixa latência
  • Confiável por design

Última atualização:

Escolha a sua stack

O mesmo endpoint. Quatro linguagens.

Um único contrato JSON. Copie, cole e coloque no ar. A especificação OpenAPI completa documenta cada endpoint, cada erro e cada payload de webhook.

curl -X POST https://api.pinlyx.com/v1/telegram/messages \  -H "Authorization: Bearer csk_live_***" \  -H "Idempotency-Key: $(uuidgen)" \  -H "Content-Type: application/json" \  -d '{"accountId":7421,"username":"sarah_miller","text":"Boas-vindas a bordo"}'

Referência completa e catálogo de erros em docs.pinlyx.com/api

Autenticação

Chaves com escopo. Privilégio mínimo por padrão.

Gere chaves de API com escopo: somente leitura para painéis de análise, escrita para os envios em produção e gestão para a automação operacional. Faça a rotação sem tempo fora do ar: as chaves convivem durante a troca, então nada quebra.

  • Autenticação Bearer

    Envie Authorization: Bearer csk_live_… em toda requisição. Chaves de produção e de teste são visualmente diferentes, para que os fluxos em produção fiquem protegidos.

  • Permissões por escopo

    Escolha o menor conjunto de escopos de que a chave precisa. Uma chave de painel vazada nunca consegue enviar uma mensagem.

  • Rotação sem tempo fora do ar

    Emita uma chave substituta, faça o deploy e depois revogue a antiga. As duas valem durante a janela de transição, sem uma avalanche de erros 401.

Envios em produçãoProdução
csk_live_a4f9_
Escopos
  • contacts:readListar, buscar e ler contatos e as conversas deles.
  • telegram:readConsultar o status de uma mensagem de Telegram na fila.
  • analytics:readPuxar estatísticas de funil, campanhas e contas.
  • telegram:sendColocar na fila mensagens de Telegram das suas próprias contas.
  • contacts:writeCriar, atualizar e etiquetar contatos.
  • sequences:writeInscrever contatos em campanhas, pausar e retomar.
  • webhooks:writeRegistrar endpoints de webhook e fazer a rotação deles.
Confiabilidade

Controle de fluxo que conta tudo para você.

Com chaves de idempotência, repetir uma requisição é seguro: a mesma mensagem nunca sai duas vezes. Os cabeçalhos de limite de taxa avisam o seu cliente quando desacelerar, antes mesmo de chegar um 429.

Resposta · 200 OK187 ms
X-RateLimit-Limit
60
# requisições por minuto, por chave
X-RateLimit-Remaining
48
# restantes na janela atual
X-RateLimit-Reset
1778077380
# horário Unix em que a janela reinicia
Retry-After
12
# em caso de 429, espere esta quantidade de segundos
  • Chaves de idempotência

    Envie Idempotency-Key em toda escrita. Uma nova tentativa com a mesma chave em até 24 horas devolve a resposta original em vez de enviar de novo.

  • Limites de taxa por chave

    Cada chave de API permite 60 requisições por minuto por padrão, com ajuste por chave. Depois, os envios no Telegram seguem o ritmo da própria conta: 20 mensagens por hora e um intervalo de 10 segundos por padrão, com espera automática em caso de flood wait.

  • Catálogo de erros estável

    Todo erro devolve um campo Error estável para a sua lógica decidir o que fazer, além de um campo Message em linguagem clara para mostrar ao usuário, no mesmo formato JSON em todos os endpoints.

Webhooks

Webhooks de saída para cada evento.

Receba 31 eventos do CRM em tempo real. Assinaturas HMAC-SHA256, novas tentativas automáticas com espera exponencial e um registro de entregas onde você pode reenviar qualquer entrega.

Mais eventos
  • message.sent
  • contact.created
  • pipeline.stage_changed
  • sequence.completed
  • outreach.replied
  • task.completed
  • support.ticket.created
  • subscription.changed
POSTyour-handlerentregue
{  "event": "message.received",  "id": "8c1f4b9e2d7a4c03b5e6f1a2",  "deliveredAt": "2026-05-06T14:32:18Z",    "channel": "telegram",    "contactId": 8821,    "counterparty": "@sarah_miller",    "text": "Oi, pode me mandar a demo?"}
Verifique ao receberNode.js
const sig = crypto.createHmac('sha256', secret).update(rawBody).digest('hex');if ('sha256=' + sig !== headers['x-webhook-signature']) return 401;

Quando você quiser começar

Construa com o Pinlyx. No ar em minutos.

No plano Business, você cria uma chave no painel, cola um curl e vê a mensagem entrar na fila. A referência OpenAPI documenta cada endpoint e cada erro.

  • No plano Business
  • Chaves criadas no painel
  • Webhooks assinados com HMAC