**Versão:** 1.1 

**Atualizado em:** 2026-03-31

—

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 obrigatório:**

| Parâmetro | Tipo   | Descrição                                                     |

|———–|——–|—————————————————————|

| `apiId`   | string | O identificador único do acervo (ex: `rec02n7cun5sRDcY2`).   |

**Exemplo de chamada:**

“`

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

“`

—

## 2. O Gatilho de Publicação (Airtable)

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

– No Airtable, 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 no Airtable, 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.

—

### 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 do Airtable 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.