Perguntas frequentes
Respostas diretas para as dúvidas mais comuns ao integrar a API pública. Tudo aqui se baseia na especificação OpenAPI; quando algo não está definido, dizemos explicitamente.
O que faz parte da API pública?
Apenas os endpoints sob o prefixo /public, em cinco
domínios: Posts, Categorias, Tags, Busca e Anúncios (Delivery). São
rotas de leitura de conteúdo
destinadas ao consumo por sites e aplicações de terceiros, autenticadas
por chave de API. Rotas administrativas, de billing, de equipe e do painel
não fazem parte desta API e não são documentadas aqui.
Como obtenho a chave de API?
A chave é gerada e gerenciada no painel da DraftIn, nas configurações do blog. Cada chave pertence a um blog e dá acesso somente ao conteúdo publicado daquele blog. Lá também é possível rotacioná-la. Veja Autenticação.
Posso usar a chave diretamente no navegador?
Não é recomendado. A chave identifica seu blog e deve ficar no servidor — em builds estáticos, rotas de API ou funções serverless. Expor a chave em JavaScript de cliente a torna visível para qualquer visitante.
A API permite criar ou editar conteúdo?
Não. A API pública é somente leitura. A criação,
edição e publicação de conteúdo acontecem no editor e no painel da
DraftIn. Os únicos endpoints públicos que aceitam
POST são os de anúncios (entrega em lote e tracking de clique),
que não escrevem conteúdo editorial.
Por que um post que existe retorna 404?
Os endpoints públicos só enxergam conteúdo com status PUBLISHED. Um post em rascunho ou agendado é, para esta API, equivalente a
inexistente — e responde
404. Confirme que o post está publicado.
Qual base URL devo usar?
A especificação OpenAPI declara o servidor de produção como
https://api.draftin.io (e http://localhost:3000 para desenvolvimento). O portal de documentação, por sua vez, é servido
de
https://api.draftin.io. Em caso de dúvida sobre o host
correto para a sua integração, confirme com o painel/equipe da
DraftIn. Veja Base URL.
Por que existem formas diferentes de paginação?
A listagem geral de posts usa limit/offset e retorna
um array; as listagens por categoria e por tag usam page/pageSize com envelope; e a busca usa limit/offset com envelope data/meta. A tabela em Paginação resume
os três estilos.
Existe limite de requisições (rate limit)?
A especificação não define limites de taxa para os endpoints públicos. Não presuma um número específico. Ainda assim, cacheie respostas, faça chamadas no servidor e implemente retentativas com backoff — veja Rate limits.
A DraftIn notifica meu site quando o conteúdo muda?
A plataforma oferece webhooks de saída por blog, que notificam mudanças de estado de posts (criar, editar, publicar, excluir, restaurar) para que sites SSR façam redeploy/revalidação. Esses webhooks são configurados no painel — a administração deles não faz parte desta API pública, por isso não documentamos esses endpoints aqui. No seu site, você implementa um receptor que invalida o cache ao receber a notificação.
A API é REST ou GraphQL?
A especificação OpenAPI que fundamenta esta documentação descreve uma API REST sobre HTTPS, com respostas JSON. Qualquer outra interface de consulta não está definida nesta especificação e, portanto, não é documentada aqui.
Em que formato vem o conteúdo dos posts?
O campo content pode conter HTML ou Markdown, conforme produzido no editor. Ao renderizar HTML de fontes não
totalmente confiáveis, sanitize antes de injetar no DOM.
Como funcionam impressões e cliques de anúncios?
A impressão é registrada automaticamente no servidor no
momento da entrega — você não precisa chamar nenhum endpoint para isso.
O clique é registrado por você chamando POST /public/ads/tracking/click com o clickToken
recebido na entrega, que tem proteções anti-fraude (uso único, TTL de 10
min, validação de origem e deduplicação por IP). Veja Anúncios · Delivery.
Existe um SDK oficial?
A especificação não define um SDK oficial. Como a API é REST simples, um cliente próprio de poucas linhas costuma bastar — há um exemplo em Autenticação e tipos prontos em Modelos de dados.