Introdução

A API do MercadoEditorial.org 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.mercadoeditorial.org, e apenas após completar a integração, deve-se apontar para a URL de produção, https://api.mercadoeditorial.org.

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 do MercadoEditorial.org.

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>,
            },
            
        

Paginação

Agora na versão 1.2 da API do MercadoEditorial.org, 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.mercadoeditorial.org/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
            },
            
        

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.mercadoeditorial.org/api/v1.2/book?isbn=<ISBN>&titulo=<título-da-obra>

Production: https://api.mercadoeditorial.org/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.mercadoeditorial.org/api/v1.2/book

Production: https://api.mercadoeditorial.org/api/v1.2/book

#Requisição por ISBN

Parâmetros

Modelo de requisição GET

Sandbox: https://sandbox.mercadoeditorial.org/api/v1.2/book?isbn=<ISBN>

Production: https://api.mercadoeditorial.org/api/v1.2/book?isbn=<ISBN>

Resposta

                
                "contribuicao": [
                {
                    "nome": "Machado de",
                    "sobrenome": "Assis",
                    "tipo_de_contribuicao": "Autor",
                    "codigo_contribuicao": 1
                },
                
            

                    "classificacao_indicativa": 2
                

                    "status": 2,
                

                    "faixa_etaria": 1,
                

                "encadernacao": 1
            

#Requisição por Título

Parâmetros

Modelo de requisição GET

Sandbox: https://sandbox.mercadoeditorial.org/api/v1.2/book?titulo=<título-da-obra>

Production: https://api.mercadoeditorial.org/api/v1.2/book?titulo=<título-da-obra>

Resposta

                
                "contribuicao": [
                {
                    "nome": "Machado de",
                    "sobrenome": "Assis",
                    "tipo_de_contribuicao": "Autor",
                    "codigo_contribuicao": 1
                },
                
            

                    "classificacao_indicativa": 2
                

                    "status": 2,
                

                    "faixa_etaria": 1,
                

                "encadernacao": 1
            

#Requisição por Contribuição (Autores e Colaboradores)

Parâmetros

Modelo de requisição GET

Sandbox: https://sandbox.mercadoeditorial.org/api/v1.2/book?contribuicao=<nome-de-contribuição>

Production: https://api.mercadoeditorial.org/api/v1.2/book?contribuicao=<nome-de-contribuição>

Resposta

                
                "contribuicao": [
                {
                    "nome": "Machado de",
                    "sobrenome": "Assis",
                    "tipo_de_contribuicao": "Autor",
                    "codigo_contribuicao": 1
                },
                
            

                    "classificacao_indicativa": 2
                

                    "status": 2,
                

                    "faixa_etaria": 1,
                

                "encadernacao": 1
            

#Requisição por Formato do livro (BOOK ou EBOOK)

Parâmetros

Modelo de requisição GET

Sandbox: https://sandbox.mercadoeditorial.org/api/v1.2/book?formato=<formato-do-livro>

Production: https://api.mercadoeditorial.org/api/v1.2/book?formato=<formato-do-livro>

Resposta

                
                "contribuicao": [
                {
                    "nome": "Machado de",
                    "sobrenome": "Assis",
                    "tipo_de_contribuicao": "Autor",
                    "codigo_contribuicao": 1
                },
                
            

                    "classificacao_indicativa": 2
                

                    "status": 2,
                

                    "faixa_etaria": 1,
                

                "encadernacao": 1
            

#Requisição por Status do livro

Parâmetros

Opções de Status

Modelo de requisição GET

Sandbox: https://sandbox.mercadoeditorial.org/api/v1.2/book?codigo_status=<codigo-do-status>

Production: https://api.mercadoeditorial.org/api/v1.2/book?codigo_status=<codigo-do-status>

Resposta

                
                "contribuicao": [
                {
                    "nome": "Machado de",
                    "sobrenome": "Assis",
                    "tipo_de_contribuicao": "Autor",
                    "codigo_contribuicao": 1
                },
                
            

                    "classificacao_indicativa": 2
                

                    "status": 2,
                

                    "faixa_etaria": 1,
                

                "encadernacao": 1
            

#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

Modelo de requisição GET

Sandbox: https://sandbox.mercadoeditorial.org/api/v1.2/book?<campo>=<codigo-ou-nome-da-editora>

Production: https://api.mercadoeditorial.org/api/v1.2/book?<campo>=<codigo-ou-nome-da-editora>

Resposta

                
                "contribuicao": [
                {
                    "nome": "Machado de",
                    "sobrenome": "Assis",
                    "tipo_de_contribuicao": "Autor",
                    "codigo_contribuicao": 1
                },
                
            

                    "classificacao_indicativa": 2
                

                    "status": 2,
                

                    "faixa_etaria": 1,
                

                "encadernacao": 1
            

#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

Modelo de requisição GET

Sandbox: https://sandbox.mercadoeditorial.org/api/v1.2/book?<campo>=<codigo-ou-nome-do-selo-editorial>

Production: https://api.mercadoeditorial.org/api/v1.2/book?<campo>=<codigo-ou-nome-do-selo-editorial>

Resposta

                
                "contribuicao": [
                {
                    "nome": "Machado de",
                    "sobrenome": "Assis",
                    "tipo_de_contribuicao": "Autor",
                    "codigo_contribuicao": 1
                },
                
            

                    "classificacao_indicativa": 2
                

                    "status": 2,
                

                    "faixa_etaria": 1,
                

                "encadernacao": 1
            

#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 MercadoEditorial.ORG 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

Modelo de requisição GET

Sandbox: https://sandbox.mercadoeditorial.org/api/v1.2/book?<campo>=<data>

Production: https://api.mercadoeditorial.org/api/v1.2/book?<campo>=<data>

Resposta

                
                "contribuicao": [
                {
                    "nome": "Machado de",
                    "sobrenome": "Assis",
                    "tipo_de_contribuicao": "Autor",
                    "codigo_contribuicao": 1
                },
                
            

                    "classificacao_indicativa": 2
                

                    "status": 2,
                

                    "faixa_etaria": 1,
                

                "encadernacao": 1
            

#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 no MercadoEditorial.org. 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 do MercadoEditorial.org, seguida do endpoint desejado.

Parâmetros

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.mercadoeditorial.org/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 MercadoEditorial.org enviará novamente todos os mesmos livros na próxima vez que a requisição for efetuada.

Modelo de requisição POST

Sandbox: https://sandbox.mercadoeditorial.org/api/v1.2/book/news/confirmation

Production: https://api.mercadoeditorial.org/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.mercadoeditorial.org/api/v1.2/company

Production: https://api.mercadoeditorial.org/api/v1.2/company

#Mostrar todas as editoras

Modelo de requisição GET

Sandbox: https://sandbox.mercadoeditorial.org/api/v1.2/company

Production: https://api.mercadoeditorial.org/api/v1.2/company

Resposta

#Requisição por Código da Editora

Parâmetros

Modelo de requisição GET

Sandbox: https://sandbox.mercadoeditorial.org/api/v1.2/company?codigo_editoras=<valor>

Production: https://api.mercadoeditorial.org/api/v1.2/company?codigo_editoras=<valor>

Resposta

#Requisição por Nome da Editora

Parâmetros

Modelo de requisição GET

Sandbox: https://sandbox.mercadoeditorial.org/api/v1.2/company?nome_fantasia_da_editora=<valor>

Production: https://api.mercadoeditorial.org/api/v1.2/company?nome_fantasia_da_editora=<valor>

Resposta

#Requisição por CNPJ da Editora

Parâmetros

Modelo de requisição GET

Sandbox: https://sandbox.mercadoeditorial.org/api/v1.2/company?cnpj=<valor>

Production: https://api.mercadoeditorial.org/api/v1.2/company?cnpj=<valor>

Resposta

#Requisição por Código do Selo Editorial

Parâmetros

Modelo de requisição GET

Sandbox: https://sandbox.mercadoeditorial.org/api/v1.2/company?codigo_selos=<valor>

Production: https://api.mercadoeditorial.org/api/v1.2/company?codigo_selos=<valor>

Resposta

#Notificação Automática

A Notificação Automática é a maneira mais simples de receber em seu sistema os novos livros publicados no MercadoEditorial.org. 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 do MercadoEditorial.org, não necessariamente apenas dos selos que seu usuário segue na plataforma.
ATENÇÃO: É necessário que essa URL esteja acessível ao MercadoEditorial.org, sem necessitar de Logins ou quaisquer outras autenticações.

Exemplo de dados enviados

Manipulação de Metadados

Os métodos abaixo mostrarão como é possível adicionar e editar livros da sua editora no MercadoEditorial.org.

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.mercadoeditorial.org/api/v1.2/book/add
Produção: https://api.mercadoeditorial.org/api/v1.2/book/add

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

	
{
    "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.mercadoeditorial.org/api/v1.2/book/edit/<isbn-do-livro-a-ser-alterado>

Production: https://api.mercadoeditorial.org/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

	
{
	"isbn": "9788528617931",
	"book_url": "<URL-DO-LIVRO-NO-MERCADOEDITORIAL.ORG>",
	"update_status": "Metadados atualizados com sucesso",
	"date": "2017-11-16 19:11:24",
	"status": "ok"
}