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

CampoTipoObrigatórioDescrição
external_referencestringSimO id do pin no seu sistema (até 100 caracteres). Impede publicar o mesmo pin duas vezes na mesma conta.
formatstringSimSempre feed no Pinterest.
captionstringNãoA descrição do pin, até 800 caracteres.
mediaarraySimExatamente 1 imagem ou 1 vídeo. alt_text vai até 500 caracteres.
pinterest.board_idstringSimO board onde o pin é salvo (string numérica, até 50 caracteres). Vem de GET /posts/pinterest/boards.
pinterest.board_section_idstringNãoA seção do board. Vem de GET /posts/pinterest/boards/{board_id}/sections.
pinterest.titlestringNãoTítulo do pin, até 100 caracteres.
pinterest.linkstringNãoURL de destino ao clicar no pin (http ou https).
pinterest.cover_urlstringNãoCapa 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.

Relacionadas

Ver tudo que dá para fazer em Posts

Veja o Connect aplicado ao seu produto.

Teste por 15 dias sem cartão, ou mostre seu cenário ao nosso time.