Versão:** 1.2

Atualizado em: 2026-09-14

Este documento descreve como consumir os dados do Acervo Vivo para integração em sites de portfólio. A API é pública e de leitura única — não requer autenticação via cabeçalhos e retorna um JSON blindado, sem dados sensíveis.

1. O Endpoint

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

• Parâmetro: mode | Tipo: string | Descricao: (Opcional) Envie o valor ecommerce para habilitar a injeção de dados comerciais, logísticos e financeiros no retorno da API.
• Parâmetro: priceListId | Tipo: string | Descricao: (Opcional) ID de uma Lista de Preços específica gerada pela nossa equipe (ex: recXYZ123). Só funciona se mode=ecommerce estiver ativo.

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

2. O Gatilho de Publicação

A API não expõe todo o acervo. O conteúdo é filtrado dinamicamente:

– No banco de dados, a obra (ou evento, texto, publicação) deve estar vinculada a uma **Palavra-chave**.

– Essa palavra-chave deve pertencer ao tipo: **🌐Site/Ecommerce**.

Dica: Isso permite ao artista controlar exatamente o que aparece no site, simplesmente marcando ou desmarcando essa tag na Plataforma do Acervo Vivo, sem qualquer intervenção técnica.

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

3.1 Módulo `artworks` — Obras

Cada item representa uma obra do acervo.

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”
 ]
}

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.

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

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.