Social

Endpoints de Social: marcas, enlaces de conexión alojados, publicación individual y masiva, programación, estadísticas y límite global de conexiones.

La API de Social publica en Facebook, Instagram, X, LinkedIn y Pinterest. Todo el modelo se basa en dos objetos. Una marca es la identidad con la que publicas: un nombre, una zona horaria y las cuentas de redes sociales asociadas a ella. Una conexión es una cuenta de red social autorizada, asociada a una marca en una plataforma. Las marcas son ilimitadas en un plan de API y no tienen coste. El plan mide el uso por conexiones, así que el límite de conexiones es la restricción que debes tener en cuenta al diseñar tu integración.

No se puede conectar una cuenta desde tu servidor. El usuario final tiene que autorizarla en la plataforma, así que solicitas un enlace alojado y lo rediriges a él. La publicación es asíncrona: cada llamada de creación devuelve una respuesta en cuanto se acepta la publicación, y tú consultas periódicamente el resultado de cada canal.

Endpoints de un vistazo

Valores que usarás en todas partes

Los valores de plataforma son nombres de enumeración en mayúsculas. Si envías "instagram", se rechaza la solicitud. TWITTER es X; el nombre de la enumeración no cambió cuando cambió el del producto.

Crear una marca

POST /social/brands

profileName y timezone son obligatorios. La zona horaria es un objeto, y tzCode es el campo que importa: es el identificador IANA que se usa para interpretar cada scheduleDate y scheduleTime de las publicaciones de esta marca. Las otras tres claves son etiquetas de visualización.

curl -X POST https://listingsapi.com/api/v4/social/brands \  -H "Authorization: API $LISTINGSAPI_KEY" \  -H "Content-Type: application/json" \  -d '{    "input": {      "profileName": "Jenny Home",      "timezone": {        "label": "(GMT-05:00) Eastern Time",        "tzCode": "America/New_York",        "name": "Eastern Standard Time",        "utc": "-05:00"      },      "categories": ["Furniture Store"],      "siteUrl": "https://jennyhome.example"    }  }'

Conserva el identificador de marca devuelto. Es el parámetro brandId de la ruta en todos los demás endpoints de marcas y el campo socialProfileId del cuerpo cuando publicas.

Listar y consultar marcas

GET /social/brands devuelve una página de marcas. GET /social/brands/{brandId} devuelve una marca con todos sus detalles.

curl -H "Authorization: API $LISTINGSAPI_KEY" \  "https://listingsapi.com/api/v4/social/brands?page=1&size=25"

Si una consulta con un identificador devuelve SY95043, la marca no pertenece a esta cuenta o ya está archivada.

Actualizar una marca

POST /social/brands/update

El identificador de la marca va en el cuerpo como input.profileId, no en la ruta. Envía solo los campos que vas a cambiar; cualquier campo que omitas conserva su valor actual.

curl -X POST https://listingsapi.com/api/v4/social/brands/update \  -H "Authorization: API $LISTINGSAPI_KEY" \  -H "Content-Type: application/json" \  -d '{"input": {"profileId": "6f2c9a41-7b0e-4d55-9a2f-3c8e1d47b902", "bio": "Handmade furniture for real homes."}}'

Archivar una marca

POST /social/brands/archive

Una marca debe haber existido durante 90 días antes de poder archivarse. Antes de ese plazo, la llamada se rechaza con SY95051 y no cambia nada. Una vez que la marca tiene la antigüedad suficiente, el archivado surte efecto de inmediato y archiva todas sus conexiones al mismo tiempo.

Esas conexiones dejan de publicar de inmediato, pero sus plazas siguen contando hasta el final del período de facturación, exactamente igual que con una desconexión manual. Archivar no es una forma de liberar capacidad hoy.

curl -X POST https://listingsapi.com/api/v4/social/brands/archive \  -H "Authorization: API $LISTINGSAPI_KEY" \  -H "Content-Type: application/json" \  -d '{"input": {"socialProfileId": "6f2c9a41-7b0e-4d55-9a2f-3c8e1d47b902"}}'

Obtener un enlace de conexión

POST /social/brands/{brandId}/connections/link

Esta es la única forma de añadir una conexión. La respuesta incluye un url alojado, válido durante expiresIn segundos. Redirige al usuario final a ese enlace; el usuario concede la autorización en la plataforma y vuelve a tu redirectUrl con el resultado en la cadena de consulta. Pasa errorUrl para distinguir las cancelaciones de las operaciones completadas correctamente, y state para mantener tu propio valor de correlación durante todo el recorrido de ida y vuelta.

Recuerda que este cuerpo es plano, sin un contenedor input.

curl -X POST https://listingsapi.com/api/v4/social/brands/6f2c9a41-7b0e-4d55-9a2f-3c8e1d47b902/connections/link \  -H "Authorization: API $LISTINGSAPI_KEY" \  -H "Content-Type: application/json" \  -d '{    "channel": "INSTAGRAM",    "redirectUrl": "https://app.example.com/social/connected",    "errorUrl": "https://app.example.com/social/failed"  }'

{  "data": {    "connectSocialAccount": {      "status": "success",      "url": "https://social.listingsapi.com/connect/start?token=bfac8e06-8d72-4810-9c50-ae7ee12a7b52",      "expiresIn": 900    }  }}

Comprueba status antes de redirigir. Una respuesta failed no devuelve ningún url e incluye el motivo en title, normalmente el límite de conexiones (SY95042) o una plataforma que la cuenta no tiene (SY95044).

Listar las conexiones de una marca

GET /social/brands/{brandId}/connections

Devuelve las cuentas vinculadas a la marca, cada una con el id que necesitas para publicar en una conexión específica o para desconectarla.

curl -H "Authorization: API $LISTINGSAPI_KEY" \  https://listingsapi.com/api/v4/social/brands/6f2c9a41-7b0e-4d55-9a2f-3c8e1d47b902/connections

Desconectar una conexión

POST /social/connections/disconnect

Recibe el id de la conexión de la lista anterior. La cuenta deja de publicar de inmediato, pero la plaza que ocupaba no vuelve a estar disponible hasta que termina el período de facturación. Volver a conectar la misma cuenta a la misma marca dentro del período reutiliza esa plaza y no tiene ningún coste; vincularla a una marca diferente ocupa una segunda plaza.

curl -X POST https://listingsapi.com/api/v4/social/connections/disconnect \  -H "Authorization: API $LISTINGSAPI_KEY" \  -H "Content-Type: application/json" \  -d '{"input": {"socialProfileConnectedChannelId": "b81d5b3c-4a90-4f6a-9c11-71e0dd2fa4a7"}}'

Publicar una publicación

POST /social/posts

Una sola llamada publica el mismo contenido en todas las plataformas de platforms. Cada una de esas plataformas debe tener ya una conexión en la marca; de lo contrario, la llamada devuelve SY95045. Instagram y Pinterest requieren al menos una entrada en mediaUrls.

Programa una publicación de una de las dos formas, nunca de ambas. scheduledAt es una marca de tiempo ISO-8601 con un desplazamiento horario. scheduleDate y scheduleTime se envían juntos y se interpretan en la zona horaria de la marca. Si envías ambas formas de programación, o una fecha y hora de programación en el pasado, se devuelve SY95046.

curl -X POST https://listingsapi.com/api/v4/social/posts \  -H "Authorization: API $LISTINGSAPI_KEY" \  -H "Content-Type: application/json" \  -d '{    "input": {      "socialProfileId": "6f2c9a41-7b0e-4d55-9a2f-3c8e1d47b902",      "name": "Autumn collection launch",      "platforms": ["INSTAGRAM", "FACEBOOK"],      "content": "Our autumn collection lands today.",      "mediaUrls": ["https://cdn.example.com/social/autumn-collection.jpg"],      "action": "SCHEDULE",      "scheduleDate": "2026-10-02",      "scheduleTime": "09:30",      "clientReference": "campaign-4471-slot-01"    }  }'

Establece clientReference con tu propio identificador. Se almacena y se devuelve, lo que te permite cotejar una publicación con tus registros sin guardar el UUID.

Consultar una publicación

GET /social/posts/{postId}

Así puedes averiguar si la publicación se realizó correctamente. El status de la propia publicación es un resumen; el resultado real se encuentra por canal en connectedChannels, donde cada entrada incluye su propio status, un liveLink una vez que la plataforma la acepta, y reason o error cuando no la acepta.

{  "connectedChannels": [    {      "platform": "INSTAGRAM",      "status": "SUCCESS",      "liveLink": "https://www.instagram.com/p/CxYz1234abc/",      "error": null    }  ]}

Consulta este recurso periódicamente después de un PUBLISH. Un canal puede fallar mientras los demás tienen éxito, así que comprueba cada entrada en lugar de comprobar únicamente el status del nivel superior.

Listar las publicaciones de una marca

GET /social/brands/{brandId}/posts

Una página de las publicaciones de la marca, con filtros para acotar los resultados por estado. Úsala para conciliar los datos en bloque en lugar de consultar los ids uno por uno.

curl -H "Authorization: API $LISTINGSAPI_KEY" \  "https://listingsapi.com/api/v4/social/brands/6f2c9a41-7b0e-4d55-9a2f-3c8e1d47b902/posts?page=1&size=25"

Cancelar una publicación programada

POST /social/posts/cancel

Cancela una publicación que aún no se ha publicado. Una publicación que ya esté publicada en una plataforma no se puede retirar mediante este endpoint.

curl -X POST https://listingsapi.com/api/v4/social/posts/cancel \  -H "Authorization: API $LISTINGSAPI_KEY" \  -H "Content-Type: application/json" \  -d '{"input": {"socialPostId": "a3f81c62-9d4e-4a17-b5c0-2e7f6d8a9b10"}}'

Consultar estadísticas y comentarios

GET /social/posts/{postId}/insights

Recuentos de interacciones y comentarios de una publicación en un canal. El canal es obligatorio, porque una publicación difundida en tres plataformas tiene tres conjuntos de cifras independientes.

curl -H "Authorization: API $LISTINGSAPI_KEY" \  "https://listingsapi.com/api/v4/social/posts/a3f81c62-9d4e-4a17-b5c0-2e7f6d8a9b10/insights?socialConnectedChannelId=b81d5b3c-4a90-4f6a-9c11-71e0dd2fa4a7"

Crear publicaciones en bloque

POST /social/bulk-posts

Acepta de 1 a 500 filas en input.posts. Cada fila es el mismo objeto que POST /social/posts acepta como input, y las filas pueden dirigirse a distintas marcas en una misma solicitud.

Se valida todo el lote antes de crear nada. Si alguna fila no supera la validación, recibes SY95050 con errores por fila y no se pone nada en cola, así que corrige los errores y vuelve a enviar el lote. Si se envían más de 500 filas, se devuelve SY95048 y tampoco se crea nada. Un lote válido devuelve un trabajo cuyo estado puedes consultar periódicamente.

curl -X POST https://listingsapi.com/api/v4/social/bulk-posts \  -H "Authorization: API $LISTINGSAPI_KEY" \  -H "Content-Type: application/json" \  -d '{    "input": {      "name": "October launch batch",      "posts": [        {          "socialProfileId": "6f2c9a41-7b0e-4d55-9a2f-3c8e1d47b902",          "name": "Launch day",          "platforms": ["FACEBOOK"],          "content": "Doors open at nine.",          "action": "SCHEDULE",          "scheduleDate": "2026-10-02",          "scheduleTime": "09:00"        }      ]    }  }'

Una operación en bloque cuenta como una sola solicitud a efectos de tu límite de solicitudes, lo que la convierte en la opción eficiente para lotes grandes.

Consultar periódicamente un trabajo en bloque

GET /social/bulk-posts/{bulkJobId}

Devuelve el estado del trabajo con resultados por fila, incluido el id de la publicación creada para cada fila y cualquier fila que haya fallado tras ponerse en cola. Los trabajos no se conservan para siempre; al consultar un id cuyo plazo de retención haya vencido, se devuelve SY95047.

curl -H "Authorization: API $LISTINGSAPI_KEY" \  https://listingsapi.com/api/v4/social/bulk-posts/f47ac10b-58cc-4372-a567-0e02b2c3d479

Consultar límites y uso

GET /social/limits

Consulta esta información antes de crear conexiones, en lugar de hacerlo después de recibir un SY95042. Compara usage.connections con maxConnections: ese es el recuento facturable, que incluye las conexiones actuales y las liberadas anteriormente en este período. usage.connectionsActive indica lo que está activo en este momento, y usage.connectionsReleased indica cuánta capacidad se recupera al renovar.

brands se devuelve con el valor null, que significa sin límite. Las marcas no se contabilizan en un plan de API.

curl -H "Authorization: API $LISTINGSAPI_KEY" \  https://listingsapi.com/api/v4/social/limits

Errores que puedes encontrar

La lista completa está en la referencia de códigos de error.

Siguientes pasos

Consulta Planes y complementos para saber cómo interactúan el límite de conexiones, los paquetes de 5 conexiones y la regla de archivado de 90 días, y Reaccionar a eventos con webhooks para recibir eventos social_post.* y social_connection.* en lugar de realizar consultas periódicas.

El Python SDK incluye estos endpoints como client.social.brands, client.social.connections, client.social.posts y client.social.bulk; consulta el recurso Social. El Node SDK aún no incluye Social, así que llama a los endpoints REST directamente desde Node.