Saltar al contenido
Ayuda · Sitios web y blogs

Conecta tu sitio web a Posttai

Cualquier sitio, no solo WordPress. Posttai entrega el artículo por un webhook firmado, o tu sitio lo consulta en la API de contenido. Esta guía tiene el contrato y ejemplos listos. Los nombres de los campos quedan en portugués, tal como los envía la API.

Elige cómo conectar

El resto de Posttai (editor, calendario, aprobación, IA e informe) funciona igual en todas.

Webhook de Posttai

Sitios con back-end propio, en cualquier lenguaje.

A la hora de publicar, Posttai envía un POST firmado con el artículo. El sitio lo guarda y responde con el enlace.

API de contenido

Sitio estático, o Nuxt o Next con build.

El sitio consulta los artículos con una clave de lectura, o por los feeds JSON y RSS.

WordPress

WordPress.com o WordPress propio.

Inicio de sesión de WordPress.com o contraseña de aplicación, sin nada de código.

Conectar por webhook

  1. En la app, abre Canais (Canales), elige Site e indica la URL https:// que recibirá los artículos.
  2. Posttai muestra el secreto de firma (whsec_…) una sola vez. Guárdalo en una variable de entorno del sitio, como POSTTAI_SEGREDO.
  3. Publica el código que recibe la llamada (mira los ejemplos de abajo) y pulsa conectar. Posttai envía un evento ping firmado y solo guarda el canal si la respuesta es 2xx.

La URL tiene que ser pública: solo https, puerto 443 u 8443, sin usuario en la URL y con un nombre que resuelva a una IP pública. Las direcciones internas o privadas se rechazan.

Lo que llega a tu sitio

Un POST con Content-Type: application/json y estas cabeceras:

  • x-posttai-evento: artigo.publicar o ping.
  • x-posttai-entrega: ent_…, el mismo en todos los intentos de la misma publicación. El mismo valor llega firmado en el cuerpo (entrega): usa el del cuerpo para no guardar dos veces.
  • x-posttai-assinatura: t=UNIX,v1=HEX, con v1 = HMAC-SHA256(secreto, "T.CUERPO") sobre los bytes exactos del cuerpo (T es el mismo número que t).

Cuerpo de artigo.publicar:

{
  "evento": "artigo.publicar",
  "entrega": "ent_3f9a0c1b2d4e5f60718293a4b5c6d7e8",
  "id": "6720f0c1a2b3c4d5e6f70809",
  "titulo": "Café coado: o guia",
  "slug": "cafe-coado-o-guia",
  "resumo": "Como coar café em casa.",
  "html": "<h2>Por que coar</h2>\n<p>…</p>",
  "markdown": "## Por que coar\n\n…",
  "imagens": [
    {
      "url": "https://cdn.posttai.com/…/capa.webp",
      "alt": "Xícara de café",
      "largura": 1200,
      "altura": 630
    }
  ],
  "categorias": [
    "Receitas"
  ],
  "tags": [
    "café"
  ],
  "seo": {
    "titulo": "Café coado: o guia",
    "descricao": "Como coar café em casa.",
    "palavraChave": "café coado"
  },
  "publicarEm": "2026-10-10T12:00:00.000Z",
  "idioma": "pt-BR",
  "marca": {
    "nome": "Sua marca"
  }
}
  • id es el id de la publicación en Posttai (el mismo si el artículo se reenvía). marca lleva solo el nombre.
  • El html ya sale escapado y seguro; el markdown va tal como se escribió.
  • El ping trae { evento: "ping", entrega, id, criadoEm, marca: { nome } }.

Respuesta, errores y reintentos

  • Todo bien: responde 2xx con { "url": "https://…" }. El enlace pasa a ser la dirección de la publicación, entra en el informe y va a las redes al publicar juntos.
  • Error definitivo: 4xx (salvo 408 y 429) se detiene al instante, con tu mensaje (erro, error o message) en la publicación.
  • Reintento: 5xx, 408, 429, tiempo agotado o caída de red vuelven a la cola a los 1, 5, 15 y 60 minutos (5 intentos en total).
  • Las redirecciones (3xx) no se siguen. Cada llamada tiene un plazo de 15 segundos.
  • Si falla del todo, la publicación queda con error y la campana de la app avisa.

Verificar la firma

  • Verifica con el cuerpo sin procesar, antes de interpretar el JSON.
  • Acepta solo un v1 con 64 caracteres hexadecimales y compara en tiempo constante.
  • Rechaza un t con más de 5 minutos de diferencia con tu reloj.
  • Cambio de secreto sin parar: al generar un secreto nuevo, durante 24 horas la cabecera lleva dos v1 (el nuevo y el anterior). Acepta la llamada si cualquier v1 coincide con POSTTAI_SEGREDO o POSTTAI_SEGREDO_ANTERIOR; pasado el plazo, borra el anterior.

Ejemplos listos

Los mismos de la pantalla del canal en la app. Todos verifican la firma, devuelven 400 ante una solicitud inválida y 5xx cuando falla al guardar (Posttai lo reintenta), y guardan una sola vez por entrega.

Node (Express)
// Node + Express: npm i express
import express from 'express'
import crypto from 'node:crypto'

const app = express()
// Segredos aceitos: o atual e, durante a troca, o anterior. Sempre em variável de ambiente.
const SEGREDOS = [process.env.POSTTAI_SEGREDO, process.env.POSTTAI_SEGREDO_ANTERIOR].filter(Boolean)
const HEX64 = /^[0-9a-f]{64}$/

// corpo: Buffer com os bytes exatos; cabecalho: "t=<unix>,v1=<hex>[,v1=<hex>]".
function assinaturaValida (corpo, cabecalho, segredos = SEGREDOS) {
  const partes = String(cabecalho || '').split(',').map(p => p.trim())
  const tTexto = partes.find(p => p.startsWith('t='))?.slice(2) || ''
  const t = /^\d{1,12}$/.test(tTexto) ? Number(tTexto) : 0
  // Só v1 com 64 caracteres hex; o resto é descartado ANTES de comparar (bytes com bytes, 32 e 32).
  const recebidas = partes.filter(p => p.startsWith('v1=')).map(p => p.slice(3)).filter(v => HEX64.test(v)).map(v => Buffer.from(v, 'hex'))
  if (!t || !recebidas.length || Math.abs(Date.now() / 1000 - t) > 300) return false // janela de 5 min
  return segredos.some(segredo => {
    const esperada = crypto.createHmac('sha256', segredo).update(`${t}.`).update(corpo).digest()
    return recebidas.some(r => crypto.timingSafeEqual(r, esperada))
  })
}

// express.raw: a assinatura é sobre os bytes exatos do corpo (nada de express.json antes desta rota).
app.post('/api/posttai', express.raw({ type: 'application/json', limit: '2mb' }), async (req, res) => {
  let dados
  try {
    const corpo = Buffer.isBuffer(req.body) ? req.body : Buffer.alloc(0)
    if (!assinaturaValida(corpo, req.get('x-posttai-assinatura'))) return res.status(401).json({ erro: 'Assinatura inválida' })
    dados = JSON.parse(corpo.toString('utf8'))
  } catch {
    return res.status(400).json({ erro: 'Pedido inválido' })
  }
  if (dados?.evento === 'ping') return res.json({ ok: true })
  if (dados?.evento !== 'artigo.publicar' || typeof dados.entrega !== 'string') return res.status(400).json({ erro: 'Evento desconhecido' })
  try {
    // dados.entrega vem DENTRO do corpo assinado e se repete nas novas tentativas:
    // grave o artigo uma vez só por entrega (ex.: índice único na sua tabela).
    const url = await salvarArtigo(dados.entrega, dados) // sua função: devolve o link do artigo
    return res.json({ url })
  } catch {
    return res.status(500).json({ erro: 'Falha ao gravar' }) // 5xx: a Posttai tenta de novo
  }
})

app.listen(3000)
Nuxt (server route)
// Nuxt 3: server/api/posttai.post.ts
import crypto from 'node:crypto'

const HEX64 = /^[0-9a-f]{64}$/

function assinaturaValida (corpo: Buffer, cabecalho: string, segredos: string[]) {
  const partes = cabecalho.split(',').map(p => p.trim())
  const tTexto = partes.find(p => p.startsWith('t='))?.slice(2) || ''
  const t = /^\d{1,12}$/.test(tTexto) ? Number(tTexto) : 0
  // Só v1 com 64 caracteres hex; o resto é descartado ANTES de comparar.
  const recebidas = partes.filter(p => p.startsWith('v1=')).map(p => p.slice(3)).filter(v => HEX64.test(v)).map(v => Buffer.from(v, 'hex'))
  if (!t || !recebidas.length || Math.abs(Date.now() / 1000 - t) > 300) return false
  return segredos.some(segredo => {
    const esperada = crypto.createHmac('sha256', segredo).update(`${t}.`).update(corpo).digest()
    return recebidas.some(r => crypto.timingSafeEqual(r, esperada))
  })
}

export default defineEventHandler(async (event) => {
  const segredos = [process.env.POSTTAI_SEGREDO, process.env.POSTTAI_SEGREDO_ANTERIOR].filter(Boolean) as string[]
  let dados: any
  try {
    const corpo = (await readRawBody(event, false)) || Buffer.alloc(0) // bytes exatos
    if (!assinaturaValida(corpo, getHeader(event, 'x-posttai-assinatura') || '', segredos)) {
      setResponseStatus(event, 401)
      return { erro: 'Assinatura inválida' }
    }
    dados = JSON.parse(corpo.toString('utf8'))
  } catch {
    setResponseStatus(event, 400)
    return { erro: 'Pedido inválido' }
  }
  if (dados?.evento === 'ping') return { ok: true }
  if (dados?.evento !== 'artigo.publicar' || typeof dados.entrega !== 'string') {
    setResponseStatus(event, 400)
    return { erro: 'Evento desconhecido' }
  }
  // dados.entrega vem no corpo assinado e se repete nas novas tentativas: grave uma vez só por entrega.
  const url = await salvarArtigo(dados.entrega, dados) // sua função; se lançar, o Nuxt responde 500 e a Posttai tenta de novo
  return { url }
})
Next (route handler)
// Next.js (App Router): app/api/posttai/route.ts
import crypto from 'node:crypto'

export const runtime = 'nodejs' // node:crypto

const SEGREDOS = [process.env.POSTTAI_SEGREDO, process.env.POSTTAI_SEGREDO_ANTERIOR].filter(Boolean) as string[]
const HEX64 = /^[0-9a-f]{64}$/

function assinaturaValida (corpo: Buffer, cabecalho: string) {
  const partes = cabecalho.split(',').map(p => p.trim())
  const tTexto = partes.find(p => p.startsWith('t='))?.slice(2) || ''
  const t = /^\d{1,12}$/.test(tTexto) ? Number(tTexto) : 0
  // Só v1 com 64 caracteres hex; o resto é descartado ANTES de comparar.
  const recebidas = partes.filter(p => p.startsWith('v1=')).map(p => p.slice(3)).filter(v => HEX64.test(v)).map(v => Buffer.from(v, 'hex'))
  if (!t || !recebidas.length || Math.abs(Date.now() / 1000 - t) > 300) return false
  return SEGREDOS.some(segredo => {
    const esperada = crypto.createHmac('sha256', segredo).update(`${t}.`).update(corpo).digest()
    return recebidas.some(r => crypto.timingSafeEqual(r, esperada))
  })
}

export async function POST (req: Request) {
  let dados: any
  try {
    const corpo = Buffer.from(await req.arrayBuffer()) // bytes exatos, antes de qualquer JSON.parse
    if (!assinaturaValida(corpo, req.headers.get('x-posttai-assinatura') || '')) {
      return Response.json({ erro: 'Assinatura inválida' }, { status: 401 })
    }
    dados = JSON.parse(corpo.toString('utf8'))
  } catch {
    return Response.json({ erro: 'Pedido inválido' }, { status: 400 })
  }
  if (dados?.evento === 'ping') return Response.json({ ok: true })
  if (dados?.evento !== 'artigo.publicar' || typeof dados.entrega !== 'string') {
    return Response.json({ erro: 'Evento desconhecido' }, { status: 400 })
  }
  // dados.entrega vem no corpo assinado e se repete nas novas tentativas: grave uma vez só por entrega.
  const url = await salvarArtigo(dados.entrega, dados) // sua função; se lançar, o Next responde 500 e a Posttai tenta de novo
  return Response.json({ url })
}
PHP
<?php
// PHP 7.4+: posttai.php
header('Content-Type: application/json');

function assinatura_valida(string $corpo, string $cabecalho, array $segredos): bool
{
    $t = 0;
    $recebidas = [];
    foreach (explode(',', $cabecalho) as $parte) {
        $par = explode('=', trim($parte), 2);
        if (count($par) !== 2) continue;
        [$chave, $valor] = $par;
        if ($chave === 't' && preg_match('/^[0-9]{1,12}\z/', $valor) === 1) $t = (int) $valor;
        // Só v1 com 64 caracteres hex; o resto é descartado antes de comparar.
        if ($chave === 'v1' && preg_match('/^[0-9a-f]{64}\z/', $valor) === 1) $recebidas[] = $valor;
    }
    if ($t === 0 || count($recebidas) === 0 || abs(time() - $t) > 300) return false;
    foreach ($segredos as $segredo) {
        $esperada = hash_hmac('sha256', $t . '.' . $corpo, $segredo);
        foreach ($recebidas as $r) {
            if (hash_equals($esperada, $r)) return true;
        }
    }
    return false;
}

try {
    $corpo = file_get_contents('php://input'); // bytes exatos
    $segredos = array_filter([getenv('POSTTAI_SEGREDO'), getenv('POSTTAI_SEGREDO_ANTERIOR')]);
    if (!is_string($corpo) || !assinatura_valida($corpo, (string) ($_SERVER['HTTP_X_POSTTAI_ASSINATURA'] ?? ''), $segredos)) {
        http_response_code(401);
        echo json_encode(['erro' => 'Assinatura inválida']);
        exit;
    }
    $dados = json_decode($corpo, true, 64, JSON_THROW_ON_ERROR);
} catch (\Throwable $e) {
    http_response_code(400);
    echo json_encode(['erro' => 'Pedido inválido']);
    exit;
}

$evento = is_array($dados) ? ($dados['evento'] ?? '') : '';
if ($evento === 'ping') {
    echo json_encode(['ok' => true]);
    exit;
}
if ($evento !== 'artigo.publicar' || !is_string($dados['entrega'] ?? null)) {
    http_response_code(400);
    echo json_encode(['erro' => 'Evento desconhecido']);
    exit;
}

// $dados['entrega'] vem no corpo assinado e se repete nas novas tentativas: grave uma vez só por entrega.
$url = salvar_artigo($dados['entrega'], $dados); // sua função: devolve o link (se falhar, responda 500)
echo json_encode(['url' => $url]);
Python (Flask)
# Python 3 + Flask: pip install flask
import hashlib
import hmac
import json
import os
import re
import time

from flask import Flask, jsonify, request

app = Flask(__name__)
SEGREDOS = [s for s in (os.environ.get('POSTTAI_SEGREDO'), os.environ.get('POSTTAI_SEGREDO_ANTERIOR')) if s]
HEX64 = re.compile(r'[0-9a-f]{64}')
NUMERO = re.compile(r'[0-9]{1,12}')


def assinatura_valida(corpo: bytes, cabecalho: str) -> bool:
    partes = [p.strip() for p in (cabecalho or '').split(',')]
    t_texto = next((p[2:] for p in partes if p.startswith('t=')), '')
    t = int(t_texto) if NUMERO.fullmatch(t_texto) else 0
    # Só v1 com 64 caracteres hex; o resto é descartado antes de comparar (bytes com bytes).
    recebidas = [bytes.fromhex(p[3:]) for p in partes if p.startswith('v1=') and HEX64.fullmatch(p[3:])]
    if not t or not recebidas or abs(time.time() - t) > 300:
        return False
    for segredo in SEGREDOS:
        esperada = hmac.new(segredo.encode(), f'{t}.'.encode() + corpo, hashlib.sha256).digest()
        if any(hmac.compare_digest(esperada, r) for r in recebidas):
            return True
    return False


@app.post('/api/posttai')
def posttai():
    try:
        corpo = request.get_data(cache=False)  # bytes exatos
        if not assinatura_valida(corpo, request.headers.get('x-posttai-assinatura', '')):
            return jsonify(erro='Assinatura inválida'), 401
        dados = json.loads(corpo)
    except Exception:
        return jsonify(erro='Pedido inválido'), 400
    if not isinstance(dados, dict):
        return jsonify(erro='Pedido inválido'), 400
    if dados.get('evento') == 'ping':
        return jsonify(ok=True)
    if dados.get('evento') != 'artigo.publicar' or not isinstance(dados.get('entrega'), str):
        return jsonify(erro='Evento desconhecido'), 400
    # dados['entrega'] vem no corpo assinado e se repete nas novas tentativas: grave uma vez só por entrega.
    url = salvar_artigo(dados['entrega'], dados)  # sua função: devolve o link (se lançar, o Flask responde 500)
    return jsonify(url=url)

API de contenido y feeds

Para un sitio estático o con build: genera una clave de lectura (pts_…) en la pantalla del canal y envíala en la cabecera Authorization: Bearer. La clave lee solo los artículos de ese canal (planes Profissional / Agência).

  • GET /v1/sites/:idCanal/artigos?pagina=1&porPagina=20&desde=… lista los artículos publicados, los más nuevos primero (hasta 100 por página).
  • GET /v1/sites/:idCanal/artigos/:slug trae un artículo.
  • GET /v1/sites/:idCanal/feed.json y /rss.xml son los feeds públicos, si están activados en el canal.
  • Toda respuesta tiene ETag y responde 304 con If-None-Match; caché de 60 segundos.
  • Límites: 120 lecturas por minuto por clave y 300 por IP.
  • La clave es solo para el servidor o el build del sitio. Nunca en el código que va al navegador; para leer directo en el navegador, usa los feeds.
curl https://api.posttai.com/v1/sites/ID_DO_CANAL/artigos \
  -H "Authorization: Bearer $POSTTAI_CHAVE_SITE"

Aviso de despliegue: indica la URL del deploy hook (Vercel, Netlify, DigitalOcean, Cloudflare) y, después de cada artículo publicado, Posttai lo llama para que el sitio vuelva a hacer el build.

Publicar juntos

En el editor, marca Publicar o artigo no site e as redes com o link (publicar el artículo en el sitio y las redes con el enlace). El artículo sale primero; las redes reciben el texto con el enlace del artículo, con UTM y por el acortador de Posttai, para que veas los clics de cada red. Si el sitio tarda, las redes esperan hasta 30 minutos (o salen sin el enlace, si lo prefieres).

La IA también escribe el artículo a partir de la publicación o del carrusel, con título, resumen, slug y SEO.

Empieza hoy

Pon tu sitio en el calendario

Crea la cuenta, conecta el sitio y las redes, y publícalo todo junto.

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