TrackPost — Documentación

Getting Started

1. Crea y verifica una única cuenta de Cloud. 2. Selecciona o crea la organización propietaria de la integración. 3. Crea un proyecto para el sitio, tienda o marca cuyos datos deban permanecer juntos. 4. Abre el espacio del producto y confirma que está habilitado antes de copiar credenciales o enviar tráfico de producción.

Con esto termina la configuración de la cuenta. Las secciones siguientes son guías de implementación. Las credenciales siempre pertenecen a un proyecto; los secretos de servidor nunca deben aparecer en código del navegador, repositorios públicos ni variables del cliente.

Conecta un destino antes de publicar

Abre TrackPost → Conexiones y conecta al menos una cuenta que tengas permiso para usar. Selecciona el destino mostrado en la publicación o en la solicitud API; TrackPost impide publicar en destinos no disponibles o no autorizados.

Conectar cuentas de publicación

Una vez habilitado, cada usuario puede conectar las Páginas de Facebook, cuentas profesionales de Instagram, perfiles de Threads, ubicaciones de Google Business, perfiles de LinkedIn o páginas de organización de LinkedIn en los que tiene permiso para publicar. El callback de OAuth importa las cuentas aptas como connection IDs estables; las aplicaciones nunca recogen tokens del proveedor.

Un destino personal de LinkedIn queda ligado a la persona que lo conectó. La disponibilidad y permisos se validan por conexión.

Crear una clave API de TrackPost

Abre TrackPost → API. Un propietario o administrador crea una clave con nombre; el token tp_live_ completo se muestra una vez y debe guardarse en el gestor de secretos del servidor. El mismo panel muestra el endpoint exacto, cada plataforma utilizable y su connection ID. Las claves caducan y pueden revocarse.

Publicar o programar con post.publish

Envía un evento post.publish por POST al endpoint mostrado usando Authorization: Bearer <token>. eventId es la ID estable de idempotencia. post acepta texto, enlace HTTPS, URL HTTPS de media o combinación; destinations contiene de 1 a 25 objetos con la plataforma seleccionada y la connectionId exacta. scheduledAt es opcional y usa ISO 8601.

Los valores de plataforma permitidos son facebook, instagram, threads, google_business y linkedin. TrackPost comprueba que cada plataforma coincida con la conexión guardada. El nombre de una plataforma nunca publica por sí solo en todas las cuentas. Las integraciones existentes pueden mantener el arreglo heredado targets; una solicitud debe usar exactamente destinations o targets.

curl --request POST "$TRACKPOST_API_URL" \
  --header "Authorization: Bearer $TRACKPOST_API_KEY" \
  --header "Content-Type: application/json" \
  --header "X-Request-Id: release_2030_001" \
  --data '{
  "eventId": "blog_release_2030_001",
  "type": "post.publish",
  "scheduledAt": "2030-01-15T14:00:00.000Z",
  "post": {
    "text": "Our new article is live.",
    "linkUrl": "https://example.com/blog/article"
  },
  "destinations": [
    {
      "platform": "linkedin",
      "connectionId": "CONNECTION_ID"
    }
  ]
}'

Casos por canal y programación

Un evento crea una entrega por destino. Instagram profesional necesita media adecuada. Las solicitudes inmediatas comienzan tras ser aceptadas; scheduledAt futuro permanece en cola para el scheduler. Los enlaces de dominios de la organización reciben parámetros TrackAny.Click cuando la medición cruzada está habilitada.

Integrar agentes de IA con seguridad

Un agente puede preparar texto y referencias de media por canal, pero debe entregar el payload final de post.publish a un flujo de servidor autorizado. Separa generación, revisión humana, selección de destinos y publicación como pasos auditables; nunca entregues la clave API ni tokens de proveedor a código de agente en el navegador.

Aprobación e idempotencia

Envía solo después de aprobar contenido y destinos exactos. Repetir eventId con la misma clave devuelve el post existente con status=duplicate. Guarda requestId, postId, status y publishAt; no generes otra eventId solo porque una respuesta agotó el tiempo.

Respuestas, errores y medición

Un plan nuevo devuelve HTTP 202 y un replay idempotente HTTP 200. Corrige 400 invalid_request, 401 invalid_token, 403 permission y 409 idempotency_conflict antes de reintentar. Respeta Retry-After en 429 y usa backoff limitado para 503 transitorios.

Los parámetros TrackAny.Click en enlaces propios miden visitas y resultados posteriores, no demuestran que el post haya sido visto. Estado de publicación y atribución web son señales separadas.