API Pública de Conteúdo

A API Pública de Conteúdo dá-lhe acesso programático só de leitura aos artigos de blog da sua organização Nolorem. Utilize-a para importar conteúdo para um site Drupal, um front end personalizado, uma aplicação móvel ou qualquer sistema externo que precise dos dados do seu blog.

A API está disponível em todos os planos pagos, incluindo um período de avaliação. É necessária uma subscrição ativa; todo o acesso é só de leitura, e a publicação e a edição permanecem dentro do Nolorem.

Criar uma Chave de API

Só os administradores da organização podem criar chaves de API.

1. Nas Definições, desloque-se até à secção Chaves de API (visível apenas para administradores).
2. Clique em Criar chave de API.
3. Introduza um nome descritivo para a chave (por exemplo, "Website Drupal" ou "Script de sincronização de conteúdo").
4. Escolha o âmbito da chave (ver abaixo).
5. Copie a chave apresentada no ecrã. Começa por nlr_live_.

A chave é apresentada apenas uma vez. Guarde-a imediatamente num gestor de segredos ou variável de ambiente. Se a perder, revogue a chave e crie uma nova.

Escolher o Âmbito de uma Chave

Ao criar uma chave, escolhe se esta abrange um blog específico ou todos os blogs da sua organização.

Chave delimitada a um blog (recomendado): a chave está associada a um único blog. Só pode aceder a artigos, categorias e etiquetas desse blog. Se a chave for alguma vez divulgada ou partilhada, apenas o conteúdo desse blog fica exposto.

Chave de toda a organização: a chave tem acesso a todos os blogs da sua organização. Utilize-a apenas quando tiver uma razão deliberada para aceder a vários blogs com uma única chave.

O selo de âmbito em cada chave da lista mostra a que blog a chave está associada, ou "Todos os blogs" para uma chave de toda a organização. O âmbito é fixado na criação. Para alterar o âmbito, crie uma nova chave com o âmbito pretendido, atualize os consumidores e depois revogue a chave antiga.

Autenticar Pedidos

Passe a chave no cabeçalho Authorization de cada pedido:

Authorization: Bearer nlr_live_your_key_here

Exemplo com curl:

curl https://nolorem.io/api/v1/posts \
  -H "Authorization: Bearer nlr_live_your_key_here"

A API é servidor-a-servidor. Não existem cabeçalhos CORS, pelo que os clientes de navegador não a podem chamar diretamente. Faça todas as chamadas à API a partir do seu back-end ou de um script do lado do servidor.

Listar os Seus Blogs

GET /api/v1/blogs lista os blogs a que a sua chave pode aceder. A estrutura da resposta é a mesma quer a chave esteja delimitada a um blog quer seja de toda a organização.

curl https://nolorem.io/api/v1/blogs \
  -H "Authorization: Bearer nlr_live_your_key_here"

Resposta:

{
  "data": [
    { "id": "uuid", "slug": "my-blog", "name": "My Blog" },
    { "id": "uuid", "slug": "company-news", "name": "Company News" }
  ]
}

Uma chave delimitada a um blog devolve exatamente uma entrada (o blog associado). Uma chave de toda a organização devolve todos os blogs. Utilize este endpoint para descobrir que blogs uma chave abrange antes de obter conteúdo.

Filtrar Artigos por Blog

Todos os endpoints de conteúdo aceitam um parâmetro blog opcional. Passe o UUID ou o slug do blog:

# Filtrar por slug
curl "https://nolorem.io/api/v1/posts?blog=my-blog" \
  -H "Authorization: Bearer nlr_live_your_key_here"

# Filtrar por UUID
curl "https://nolorem.io/api/v1/posts?blog=550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer nlr_live_your_key_here"

Se omitir blog, a API devolve conteúdo de todos os blogs a que a sua chave pode aceder (o comportamento predefinido, não disruptivo).

Se utilizar uma chave delimitada a um blog e passar ?blog= a apontar para um blog diferente, a API devolve 403 Forbidden. Isto impede adivinhar que blogs existem numa organização.

O mesmo parâmetro blog funciona em /api/v1/categories e /api/v1/tags.

Listar Artigos

GET /api/v1/posts devolve uma lista paginada de artigos dos blogs acessíveis pela sua chave. Por predefinição, devolve artigos publicados, 20 por página.

curl "https://nolorem.io/api/v1/posts?status=published&per_page=50" \
  -H "Authorization: Bearer nlr_live_your_key_here"

Resposta:

{
  "data": [
    {
      "id": "uuid",
      "blog_id": "uuid",
      "title": "My blog post",
      "slug": "my-blog-post",
      "excerpt": "Lead paragraph...",
      "language": "en",
      "available_locales": ["en", "nl"],
      "locale_slugs": {
        "en": "my-blog-post",
        "nl": "mijn-blogbericht-over-contentgeneratie"
      },
      "category": "Technology",
      "tags": ["AI", "Productivity"],
      "featured_image_url": "https://...",
      "published_at": "2026-06-01T10:00:00Z",
      "updated_at": "2026-06-10T14:30:00Z",
      "html": null
    }
  ],
  "meta": { "page": 1, "per_page": 50, "total": 123 }
}

O campo html é sempre null nas respostas de lista. Utilize os endpoints de detalhe para obter o corpo completo do artigo.

Filtros Disponíveis

Parâmetro	Descrição	Exemplo
blog	UUID ou slug do blog (predefinição: todos os blogs acessíveis)	blog=my-blog
status	published, draft ou scheduled (predefinição: published)	status=published
language	Código de idioma ISO 639-1	language=nl
category	Nome da categoria (não distingue maiúsculas de minúsculas)	category=Technology
tag	Nome da etiqueta (não distingue maiúsculas de minúsculas)	tag=AI
updated_since	Data e hora ISO 8601; apenas artigos modificados após esta data	updated_since=2026-06-01T00:00:00Z
page	Número da página, a começar em 1	page=2
per_page	Itens por página, máx. 100	per_page=100

Obter um Artigo noutro Idioma

language e locale parecem-se e fazem o contrário um do outro. Leia isto uma vez e não voltará a confundi-los.

language filtra. Seleciona quais artigos são devolvidos, com base no idioma em que o artigo foi escrito. ?language=nl devolve os seus artigos em neerlandês e deixa de fora os que estão em inglês.

locale não filtra nada. Devolve os artigos que já recebia, mas no idioma pedido, sempre que exista uma tradução completa desse artigo. ?locale=nl no endpoint de listagem continua a devolver todos os artigos: os que têm uma tradução neerlandesa completa voltam com title, slug, excerpt, seo_title e seo_description em neerlandês, e os restantes voltam inalterados.

Já usa ?language=? Nada muda para si. Deixe locale de fora e cada campo que já lia mantém exatamente o valor que tinha, e language mantém o significado que sempre teve. A única diferença são os dois campos descritos mais abaixo, que passam a estar sempre presentes em todas as respostas.

# Todos os artigos, em neerlandês onde exista uma tradução neerlandesa completa
curl "https://nolorem.io/api/v1/posts?locale=nl" \
  -H "Authorization: Bearer nlr_live_your_key_here"

# Um artigo, em neerlandês, incluindo o corpo HTML e os textos alternativos das imagens
curl "https://nolorem.io/api/v1/posts/550e8400-e29b-41d4-a716-446655440000?locale=nl" \
  -H "Authorization: Bearer nlr_live_your_key_here"

Nos dois endpoints de detalhe a projeção abrange também html e o texto alt de cada entrada em images, de modo que a página inteira fica num só idioma.

Uma tradução ainda em curso não conta. Se a tradução para o idioma pedido não estiver terminada, recebe a versão de origem inalterada, nunca uma página que muda de idioma a meio. language continua a indicar o idioma de origem em todas as respostas, quer passe locale quer não.

O endpoint por slug também aceita um slug traduzido. Com locale definido, /api/v1/posts/slug/{slug} corresponde também ao slug que esse idioma transporta, e não apenas ao slug de origem: /api/v1/posts/slug/contentkalender-vullen-met-geautomatiseerde-contentgeneratie?locale=nl devolve o mesmo artigo que o seu endereço em inglês. O slug de origem é tentado primeiro e ganha sempre, para que um slug traduzido nunca possa tapar o endereço próprio de outro artigo. Sem locale, só o slug de origem corresponde, portanto um slug traduzido por si só devolve 404.

Saber que Idiomas Tem um Artigo

Não precisa de adivinhar nem de fazer um pedido por idioma. Cada artigo transporta dois campos, tanto nas respostas de listagem como nas de detalhe:

{
  "language": "en",
  "available_locales": ["en", "nl"],
  "locale_slugs": {
    "en": "why-automated-content-generation-fixes-your-empty-calendar",
    "nl": "contentkalender-vullen-met-geautomatiseerde-contentgeneratie"
  }
}

available_locales enumera todos os idiomas em que este artigo pode ser servido, incluindo sempre o seu idioma de origem. Um idioma só aparece ali quando ?locale= consegue mesmo entregar uma página completa nesse idioma, pelo que a lista é segura para construir as suas etiquetas hreflang.

locale_slugs indica o slug que cada um desses idiomas transporta. Repare que os dois slugs acima diferem em mais do que uma palavra traduzida: cada idioma escolhe o seu próprio slug em torno da sua própria palavra-chave alvo, pelo que não pode deduzir um a partir do outro. Use este mapa para construir o URL por idioma no seu próprio site.

Obter um Único Artigo

Obtenha um artigo pelo seu UUID para conseguir o corpo HTML completo:

curl "https://nolorem.io/api/v1/posts/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer nlr_live_your_key_here"

Ou pelo seu slug:

curl "https://nolorem.io/api/v1/posts/slug/my-blog-post" \
  -H "Authorization: Bearer nlr_live_your_key_here"

Ambos devolvem um único objeto PublicPost (não envolvido num array data) com o campo html preenchido.

Ambos os endpoints usam por defeito status=published, tal como o endpoint de listagem acima. Obter um artigo pelo id ou pelo slug que não esteja publicado agora devolve 404, a menos que adicione ?status=draft ou ?status=scheduled ao pedido.

Sincronização Incremental com updated_since

Para sincronizar apenas conteúdo novo ou alterado, guarde a data e hora da sua última sincronização bem-sucedida e passe-a como updated_since na execução seguinte:

# Sincronização inicial: obter todos os artigos publicados
curl "https://nolorem.io/api/v1/posts?per_page=100" \
  -H "Authorization: Bearer nlr_live_your_key_here"

# Sincronizações seguintes: apenas artigos alterados desde a última sincronização
curl "https://nolorem.io/api/v1/posts?updated_since=2026-06-10T14:30:00Z&per_page=100" \
  -H "Authorization: Bearer nlr_live_your_key_here"

Percorra todos os resultados com paginação antes de guardar a nova data e hora de sincronização.

Detetar Artigos Despublicados ou Eliminados

Quando utiliza updated_since para sincronização incremental, a resposta predefinida só devolve artigos que ainda estejam publicados. Se um artigo foi despublicado ou eliminado no Nolorem desde a sua última sincronização, simplesmente desaparece dos resultados, sem qualquer sinal para o remover no destino.

Para obter esse sinal, passe include_deleted=true juntamente com a sua data e hora updated_since:

curl "https://nolorem.io/api/v1/posts?updated_since=2026-06-10T14:30:00Z&include_deleted=true" \
  -H "Authorization: Bearer nlr_live_your_key_here"

A resposta inclui todos os artigos em direto normalmente, mais entradas de lápide mínimas acrescentadas ao final de data. Cada lápide tem:

• id: o UUID do artigo que já tem de uma sincronização anterior
• status: o estado atual do artigo, ou "deleted" se foi removido permanentemente
• updated_at: quando ocorreu a alteração
• deleted: true se o artigo foi eliminado, false se foi apenas despublicado ou movido para rascunho

{
  "data": [
    { "id": "...", "title": "Live post", "updated_at": "..." },
    { "id": "...", "status": "draft", "updated_at": "...", "deleted": false },
    { "id": "...", "status": "deleted", "updated_at": "...", "deleted": true }
  ],
  "meta": { "page": 1, "per_page": 20, "total": 1, "tombstones": 2 }
}

Utilize meta.tombstones para saber quantas entradas de lápide estão acrescentadas. meta.total reflete sempre apenas os artigos em direto.

Quando a sua ferramenta de sincronização vê uma lápide, despublique ou remova a página correspondente no destino (por exemplo, defina o nó Drupal correspondente como despublicado ou rascunho).

Sem include_deleted=true, o comportamento é idêntico ao anterior a esta alteração: só são devolvidos os artigos publicados em direto.

Listar Categorias e Etiquetas

Dois endpoints devolvem a taxonomia completa de categorias e etiquetas do seu blog. São úteis para ferramentas externas que precisam de mapear categorias ou etiquetas do Nolorem para a sua própria taxonomia (por exemplo, um conector Drupal a fazer corresponder categorias do Nolorem a termos de vocabulário do Drupal). Ambos aceitam o parâmetro blog.

# Todas as categorias da sua organização (ou do blog delimitado)
curl "https://nolorem.io/api/v1/categories?blog=my-blog" \
  -H "Authorization: Bearer nlr_live_your_key_here"

# Todas as etiquetas da sua organização (ou do blog delimitado)
curl "https://nolorem.io/api/v1/tags?blog=my-blog" \
  -H "Authorization: Bearer nlr_live_your_key_here"

Ambos devolvem a lista completa numa única resposta (não paginada):

{ "data": [{ "id": "uuid", "name": "Marketing" }, { "id": "uuid", "name": "Technology" }] }

Aplicam-se o mesmo token bearer, o mesmo requisito de subscrição ativa e o mesmo âmbito posts:read que nos endpoints de artigos.

Análise de Utilização por Chave

Nas Definições, cada linha de chave pode ser expandida para mostrar análises de utilização:

• Pedidos (últimas 24h / total): quantas chamadas à API esta chave fez.
• Fontes distintas: quantos endereços IP distintos e aplicações cliente utilizaram esta chave recentemente.
• Última utilização: a data e hora do pedido autenticado mais recente.

Estas análises ajudam-no a compreender como as suas chaves estão a ser utilizadas e a identificar padrões inesperados.

Sinalização de Partilha de Chaves

Se uma chave apresentar um grande número de endereços IP distintos num curto período, o Nolorem pode sinalizá-la como "possivelmente partilhada ou comprometida". A sinalização aparece como um aviso âmbar na linha da chave. A chave continua a funcionar, e não é tomada qualquer ação automática: trata-se de um sinal informativo.

Quando vir a sinalização, reveja os seus registos de utilização. Se partilhou a chave intencionalmente (por exemplo, com vários servidores num cluster), pondere se o padrão de acesso é o esperado. Se a chave puder ter sido divulgada ou partilhada com partes não pretendidas, revogue-a e crie uma nova para limitar o acesso.

Limites de Taxa

Cada chave de API está sujeita a estes limites:

• 60 pedidos por minuto
• 5 000 pedidos por dia

Quando excede um limite, a API devolve HTTP 429 com um cabeçalho Retry-After que indica quantos segundos deve esperar antes de tentar novamente:

HTTP/1.1 429 Too Many Requests
Retry-After: 43

{ "error": "Rate limit exceeded" }

Implemente recuo exponencial para scripts de sincronização fiáveis e de longa duração.

Códigos de Erro

Estado	Significado
400	Parâmetros de consulta inválidos
401	Chave de API em falta ou inválida
403	Subscrição ativa necessária, a chave não tem o âmbito posts:read, ou uma chave delimitada a um blog utilizada com um valor ?blog= que não corresponde
404	Artigo não encontrado
429	Limite de taxa excedido (verifique o cabeçalho Retry-After)

Especificação Legível por Máquina

A especificação completa da API no formato OpenAPI 3.1 está disponível em:

GET /api/v1/openapi.json

Este endpoint não é autenticado. Pode importá-lo para o Postman, o Insomnia ou qualquer ferramenta compatível com OpenAPI.

Revogar uma Chave

Para revogar uma chave, desloque-se até à secção Chaves de API nas Definições, encontre a chave pelo nome e clique em Revogar. A chave deixa de funcionar imediatamente. Os pedidos em curso que já tinham sido autenticados serão concluídos, mas nenhum novo pedido com a chave revogada será bem-sucedido.