Posts

Publicar pins en Pinterest con la API

Un POST /posts con la conexión pinterest crea un pin en el tablero que elijas. Connect lista en vivo los tableros y secciones de la cuenta del cliente, así que tu producto no implementa el OAuth de Pinterest ni guarda tokens.

La llamada

POST /api/posts?customer_integration=<connection uuid>
Authorization: Bearer <merchant token>
x-customer-token: <customer token>
Idempotency-Key: <unique key>

{
  "external_reference": "pin-3301",
  "format": "feed",
  "caption": "Linen sofa in warm oat. Free shipping this month.",
  "media": [
    {
      "type": "image",
      "url": "https://cdn.example.com/sofa.jpg",
      "alt_text": "Oat linen sofa in a bright living room"
    }
  ],
  "pinterest": {
    "board_id": "<board id>",
    "board_section_id": "<section id>",
    "title": "Oat linen sofa",
    "link": "https://shop.example.com/sofa"
  }
}

Qué puedes hacer

  • Publicar un pin de imagen o de video.
  • Listar los tableros de la cuenta con GET /posts/pinterest/boards y las secciones con GET /posts/pinterest/boards/{board_id}/sections.
  • Definir título, enlace de destino y descripción del pin.
  • Guardar el pin en una sección concreta del tablero con board_section_id.
  • Informar alt_text de hasta 500 caracteres para accesibilidad.

Reglas y límites

  • Un pin es exactamente 1 medio (imagen o video) y el format es siempre feed.
  • pinterest.board_id es obligatorio. pinterest.cover_url es obligatoria en un pin de video y se rechaza en uno de imagen.
  • Al elegir la cuenta por nombre, solo se usa source_name, sin integration_slug.
  • POST /posts responde 202 y la publicación corre después. Síguela con GET /posts/{uuid}.
  • external_reference es obligatoria y el header Idempotency-Key evita duplicar la solicitud.

Campos principales

CampoTipoObligatorioDescripción
external_referencestringSíEl id del pin en tu sistema (hasta 100 caracteres). Evita publicar el mismo pin dos veces en la misma cuenta.
formatstringSíSiempre feed en Pinterest.
captionstringNoLa descripción del pin, hasta 800 caracteres.
mediaarraySíExactamente 1 imagen o 1 video. alt_text llega hasta 500 caracteres.
pinterest.board_idstringSíEl tablero donde se guarda el pin (cadena numérica, hasta 50 caracteres). Viene de GET /posts/pinterest/boards.
pinterest.board_section_idstringNoLa sección del tablero. Viene de GET /posts/pinterest/boards/{board_id}/sections.
pinterest.titlestringNoTítulo del pin, hasta 100 caracteres.
pinterest.linkstringNoURL de destino al hacer clic en el pin (http o https).
pinterest.cover_urlstringNoPortada del pin. Obligatoria en un pin de video y rechazada en uno de imagen.

Para quién

  • E-commerce y catálogos

    La tienda publica cada producto nuevo como pin en el tablero de la colección, con enlace a la página de compra.

  • Plataforma de marketing de contenidos

    Cada artículo publicado se vuelve un pin con imagen de portada, título y enlace, en la sección correcta del tablero.

  • Agente de IA de redes sociales

    Un agente lista los tableros de la cuenta, elige el más adecuado y publica el pin con descripción y alt_text generados.

Funciona con

  • Pinterest

Preguntas frecuentes

¿Cómo encuentro el board_id?

Llama a GET /posts/pinterest/boards con la conexión del cliente. La respuesta trae id, name, description y privacy de cada tablero.

¿Puedo publicar un video?

Sí: 1 video por pin, con pinterest.cover_url obligatoria como portada.

¿Cuántos medios caben en un pin?

Exactamente 1, una imagen o un video.

Relacionadas

Ver todo lo que puedes hacer con Posts

Mira Connect aplicado a tu producto.

Pruébalo durante 15 días sin tarjeta, o cuéntale tu caso a nuestro equipo.