Guia Técnico — API Headless CMS

"Aplica-se a: Studio Pro" "Keyword: api headless cms integração json desenvolvedor portfólio site" "Title: Guia Técnico: API Headless CMS | Central de Ajuda - Acervo Vivo" "Meta: Documentação técnica completa para integrar e consumir a API Headless CMS do Acervo Vivo no seu site ou portfólio." "Slug: api-headless-cms" "Alt-Capa: Diagrama de arquitetura da API Headless CMS"

O que é este módulo?

A API Headless CMS é a ponte que permite que desenvolvedores consumam os dados do Acervo Vivo em tempo real para alimentar sites de portfólio externos ou e-commerces. A API é pública e de leitura única — não requer autenticação complexa via cabeçalhos e retorna um JSON blindado contendo os Trabalhos, Textos e Exposições, protegendo totalmente dados sensíveis de mercado.

Como acessar

Sendo uma ferramenta de infraestrutura, a API atua nos bastidores e não possui uma tela própria de configuração no painel.

💡 Disponível mediante ativação nos planos Studio Pro.

a) O Gatilho de Publicação no Sistema: Para que um Trabalho, Evento ou Texto apareça na resposta da API, a equipe deve sinalizá-lo individualmente. Dentro da Ficha Técnica do Trabalho, vá ao campo de Palavras-chave e adicione a tag 🌐Site/Ecommerce.

⚠️ Esta ação permite ao artista controlar perfeitamente o seu portfólio público apenas clicando na tag, sem necessidade de programadores.

Como usar

Abaixo está a especificação técnica para o seu desenvolvedor realizar a integração frontal (Frontend integration).

1. O Endpoint

URL Base:

GET https://app.acervovivo.com/api/v1/public/sandbox

Parâmetro obrigatório:

Exemplo de chamada:

https://app.acervovivo.com/api/v1/public/sandbox?apiId=SEU_ID_AQUI

2. CORS — Requisições Diretas do Navegador

A API suporta CORS aberto (Access-Control-Allow-Origin: *). Isso significa que a sua equipe técnica pode chamar o endpoint diretamente do navegador, sem necessidade de proxy ou servidor intermediário.

Exemplo — fetch nativo:

const res = await fetch(
  'https://app.acervovivo.com/api/v1/public/sandbox?apiId=SEU_ID_AQUI'
);
const data = await res.json();
console.log(data.artworks);

3. Estrutura da Resposta (JSON)

A resposta retorna um único objeto com o account do acervo e seis arrays, um para cada módulo de conteúdo do Studio:

{
  "account":       { ... },
  "series":        [ ... ],
  "artworks":      [ ... ],
  "events":        [ ... ],
  "texts":         [ ... ],
  "publications":  [ ... ],
  "cvs":           [ ... ]
}

O site do artista pode usar apenas os módulos de que precisar, ignorando os demais.

4. Módulo account — Identidade do Acervo

Retornado sempre no root da resposta, serve para configurar o tema visual do site e as meta-tags de SEO organicamente a partir da plataforma.

{
  "name":    "Rogério Pessôa",
  "tagline": "OBRAS — ACERVO",
  "slug":    "rogerio-pessoa",
  "website": "https://artepessoa.com.br",
  "contact": {
    "email":     "contato@artepessoa.com.br",
    "phone":     "+55 11 99999-0000",
    "instagram": "@rogeriopessoa"
  },
  "theme": {
    "bgPage":       "#eae7db",
    "textPrimary":  "#1c1c2e",
    "textAccent":   "#b33a2a"
  },
  "seo": {
    "title":       "Rogério Pessôa — Obras em Ferro e Cerâmica",
    "description": "Acervo digital das obras do escultor Rogério Pessôa."
  }
}

5. Módulo series — Séries (Capítulos do Acervo)

Cada item representa uma série, já ordenada curatoriamente pelo próprio artista na aba Séries do Studio.

[
  {
    "id": "recABC123",
    "title": "Ferro e Fogo",
    "description": "Trabalhos fundidos. Tensão entre matéria e forma.",
    "displayOrder": "01"
  }
]

💡 O array series[] já é retornado ordenado (ASC) — nenhuma ordenação adicional é necessária no cliente.

6. Módulo artworks — Trabalhos

Traz a consolidação limpa dos Trabalhos visíveis no portfólio.

{
  "id": "recAbCdEfGhIjKlMn",
  "title": "O Jardim Suspenso",
  "year": "2023",
  "medium": "Acrílica sobre tela",
  "dimensions": "120 x 80 cm",
  "imageUrl": "https://v5.airtableusercontent.com/...",
  "carouselImages": [
    "https://v5.airtableusercontent.com/..."
  ],
  "concept": "Texto descritivo principal do Trabalho.",
  "language": ["Pintura"],
  "series": ["Fase Botânica"],
  "status": ["Disponível"],
  "location": "São Paulo, SP",
  "photoCredit": "João Fotógrafo",
  "curatorialOrder": 0
}

Notas cruciais:

• imageUrl aponta para a miniatura principal WebP/JPG, otimizada para web (máx. 1080px). Não é necessário redimensionamento.
• Campo curatorialOrder: Número que representa a posição do Trabalho. O array artworks[] já chega pré-ordenado (Soberania Curatorial).

7. Demais Módulos Documentais (Trajetória, Fortuna Crítica, CV)

A estrutura completa acompanha o ecossistema do Studio. Todos os textos longos (content) nos módulos de events, texts e cvs são suportados via Markdown puro e possuem chaves de relacionamento, permitindo ao site desenhar, por exemplo, "Exposições onde este Trabalho participou".

8. Códigos de Retorno (Tratamento de Erros)

Seu site deve prever a inadiplência ou atualização do servidor:

Perguntas Frequentes

P: A API impõe algum limite de chamadas (Rate Limit)? R: Nossa integração Sandbox possui resiliência elástica para suportar picos comuns de tráfego de portfólios institucionais, mas sugerimos implementar cache local no seu framework (Next.js ISR a cada 60s ou SWR em Nuxt).

P: Eu consigo mandar contatos formulário do meu site ou criar Trabalhos novos via essa API? R: Não. Esta API é Headless CMS (1-Way). Ela serve especificamente e exclusivamente para expor os dados consolidados no Acervo Vivo e espelhá-los como um vidro ("Read-only"). Entradas de clientes devem ser geridas por um provedor de formulário terceirizado no seu site.

P: Se eu desmarcar a flag 🌐Site/Ecommerce de um Trabalho agora, ele some do site? R: Sim, o reflexo é instantâneo no endpoint JSON, bastando apenas expirar os segundos do Cache do seu site. O dado sensível é decapitado do payload no mesmo milissegundo.