To Aqui - Sandbox

O modelo título

id uuid

Identificador do título.

item_type string

Tipo de item: livro, e-book, revista, periódico, DVD ou referência.

loanable boolean

false para itens somente de consulta local.

authors string[]

Autores.

isbn / issn / call_number string|null

Identificadores bibliográficos e número de chamada.

total_copies / available_copies integer

Exemplares no acervo e disponíveis agora.

O modelo título

{
  "id": "01a1d000-0000-7000-8000-000000000101",
  "title": "Dom Casmurro",
  "subtitle": null,
  "item_type": "book",
  "loanable": true,
  "authors": [
    "Machado de Assis"
  ],
  "category": {
    "id": "01a1d000-0000-7000-8000-000000000102",
    "name": "Literatura brasileira"
  },
  "publisher": {
    "id": "01a1d000-0000-7000-8000-000000000103",
    "name": "Penguin-Companhia"
  },
  "isbn": "9788535910663",
  "issn": null,
  "edition": "1ª",
  "publication_year": 1899,
  "language": "pt",
  "call_number": "869.3 M149d",
  "description": null,
  "tags": [
    "clássico",
    "vestibular"
  ],
  "total_copies": 2,
  "available_copies": 1
}

O modelo empréstimo

id uuid

Identificador do empréstimo.

status string

active, returned, overdue ou lost.

is_overdue boolean

Em aberto e com o prazo vencido.

title / copy / member object

Título, exemplar (tombo) e leitor (carteirinha e nome).

loan_date / due_date date

Data do empréstimo e prazo de devolução.

returned_at datetime|null

Data e hora da devolução.

renewals_count integer

Quantas vezes foi renovado.

O modelo empréstimo

{
  "id": "01a1d000-0000-7000-8000-000000000201",
  "status": "active",
  "status_label": "Ativo",
  "is_overdue": false,
  "title": {
    "id": "01a1d000-0000-7000-8000-000000000101",
    "title": "Dom Casmurro",
    "isbn": "9788535910663"
  },
  "copy": {
    "id": "01a1d000-0000-7000-8000-000000000104",
    "accession_number": "BIB-0001"
  },
  "member": {
    "id": "01a1d000-0000-7000-8000-000000000301",
    "card_number": "LIB-DEMO-0001",
    "name": "Ana Beatriz Costa"
  },
  "loan_date": "2026-10-01",
  "due_date": "2026-10-15",
  "returned_at": null,
  "renewals_count": 0
}

GET /v1/partners/library/titles/all

Listar títulos

Catálogo do acervo, em ordem alfabética. Paginado (25 por página).

Filtros (query string)

search string opcional

Parte do título, subtítulo ou do nome de um autor.

isbn string opcional

ISBN exato (com ou sem hífens).

available boolean opcional

1 para títulos com ao menos um exemplar disponível.

Códigos de resposta

200

Sucesso.

401

Credenciais inválidas (X-Partner, X-Client ou X-Authorization).

403

Cliente fora do plano Gestão Escolar (ERP_REQUIRED) ou módulo exclusivo de escolas privadas (PRIVATE_CLIENT_REQUIRED).

404

Recurso não encontrado.

422

Parâmetros inválidos — veja errors.

Requisição GET

GET /v1/partners/library/titles/all

curl https://toakiescola.com.br/api/v1/partners/library/titles/all \
  -H "X-Authorization: {api_token}" \
  -H "X-Partner: {partner_token}" \
  -H "X-Client: {client_slug}"

$response = $client->get('https://toakiescola.com.br/api/v1/partners/library/titles/all', [
    'headers' => $headers, // X-Authorization, X-Partner, X-Client
]);

const res = await fetch('https://toakiescola.com.br/api/v1/partners/library/titles/all', {
    method: 'GET',
    headers: { /* X-Authorization, X-Partner, X-Client */ 'Content-Type': 'application/json' },
});

Resposta

{
  "data": [
    {
      "id": "01a1d000-0000-7000-8000-000000000101",
      "title": "Dom Casmurro",
      "subtitle": null,
      "item_type": "book",
      "loanable": true,
      "authors": [
        "Machado de Assis"
      ],
      "category": {
        "id": "01a1d000-0000-7000-8000-000000000102",
        "name": "Literatura brasileira"
      },
      "publisher": {
        "id": "01a1d000-0000-7000-8000-000000000103",
        "name": "Penguin-Companhia"
      },
      "isbn": "9788535910663",
      "issn": null,
      "edition": "1ª",
      "publication_year": 1899,
      "language": "pt",
      "call_number": "869.3 M149d",
      "description": null,
      "tags": [
        "clássico",
        "vestibular"
      ],
      "total_copies": 2,
      "available_copies": 1
    }
  ],
  "links": { /* first, prev, next */ },
  "meta": { "current_page": 1, "per_page": 25 }
}

{
  "success": false,
  "message": "Recurso não encontrado."
}

GET /v1/partners/library/title/{id}

Obter título

Um título com todos os seus exemplares e a situação de cada um.

Parâmetros de rota

id uuid obrigatório

UUID do título.

Códigos de resposta

200

Sucesso.

401

Credenciais inválidas (X-Partner, X-Client ou X-Authorization).

403

Cliente fora do plano Gestão Escolar (ERP_REQUIRED) ou módulo exclusivo de escolas privadas (PRIVATE_CLIENT_REQUIRED).

404

Recurso não encontrado.

Requisição GET

GET /v1/partners/library/title/{id}

curl https://toakiescola.com.br/api/v1/partners/library/title/{id} \
  -H "X-Authorization: {api_token}" \
  -H "X-Partner: {partner_token}" \
  -H "X-Client: {client_slug}"

$response = $client->get('https://toakiescola.com.br/api/v1/partners/library/title/{id}', [
    'headers' => $headers, // X-Authorization, X-Partner, X-Client
]);

const res = await fetch('https://toakiescola.com.br/api/v1/partners/library/title/{id}', {
    method: 'GET',
    headers: { /* X-Authorization, X-Partner, X-Client */ 'Content-Type': 'application/json' },
});

Resposta

{
  "data": {
    "id": "01a1d000-0000-7000-8000-000000000101",
    "title": "Dom Casmurro",
    "subtitle": null,
    "item_type": "book",
    "loanable": true,
    "authors": [
      "Machado de Assis"
    ],
    "category": {
      "id": "01a1d000-0000-7000-8000-000000000102",
      "name": "Literatura brasileira"
    },
    "publisher": {
      "id": "01a1d000-0000-7000-8000-000000000103",
      "name": "Penguin-Companhia"
    },
    "isbn": "9788535910663",
    "issn": null,
    "edition": "1ª",
    "publication_year": 1899,
    "language": "pt",
    "call_number": "869.3 M149d",
    "description": null,
    "tags": [
      "clássico",
      "vestibular"
    ],
    "total_copies": 2,
    "available_copies": 1,
    "copies": [
      {
        "id": "01a1d000-0000-7000-8000-000000000104",
        "accession_number": "BIB-0001",
        "status": "loaned",
        "status_label": "Emprestado",
        "condition": "good",
        "shelf_location": "Estante 3 — prateleira B"
      },
      {
        "id": "01a1d000-0000-7000-8000-000000000105",
        "accession_number": "BIB-0002",
        "status": "available",
        "status_label": "Disponível",
        "condition": "good",
        "shelf_location": "Estante 3 — prateleira B"
      }
    ]
  }
}

{
  "success": false,
  "message": "Recurso não encontrado."
}

GET /v1/partners/library/members/all

Listar leitores

Leitores da biblioteca (alunos, professores e funcionários) com a quantidade de empréstimos em aberto. Paginado.

Filtros (query string)

search string opcional

Número da carteirinha exato.

category string opcional

student, teacher ou staff.

status string opcional

active, suspended ou expired.

Códigos de resposta

200

Sucesso.

401

Credenciais inválidas (X-Partner, X-Client ou X-Authorization).

403

Cliente fora do plano Gestão Escolar (ERP_REQUIRED) ou módulo exclusivo de escolas privadas (PRIVATE_CLIENT_REQUIRED).

404

Recurso não encontrado.

422

Parâmetros inválidos — veja errors.

Requisição GET

GET /v1/partners/library/members/all

curl https://toakiescola.com.br/api/v1/partners/library/members/all \
  -H "X-Authorization: {api_token}" \
  -H "X-Partner: {partner_token}" \
  -H "X-Client: {client_slug}"

$response = $client->get('https://toakiescola.com.br/api/v1/partners/library/members/all', [
    'headers' => $headers, // X-Authorization, X-Partner, X-Client
]);

const res = await fetch('https://toakiescola.com.br/api/v1/partners/library/members/all', {
    method: 'GET',
    headers: { /* X-Authorization, X-Partner, X-Client */ 'Content-Type': 'application/json' },
});

Resposta

{
  "data": [
    {
      "id": "01a1d000-0000-7000-8000-000000000301",
      "card_number": "LIB-DEMO-0001",
      "name": "Ana Beatriz Costa",
      "category": "student",
      "category_label": "Aluno",
      "status": "active",
      "status_label": "Ativo",
      "student_id": "01a0aab3-550d-7077-aad1-a6d67b1452d8",
      "join_date": "2026-02-01",
      "expires_at": "2026-12-31",
      "open_loans_count": 1
    }
  ],
  "links": { /* first, prev, next */ },
  "meta": { "current_page": 1, "per_page": 25 }
}

{
  "success": false,
  "message": "Recurso não encontrado."
}

GET /v1/partners/library/loans/all

Listar empréstimos

Empréstimos, do mais recente para o mais antigo. Paginado.

Filtros (query string)

status string opcional

active, returned, overdue ou lost.

member_id uuid opcional

Somente os empréstimos de um leitor.

overdue boolean opcional

1 para os empréstimos em aberto com devolução atrasada.

Códigos de resposta

200

Sucesso.

401

Credenciais inválidas (X-Partner, X-Client ou X-Authorization).

403

Cliente fora do plano Gestão Escolar (ERP_REQUIRED) ou módulo exclusivo de escolas privadas (PRIVATE_CLIENT_REQUIRED).

404

Recurso não encontrado.

422

Parâmetros inválidos — veja errors.

Requisição GET

GET /v1/partners/library/loans/all

curl https://toakiescola.com.br/api/v1/partners/library/loans/all \
  -H "X-Authorization: {api_token}" \
  -H "X-Partner: {partner_token}" \
  -H "X-Client: {client_slug}"

$response = $client->get('https://toakiescola.com.br/api/v1/partners/library/loans/all', [
    'headers' => $headers, // X-Authorization, X-Partner, X-Client
]);

const res = await fetch('https://toakiescola.com.br/api/v1/partners/library/loans/all', {
    method: 'GET',
    headers: { /* X-Authorization, X-Partner, X-Client */ 'Content-Type': 'application/json' },
});

Resposta

{
  "data": [
    {
      "id": "01a1d000-0000-7000-8000-000000000201",
      "status": "active",
      "status_label": "Ativo",
      "is_overdue": false,
      "title": {
        "id": "01a1d000-0000-7000-8000-000000000101",
        "title": "Dom Casmurro",
        "isbn": "9788535910663"
      },
      "copy": {
        "id": "01a1d000-0000-7000-8000-000000000104",
        "accession_number": "BIB-0001"
      },
      "member": {
        "id": "01a1d000-0000-7000-8000-000000000301",
        "card_number": "LIB-DEMO-0001",
        "name": "Ana Beatriz Costa"
      },
      "loan_date": "2026-10-01",
      "due_date": "2026-10-15",
      "returned_at": null,
      "renewals_count": 0
    }
  ],
  "links": { /* first, prev, next */ },
  "meta": { "current_page": 1, "per_page": 25 }
}

{
  "success": false,
  "message": "Recurso não encontrado."
}

GET /v1/partners/library/loan/{id}

Obter empréstimo

Um empréstimo.

Parâmetros de rota

id uuid obrigatório

UUID do empréstimo.

Códigos de resposta

200

Sucesso.

401

Credenciais inválidas (X-Partner, X-Client ou X-Authorization).

403

Cliente fora do plano Gestão Escolar (ERP_REQUIRED) ou módulo exclusivo de escolas privadas (PRIVATE_CLIENT_REQUIRED).

404

Recurso não encontrado.

Requisição GET

GET /v1/partners/library/loan/{id}

curl https://toakiescola.com.br/api/v1/partners/library/loan/{id} \
  -H "X-Authorization: {api_token}" \
  -H "X-Partner: {partner_token}" \
  -H "X-Client: {client_slug}"

$response = $client->get('https://toakiescola.com.br/api/v1/partners/library/loan/{id}', [
    'headers' => $headers, // X-Authorization, X-Partner, X-Client
]);

const res = await fetch('https://toakiescola.com.br/api/v1/partners/library/loan/{id}', {
    method: 'GET',
    headers: { /* X-Authorization, X-Partner, X-Client */ 'Content-Type': 'application/json' },
});

Resposta

{
  "data": {
    "id": "01a1d000-0000-7000-8000-000000000201",
    "status": "active",
    "status_label": "Ativo",
    "is_overdue": false,
    "title": {
      "id": "01a1d000-0000-7000-8000-000000000101",
      "title": "Dom Casmurro",
      "isbn": "9788535910663"
    },
    "copy": {
      "id": "01a1d000-0000-7000-8000-000000000104",
      "accession_number": "BIB-0001"
    },
    "member": {
      "id": "01a1d000-0000-7000-8000-000000000301",
      "card_number": "LIB-DEMO-0001",
      "name": "Ana Beatriz Costa"
    },
    "loan_date": "2026-10-01",
    "due_date": "2026-10-15",
    "returned_at": null,
    "renewals_count": 0
  }
}

{
  "success": false,
  "message": "Recurso não encontrado."
}

POST /v1/partners/library/loans

Realizar empréstimo

Empresta um exemplar a um leitor — o equivalente ao balcão de circulação. O prazo de devolução segue a política da categoria do leitor, descontando feriados e dias sem expediente. Dispara o webhook library_loan.created.

Parâmetros do corpo

accession_number string opcional

Tombo (código) do exemplar. Obrigatório sem copy_id.

copy_id uuid opcional

UUID do exemplar. Obrigatório sem accession_number.

card_number string opcional

Carteirinha do leitor. Obrigatório sem member_id.

member_id uuid opcional

UUID do leitor. Obrigatório sem card_number.

As mesmas regras do balcão valem aqui e respondem 422 com code: "BUSINESS_RULE": leitor suspenso ou com carteirinha vencida, limite de empréstimos simultâneos, multas em aberto acima do permitido, item somente para consulta local, ou exemplar que não está disponível (já emprestado ou reservado para outro leitor).

Códigos de resposta

201

Recurso criado.

401

Credenciais inválidas (X-Partner, X-Client ou X-Authorization).

403

Cliente fora do plano Gestão Escolar (ERP_REQUIRED) ou módulo exclusivo de escolas privadas (PRIVATE_CLIENT_REQUIRED).

404

Exemplar ou leitor não encontrado.

422

Dados inválidos, ou uma regra de circulação impediu o empréstimo (BUSINESS_RULE).

Requisição POST

POST /v1/partners/library/loans

curl https://toakiescola.com.br/api/v1/partners/library/loans \
  -X POST \
  -H "X-Authorization: {api_token}" \
  -H "X-Partner: {partner_token}" \
  -H "X-Client: {client_slug}" \
  -H "Content-Type: application/json" \
  -d '{"accession_number":"BIB-0002","card_number":"LIB-DEMO-0001"}'

$response = $client->post('https://toakiescola.com.br/api/v1/partners/library/loans', [
    'headers' => $headers, // X-Authorization, X-Partner, X-Client
    'json' => json_decode('{"accession_number":"BIB-0002","card_number":"LIB-DEMO-0001"}', true),
]);

const res = await fetch('https://toakiescola.com.br/api/v1/partners/library/loans', {
    method: 'POST',
    headers: { /* X-Authorization, X-Partner, X-Client */ 'Content-Type': 'application/json' },
    body: JSON.stringify({"accession_number":"BIB-0002","card_number":"LIB-DEMO-0001"}),
});

Resposta

{
  "data": {
    "id": "01a1d000-0000-7000-8000-000000000201",
    "status": "active",
    "status_label": "Ativo",
    "is_overdue": false,
    "title": {
      "id": "01a1d000-0000-7000-8000-000000000101",
      "title": "Dom Casmurro",
      "isbn": "9788535910663"
    },
    "copy": {
      "id": "01a1d000-0000-7000-8000-000000000105",
      "accession_number": "BIB-0002"
    },
    "member": {
      "id": "01a1d000-0000-7000-8000-000000000301",
      "card_number": "LIB-DEMO-0001",
      "name": "Ana Beatriz Costa"
    },
    "loan_date": "2026-10-01",
    "due_date": "2026-10-15",
    "returned_at": null,
    "renewals_count": 0
  }
}

{
  "success": false,
  "message": "Limite de 3 empréstimo(s) simultâneo(s) atingido para esta categoria."
}

{
  "success": false,
  "message": "Recurso não encontrado."
}

POST /v1/partners/library/loan/{id}/return

Registrar devolução

Devolve o exemplar. Se houver atraso (descontados feriados e a carência da política), a multa é gerada automaticamente e informada em fine_amount; se houver reserva na fila, o exemplar é separado para o próximo leitor (hold_fulfilled). Dispara o webhook library_loan.returned.

Parâmetros de rota

id uuid obrigatório

UUID do empréstimo.

Códigos de resposta

200

Sucesso.

401

Credenciais inválidas (X-Partner, X-Client ou X-Authorization).

403

Cliente fora do plano Gestão Escolar (ERP_REQUIRED) ou módulo exclusivo de escolas privadas (PRIVATE_CLIENT_REQUIRED).

404

Recurso não encontrado.

422

Empréstimo já devolvido (ALREADY_RETURNED).

Requisição POST

POST /v1/partners/library/loan/{id}/return

curl https://toakiescola.com.br/api/v1/partners/library/loan/{id}/return \
  -X POST \
  -H "X-Authorization: {api_token}" \
  -H "X-Partner: {partner_token}" \
  -H "X-Client: {client_slug}"

$response = $client->post('https://toakiescola.com.br/api/v1/partners/library/loan/{id}/return', [
    'headers' => $headers, // X-Authorization, X-Partner, X-Client
]);

const res = await fetch('https://toakiescola.com.br/api/v1/partners/library/loan/{id}/return', {
    method: 'POST',
    headers: { /* X-Authorization, X-Partner, X-Client */ 'Content-Type': 'application/json' },
});

Resposta

{
  "data": {
    "id": "01a1d000-0000-7000-8000-000000000201",
    "status": "returned",
    "status_label": "Devolvido",
    "is_overdue": false,
    "title": {
      "id": "01a1d000-0000-7000-8000-000000000101",
      "title": "Dom Casmurro",
      "isbn": "9788535910663"
    },
    "copy": {
      "id": "01a1d000-0000-7000-8000-000000000104",
      "accession_number": "BIB-0001"
    },
    "member": {
      "id": "01a1d000-0000-7000-8000-000000000301",
      "card_number": "LIB-DEMO-0001",
      "name": "Ana Beatriz Costa"
    },
    "loan_date": "2026-10-01",
    "due_date": "2026-10-15",
    "returned_at": "2026-10-18T10:12:00-03:00",
    "renewals_count": 0
  },
  "overdue_days": 2,
  "fine_amount": 1,
  "hold_fulfilled": false
}

{
  "success": false,
  "message": "Recurso não encontrado."
}

POST /v1/partners/library/loan/{id}/renew

Renovar empréstimo

Estende o prazo de devolução por mais um período da política. Recusado (BUSINESS_RULE) quando o limite de renovações foi atingido, quando outro leitor reservou o título ou quando há multas acima do permitido. Dispara o webhook library_loan.renewed.

Parâmetros de rota

id uuid obrigatório

UUID do empréstimo.

Códigos de resposta

200

Sucesso.

401

Credenciais inválidas (X-Partner, X-Client ou X-Authorization).

403

Cliente fora do plano Gestão Escolar (ERP_REQUIRED) ou módulo exclusivo de escolas privadas (PRIVATE_CLIENT_REQUIRED).

404

Recurso não encontrado.

422

Renovação não permitida (BUSINESS_RULE).

Requisição POST

POST /v1/partners/library/loan/{id}/renew

curl https://toakiescola.com.br/api/v1/partners/library/loan/{id}/renew \
  -X POST \
  -H "X-Authorization: {api_token}" \
  -H "X-Partner: {partner_token}" \
  -H "X-Client: {client_slug}"

$response = $client->post('https://toakiescola.com.br/api/v1/partners/library/loan/{id}/renew', [
    'headers' => $headers, // X-Authorization, X-Partner, X-Client
]);

const res = await fetch('https://toakiescola.com.br/api/v1/partners/library/loan/{id}/renew', {
    method: 'POST',
    headers: { /* X-Authorization, X-Partner, X-Client */ 'Content-Type': 'application/json' },
});

Resposta

{
  "data": {
    "id": "01a1d000-0000-7000-8000-000000000201",
    "status": "active",
    "status_label": "Ativo",
    "is_overdue": false,
    "title": {
      "id": "01a1d000-0000-7000-8000-000000000101",
      "title": "Dom Casmurro",
      "isbn": "9788535910663"
    },
    "copy": {
      "id": "01a1d000-0000-7000-8000-000000000104",
      "accession_number": "BIB-0001"
    },
    "member": {
      "id": "01a1d000-0000-7000-8000-000000000301",
      "card_number": "LIB-DEMO-0001",
      "name": "Ana Beatriz Costa"
    },
    "loan_date": "2026-10-01",
    "due_date": "2026-10-29",
    "returned_at": null,
    "renewals_count": 1
  }
}

{
  "success": false,
  "message": "Não é possível renovar: há reserva na fila para este título."
}

{
  "success": false,
  "message": "Recurso não encontrado."
}

Biblioteca

O modelo título

O modelo empréstimo

Listar títulos

Filtros (query string)

Códigos de resposta

Obter título

Parâmetros de rota

Códigos de resposta

Listar leitores

Filtros (query string)

Códigos de resposta

Listar empréstimos

Filtros (query string)

Códigos de resposta

Obter empréstimo

Parâmetros de rota

Códigos de resposta

Realizar empréstimo

Parâmetros do corpo

Códigos de resposta

Registrar devolução

Parâmetros de rota

Códigos de resposta

Renovar empréstimo

Parâmetros de rota

Códigos de resposta