Versão: 1.3

Atualizado em: 2026-09-30

Este documento descreve como consumir os dados do Acervo Vivo para integração em sites de portfólio. 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

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).

O Endpoint

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

Parâmetros obrigatórios e opcionais:

• apiId (Obrigatório): O identificador único do acervo fornecido pela nossa equipe (ex: rec02n7cun5sRDcY2).
• mode: (Opcional) Envie `ecommerce` para injetar os dados de venda (preços, peso, cubagem) na resposta.
• priceListId: (Opcional) ID de uma Lista de Preços (ex: rec123) para calcular o valor. Requer mode=ecommerce.
• keywordId: (Opcional) ID de uma Palavra-chave específica para filtrar as obras por categoria (ex: apenas Gravuras). Recomendado para vitrines de e-commerce com múltiplas categorias.
• keyword: (Opcional) Nome textual da Palavra-chave como alternativa ao keywordId (ex: Gravuras).
• expandEditions: (Opcional) Envie `true` para incluir os Exemplares (Tiragens) de cada obra no array `editions[]`. Essencial para e-commerces com seletor de exemplar.

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

Estrutura da Resposta (JSON)

A resposta retorna um único objeto com quatro arrays, um para cada módulo de conteúdo:

json {
 “artworks”:      [ … ],
 “events”:        [ … ],
 “texts”:         [ … ],
 “publications”:  [ … ]
}

Essa estrutura permite que o site use apenas os módulos que precisar, ignorando os demais.

Módulo `artworks` — Obras

Cada item representa uma obra do acervo.

A resposta retorna uma consolidação limpa dos Trabalhos visíveis no portfólio. As URLs de imagem (`imageUrl`) já apontam para a melhor resolução disponível (até 1080px), sem necessidade de redimensionamento no cliente.

json{
 “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/…”,
   “https://v5.airtableusercontent.com/…”
 ],
 “concept”: “Texto descritivo principal da obra.”,
 “language”: [“Pintura”],
 “series”: [“Fase Botânica”],
 “status”: [“Disponível”],
 “location”: “São Paulo, SP”,
 “photoCredit”: “João Fotógrafo”,
 “containerCode”: “BOT-012”,
 “pureCode”: “00012”,
 “caption”: “O Jardim Suspenso, 2023\nAcrílica sobre tela\n120 x 80 cm”,
 “exhibitionLines”: [
   “2023 – Exposição Coletiva ‘Natureza Viva’, Museu de Arte Moderna”,
   “2024 – SP-Arte, Pavilhão da Bienal”
 ]
}

Modo E-commerce (Campos Estendidos):

Caso o seu site chame a API com o parâmetro &mode=ecommerce, o Data Shield libera as seguintes propriedades extras dentro de cada Trabalho, prontas para lojas virtuais:

• price: Valor numérico (ex: 1500.5). Extraído dinamicamente da Lista de Preços ou do mercado base da obra.
• priceFormatted: String com o valor formatado amigável e com símbolo monetário da lista (ex: “R$ 1.500,50” ou “€ 1.500,50”).
• weight: Peso físico em kg, formatado para sistemas de logística.
• totalDimensions: Cubagem pronta para calculadoras de frete (Correios e Transportadoras).
• captionSec e captionTer: Legendas multilingues para interfaces internacionais.

Expansão de Exemplares (Tiragens):

Se a requisição contiver `&expandEditions=true`, cada obra incluirá o array `editions[]` com os exemplares físicos disponíveis, ideal para e-commerces com seletor de edição (ex: 10/30, PA II/III). O preço refletirá automaticamente o valor base da obra-mãe, ou o valor de ajuste cadastrado especificamente para o exemplar na Lista de Preços.

json
{
“id”: “recObraMae123”,
“title”: “Folha de parra”,
“imageUrl”: “https://…full_1080.jpg”,
“hasEditions”: true,
“editionCount”: 4,
“price”: 1200,
“priceFormatted”: “R$ 1.200,00”,
“editions”: [
{
“id”: “recTiragem1”,
“parentArtworkId”: “recObraMae123”,
“editionString”: “10/30”,
“status”: “Disponível”,
“fullCode”: “10/30 – 00629”,
“price”: 1200,
“priceFormatted”: “R$ 1.200,00”,
“netArtistValue”: 900
},
{
“id”: “recTiragemPA”,
“editionString”: “PA II/III”,
“status”: “Disponível”,
“price”: 1500,
“priceFormatted”: “R$ 1.500,00”
}
]
}

Notas sobre imagens:

– `imageUrl` aponta para a miniatura principal (`thumbnails.large`) gerada pelo Airtable — WebP/JPG, otimizada para galerias web (máx. 1080px). Não é necessário redimensionamento adicional.

– `carouselImages` é um array de miniaturas das imagens adicionais da obra, prontas para uso em carrosséis. Pode ser vazio (`[]`).

Ordenação: As obras são retornadas ordenadas pelo `containerCode` (ordenação numérica), espelhando a ordem do catálogo.

3.2 Módulo `events` — Exposições e Eventos (Trajetória)

Cada item representa um evento da carreira (exposição individual, coletiva, feira, residência, etc.).

json{
 “id”: “recXxYyZz…”,
 “title”: “Natureza Viva”,
 “year”: “2023”,
 “type”: “Exposição Coletiva”,
 “venue”: “Museu de Arte Moderna”,
 “city”: “São Paulo, SP”,
 “description”: “Apresentação de obras recentes da série Fase Botânica.”,
 “link”: “https://mam.org.br/…”,
 “imageUrl”: “https://v5.airtableusercontent.com/…”,
 “openingDate”: “2023-09-14”,
 “curriculumLine”: “2023 – Natureza Viva, MAM São Paulo”,
 “clipping”: “Texto de clipping de imprensa.”,
 “artworkIds”: [“recAbCd…”, “recEfGh…”],
 “textIds”: [“recIjKl…”]
}

Notas:

– `curriculumLine` é a linha sugerida para uso em CVs e catálogos — pronta para uso direto.
– `artworkIds` e `textIds` são arrays de IDs que cruzam referências com os outros módulos da resposta.

Ordenação: Eventos retornados do mais recente ao mais antigo (por `openingDate` ou `year`).

3.3 Módulo `texts` — Textos Críticos (Fortuna Crítica)

Cada item representa um texto crítico, ensaio, apresentação ou depoimento.

json{
 “id”: “recMnOpQr…”,
 “title”: “A Botânica do Invisível”,
 “type”: “Texto Crítico”,
 “author”: “Maria Santos”,
 “date”: “2023-09-01”,
 “content”: “Texto completo do ensaio ou crítica…”,
 “aiSummary”: “Resumo gerado por IA do conteúdo do texto.”,
 “eventIds”: [“recXxYyZz…”],
 “artworkIds”: [“recAbCdEf…”]
}

Notas:

– `content` contém o texto completo (plain text ou Markdown).
– `aiSummary` é um resumo automaticamente gerado pelo Acervo Vivo — útil para exibir uma prévia antes de expandir o texto completo.
– `eventIds` e `artworkIds` permitem associar o texto ao evento ou obra correspondente nos outros módulos.

3.4 Módulo `publications` — Publicações (Bibliografia)

Cada item representa uma publicação editorial: catálogo, livro, revista, etc.

json{
 “id”: “recStUvWx…”,
 “title”: “Catálogo Fase Botânica”,
 “type”: “Catálogo de Exposição”,
 “publisher”: “Museu de Arte Moderna”,
 “year”: “2023”,
 “isbn”: “978-85-…”,
 “edition”: “1ª edição”,
 “authorship”: “Curadoria: Ana Lima”,
 “pages”: “128”,
 “description”: “Catálogo da exposição individual…”,
 “externalLink”: “https://loja.mam.org.br/…”,
 “clipping”: “”,
 “releaseDate”: “2023-09-14”,
 “curriculumLine”: “2023 – Catálogo ‘Fase Botânica’, MAM São Paulo”,
 “imageUrl”: “https://v5.airtableusercontent.com/…”,
 “artworkIds”: [“recAbCdEf…”],
 “textIds”: [“recMnOpQr…”],
 “eventIds”: [“recXxYyZz…”]
}

Notas:
– `curriculumLine` é a referência bibliográfica formatada, pronta para uso em CVs.
– `imageUrl` aponta para a capa da publicação (thumbnail otimizado).

Ordenação: Publicações retornadas da mais recente à mais antiga (por `releaseDate`).

4. Cruzamento entre Módulos

Os módulos se interconectam via arrays de IDs. Isso permite construir páginas ricas sem chamadas adicionais à API:

Obra (artworks)

 └── artworkIds ────→ Event (events)

 └── artworkIds ────→ Text (texts)

 └── artworkIds ────→ Publication (publications)

Evento (events)

 └── artworkIds ────→ Artwork (artworks)

 └── textIds    ────→ Text (texts)

Exemplo de uso: Para exibir, na página de uma obra, todos os eventos em que ela foi exposta, basta filtrar `events` pelo `id` da obra presente em `artworkIds`.

5. Cache e Performance

Os dados na Plataforma do Acervo Vivo podem levar alguns segundos para propagar após uma edição. Recomendamos:

SWR / React Query: revalidação automática em background.
ISR (Next.js): `revalidate: 60` para regenerar a página a cada 60 segundos.
Cache simples: armazenar a resposta em `localStorage` ou `sessionStorage` com TTL de 5 minutos.

6. Suporte

Qualquer dúvida sobre IDs de acervos, campos adicionais ou integrações específicas, entre em contato com a equipe do Acervo Vivo.