Posts
Publicar pins no Pinterest pela API
Um POST /posts com a conexão pinterest cria um pin no board que você escolher. O Connect lista os boards e as seções da conta do cliente em tempo real, então seu produto não implementa o OAuth do Pinterest nem guarda tokens.
A chamada
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"
}
}O que dá para fazer
- Publicar um pin de imagem ou de vídeo.
- Listar os boards da conta com GET /posts/pinterest/boards e as seções com GET /posts/pinterest/boards/{board_id}/sections.
- Definir título, link de destino e descrição do pin.
- Salvar o pin em uma seção específica do board com board_section_id.
- Informar alt_text de até 500 caracteres para acessibilidade.
Regras e limites
- Um pin é exatamente 1 mídia (imagem ou vídeo) e o format é sempre feed.
- pinterest.board_id é obrigatório. pinterest.cover_url é obrigatória em pin de vídeo e recusada em pin de imagem.
- Na escolha da conta por nome, só o source_name é usado, sem integration_slug.
- O POST /posts responde 202 e a publicação roda depois. Acompanhe por GET /posts/{uuid}.
- external_reference é obrigatória e o header Idempotency-Key evita duplicar a requisição.
Campos principais
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| external_reference | string | Sim | O id do pin no seu sistema (até 100 caracteres). Impede publicar o mesmo pin duas vezes na mesma conta. |
| format | string | Sim | Sempre feed no Pinterest. |
| caption | string | Não | A descrição do pin, até 800 caracteres. |
| media | array | Sim | Exatamente 1 imagem ou 1 vídeo. alt_text vai até 500 caracteres. |
| pinterest.board_id | string | Sim | O board onde o pin é salvo (string numérica, até 50 caracteres). Vem de GET /posts/pinterest/boards. |
| pinterest.board_section_id | string | Não | A seção do board. Vem de GET /posts/pinterest/boards/{board_id}/sections. |
| pinterest.title | string | Não | Título do pin, até 100 caracteres. |
| pinterest.link | string | Não | URL de destino ao clicar no pin (http ou https). |
| pinterest.cover_url | string | Não | Capa do pin. Obrigatória em pin de vídeo e recusada em pin de imagem. |
Para quem
E-commerce e catálogo
A loja publica cada produto novo como pin no board da coleção, com link de volta para a página de compra.
Plataforma de marketing de conteúdo
Cada artigo publicado vira um pin com imagem de capa, título e link, na seção certa do board.
Agente de IA de social media
Um agente lista os boards da conta, escolhe o mais adequado e publica o pin com descrição e alt_text gerados.
Funciona com
Pinterest
Perguntas frequentes
Como descubro o board_id?
Chame GET /posts/pinterest/boards com a conexão do cliente. A resposta traz id, name, description e privacy de cada board.
Posso publicar um vídeo?
Sim: 1 vídeo por pin, com pinterest.cover_url obrigatória como capa.
Quantas mídias cabem em um pin?
Exatamente 1, uma imagem ou um vídeo.
Veja o Connect aplicado ao seu produto.
Teste por 15 dias sem cartão, ou mostre seu cenário ao nosso time.
