Saltar al contenido
Para desarrolladores

API y webhooks de Posttai

El mismo token que conecta tu IA (MCP) también abre la API REST. Crea publicaciones, prográmalas, sube medios y recibe avisos firmados cuando algo pase. Los nombres de los campos y los mensajes de la API están en portugués.

Autenticación

Genera un token en Configurações → Tokens e MCP (Configuración → Tokens y MCP, planes Profissional y Agência). Empieza por ptt_, pertenece a una marca y aparece una sola vez. Envíalo en cada solicitud en la cabecera Authorization:

curl https://api.posttai.com/tokens-api/atual \
  -H "Authorization: Bearer ptt_seu_token"
  • El token tiene el rol de editor: crea, edita, programa y cancela publicaciones; no aprueba ni toca el equipo, los tokens, los webhooks ni el plan.
  • Si quien creó el token sale del equipo, o si el plan deja de incluir la API, el token deja de funcionar al instante (401/403).
  • Horarios en ISO 8601. Envíalos con zona horaria (2026-10-09T18:30:00-03:00); Posttai trabaja en el horario de Brasilia.

Respuestas y errores

Todas las respuestas vienen en el mismo sobre. En caso de error, body trae el mensaje listo, en portugués.

{ "status": "ok", "statusCode": 200, "body": { ... } }
{ "status": "error", "statusCode": 422, "body": "Escolha pelo menos um canal." }
  • 401 token inválido o revocado · 403 sin permiso o fuera del plan · 404 no existe en esta marca · 409 conflicto de estado · 422 dato inválido · 429 límite.
  • Límite general: 300 solicitudes por minuto por IP. La IA tiene su propio límite por persona y por marca.

Canales

Las cuentas conectadas de la marca. Conectar una cuenta nueva se hace en la app (o con el enlace para pedir al cliente que conecte).

GET/canais

Lista las cuentas conectadas: _id, rede, nome, usuario y status (activo, caducado, error).

curl https://api.posttai.com/canais -H "Authorization: Bearer $POSTTAI_TOKEN"
GET/canais/redes

Redes disponibles, con los límites de texto y medios de cada una.

curl https://api.posttai.com/canais/redes -H "Authorization: Bearer $POSTTAI_TOKEN"
GET/grupos-canais

Grupos de canales (p. ej., "Cliente X"), para publicar en varios a la vez.

curl https://api.posttai.com/grupos-canais -H "Authorization: Bearer $POSTTAI_TOKEN"

Publicaciones

Una publicación tiene texto base, canales, medios y, si quieres, un texto propio por canal (variacoes).

GET/posts?status=agendado&de=…&ate=…

Lista publicaciones. status acepta varios valores separados por comas; de/ate filtran por la fecha programada.

curl "https://api.posttai.com/posts?status=agendado,publicado&de=2026-10-01&ate=2026-10-31" -H "Authorization: Bearer $POSTTAI_TOKEN"
GET/posts/:id

Una publicación con sus publicaciones por red (enlace y error de cada una) e historial.

curl https://api.posttai.com/posts/ID_DO_POST -H "Authorization: Bearer $POSTTAI_TOKEN"
POST/posts

Crea un borrador. canais y midias son ids; variacoes es opcional.

curl -X POST https://api.posttai.com/posts -H "Authorization: Bearer $POSTTAI_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"conteudo":"Novidade na loja!","canais":["ID_DO_CANAL"],"midias":[]}'
PUT/posts/:id

Cambia texto, canales, medios, variaciones o fecha (los mismos campos del POST).

curl -X PUT https://api.posttai.com/posts/ID_DO_POST -H "Authorization: Bearer $POSTTAI_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"conteudo":"Texto novo"}'
POST/posts/:id/agendar

Programa. Si la marca exige aprobación, la publicación va a la cola de aprobación en lugar de programarse.

curl -X POST https://api.posttai.com/posts/ID_DO_POST/agendar -H "Authorization: Bearer $POSTTAI_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"agendadoPara":"2026-10-09T18:30:00-03:00"}'
POST/posts/:id/publicar-agora

La envía ahora a la cola de publicación.

curl -X POST https://api.posttai.com/posts/ID_DO_POST/publicar-agora -H "Authorization: Bearer $POSTTAI_TOKEN"
POST/posts/:id/cancelar

Saca de la cola una publicación programada (vuelve a borrador).

curl -X POST https://api.posttai.com/posts/ID_DO_POST/cancelar -H "Authorization: Bearer $POSTTAI_TOKEN"
DELETE/posts/:id

Elimina una idea, un borrador, una publicación cancelada o con error.

curl -X DELETE https://api.posttai.com/posts/ID_DO_POST -H "Authorization: Bearer $POSTTAI_TOKEN"
GET/calendario?de=…&ate=…

Publicaciones del periodo en todos los estados del calendario.

curl "https://api.posttai.com/calendario?de=2026-10-01&ate=2026-10-31" -H "Authorization: Bearer $POSTTAI_TOKEN"
GET/sugestoes/horarios?rede=instagram&dias=7

Horarios sugeridos y libres en los próximos días.

curl "https://api.posttai.com/sugestoes/horarios?rede=instagram&dias=7" -H "Authorization: Bearer $POSTTAI_TOKEN"

Medios

POST/midias/url

Trae una imagen o un video desde una dirección pública y devuelve el _id para usar en midias.

curl -X POST https://api.posttai.com/midias/url -H "Authorization: Bearer $POSTTAI_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://exemplo.com/foto.jpg"}'
POST/midias

Sube un archivo (multipart, campo arquivo, hasta 100 MB).

curl -X POST https://api.posttai.com/midias -H "Authorization: Bearer $POSTTAI_TOKEN" -F "[email protected]"
GET/midias

Biblioteca de medios de la marca.

curl https://api.posttai.com/midias -H "Authorization: Bearer $POSTTAI_TOKEN"

Flujo y comentarios

GET/fluxo

Etapas del tablero de la marca.

curl https://api.posttai.com/fluxo -H "Authorization: Bearer $POSTTAI_TOKEN"
POST/posts/:id/etapa

Mueve la publicación de etapa (con responsable y plazo opcionales).

curl -X POST https://api.posttai.com/posts/ID_DO_POST/etapa -H "Authorization: Bearer $POSTTAI_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"etapa":"revisao"}'
GET/posts/:id/comentarios

Comentarios del equipo en la publicación.

curl https://api.posttai.com/posts/ID_DO_POST/comentarios -H "Authorization: Bearer $POSTTAI_TOKEN"
POST/posts/:id/comentarios

Comenta en la publicación.

curl -X POST https://api.posttai.com/posts/ID_DO_POST/comentarios -H "Authorization: Bearer $POSTTAI_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"texto":"Pronto para revisar"}'

Webhooks

En Configurações → Webhooks (Configuración → Webhooks), el dueño y los administradores registran hasta 5 URL por marca y eligen los eventos. Cada envío es un POST con JSON, desde nuestro worker (nunca bloquea la app).

  • post.publicado la publicación salió en todas las redes (o en parte de ellas, con status: "parcial").
  • post.erro una o más redes la rechazaron de forma definitiva.
  • post.aprovado aprobada por el equipo o por el cliente (dados.por).
  • post.reprovado rechazada por el equipo o con cambios pedidos por el cliente, con dados.motivo.
  • canal.desconectado la cuenta salió, caducó o se le quitó el acceso en la red (dados.motivo).
  • webhook.teste solo desde el botón "Testar" (Probar).
POST https://seu-sistema.com/webhooks/posttai
Content-Type: application/json
X-Posttai-Evento: post.publicado
X-Posttai-Entrega: 6702f0c1a9e4b1d2c3e4f5a6
X-Posttai-Assinatura: t=1791403800,v1=5f0c…e9

{
  "id": "6702f0c1a9e4b1d2c3e4f5a6",
  "evento": "post.publicado",
  "criadoEm": "2026-10-09T21:30:04.120Z",
  "idMarca": "66fe…",
  "dados": {
    "post": { "id": "6701…", "status": "publicado", "trecho": "Lançamento amanhã…", "agendadoPara": "2026-10-09T21:30:00.000Z", "publicadoEm": "2026-10-09T21:30:04.000Z" },
    "publicacoes": [{ "idCanal": "66ff…", "rede": "instagram", "status": "publicado", "url": "https://www.instagram.com/p/…", "erro": null }]
  }
}
  • Entregado = respuesta 2xx en hasta 10 s. No se siguen redirecciones.
  • Reintentos: 408, 429, 5xx y fallos de red se reintentan a los 30 s, 1, 2, 4 y 8 min (6 intentos). Los demás 4xx se detienen al instante.
  • Usa id (igual a X-Posttai-Entrega) para ignorar repetidos: la misma entrega puede llegar más de una vez.
  • Las últimas 20 entregas de cada URL, con cuerpo y respuesta, quedan en la pantalla del webhook durante 30 días.
  • Solo https://. Las direcciones internas o privadas (localhost, 10/8, 172.16/12, 192.168/16, 169.254/16, ::1, fc00::/7…) se rechazan, incluso cuando el nombre resuelve a ellas en el DNS.

Verificar la firma

El secreto (whsec_…) aparece una vez, al crear el webhook. La firma es HMAC-SHA256(secreto, t + "." + cuerpo sin procesar) en hexadecimal. Verifica siempre con el cuerpo exactamente como llegó, antes de interpretar el JSON, y rechaza t con más de 5 minutos.

import crypto from 'node:crypto'
import express from 'express'

const app = express()

// Corpo CRU: a assinatura é sobre os bytes que chegaram.
app.post('/webhooks/posttai', express.raw({ type: 'application/json' }), (req, res) => {
  const corpo = req.body.toString('utf8')
  const { t, v1 } = Object.fromEntries(String(req.get('X-Posttai-Assinatura')).split(',').map(p => p.split('=')))
  const esperado = crypto.createHmac('sha256', process.env.POSTTAI_WEBHOOK_SEGREDO).update(`${t}.${corpo}`).digest('hex')
  const ok = v1 && esperado.length === v1.length && crypto.timingSafeEqual(Buffer.from(esperado), Buffer.from(v1))
  if (!ok || Math.abs(Date.now() / 1000 - Number(t)) > 300) return res.sendStatus(401)

  const evento = JSON.parse(corpo)
  // ...trate evento.evento e evento.dados (ignore ids de entrega já vistos)
  res.sendStatus(204)
})

Empieza hoy

Organiza tu semana hoy

Crea la cuenta, conecta las redes y deja el calendario listo. Prueba el Profissional durante 7 días, sin tarjeta.

  • 7 días gratis
  • Sin tarjeta para probar
  • Publicaciones ilimitadas en todos los planes
Habla con nosotros