Para desenvolvedores
API de consulta
Mostre no site da livraria, no sistema de vendas ou num totem da loja onde está cada livro, direto do mapa do Acervo. Só leitura: a API nunca muda nada no mapa. Faz parte do plano Livraria.
1. A chave
Quem administra a organização cria a chave no Acervo, em Plano → API de consulta. Ela aparece uma vez só: guarde-a no servidor do seu site ou sistema. Mande em todo pedido no cabeçalho:
Authorization: Bearer acv_SUA_CHAVECrie uma chave para cada uso (site, sistema, totem). Se uma vazar, revogue só ela, na mesma tela, e ela para de responder na hora.
2. Onde está um livro
GET /api/v1/onde?isbn=9788535908770Aceita ISBN-13 ou ISBN-10, com ou sem traços. Devolve o livro e cada lugar em que ele mora agora: seção, tábua (quando o livro tem tábua), se é estoque e quantos exemplares. Mesas e vitrines aparecem com tipo mesa ou vitrine. (ISBN, endereços e números abaixo são de exemplo.)
{
"isbn": "9788535908770",
"titulo": "Viva o povo brasileiro",
"autoria": "João Ubaldo Ribeiro",
"editora": "Alfaguara",
"capa": "https://…/9788535908770.jpg",
"exemplares": 3,
"lugares": [
{ "secao": "Literatura brasileira", "codigo_secao": "LIT", "tipo": "secao",
"tabua": "LIT-03", "estoque": false, "exemplares": 2, "desde": "2026-11-12T14:03:00Z" },
{ "secao": "Mesa de lançamentos", "codigo_secao": "MESA", "tipo": "mesa",
"tabua": null, "estoque": false, "exemplares": 1, "desde": "2026-11-15T10:20:00Z" }
]
}ISBN fora do catálogo da organização: 404. exemplares é null quando ninguém contou ainda.
3. O mapa inteiro
GET /api/v1/mapa?pagina=1&por_pagina=500&desde=2026-11-01Uma linha por livro e lugar, em páginas de até 1.000 (500 se não disser). Com desde, vêm só os livros que chegaram a um lugar depois dessa data: bom para atualizar o seu sistema todo dia sem baixar tudo.
{
"pagina": 1, "por_pagina": 500, "total": 2340, "paginas": 5,
"itens": [
{ "isbn": "9788535908770", "titulo": "Viva o povo brasileiro", "autoria": "João Ubaldo Ribeiro",
"editora": "Alfaguara", "secao": "Literatura brasileira", "codigo_secao": "LIT", "tipo": "secao",
"tabua": "LIT-03", "estoque": false, "exemplares": 2, "desde": "2026-11-12T14:03:00Z" }
]
}4. Erros e limites
- 401: chave ausente, desconhecida ou revogada.
- 402: o plano da organização venceu; volta quando for renovado.
- 403: o plano não inclui a API (ela faz parte do Livraria e do Rede).
- 404: o ISBN não está no catálogo.
- 429: passou de 60 consultas por minuto com a mesma chave; o cabeçalho
Retry-Afterdiz quantos segundos esperar.
Toda resposta é JSON em UTF-8; erro vem como { "erro": "…" }. A API aceita chamada de qualquer site (CORS), mas o certo é chamar do seu servidor, para a chave não ficar exposta na página.
5. Exemplos
No terminal:
curl -H "Authorization: Bearer acv_SUA_CHAVE" \
"https://acervo-jade-one.vercel.app/api/v1/onde?isbn=9788535908770"No servidor do site (JavaScript):
const r = await fetch('https://acervo-jade-one.vercel.app/api/v1/onde?isbn=' + isbn, {
headers: { Authorization: 'Bearer ' + process.env.ACERVO_CHAVE },
})
const livro = await r.json()
// "Literatura brasileira, tábua LIT-03 (2 exemplares)"
const onde = livro.lugares.map(l => `${l.secao}${l.tabua ? ', tábua ' + l.tabua : ''} (${l.exemplares ?? '?'} exemplares)`).join(' · ')Precisa gravar no Acervo, receber aviso quando algo muda ou ligar ao seu sistema de vendas? Isso é do plano Rede: fale com a gente.