Exemplo de Doc de Endpoint

❗️
Importante!
Esse template deve ser duplicado antes de ser editado!

Este endpoint possibilita cadastrar novos livros no catálogo da sua editora. A partir dele, você pode inserir informações detalhadas sobre os livros, como título, autor, ISBN e gênero.

Pré-requisito

Para que seja possível utilizar este endpoint, é necessário que:

O parceiro tenha contratado o serviço de gestão de livros da nossa plataforma.

Requisição

Requisição HTTP

POST https://api-mtls.sandbox.bankly.com.br/{isbn}/bookManagement/

--request POST 
--url 'https://api-mtls.sandbox.bankly.com.br/{isbn}/bookManagement/' \  
--header 'api-version: 1' \  
--header 'Authorization: Bearer {{Token}}' \  
--header 'Content-Type: application/json' \  
--data-raw '  
{  
    "title": "O mistério do código quebrado", 
    "author": "Silvana Sales",
		"isbn": "12345467780086434",
    "genre": "horror"
}

Autorização

Esta requisição requer o scope descrito a seguir:

Scope	Descrição
`book.create`	Concede acesso para cadastrar um novo livro no catálogo de uma editora.

Cabeçalhos (Headers)

Nome	Descrição
`api-version`	Obrigatório. Versão da API. Atualmente estamos na versão 1.0.
`Authorization`	Obrigatório. Token de autorização do tipo Bearer.

Parâmetros da rota (Path)

No path desta requisição envie o seguinte campo:

Nome	Tipo	Descrição	Especificação
`isbn`	`path`	Obrigatório. Código que identifica a publicação.	Informe somente números.

Corpo da requisição (Body)

No body, envie os seguintes campos em formato JSON:

Nome	Tipo	Descrição	Especificação
`title`	`string`	Obrigatório. Título do livro a ser cadastrado.	Tamanho máximo: 200 caracteres.
`author`	`string`	Obrigatório. Nome do autor (a) do livro.	Esse campo não aceita caracteres especiais.
`isbn`	`string`	Código que identifica a publicação.	Tamanho máximo: 13 caracteres.
`genre`	`string`	Gênero da publicação.	—

{  
    "title": "O mistério do código quebrado", 
    "author": "Silvana Sales",
		"isbn": "12345467780086434",
    "genre": "horror"
}

🚧
Importante
Lembre-se de que o formato do ISBN é composto por cinco partes: o prefixo (978 neste caso, indicando o uso internacional), o grupo de registro (3 neste exemplo, indicando a língua ou região geográfica), o código do editor (16 neste caso, atribuído ao editor específico), o número de título (148410, identificando o livro individualmente) e o dígito de verificação (0, utilizado para garantir a precisão do ISBN).

Resposta (Response)

Os status 200 indica que a solicitação foi aceita e o livro está sendo adicionado ao catálogo.

Sendo bem-sucedido, o retorno irá trazer os seguintes campos em formato JSON:

Nome	Tipo	Descrição	Número máximo de caracteres
`bookId`	`string`	Identificador único do livro adicionado. Guarde-o, pois ele deverá ser utilizado na requisição de consulta, atualização e exclusão de um livro	20

{ 
   "bookId": "47742stguy663023",   
}

Erros

Este endpoint pode retornar erros específicos, conforme a tabela a seguir:

Status Code	Código	Mensagem	Descrição
400	INVALID_PARAMETER	The field title must not be empty.	O campo `title` é obrigatório.
400	BOOK_GENRE_INVALID	Please select a valid genre for the book. Ensure that you choose from the available genres listed in the dropdown menu.	Este erro ocorre quando o gênero fornecido para o cadastro do livro não é válido ou não está em conformidade com os padrões aceitos em nosso sistema.

Recordamos que esta API também poderá retornar erros comuns entre todos os endpoints. Portanto, recomendamos a consulta da documentação de erros, onde é possível encontrar as mensagens comuns em inglês que acompanham os erros 400 (se houver).

Eventos

Caso o parceiro deseje receber mensagens referentes aos eventos relacionados a esse endpoint, é preciso configurar o webhook. O evento é:

Nome do evento	Descrição
`BOOK_WAS_ REGISTERED`	Comunica o cadastro de um livro no catálogo.