API para desarrolladores

Envía un mensaje directo con un solo POST.

Una API REST para tu CRM en el plan Business: contactos, conversaciones, negocios, tareas, campañas y mensajes en Telegram, X y la bandeja social. Autenticación Bearer, claves con permisos acotados, idempotencia, cabeceras de límite de peticiones y webhooks salientes. Sin necesidad de SDK.

  • JSON sobre HTTPS
  • Respuestas de baja latencia
  • Fiable por diseño

Última actualización:

Elige tu stack

El mismo endpoint. Cuatro lenguajes.

Un único contrato JSON. Copia, pega y publica. La especificación OpenAPI completa documenta cada endpoint, cada error y 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":"Te damos la bienvenida"}'

Referencia completa y catálogo de errores en docs.pinlyx.com/api

Autenticación

Claves con permisos acotados. Mínimo privilegio por defecto.

Genera claves de API con permisos acotados: solo lectura para paneles de analítica, escritura para los envíos en producción y gestión para la automatización de operaciones. Rótalas sin interrupciones: durante el cambio, ambas claves conviven y nada se rompe.

  • Autenticación Bearer

    Envía Authorization: Bearer csk_live_… en cada petición. Las claves de producción y de prueba se distinguen a simple vista, así tus flujos en producción están a salvo.

  • Permisos acotados

    Asigna a cada clave solo los permisos que necesita. Una clave de panel filtrada nunca podrá enviar un mensaje.

  • Rotación sin interrupciones

    Emite una clave nueva, despliégala y revoca la anterior. Ambas son válidas durante el periodo de transición, sin avalanchas de errores 401.

Envíos en producciónProducción
csk_live_a4f9_
Permisos
  • contacts:readLista, busca y lee contactos y sus conversaciones.
  • telegram:readConsulta el estado de un mensaje de Telegram en cola.
  • analytics:readObtén estadísticas de embudos, campañas y cuentas.
  • telegram:sendPon en cola mensajes de Telegram desde tus propias cuentas.
  • contacts:writeCrea, actualiza y etiqueta contactos.
  • sequences:writeInscribe contactos en campañas, y pausa o reanuda su avance.
  • webhooks:writeRegistra y rota los endpoints de webhook.
Fiabilidad

Un control de carga que te lo cuenta todo.

Con las claves de idempotencia, reintentar es seguro: el mismo mensaje nunca se envía dos veces. Las cabeceras de límite de peticiones avisan a tu cliente de que debe ir más despacio antes de que llegue un 429.

Respuesta · 200 OK187 ms
X-RateLimit-Limit
60
# peticiones por minuto y por clave
X-RateLimit-Remaining
48
# restantes en la ventana actual
X-RateLimit-Reset
1778077380
# hora Unix en la que se reinicia la ventana
Retry-After
12
# ante un 429, espera estos segundos
  • Claves de idempotencia

    Envía Idempotency-Key en cada escritura. Un reintento con la misma clave en un plazo de 24 horas devuelve la respuesta original en lugar de volver a enviar.

  • Límites por clave

    Cada clave de API admite 60 peticiones por minuto por defecto, y el límite se ajusta por clave. Después, los envíos de Telegram siguen el ritmo propio de la cuenta: 20 mensajes por hora y 10 segundos entre mensajes por defecto, con espera automática ante el flood-wait.

  • Catálogo de errores estable

    Cada error devuelve un Error estable sobre el que puedes ramificar tu lógica, y un Message legible que puedes mostrar al usuario, con la misma estructura JSON en todos los endpoints.

Webhooks

Webhooks salientes para cada evento.

Recibe 31 eventos del CRM en tiempo real. Firmas HMAC-SHA256, reintentos automáticos con espera exponencial y un registro de entregas desde el que puedes reintentar cualquier envío.

Más eventos
  • message.sent
  • contact.created
  • pipeline.stage_changed
  • sequence.completed
  • outreach.replied
  • task.completed
  • support.ticket.created
  • subscription.changed
POSTyour-handlerentregado
{  "event": "message.received",  "id": "8c1f4b9e2d7a4c03b5e6f1a2",  "deliveredAt": "2026-05-06T14:32:18Z",    "channel": "telegram",    "contactId": 8821,    "counterparty": "@sarah_miller",    "text": "Hola, ¿me puedes enviar la demo?"}
Verifica al recibirNode.js
const sig = crypto.createHmac('sha256', secret).update(rawBody).digest('hex');if ('sha256=' + sig !== headers['x-webhook-signature']) return 401;

Cuando quieras empezar

Construye con Pinlyx. En marcha en minutos.

Con el plan Business, crea una clave en el panel, pega un curl y verás cómo el mensaje entra en la cola. La referencia OpenAPI documenta cada endpoint y cada error.

  • Incluido en el plan Business
  • Claves creadas en el panel
  • Webhooks firmados con HMAC