registe-se
Dica do terralivro.com
Atualidades

Descrição técnica do Programa de Afiliação

Aqui encontra informações para a instalação do Programa de Afiliação de terralivro.com no design do seu website.
Para pedidos de informação por favor db.dev@terralivro.com.

Qual é o Programa de Afiliação do terralivro.com ?
O seu lucro
  • Beneficie da velocidade de procura do terralivro.com
  • Beneficie de atualmente 150 milhões de livros revistos, que constam no Terralivro.com.
  • Beneficie até 30% da quota do volume de vendas dos livros vendidos.
  • Pode continuar a processar os dados dos livros do Terralivro.com e ainda oferecer aos utilizadores serviços adicionais que não existem no Terralivro.com .
O que deve fazer?
  • Para poder ver os resultados de procura do Terralivro.com no seu site, o seu programador do website terá de escrever um programa que aceda aos nossos dados dos livros por XML ou CSV.
  • Esta programação não é mais trabalhosa (normalmente menos)do que a procura e apresentação dos resultados de procura nos seus próprios dados no seu website (no caso de já oferecer).
    A programação em geral não é muito trabalhosa..
  • Disponibilizamos aqui, neste site, ao seu programador dicas e fragmentos do código fonte (da linguagem de programação PHP), simplificando a programação desta consulta.
    Pedidos de informação dirige por favor àdb.dev@terralivro.com.
  • Mais em baixo encontra-se um exemplo de um programa mais simples e um programa um pouco mais complexo disponibilizado também para download. Com isso pode integrar facilmente uma procura directamente no seu site. Estes exemplos programadas podem ser modificados facilmente pelo seu programador, para satisfazer as seus exigências de layout e funcionalidade.
Como funciona?
  • Pede um nome de utilizador e uma palavra-passe para o Programa de Afiliação.
  • Teste-se chamando a consulta de URL no nosso site (ver em baixo ).
  • O seu programador consulta estas páginas implementando a procura conforme desejar.
  • pronto.

Para pedidos de informação técnica, por favor dirija-se ao db.dev@terralivro.com.

Informações para o seu programador
Nós utilizamos os seguintes termos:
  • Site dos Afiliados: site dos nossos afiliados de Terralivro.com,i.e. o seu site ou o site para o qual deseja integrar a procura como programador.
  • Plataformas de livros: são sites que disponibilizam os dados dos seus livros ao Terralivro.com (p.ex. Amazon, Antbo, Booklooker, Abebooks etc.)
  • Utilizador: é o utilizador do site dos Afiliados, que procura por exemplo um livro introduzindo os dados para poder ver os resultados
O que devo fazer?

Único sítio central é o endereço URL seguinte:

https://www.terralivro.com/extreq/meta/extquery.php?platform=<Your Username>&
password=<Your Password>&author=<Autor>&title=<Titel>
&search=<Schluesselwort>&isbn=<ISBN>&&mediatype=0&clientip=<Enduser-IP-Adresse>&format=xml

No caso de chamar este endereço URL num browser (por exemplo IE) (nome de utilizador, palavra-passe serão comunicadas por nós ou pelo afiliado), indicando no campo de por exemplo "Holl", no "Jesus" e os outros parâmetros vazios(ou omite), receberá então, por exemplo, o resultado seguinte(os parêntesis agudos são parte do parâmetro e não constam mais no URL!):

<?xml version="1.0" encoding="ISO-8859-1" ?>
  <!DOCTYPE ResultList (View Source for full doctype...)>
- <ResultList id="23291123">
  <Book id="16048251" author="Holl, Adolf" title="Jesus in schlechter Gesellschaft" comment="Wien : Buchgemeinschaft Donauland; Stuttgart : Europ. Bildungsgemeinschaft; [1972]; 21 cm; 215 S.; Aufl.: Lizenzausgabe; Leinen, Schutzumschlag, gut;" year="1972" price="8.00" currency="EUR" priceeur="8.00" country="A" dealer="SFB1050" url="https://www.terralivro.com/extreq/meta/bestellung.php?qid=16048251" platform="Booklooker.de" />
  <Book id="16048253" author="Holl, Adolf" title="Jesus in schlechter Gesellschaft. (Was Menschen bewegt)." comment="190 S. 21,5 cm. Gebunden. 318gr. Kreuz," isbn="3783118166" price="7.45" currency="EUR" priceeur="7.45" country="D" dealer="Laetare Büchermarkt" url="https://www.terralivro.com/extreq/meta/bestellung.php?qid=16048253" picurl="https://www.booklooker.de/images/cover/user_thumb/0309/0803/bl1060.jpg" hardcover="1" platform="Booklooker.de" />
  <Book id="16048254" author="Holl, Adolf" title="Jesus in schlechter Gesellschaft" comment="Name auf Vorsatz, sehr guter Zustand #e5Leinen, Deutsche Verlags-Anstalt, 1971," year="1971" price="5.00" currency="EUR" priceeur="5.00" country="D" dealer="Bücher-Bezzel" url="https://www.terralivro.com/extreq/meta/bestellung.php?qid=16048254" platform="Booklooker.de" />

Aqui existe um exemplo em XML (para informação mais detalhada acerca do formato XML consulte https://www.w3c.org/XML/) dos resultados da procura que o Terralivro.com encontrou para o autor "Holl" e título "Jesus". Caso não possua nenhuma experiência com o formato XML, não se deixe confundir com as várias indicações em w3c.org, não é de forma alguma tão complicado como parece. No caso de utilizar a língua de programação PHP no website, poderá utilizar o parser XML, implementado em PHP, para poder ler o nosso output em XML. Outras línguas de programação (Perl, Phyton, ASP etc.)também possuem parsers implementados em XML, facilitando a maioria do trabalho de transferência dos dados, uma vez que nós transferimos com as variáveis respetivas. O output é apresentado em ISO-8859-1 (Westeuropa, latin1) caracteres. Com "&format=xml8" pode apresentar os dados nos caracteres internacionais UTF-8. Neste caso, também os dados transferidos de (autor, título, ...)devem ser codificados em caracteres UTF-8! No caso de não gostar do formato XML(o qual aconselhamos), poderá consultar os dados por CSV, indicando no fim em vez de "&format=xml" simplesmente "&format=csv". O resultado aparece da seguinte maneira: (para melhor legibilidade, quebras de linha são inseridas com espaço precedido):

231932123
16079133 ~||~ Holl, Adolf ~||~ Jesus in schlechter Gesellschaft ~||~
 Wien : Buchgemeinschaft Donauland; Stuttgart :  Europ. Bildungsgemeinschaft;
 [1972]; 21 cm; 215 S.; Aufl.: Lizenzausgabe; Leinen, Schutzumschlag, gut; ~||~ ~||~
 1972 ~||~ 8.00 ~||~ EUR ~||~ 8.00 ~||~ A ~||~ SFB1050 ~||~
 https://www.terralivro.com/extreq/meta/bestellung.php?qid=16079133 ~||~ ~||~ ~||~ ~||~ ~||~ ~||~
 Booklooker.de
16079134 ~||~ Holl, Adolf ~||~ Jesus in schlechter Gesellschaft. (Was Menschen bewegt). ~||~
 190 S. 21,5 cm. Gebunden. 318gr. Kreuz, ~||~ 3783118166 ~||~ 0 ~||~ 7.45 ~||~ EUR ~||~
 7.45 ~||~ D ~||~ Laetare Büchermarkt ~||~
 https://www.terralivro.com/extreq/meta/bestellung.php?qid=16079134 ~||~
 https://www.booklooker.de/images/cover/user_thumb/0309/0803/bl1060.jpg ~||~
 0 ~||~ 1 ~||~ 0 ~||~ 0 ~||~ Booklooker.de
...

São entregues exactamente os mesmos dados como no formato XML. Por livro é indicada apenas uma linha e cada campo é separado por "~||~".

Os seguintes dados são indicados no ficheiro XML (ou CSV):

  • id: É um número determinado do livro no nosso banco de dados. Este número fica válido durante aproximadamente três horas, a seguir o livro é eliminado do nosso banco de dados.
  • author: autor do livro
  • title: título do livro
  • comment: texto de comentário referente ao livro. Pode eventualmente ser muito comprido.
  • isbn: número ISBN do livro, também pode ser vazio, neste caso o atributo não é indicado.
  • year: Ano de publicação
  • price: Preço do livro
  • currency: Moeda, na qual o "preço" é indicado.
  • priceeur: Preço do livro, convertido em EUR. No caso da moeda não ser "EUR", convertemos o "priceeur" em Euro segundo o câmbio actual do dia. Recebemos de algumas plataformas de livros o preço do livro por exemplo em US$, convertendo-o em EUR segundo o cambio atual do dia. Neste caso, o preço indicado em Euro, é um preço aproximado.
  • country: País, no qual se encontra fisicamente o livro. Indicamos códigos abreviados para os países (p.ex. "D" para Alemanha, "A" para Áustria, etc.). Estes códigos abreviados podem não ser sempre correctos, porque algumas plataformas de livros não indicam esta informação,ou não tem conhecimento.
  • dealer: Nome do comerciante. No caso de algumas plataformas de livros, esta informação pode faltar ou ser idêntica ao nome da plataforma.
  • url:É o endereço URL, com o qual o livro pode ser encomendado ou consultado mais detalhadamente (detalhes). O link indicado é válido durante aproximadamente três horas, a seguir o livro respectivo será eliminado do nosso banco de dados, e o link não funciona mais.
  • picurl: Link para uma imagem de pré-visualização(também pode ser vazio /não indicado). A imagem de pré-visualização é normalmente tão pequena, que pode ser indicada na lista do livro. O link normalmente não leva a plataforma Terralivro.com, mas a um servidor da plataforma, de onde vem o livro.
  • paperback: Valor de Sim/Não (0=Não, 1= Sim), indicando se o livro é um livro de bolso ou não.
  • hardcover: Valor de Sim/Não (0=Não, 1= Sim), indicando se o livro é encadernado ou não.
  • signed: Valor de Sim/Não (0=Não, 1= Sim), indicando se o livro é autografado ou não.
  • firstedition: Valor de Sim/Não (0=Não, 1= Sim), indicando se o livro é uma primeira edição ou não.
  • platform: nome da plataforma da qual recebemos os dados do livro.

Tenha em atenção que no futuro poderemos aumentar tanto o formato XML como o formato CSV. No formato XML serão eventualmente acrescentados atributos adicionais, no formato CSV serão eventualmente adicionados campos no fim da linha. Os seus programas deverão ser capazes de gerir estas informações, caso contrário poderão deixar de funcionar no futuro.

O "id" representa um caso especial, passado no formato CSV na primeira linha ou em caso de formato XML como atributo da "ResultList". O ID passado indica claramente uma procura transferida para o Eurobuch, designado-a como "ID de procura".

O que faço com os dados no formato em CSV ou XML?

Como programador, proceda da maneira seguinte:

  • Elabore um formulário de pesquisa que corresponda aproximadamente ao nosso formulário de pesquisa (campos para autor/título/palavra-passe e IBSN). Poderá determinar como quiser o layout do formulário.
  • Envie o formulário numa página de resultados.
  • Nesta página de resultados chame o nosso URL (extquery.php) e passe como parâmetro os valores indicados pelo utilizador no formulário de procura.
  • Processe a nossa página de resultados e insira os resultados num banco de dados (e.g. em mySQL, gratuitamente disponível). Lembre-se do "ID de procura",também no banco de dados para poder, no caso de uma nova chamada da página dos resultados (p.ex. no caso de folhear), não procurar de novo em Terralivro.com, mas indicar os resultados, guardados temporariamente na base de dados. Estes resultados, guardados temporariamente, podem ser organizados e visualizados segundo os seus critérios.
  • Após um certo tempo(depois três horas ao máximo) elimine os resultados da procura, guardados temporariamente na base de dados.

Por favor tenha em atenção de não chamar constantemente a nossa consulta (extquery.php) em cada carregamento de página de uma consulta. A consequência é receber um novo ID de procura (e consequentemente um ID completamente novo do livro). Não podemos garantir que os resultados de cada chamada de extquery.php sigam na mesma sequência, dependendo da velocidade dos servidores implicados (sendo muitos, entre outros os das plataformas dos livros). Isso resulta numa pior quota de cliques de encomenda em relação à de procura o que notamos reduzindo a participação nos lucros do website do Afiliado no nosso website.Uma chamada extquery.php tem de corresponder a uma procura sua.

Para os seguintes problemas oferecemos aqui soluções rudimentares na língua de programação PHP:

Interpretar os resultados no formato XML

PHP tem um parser XML incorporado(ver http://www.php.net/manual/de/ref.xml.php)

Pode-se facilmente

function xml_startElement($parser, $name, $attrs)
{
	if($name=="RESULTLIST") {
		print "SUCH-ID: ".$attrs["ID"]."<br><hr>";
	} else if($name=="BOOK") {
		print "ID: ".$attrs["ID"]."<br>";
		print "Autor: ".$attrs["AUTHOR"]."<br>";
		print "Titel: ".$attrs["TITLE"]."<br>";
		print "<a href='".$attrs["URL"]."' target='_blank'>Bestellen</a><br><hr>";
		flush();
	}
}
function xml_endElement($parser, $name)
{
}
function parseURL($url) {
	$fp=fopen($url,"rb");
	if(!$fp) {
		return("Could not open $url");
	}
	$xml_parser = xml_parser_create();
	xml_set_element_handler($xml_parser, "xml_startElement", "xml_endElement");
	while($data=fread($fp,4096)) {
		if (!xml_parse($xml_parser, $data,feof($fp))) {
		   $ret=sprintf("XML error: %s at line %d",
					   xml_error_string(xml_get_error_code($xml_parser)),
					   xml_get_current_line_number($xml_parser));
			xml_parser_free($xml_parser);
			return($ret);
		}
	}
	xml_parser_free($xml_parser);
	fclose($fp);
	return(false);
}
parseURL("https://www.terralivro.com/extreq/meta/extquery.php?platform=test&password=test".
"&author=holl&title=jesus&clientip=".$_SERVER["REMOTE_ADDR"]."&format=xml");

Com este programa curto poderá apresentar já resultados da procura numa forma de salsicha. Com o nome de utilizador/palavra-passe "test", poderá fazer testes, sem que sejam pagas comissões para este utilizador.

No seu caso deveria escrever os dados simplesmente na sua base de dados, em vez do output via "print" em "xml_startElement()". Como já mencionado, a chamada de "parseURL" deve ser efetuada só uma vez por busca, i.e folhando, por favor lembrar do "ID de procura" e no caso de já existir, obtenha os resultados da base de dados, contrariamente chame nos e escreve os resultados na base de dados.

No caso de obter os parâmetros para extquery.php provenientes de um formato de procura fornecido pelo utilizador, não o esqueça de citar, segundo o formato de HTLM, i.e. "...author=".rawurlencode($author)."&title=".rawurlencode($title)."&...".

Seleção e subdivisão de páginas

No caso de não ter nenhuma base de dados disponível no seu servidor Web, ou de querer evitar a programação para guardar a informação numa base de dados, não querendo prescindir de características como selecção e subdivisão de páginas, extquery.php apoia onde for possível. Poderá alternativamente chamar extquery.php (após a primeira chamada com autor/título etc.) com o ID de procura, seleccionando os resultados e limitando segundo os títulos dos livros.

https://www.terralivro.com/extreq/meta/extquery.php?platform=<Ihr Username>
&password=<Ihr Passwort>&suchid=<Such-ID>&start=<Start>&end=<End>
&order=<Order>&clientip=<Enduser-IP-Adresse>&format=xml
  • ID de procura: Indique aqui o ID de procura devolvido.
  • Inicio: Indique o número do livro (numerando partindo de 1), a partir do qual quer o output em formato XML ou CSV.
  • Fim: Indique o número do livro (numerando partindo de 1, este livro não consta mais) até o qual quer o output em formato XML ou CSV.
  • Sequência: não é indicada, a organização resulta da sequência de chegada. Outros valores são "autor", "título" e "preço". A seguir, a organização segue os critérios respectivos.
Quais os parâmetros apoiados pelo extquery.php?
  • plataforma: Seu nome de utilizador.
  • palavra-passe: Sua palavra-passe.
  • autor: autor procurado(ou interprete).
  • título: Título procurado.
  • procura:procura de texto.
  • isbn: número ISBN ou EAN.
  • mediatype: 0 para livros, 1 para música.
  • suchid: indique aqui o respectivo ID de procura.
  • start: indique o número do livro (numerado, partindo de 1), a partir do qual quer o output em formato XML ou CSV.
  • end: indique o número do livro(numerado, partindo de 1), este livro não consta mais) até o qual quer o output em formato XML ou CSV..
  • order: não é indicado, sendo organizado segundo a sequência de chegada. Outros valores são "autor", "título" e "preço". A seguir, a organização segue os respectivos critérios.
  • clientip: indique aqui o endereço IP do utilizador final da consulta. No caso de não ser indicado, nenhuns resultados de procura serão transmitidos. A indicação de "-" faz com que o endereço do computador consultante é idêntico ao do utilizador final. No entanto tome em consideração que o endereço ID do utilizador,Client-IP, é decisivo para impedir pedidos de procura como avalanche. Será sempre suposto o do seu servidor,resultando num número relativamente pequeno de consultas possíveis para Terralivro.com. Consequentemente, participe-nos sempre o endereço do utilizador final, Enduser-IP-Adresse.
  • format: xml para formato XML em carateres ISO-8859-1 , xml8 para formato XML em carateres UTF-8 , csv para formato CSV carateres (ISO-8859-1).
Programa modelo

O programa modelo consiste em dois ficheiros PHP, o formulário (search.php) e a página de resultados (result.php). A título de teste, pode chamar o formulário aqui. O código de fonte encontra-se disponível para download num arquivo ZIP(3KB).

O programa modelo não necessita de nenhuma base de dados e apoia a introdução de todos os critérios de procura tal como o output dos resultados por página e a seleção segundo critérios de organização diversos.

Transmissão assíncrono

Enviamos os resultados logo após receção das plataformas de livros. Poderá receber uma série de resultados, sendo que em seguida deixará de receber durante um certo tempo (porque nenhuma plataforma fornece resultados) e depois voltará a receber ou então não receberá mais nenhum até ao fim. Por isso faria sentido para o utilizador de escrever os resultados com a ajuda de um processo na base de dados, de os ler com um outro ou de fazer pelo menos um aviso de espera. Pode faze-lo facilmente, escrevendo os resultados num pequeníssimo HTML-FRAME ou IFRAME, e a indicação num outro Frame.

Note ainda por favor que, devido a esta transmissão assíncrona, os resultados no seu website deveriam estar representados logo após recebimento, i.e. imediatamente, respeitando o seguinte:

  • O parser XML tem de escrever os resultados numa base de dados ou fornecer-los imediatamente.
  • O output tem de ser terminado com flush(); (em PHP, outras língua de programação tem exigências similares), para ser imediatamente transferido para o Client-Browser
  • Pela maioria dos browser, tabelas são representas, quando a tabela é terminada por </table>. Se um livro é representado numa linha de tabela, faz todo o sentido, de fazer uma tabela própria para cada linha de tabela (consequentemente por livro) e de terminar esta tabela.
Implementações de referência

Pedidos de informação técnica dirige por favor a db.dev@terralivro.com.