Uma API de influencers para os seus dados de ofertas.

Para que serve a API

É para a pessoa de operações ou o programador que quer os dados do Pozto noutro sítio: uma base do Airtable, um data warehouse, um painel, uma ferramenta interna. Ou no sentido inverso: adicionar criadores a partir do sistema que envia as suas ofertas, para que ninguém os escreva duas vezes.

Funciona sobre a sua própria lista, os criadores a quem enviou produto. Não é uma base de dados de influencers para pesquisar. Se é isso que procura numa API de influencers, o Pozto não é a solução.

Chaves, URL base e limites

• URL base: https://pozto.co/api/v1
• Chaves: o proprietário da equipa cria-as em Definições → API, no plano Brand. Uma chave começa por pz_ e só é mostrada uma vez: o Pozto guarda apenas uma impressão digital, por isso copie-a nesse momento. Dê a cada chave um nome que indique para que serve e revogue-a quando quiser. As Definições mostram quando cada chave foi usada pela última vez.
• Como enviá-la: Authorization: Bearer pz_… em cada pedido.
• Âmbito: uma chave lê e adiciona dados em todas as marcas da sua equipa.
• Limite de pedidos: 120 pedidos por minuto por chave.
• Páginas: GET /creators e GET /posts devolvem 100 de cada vez, ou até 500 com &limit=. Quando há mais, a resposta tem um next_cursor: envie-o de volta como &cursor= para a página seguinte. Na última página é null.
• Formato: JSON à entrada e à saída. Os ids são strings e as datas estão em ISO 8601.

Endpoints

O que inclui um criador e uma publicação

Um criador vem com o nome, e-mail, contas (e se cada nome de utilizador foi encontrado), códigos de desconto, estado e cada oferta: o produto e o resto da caixa, a campanha, as datas de envio e de entrega, o prazo em dias, o número de seguimento, o cachê, as publicações pedidas e as publicações até agora.

Uma publicação é um vídeo, com todas as plataformas onde foi publicado: link, legenda, data de publicação e se o identificou. Depois, a oferta e o produto a que corresponde, e como o Pozto o decidiu. Depois, a verificação de vídeo: se o seu produto foi encontrado, cada momento no ecrã em segundos, cada vez que foi dito, com a citação, e um breve resumo. E a divulgação: clara, fraca ou nenhuma, com o motivo.

Adicionar criadores e publicações

POST /creators recebe brand_id e handles: @nomes, links de perfil ou links ao estilo Linktree, até seis. Recebe também platform, name, email, codes, product (um id ou um nome; um nome novo adiciona o produto), shipped_at, delivered_at, due_days (21 se o omitir) e tracking. Um criador que já esteja na lista, reconhecido por qualquer uma das contas ou pelo e-mail, recebe a oferta em vez de ser duplicado. Responde 201 para um criador novo e 200 para um existente, com o id do criador e o id da oferta.

POST /posts recebe brand_id e url e, opcionalmente, creator_id e product_id. A publicação fica associada a quem é dono da conta, que é adicionado à sua lista se for novo, e entra na fila da verificação de vídeo. Responde se era nova, o nome de utilizador, a plataforma e se conta como publicação sobre si.

# Criadores atrasados, numa marca
curl "https://pozto.co/api/v1/creators?brand_id=BRAND_ID&status=late" \
  -H "Authorization: Bearer pz_…"

# Adicionar um criador e a oferta que lhe enviou
curl -X POST https://pozto.co/api/v1/creators \
  -H "Authorization: Bearer pz_…" \
  -H "Content-Type: application/json" \
  -d '{"brand_id":"BRAND_ID","handles":["@maya.glows"],"product":"Glow Serum","shipped_at":"2026-10-14"}'

# Publicações desde 1 de outubro, das mais recentes para as mais antigas
curl "https://pozto.co/api/v1/posts?brand_id=BRAND_ID&since=2026-10-01" \
  -H "Authorization: Bearer pz_…"

# A página seguinte: o next_cursor da resposta anterior
curl "https://pozto.co/api/v1/posts?brand_id=BRAND_ID&since=2026-10-01&cursor=NEXT_CURSOR" \
  -H "Authorization: Bearer pz_…"

Erros

Um erro chega em JSON com uma frase simples, como {"error": "…"}, e um estado 4xx:

• 400: o corpo não é JSON, ou um campo não é válido, como uma data de entrega no futuro.
• 401: falta a chave, ou a chave está errada ou foi revogada.
• 403: a sua equipa não está no plano Brand.
• 404: não há nenhuma marca com esse brand_id na sua equipa.
• 409: a marca está bloqueada, porque o seu plano inclui menos marcas do que as que a equipa usa.
• 429: mais de 120 pedidos num minuto.

O que a API não faz

• Não pesquisa influencers. Lê e adiciona à sua própria lista. A pesquisa de criadores é feita em Encontrar criadores, na aplicação.
• Não devolve visualizações, gostos nem EMV. Estão na aplicação a partir do Starter e no relatório semanal. Veja os relatórios de influencers.
• Sem webhooks. Para obter publicações novas, faça GET /posts com since.
• Sem edições nem eliminações. A API lê e adiciona. As alterações e remoções fazem-se na aplicação.
• Sem chaves individuais. As chaves pertencem à equipa, e só o proprietário as cria.

O conteúdo das publicações é o mesmo da aplicação: o Pozto encontra publicações analisando o vídeo, os fotogramas, o áudio e a legenda, por isso as publicações sem identificação também aparecem. O acompanhamento de influencers explica como se encontram as publicações.

Preços

A API vem com o plano Brand: $999 por mês, ou $799 por mês com pagamento anual, com 10 marcas, 1,000 criadores ativos, utilizadores ilimitados e início de sessão único (SSO). Tudo o resto no Pozto começa em planos mais baixos, e o plano gratuito cobre os seus primeiros 10 criadores. Ver planos.