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
| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| external_reference | string | Sí | El id del pin en tu sistema (hasta 100 caracteres). Evita publicar el mismo pin dos veces en la misma cuenta. |
| format | string | Sí | Siempre feed en Pinterest. |
| caption | string | No | La descripción del pin, hasta 800 caracteres. |
| media | array | Sí | Exactamente 1 imagen o 1 video. alt_text llega hasta 500 caracteres. |
| pinterest.board_id | string | Sí | El tablero donde se guarda el pin (cadena numérica, hasta 50 caracteres). Viene de GET /posts/pinterest/boards. |
| pinterest.board_section_id | string | No | La sección del tablero. Viene de GET /posts/pinterest/boards/{board_id}/sections. |
| pinterest.title | string | No | Título del pin, hasta 100 caracteres. |
| pinterest.link | string | No | URL de destino al hacer clic en el pin (http o https). |
| pinterest.cover_url | string | No | Portada 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.
Mira Connect aplicado a tu producto.
Pruébalo durante 15 días sin tarjeta, o cuéntale tu caso a nuestro equipo.
