Introdução
A API da Bookinfo Metadados permite a consulta de metadados, adição e atualização de informações de livros.
Essa é a versão 1.2 da API, divulgada oficialmente no 2º semestre de 2019.
Nesta versão, a API permite realizar busca por livros publicados, busca por novos livros de Editoras que o seu login segue e busca por Editoras e seus Selos Editoriais.
Ambientes de SANDBOX e PRODUCTION
Como na API V1.0, esta versão também disponibiliza o ambiente SANDBOX para que sejam feitos os testes de integração antes de irem para PRODUCTION, que é o ambiente de produção.
Os testes para esse ambiente devem ser feitos utilizando a chamada da API para a URL https://sandbox.bookinfometadados.com.br
, e apenas após completar a integração, deve-se apontar para a URL de produção, https://api.bookinfometadados.com.br
.
A homologação é uma etapa necessária para que seja liberada a integração em produção dos métodos de adição e edição de metadados. Portanto, por favor, envie um e-mail para [email protected] no final da etapa de testes.
Na documentação que se segue, indicamos sempre os endpoints para ambos os endereços (SANDBOX e PRODUCTION) e possibilitando também seus testes.
Para que o ambiente de testes permaneça similar ao ambiente de produção nos dados a serem devolvidos, periodicamente efetuamos a limpeza dos livros inseridos pelos usuários em seus testes.
É importante ressaltar que a chave_de_acesso para ambos ambientes será diferente. E a criação de novos cadastros no ambiente de testes deve ser solicitada diretamente à equipe da Bookinfo Metadados.
Quaisquer dúvidas, favor entrar em contato pelo endereço de e-mail [email protected].
Retorno das requisições
Todos os retornos das requisições para a API, trazem o resultado da ação seguido da Paginação (em caso da requisição ser uma pesquisa) e do Status. Esse status avisa se a requisição foi um sucesso ou não, um código de erro e uma mensagem amigável.
Abaixo explicaremos os exemplos de Status e Paginação.
Status
Status, como explicado acima, é o indice do retorno das requisições que é responsável por identificar se houve sucesso no retorno das informações ou se houve erro. Segue abaixo um exemplo de um status e em seguida os códigos de retorno existentes:
"status": [
{
"success": true/false,
"code": <numero do codigo do status>,
"message": <Mensagem correspondente ao status>,
"error_detail": <Mostrado apenas em casos de erro. Mensagem detalhando melhor o motivo do erro>,
},
Código do status | Sucesso | Mensagem |
---|---|---|
200 | true | Ok |
101 | false | Nenhum registro foi encontrado |
102 | false | Favor informar ao menos um parâmetro para busca |
102 | false | Favor informar o valor de busca |
105 | false | Token inválido |
106 | false | Favor informar seu token de acesso |
107 | false | Houve alguns erros na requisição |
108 | false | Paginação fora do limite. Tente usar a página 1 novamente |
109 | false | Requisição inválida |
110 | false | Token não autorizado |
111 | false | Você ainda não segue nenhuma editora |
112 | false | Este ISBN não pertence ao seu Selo Editorial |
112 | false | Selo editorial ainda não cadastrado na plataforma. Por gentileza, acesse o Painel de Controle, adicione o selo e reenvie a requisição. |
113 | false | Este livro não corresponde com as informações enviadas. |
Paginação
Agora na versão 1.2 da API da Bookinfo Metadados, temos a possibilidade de realizar paginação nas requisições. Isso facilita quando o retorno da requisição vem com uma quantidade muito grande de registros.
Importante: A Paginação irá aparecer apenas em requisições de pesquisa e busca por Novos Livros.
A requisição inicial sempre começa na página 1. Para acessar a próxima página de resultados, realize novamente a mesma requisição enviando junto o parâmetro page=<numero-da-pagina>
Exemplo de requisição:
Sandbox: https://sandbox.bookinfometadados.com.br/api/v1.2/book?page=2
O índice de paginação aparecerá sempre no final do resultado de uma requisição e sua estrutura será como este exemplo abaixo:
Exemplo de resposta:
"navigation": [
{
"page": 1,
"next_page": 1,
"prev_page": 1,
"total_pages": 10,
"total_records": 150
},
Indices | Valores |
---|---|
page | Página atual |
next_page | Próxima página |
prev_page | Página anterior |
total_pages | Total de páginas |
total_records | Total de registros encontrados |
Livros
Existem três possibilidades de interação com livros que são: consulta, adição e atualização de informações.
Obs.: Podem ser utilizados mais de um filtro por requisição, conforme mostrado abaixo.
Sandbox: https://sandbox.bookinfometadados.com.br/api/v1.2/book?isbn=<ISBN>&titulo=<título-da-obra>
Production: https://api.bookinfometadados.com.br/api/v1.2/book?isbn=<ISBN>&titulo=<título-da-obra>
CONSULTAS SEM AUTENTICAÇÃO
Todas as consultas de livros sem autenticação devem ser feitas para a URL de SANDBOX / PRODUCTION seguida do endpoint /book utilizando o método GET
, ficando assim:
Sandbox: https://sandbox.bookinfometadados.com.br/api/v1.2/book
Production: https://api.bookinfometadados.com.br/api/v1.2/book
#Requisição por ISBN
Parâmetros
Elemento | Tipo | Tamanho | Descrição |
---|---|---|---|
isbn | String | 10 ou 13 | O campo deve ser numérico, sem pontos ou traços, contendo 10 ou 13 digitos (para livros mais antigos ou mais novos). |
Modelo de requisição GET
Sandbox: https://sandbox.bookinfometadados.com.br/api/v1.2/book?isbn=<ISBN>
Production: https://api.bookinfometadados.com.br/api/v1.2/book?isbn=<ISBN>
Resposta
Para ver como é o retorno dessa requisição, preencha o formulário abaixo e clique em "Testar":
Explicando:
Segue abaixo o significado de alguns códigos mostrados acima:
Contribuição (ou autores)
Classificação Indicativa
Status
Faixa Etária
Encadernação
#Requisição por Título
Parâmetros
Elemento | Tipo | Tamanho | Descrição |
---|---|---|---|
titulo | String | 200 | O campo deve ser string, contendo até no máximo 200 digitos. |
Modelo de requisição GET
Sandbox: https://sandbox.bookinfometadados.com.br/api/v1.2/book?titulo=<título-da-obra>
Production: https://api.bookinfometadados.com.br/api/v1.2/book?titulo=<título-da-obra>
Resposta
Para ver como é o retorno dessa requisição, preencha o formulário abaixo e clique em "Testar":
Explicando:
Segue abaixo o significado de alguns códigos mostrados acima:
Contribuição (ou autores)
Classificação Indicativa
Status
Faixa Etária
Encadernação
#Requisição por Contribuição (Autores e Colaboradores)
Parâmetros
Elemento | Tipo | Tamanho | Descrição |
---|---|---|---|
contribuicao | String | 380 | O campo deve ser string, contendo até no máximo 380 digitos. |
Modelo de requisição GET
Sandbox: https://sandbox.bookinfometadados.com.br/api/v1.2/book?contribuicao=<nome-de-contribuição>
Production: https://api.bookinfometadados.com.br/api/v1.2/book?contribuicao=<nome-de-contribuição>
Resposta
Para ver como é o retorno dessa requisição, preencha o formulário abaixo e clique em "Testar":
Explicando:
Segue abaixo o significado de alguns códigos mostrados acima:
Contribuição (ou autores)
Classificação Indicativa
Status
Faixa Etária
Encadernação
#Requisição por Formato do livro (BOOK ou EBOOK)
Parâmetros
Elemento | Tipo | Tamanho | Descrição |
---|---|---|---|
formato | String | 5 | São aceitos apenas as duas opções a seguir: BOOK ou EBOOK. |
Modelo de requisição GET
Sandbox: https://sandbox.bookinfometadados.com.br/api/v1.2/book?formato=<formato-do-livro>
Production: https://api.bookinfometadados.com.br/api/v1.2/book?formato=<formato-do-livro>
Resposta
Para ver como é o retorno dessa requisição, preencha o formulário abaixo e clique em "Testar":
Explicando:
Segue abaixo o significado de alguns códigos mostrados acima:
Contribuição (ou autores)
Classificação Indicativa
Status
Faixa Etária
Encadernação
#Requisição por Status do livro
Parâmetros
Elemento | Tipo | Descrição |
---|---|---|
codigo_status | inteiro | São aceitos apenas as duas opções abaixo: |
Opções de Status
Código | Status do livro |
---|---|
1 | Disponível |
2 | Indisponível |
3 | Pré-Lançamento |
4 | Fora de Catálogo |
Modelo de requisição GET
Sandbox: https://sandbox.bookinfometadados.com.br/api/v1.2/book?codigo_status=<codigo-do-status>
Production: https://api.bookinfometadados.com.br/api/v1.2/book?codigo_status=<codigo-do-status>
Resposta
Para ver como é o retorno dessa requisição, preencha o formulário abaixo e clique em "Testar":
Explicando:
Segue abaixo o significado de alguns códigos mostrados acima:
Contribuição (ou autores)
Classificação Indicativa
Status
Faixa Etária
Encadernação
#Requisição por Editora
Na busca de livros por Editora, nós temos 2 opções: por codigo_editoras ou por nome_fantasia_da_editora.
Parâmetros
Elemento | Tipo | Tamanho | Descrição |
---|---|---|---|
codigo_editoras | inteiro | 1 |
Códigos das editoras que podem ser encontrado na requisição de Busca por Editoras.
Pode ser informado +1 código por requisição. Basta acrescentar , antes de informar o próximo valor.
Exemplo: 135,1327 |
nome_fantasia_da_editora | string | 250 | Nome fantasia da editora que pode ser encontrado na requisição de Busca por Editoras. |
Modelo de requisição GET
Sandbox: https://sandbox.bookinfometadados.com.br/api/v1.2/book?<campo>=<codigo-ou-nome-da-editora>
Production: https://api.bookinfometadados.com.br/api/v1.2/book?<campo>=<codigo-ou-nome-da-editora>
Resposta
Para ver como é o retorno dessa requisição, preencha o formulário abaixo e clique em "Testar":
Importante: a base de dados de sandbox contém informações diferentes da base de produção. Portanto, os resultados para ambas requisições possivelmente serão divergentes.
Explicando:
Segue abaixo o significado de alguns códigos mostrados acima:
Contribuição (ou autores)
Classificação Indicativa
Status
Faixa Etária
Encadernação
#Requisição por Selo Editorial
Na busca de livros por Selos Editoriais, nós temos 2 opções: por codigo_selos ou por nome_do_selo_editorial.
Parâmetros
Elemento | Tipo | Tamanho | Descrição |
---|---|---|---|
codigo_selos | inteiro | - - |
Códigos dos selos editoriais que podem ser encontrados na requisição de Busca por Editoras.
Pode ser informado +1 código por requisição. Basta acrescentar , antes de informar o próximo valor.
Exemplo: 972,1060 |
nome_do_selo_editorial | string | 250 | Nome do selo editorial que pode ser encontrado na requisição de Busca por Editoras. |
Modelo de requisição GET
Sandbox: https://sandbox.bookinfometadados.com.br/api/v1.2/book?<campo>=<codigo-ou-nome-do-selo-editorial>
Production: https://api.bookinfometadados.com.br/api/v1.2/book?<campo>=<codigo-ou-nome-do-selo-editorial>
Resposta
Para ver como é o retorno dessa requisição, preencha o formulário abaixo e clique em "Testar":
Importante: a base de dados de sandbox contém informações diferentes da base de produção. Portanto, os resultados para ambas requisições possivelmente serão divergentes.
Explicando:
Segue abaixo o significado de alguns códigos mostrados acima:
Contribuição (ou autores)
Classificação Indicativa
Status
Faixa Etária
Encadernação
#Requisição por Data
Na busca de livros por data, nós temos 2 opções: por data_inicio e/ou por data_termino, podendo usar ambas ao mesmo tempo.
Esse método irá retornar apenas os livros publicados no Bookinfo Metadados no período especificado, não os alterados. Caso seja necessária a busca apenas por livros alterados no período, utilize o parâmetro only_updates=true.
Parâmetros
Elemento | Tipo | Formato | Descrição |
---|---|---|---|
data_inicio | data | YYYYMMDD | Exemplo: 20190617 |
data_termino | data | YYYYMMDD | Exemplo: 20190618 |
only_updates | booleano | TRUE/FALSE | A ausência desse parâmetro ou o valor FALSE já são o padrão |
Modelo de requisição GET
Sandbox: https://sandbox.bookinfometadados.com.br/api/v1.2/book?<campo>=<data>
Production: https://api.bookinfometadados.com.br/api/v1.2/book?<campo>=<data>
Resposta
Para ver como é o retorno dessa requisição, preencha o formulário abaixo e clique em "Testar":
Importante: a base de dados de sandbox contém informações diferentes da base de produção. Portanto, os resultados para ambas requisições possivelmente serão divergentes.
Explicando:
Segue abaixo o significado de alguns códigos mostrados acima:
Contribuição (ou autores)
Classificação Indicativa
Status
Faixa Etária
Encadernação
#Requisição por Bisac
Na requisição de livros por BISAC, é possível fazer a busca por um BISAC de cada vez.
Esse método retornará apenas os livros publicados no Bookinfo Metadados que estão cadastrados com aquele BISAC específico.
Parâmetros
Elemento | Tipo | Formato | Descrição |
---|---|---|---|
bisac | String | XYZ000000 | Exemplo: COM000000 |
Modelo de requisição GET
Sandbox: https://sandbox.bookinfometadados.com.br/api/v1.2/book?<campo>=<bisac>
Production: https://api.bookinfometadados.com.br/api/v1.2/book?<campo>=<bisac>
Resposta
Para ver como é o retorno dessa requisição, preencha o formulário abaixo e clique em "Testar":
Importante: a base de dados de Sandbox contém informações diferentes da base de produção. Portanto, os resultados para ambas requisições possivelmente serão divergentes. Nos testes operados nesta página da documentação, será mostrado apenas UM registro. Por exemplo: ao pesquisar pelo BISAC geral de Ficção (FIC000000) será mostrado nesta página apenas um livro. Para obter todos, é preciso realizar a requisição GET utilizando as URLs descritas acima.
Explicando:
Segue abaixo o significado de alguns códigos mostrados acima:
Contribuição (ou autores)
Classificação Indicativa
Status
Faixa Etária
Encadernação
#Requisição apenas por Novos Livros
Com esse método, é possível buscar apenas por Novos Livros de Selos Editoriais que sua conta segue, utilizando sua chave_de_acesso como autenticação.
Atenção: nesta modalidade, serão enviados metadados apenas dos selos editoriais que seu usuário segue na Bookinfo Metadados. Para começar a seguir os selos de sua preferência, acesse a plataforma com login e senha e acesse Clientes -> Editoras. Ao encontrar o selo, clique em "Seguir este selo".
CONSULTAS AUTENTICADAS
Todas as requisições de livros com autenticação devem ser feitas para a URL de SANDBOX / PRODUCTION utilizando o método POST
contendo sua chave_de_acesso, que pode ser obtida no seu painel de controle ou então solicidada à equipe da Bookinfo Metadados, seguida do endpoint desejado.
Parâmetros
Elemento | Tipo | Obrigatório | Formato de envio | Descrição |
---|---|---|---|---|
chave_de_acesso | string | Sim | Authorization Bearer Token | A chave_de_acesso é fornecida em seu painel de controle, na página Minha conta |
A requisição de novos livros é semelhante ao botão "baixar novos livros" da página principal de usuários NÃO EDITORA
. Ela serve para baixar tudo que há de novo publicado desde o último download daquele usuário.
Seguindo os padrões de segurança, a chave_de_acesso deve ser enviada como Authorization Bearer Token no header da sua requisição.
Exemplo em cURL:
curl -X POST -H 'Authorization: Bearer <chave_de_acesso>' -H 'Host: https://api.bookinfometadados.com.br/api/v1.2/book/news'
Diferente das outras requisições mostradas acima, esta requer uma confirmação de recebimento das informações. Segue abaixo uma explicação de como funciona essa confirmação:
Confirmação
No caso de nossa API, é necessário confirmar o recebimento de todos os metadados para sabermos que a resposta foi recebida com sucesso pela sua aplicação. Com isso, ao final da resposta da requisição, é gerado um token de confirmação
, mostrado ao final do resultado, que deve ser enviado para o endpoint /book/news/confirmation para encerrar a busca por novos livros. Apenas após essa nova requisição de confirmação é que nosso sistema marca que os novos livros foram enviados.
Caso essa nova requisição não seja feita, o Bookinfo Metadados enviará novamente todos os mesmos livros na próxima vez que a requisição for efetuada.
Modelo de requisição POST
Sandbox: https://sandbox.bookinfometadados.com.br/api/v1.2/book/news/confirmation
Production: https://api.bookinfometadados.com.br/api/v1.2/book/news/confirmation
Resposta
{
"books": [
{
...
},
...
],
"success_confirmation": {
"confirmation_token": "<TOKEN-GERADO>",
"confirmation_instructions": "Realizar novamente um POST para este mesmo endpoint porém com o parâmetro confirmation_token para encerrar essa requisição"
},
"status": {
"success": true,
"code": 200
}
Limitações
Caso a quantidade de registros seja muito grande, o sistema irá paginar o resultado . Quando isso acontecer, será necessário realizar novas requisições para o mesmo método, percorrendo as páginas existentes até chegar na última página para o token de confirmação.
Resposta
{
"books": [
{
...
},
...
],
"navigation": {
"page": 1,
"next_page": 2,
"prev_page": 1,
"total_pages": 2,
"total_records": 6000
},
"status": {
"success": true,
"code": 200
}
Editoras
Agora na API 1.2 é possível buscar todas as editoras e trazer suas informações juntas ou filtrar por nome, selo editorial e outras formas.
Obs.: Os filtros mostrados abaixo podem ser utilizados mais de um por requisição.
Modelo de requisição GET
Sandbox: https://sandbox.bookinfometadados.com.br/api/v1.2/company
Production: https://api.bookinfometadados.com.br/api/v1.2/company
#Mostrar todas as editoras
Modelo de requisição GET
Sandbox: https://sandbox.bookinfometadados.com.br/api/v1.2/company
Production: https://api.bookinfometadados.com.br/api/v1.2/company
Resposta
Para ver como é o retorno dessa requisição, preencha o formulário abaixo e clique em "Testar":
#Requisição por Código da Editora
Parâmetros
Elemento | Tipo | Tamanho | Descrição |
---|---|---|---|
codigo_editoras | inteiro | - - | Pode ser informado +1 código por requisição. Basta acrescentar , antes de informar o próximo valor. Exemplo: 972,1060 |
Modelo de requisição GET
Sandbox: https://sandbox.bookinfometadados.com.br/api/v1.2/company?codigo_editoras=<valor>
Production: https://api.bookinfometadados.com.br/api/v1.2/company?codigo_editoras=<valor>
Resposta
Para ver como é o retorno dessa requisição, preencha o formulário abaixo e clique em "Testar":
#Requisição por Nome da Editora
Parâmetros
Elemento | Tipo | Tamanho | Descrição |
---|---|---|---|
nome_fantasia_da_editora | string | 250 | Nome fantasia da editora |
Modelo de requisição GET
Sandbox: https://sandbox.bookinfometadados.com.br/api/v1.2/company?nome_fantasia_da_editora=<valor>
Production: https://api.bookinfometadados.com.br/api/v1.2/company?nome_fantasia_da_editora=<valor>
Resposta
Para ver como é o retorno dessa requisição, preencha o formulário abaixo e clique em "Testar":
#Requisição por CNPJ da Editora
Parâmetros
Elemento | Tipo | Tamanho | Descrição |
---|---|---|---|
cnpj | string | até 20 caracteres | CNPJ da editora |
Modelo de requisição GET
Sandbox: https://sandbox.bookinfometadados.com.br/api/v1.2/company?cnpj=<valor>
Production: https://api.bookinfometadados.com.br/api/v1.2/company?cnpj=<valor>
Resposta
Para ver como é o retorno dessa requisição, preencha o formulário abaixo e clique em "Testar":
#Requisição por Código do Selo Editorial
Parâmetros
Elemento | Tipo | Tamanho | Descrição |
---|---|---|---|
codigo_selos | inteiro | - - | Pode ser informado +1 código por requisição. Basta acrescentar , antes de informar o próximo valor. Exemplo: 972,1060 |
nome_do_selo_editorial | string | 250 | Nome do Selo Editorial |
Modelo de requisição GET
Sandbox: https://sandbox.bookinfometadados.com.br/api/v1.2/company?codigo_selos=<valor>
Production: https://api.bookinfometadados.com.br/api/v1.2/company?codigo_selos=<valor>
Resposta
Para ver como é o retorno dessa requisição, preencha o formulário abaixo e clique em "Testar":
#Notificação Automática
A Notificação Automática é a maneira mais simples de receber em seu sistema os novos livros publicados na Bookinfo Metadados. Através do cadastro de uma URL no painel de controle, na página Minha conta do nosso site, enviaremos por método POST as informações de todo novo livro diretamente para aquela URL.
Na Notificação Automática, serão enviados metadados de todas as editoras da Bookinfo Metadados, não necessariamente apenas dos selos que seu usuário segue na plataforma.
ATENÇÃO: É necessário que essa URL esteja acessível ao Bookinfo Metadados, sem necessitar de Logins ou quaisquer outras autenticações.
Exemplo de dados enviados
Testar recebimento de requisições
Os dados enviados para a URL informada foram:
Manipulação de Metadados
Os métodos abaixo mostrarão como é possível adicionar e editar livros da sua editora na Bookinfo Metadados.
Atenção: os métodos abaixo são requisições que exigem autenticação e devem seguir os padrões de segurança explicados aqui
#Adicionar novo livro
Chamada
Sandbox: https://sandbox.bookinfometadados.com.br/api/v1.2/book/add
Produção: https://api.bookinfometadados.com.br/api/v1.2/book/add
Elemento | Tipo | Obrigatório | Tamanho | Descrição |
---|---|---|---|---|
chave_de_acesso | String | Sim | Variável |
A chave_de_acesso é fornecida em seu painel de controle, na página Minha conta Lembrando que este campo deve ser enviado como Authorization Bearer Token como explicado aqui. |
editora | Inteiro | Sim | Variável |
Deve ser usado o codigo_editora na Bookinfo Metadados.
Esse valor só pode ser encontrado na requisição Busca Por Editora (ver mais sobre esse método).
|
selo_editorial | String | Sim | Variável |
Corresponde ao nome do Selo Editorial ao qual o livro faz parte.
Deve ser usado o mesmo Nome do Selo encontrado na página Minha Conta . |
formato | String | Sim | Variável | BOOK ou EBOOK. |
isbn | String | Sim | 10 ou 13 | Adicionar o número do ISBN do livro a ser adicionado. O número deve ser único para cada livro ou edição. Caso o livro já tenha sido adicionado na Bookinfo Metadados, será devolvido um erro. |
titulo | String | Sim | Variável |
O título do livro (não incluir volume nem subtítulo) .
Deve-se utilizar letra maiúscula apenas na primeira letra da primeira palavra e nas iniciais de nomes próprios. |
subtitulo | String | Não | Variável |
Corresponde ao subtítulo do livro. Não é de preenchimento obrigatório. Não deve ser incluído volume.
Deve-se utilizar letra maiúscula apenas na primeira letra da primeira palavra e nas iniciais de nomes próprios. |
titulo_original | String | Não | Variável | Caso se trate de uma tradução, deve-se incluir aqui o título original do livro na sua lingua respectiva. |
volume | Inteiro | Não | Variável | Caso faça parte de uma coleção ou conjunto de livros, informar apenas com número qual o volume do livro em questão. |
edicao | Inteiro | Sim | Variável | Número da edição do livro. Deve ser informato apenas o número, sem qualquer sinal ou outra palavra junto a ela. |
ano_edicao | Inteiro | Sim | 4 | Ano da edição do livro. |
detalhes_da_edicao | String | Não | Variável | Para detalhes específicos dessa edição, tais como "Edição de luxo", "Edição revisada e ampliada", etc, utilizar esse campo incluíndo qualquer texto desejado. |
data_de_publicacao | Date | Sim | DD/MM/YYYY | Data de publicação da edição em questão do livro. Caso não saiba a data exata, utilize uma data aproximada. É necessário informar no formato DD/MM/YYYY |
previsao_de_disponibilidade | Date | Não | DD/MM/YYYY | Data de previsão de disponibilidade do livro – somente quando o status for pré-lançamento ou indisponível. É necessário informar no formato DD/MM/YYYY. |
colecao | String | Não | Variável | Se for o caso, a qual coleção/série pertence o título. Não deve ser incluído volume. Deve-se utilizar letra maiúscula apenas na primeira letra da primeira palavra e nas iniciais de nomes próprios. |
volume_colecao | String | Não | Variável | Caso faça parte de uma coleção ou conjunto de livros, informar apenas com número qual o volume do livro em questão. |
contribuicao_nome[...] | String | Sim | Variável |
Para envios via Formulário:Para cada contribuição (Autor, Coordenador, Organizador, Editor, Instituição, etc) do livro, incluir um valor de contribuicao_nome[i], com um valor para i iniciando em 0 (zero).Exemplo: 'contribuicao_nome[0]':'Assis, Machado de', 'contribuicao_nome[1]':'Queiroz, Eça de' Para envios via JSON:Enviar os nomes de cada contribuição em cada indice da Array.Exemplo: 'contribuicao_nome': [ 'Assis, Machado de', 'Queiroz, Eça de' ] Atenção: É necessário seguir o formato Sobrenome, Nome; para todos os autores. Caso o autor não siga essa estrutura e identifique-se com apenas 1 nome (por exemplo: Ziraldo), insira esse nome dessa maneira mesmo. |
contribuicao_tipo[...] | Inteiro | Sim | Variável |
Para envios via Formulário:Para cada contribuição adicionado à chave anterior, deve-se adicionar seu respectivo código de contribuição, identificando a chave pelo mesmo número, conforme exemplo:'contribuicao_tipo[0]':1, 'contribuicao_tipo[1]':3 Para envios via JSON:Enviar os tipos de cada contribuição em cada indice da Array.Exemplo: 'contribuicao_tipo': [ 1, 3 ] Os valores para os tipos de contribuição são:
ATENÇÃO: o Bookinfo Metadados exige ao menos o envio de tipo de contribuição de um dos itens acima marcados com (*) .
|
palavras_chave | String | Sim | Variável | Devem ser incluídas pelo menos 3 palavras ou expressões-chave que descrevam tematicamente o título a ser adicionado. Essas palavras ou expressões devem ser separadas por vírgula+espaço. |
codigo_area | Inteiro | Sim | Até 2 digitos | Deve ser adicionado um ID de uma das áreas da Bookinfo Metadados, que são:
|
cdd | Inteiro | Não | A partir de 3 digitos | CDD do livro, número encontrado na fixa catalográfica do mesmo. O quarto dígito à direita, se houver, deve ser precedido de um ponto. Ex: 341.789987 |
codigo_bisac | String | Sim | 9 | Código BISAC (versão 2020) para seu livro. |
codigo_bisac2 | String | Não | 9 | Código BISAC (versão 2020) adicional para seu livro (diferente do anterior). |
codigo_bisac3 | String | Não | 9 | Código BISAC (versão 2020) adicional para seu livro (diferente do anterior). |
codigo_thema_categoria | String | Não | Variável | Insira o código da categoria Thema. Não enviar o nome da categoria ou a descrição completa, apenas o código. Se for mais de um código, separá-los por ponto-e-vírgula. Máximo de até 5 códigos por livro. |
codigo_thema_qualificador | String | Não | Variável | Insira o código do qualificador Thema. Não enviar o nome da categoria ou a descrição completa, apenas o código. Se for mais de um código, separá-los por ponto-e-vírgula. Máximo de até 5 códigos por livro. |
idioma | String | Sim | Variável | Idioma principal do livro, escrito por extenso. Ex.: Português, Inglês, Espanhol, Alemão etc. |
origem | String | Sim | Variável | Indicar nesse campo o país de origem do produto, e não da obra. |
faixa_etaria | Inteiro | Não | 1 | A faixa etária do livro deve ser informada utilizando numeros que referenciem à faixa adequada:
|
classificacao_indicativa | Inteiro | Sim | 1 | Informar classificação indicativa através de respectivo dígito da lista:
|
sinopse | String | Sim | Até 32000 caracteres | Sinopse do livro, com até 32000 caracteres (com espaços). Caso sejam inseridos mais de 32000 caracteres, o sistema cortará automaticamente o conteúdo após esse valor. |
sumario | String | Não | Até 32000 caracteres | Sumário do livro, aceita formatação de HTML. |
link | String | Não | Variável | Link principal do livro na web. Pode ser a página da editora, ou qualquer outro site que se deseje incluir. |
book_trailer | String | Não | Variável | URL do booktrailer do livro na web. |
paginas | Inteiro | Sim (se formato for: BOOK) |
Variável | Número de páginas do livro, em formato de número apenas. |
altura | Inteiro | Sim (se formato for: BOOK) |
Variável | Altura do livro em Centímetros. |
largura | Inteiro | Sim (se formato for: BOOK) |
Variável | Largura do livro em Centímetros. |
espessura | Inteiro | Sim (se formato for: BOOK) |
Variável | Espessura do livro em Centímetros. |
peso | Inteiro | Sim (se formato for: BOOK) |
Até 40 kg. | Peso do livro em Kilogramas. |
encadernacao | Inteiro | Sim | Até 2 digitos | Escolher tipo de encadernação, conforme valores da lista a seguire:
|
formato_ebook | String | Sim (se formato for: EBOOK) |
Variável | Inserir os formatos em que o eBook está disponível:
|
drm_ebook | String | Sim (se formato for: EBOOK) |
Variável | Se o eBook possuir proteção, informar com as opções abaixo:
|
plataforma_disponivel_ebook | String | Sim (se formato for: EBOOK) |
Variável | Para informar a(s) plataforma(s) em que o eBook está disponível. Os valores aceitáveis são estes:
|
material_adicional | Inteiro | Não | Até 2 digitos | Materiais que acompanham o livro. Utilizar um dos valores a seguir:
|
grau_escolar | Inteiro | Não | Até 1 dígito | Em caso de livro educacional, preencher com o valor correspondente à lista abaixo:
|
ano_escolar | Inteiro | Não | Até 2 digitos | Em caso de livro didático, informar a qual ano o livro se destina, seguindo os valores abaixo:
|
materia_escolar | String | Não | Variável | Para livros de educação, a qual matéria ou disciplina se dedica. |
codigo_status | Inteiro | Sim | 1 | O status do livro deve ser informado por meio de um numeral, que corresponda a uma das opções:
|
moeda | String | Sim | Insira a moeda correspondente ao valor da obra:
|
|
preco | Inteiro | Sim | A partir de 3 dígitos | Corresponde ao preço de capa do livro. A informação deve constar dos centavos, mesmo que zerados (ex. 14,00). Não deve ser incluído sinal de cifrão ou da moeda. |
codigo_de_barras | Inteiro | Sim | 13 dígitos | Deve ser utilizado necessariamente 13 dígitos ao código de barras. |
codigo_fiscal | Inteiro | Sim | 8 dígitos | Classificação fiscal do livro, podendo ser:
|
codigo_cst | String | Não | 3 dígitos |
O CST é composto de três dígitos (três números). Exemplo: 010 O primeiro dígito sempre determina a origem da mercadoria, conforme a tabela abaixo, que é conhecida como tabela A do CST:
Já os dois últimos dígitos indicam de qual forma deve ser realizada a tributação da mercadoria. Confira na tabela B do CST:
|
codigo_interno | String | Sim | Variável | Código do produto conforme o próprio sistema da Editora. Usado para integrações entre o Bookinfo Metadados e sistemas da editora e algumas livrarias. Caso não se aplique, utilize o ISBN do livro. |
certificacao_inmetro | String | Não | Variável | Código da certificação Inmetro. |
isbn_relacionado[i] | String | Não | 10 ou 13 digitos | Funciona da mesma maneira que constribuicao_nome, mas refere-se a ISBN's relacionados ao título, tais como Edições anteriores, Edições Digitais, etc. Obrigatório o preenchimento do campo isbn_relacionado_tipo[i]. |
isbn_relacionado_tipo[i] | Inteiro | Não* | Até 2 digitos | Funciona da mesma maneira que constribuicao_tipo, referindo-se ao tipo do ISBN adicionado no respectivo campo isbn_relacionado[i]. Dentre as opções aceitas, segue a lista com seus respectivos valores numéricos:
|
imagem_primeira_capa | URL | Sim | Variável | Inserir aqui a imagem da primeira capa de seu livro. Deve ser uma URL que o sistema da Bookinfo Metadados possa acessar automaticamente e capturar a imagem. Portanto, não pode depender de logins, ou qualquer tipo de autenticação. Deve-se utilizar, na Bookinfo Metadados, arquivos de imagem em boa qualidade (JPG ou PNG), com, no mínimo, 72 dpi de resolução. A região correspondente à primeira capa deve ter entre 700 pixels e 1000 pixels no seu lado menor. |
imagem_lombada | URL | Não | Variável | Inserir aqui a imagem da lombada de seu livro. Deve ser uma URL que o sistema da Bookinfo Metadados possa acessar automaticamente e capturar a imagem. Portanto, não pode depender de logins, ou qualquer tipo de autenticação. |
imagem_quarta_capa | URL | Não | Variável | Inserir aqui a imagem da quarta-capa de seu livro. Deve ser uma URL que o sistema da Bookinfo Metadados possa acessar automaticamente e capturar a imagem. Portanto, não pode depender de logins, ou qualquer tipo de autenticação. Deve-se utilizar, na Bookinfo Metadados, arquivos de imagem em boa qualidade (JPG ou PNG), com, no mínimo, 72 dpi de resolução. A região correspondente à primeira capa deve ter entre 700 pixels e 1000 pixels no seu lado menor. |
imagens_internas[i] | String | Não | Variável | Inserir aqui imagens internas de seu livro. Deve ser uma URL que o sistema da Bookinfo Metadados possa acessar automaticamente e capturar a imagem. Portanto, não pode depender de logins, ou qualquer tipo de autenticação. Deve-se utilizar, na Bookinfo Metadados, arquivos de imagem em boa qualidade (JPG ou PNG), com, no mínimo, 72 dpi de resolução. |
imagem_perspectiva[i] | String | Não | Variável | Inserir aqui a imagem em perspectiva (3D) de seu livro. Deve ser uma URL que o sistema da Bookinfo Metadados possa acessar automaticamente e capturar a imagem. Portanto, não pode depender de logins, ou qualquer tipo de autenticação. Deve-se utilizar, na Bookinfo Metadados, arquivos de imagem em boa qualidade (JPG ou PNG), com, no mínimo, 72 dpi de resolução. |
Exemplo de Chamada
$post_data = array(
'chave_de_acesso' => '1234567890', // sua chave de acesso vai aqui
'editora' => '135', // ID da Editora puxado pela API
'selo_editorial' => 'Imprensa Régia',
'formato' => 'BOOK',
'isbn' => '9781234567890',
'titulo' => 'Marília de Dirceu',
'subtitulo' => '',
'titulo_original' => '',
'edicao' => '1',
'ano_edicao' => '1810',
'detalhes_da_edicao' => 'Edição de luxo, Edição de bolso',
'data_de_publicacao' => '05/10/1810',
'volume' => '',
'colecao' => 'Coleção Clássicos',
'volume_colecao' => '1',
'contribuicao_nome[0]' => 'Silva, José da',
'contribuicao_tipo[0]' => 1, // ilustrador
'colaborador_nome[1]' => 'Bragança, João de',
'contribuicao_tipo[1]' => 8, // diagramador
'palavras_chave' => 'Literatura portuguesa, Poesia, Arcadismo',
'codigo_area' => 7, // literatura e fição
'cdd' => '869.12',
'codigo_bisac' => 'POE020000',
'codigo_bisac2' => '',
'codigo_bisac3' => '',
'idioma' => 'Português',
'origem' => 'Brasil',
'faixa_etaria' => 5, // acima de 12 anos
'classificacao_indicativa' => 1, //Livre para todos os públicos
'sinopse' => 'Um clássico da literatura em língua portuguêsa, Marília de Dirceu foi publicado em Lisboa, pela primeira vez, em 1792. Trata-se de um poema divido em três partes, uma declaração de amor que, mais de dois séculos depois de sua publicação, continua encantando gerações de leitores.',
'sumario' => '-',
'link' => 'http://www.2ab.com.br/pd-8d670-identidade-e-cultura.html',
'paginas' => '176',
'altura' => '24', // cm
'largura' => '17', // cm
'espessura' => '1', // cm
'peso' => '0.120', // kg
'encadernacao' => 1, // Brochura
'material_adicional' => '',
'status' => 1, // disponível
'moeda' => 'BRL', // reais
'preco' => '25,00',
'codigo_de_barras' => '9781234567890',
'codigo_fiscal' => '49019900',
'codigo_interno' => '123',
'isbn_relacionado[0]' => '9781234567890',
'isbn_relacionado_tipo[0]' => '5', // ISBN da versão em PDF
'isbn_relacionado[1]' => '9781234567890',
'isbn_relacionado_tipo[1]' => '12', // ISBN do Audiobook
'imagem_primeira_capa' => 'https://www.bn.br/imagens/marilia_de_dirceu.jpg', // URL com a capa do livro
'imagem_lombada' => '',
'imagem_quarta_capa' => '',
);
Resposta
Não há teste disponível para adição de novo livro. Desculpe! Mas veja abaixo um exemplo de resposta de livro adicionado com sucesso.
{
"message":{
"message": "Registro cadastrado com sucesso. Aguardando análise e liberação da nossa equipe.",
"date_time_log":"2016-07-21 19:13:13" //horário que o livro foi recebido pelo nosso sistema.
},
"status_code":"200",
"status":"ok"
}
#Atualizar livro
Assim como a adição de livros, a atualização também requer autenticação, e só pode ser feita pela própria editora.
É necessário também enviar junto à URL da requisição, o ISBN do livro que será editado. Exemplo abaixo:
Modelo de requisição POST
Sandbox: https://sandbox.bookinfometadados.com.br/api/v1.2/book/edit/<isbn-do-livro-a-ser-alterado>
Production: https://api.bookinfometadados.com.br/api/v1.2/book/edit/<isbn-do-livro-a-ser-alterado>
Os campos a serem editados são os mesmos do método de cadastro do livro, porém a diferênça é que não é necessário enviar todos novamente e sim apenas os que serão alterados.
Resposta
Mensagem que o sistema retorna ao atualizar um livro.
{
"isbn": "9788528617931",
"book_url": "<URL-DO-LIVRO-NO-SISTEMA>",
"update_status": "Metadados atualizados com sucesso",
"date": "2017-11-16 19:11:24",
"status": "ok"
}