Biblioteca
Acervo, exemplares e circulação (empréstimo/devolução). Diferente de todo o resto desta
referência, a Biblioteca é compartilhada por todo o cliente — o catálogo não pertence a uma
escola específica, então estas rotas ficam em /v1/partners/library/...,
sem CNPJ na URL.
O ponto de maior valor para integração é a circulação: o empréstimo identifica o exemplar pelo seu
accession_number (código de
barras/tombo) e o leitor pela sua card_number
(carteirinha) — os dois valores que um totem de autoatendimento ou leitor RFID realmente lê.
403
com "code": "ERP_REQUIRED".
O modelo título
Um título é a obra (o registro bibliográfico); os exemplares (copies) são os itens físicos individuais que podem ser emprestados.
id
uuid
Identificador único.
item_type
string
book, ebook, magazine, journal, dvd ou reference.
is_loanable
boolean
false para reference — consulta local apenas.
title
string
Título da obra.
subtitle
string|null
Subtítulo.
isbn
string|null
ISBN.
publication_year
integer|null
Ano de publicação.
call_number
string|null
Número de chamada (classificação de prateleira).
tags
array
Tags livres.
total_copies
integer
Total de exemplares cadastrados (cache).
available_copies
integer
Exemplares disponíveis agora (cache).
category
object|null
id e name da categoria.
publisher
object|null
id e name da editora.
{ "id": "lib1title-0000-0000-0000-000000000001", "item_type": "book", "is_loanable": true, "title": "Dom Casmurro", "isbn": "9788525406958", "total_copies": 3, "available_copies": 2 }
O modelo empréstimo
id
uuid
Identificador único do empréstimo.
status
string
active, returned, overdue ou lost.
is_overdue
boolean
Calculado: em aberto e com due_date no passado.
loan_date
date
Data do empréstimo.
due_date
date
Data limite para devolução.
returned_at
datetime|null
Data/hora da devolução.
renewals_count
integer
Quantas vezes já foi renovado.
copy
object
id, accession_number, title e title_id do exemplar.
member
object
id, card_number e name do leitor.
{ "id": "...", "status": "active", "is_overdue": false, "loan_date": "2026-09-02", "due_date": "2026-09-16", "copy": { "accession_number": "ACC-0001", "title": "Dom Casmurro" }, "member": { "card_number": "CARD-0001", "name": "João da Silva" } }
/v1/partners/library/titles/all
Listar títulos
Catálogo completo do cliente, paginado.
Códigos de resposta
200
Sucesso.
404
Não encontrado.
/v1/partners/library/title/{id}
Obter um título
Retorna um título com categoria, editora e autores.
Códigos de resposta
200
Sucesso.
404
Não encontrado.
/v1/partners/library/title
Criar título
Corpo: item_type, title (obrigatórios); subtitle, isbn, issn, edition, publication_year, language, call_number, description, price, tags, location_default, category_id, publisher_id (opcionais).
Códigos de resposta
201
Sucesso.
404
Não encontrado.
/v1/partners/library/title/{id}
Editar título
Atualiza os campos enviados.
Códigos de resposta
200
Sucesso.
404
Não encontrado.
/v1/partners/library/title/{id}
Excluir título
Remove o título (soft delete).
Códigos de resposta
200
Sucesso.
404
Não encontrado.
/v1/partners/library/title/{id}/copies
Listar exemplares
Exemplares físicos de um título, com status individual.
Códigos de resposta
200
Sucesso.
404
Não encontrado.
/v1/partners/library/title/{id}/copy
Cadastrar exemplar
Corpo: accession_number (gerado automaticamente se omitido), status, condition, shelf_location, acquisition_date, price_override, notes.
Códigos de resposta
201
Sucesso.
404
Não encontrado.
/v1/partners/library/copy/{id}
Editar exemplar
Atualiza status, condition, shelf_location ou notes.
Códigos de resposta
200
Sucesso.
404
Não encontrado.
/v1/partners/library/copy/{id}
Excluir exemplar
Remove o exemplar (soft delete).
Códigos de resposta
200
Sucesso.
404
Não encontrado.
/v1/partners/library/loans
Listar empréstimos
Empréstimos do cliente, paginados. Filtro opcional status (query string).
Códigos de resposta
200
Sucesso.
404
Não encontrado.
/v1/partners/library/loan
Registrar empréstimo
Corpo: accession_number, card_number (ambos obrigatórios). Aplica as regras de política de empréstimo da categoria do leitor (limite simultâneo, multas em aberto, reservas).
Códigos de resposta
201
Sucesso.
422
Regra de circulação violada (limite de empréstimos, multa em aberto, item indisponível, ...).
409
Escola sem políticas de empréstimo configuradas para a categoria do leitor.
404
Não encontrado.
{ "accession_number": "ACC-0001", "card_number": "CARD-0001" }
/v1/partners/library/loan/{id}/return
Registrar devolução
Devolve o exemplar do empréstimo. Calcula multa por atraso automaticamente e libera a próxima reserva da fila, se houver.
Códigos de resposta
200
Sucesso.
422
Regra de circulação violada (limite de empréstimos, multa em aberto, item indisponível, ...).
404
Não encontrado.