Programa de afiliados - descripción técnica
Aquí encontrrá información acerca de la implementación del programa de afiliados de terralibro.com en el diseño de su página web.
Por favor dirija cualquier pregunta a db.dev@terralibro.com.
Qué es el programa de afiliados de terralibro.com?
- Permite la consulta de los resultados de búsqueda de terralibro.com en formato XML o CSV.
- Con ello es posible representar en su propia página los datos de libros de terralibro.com en su diseño y ofrecer un link de pedido directo.
- Ejemmplo de como se muestran los resultados (ISO-8859-1 set de caracteres)
- Ejemlo de como se muestran los resultados (UTF-8 set de caracteres)
- Umsetzungsbeispiel
Su ganancia
- Usted aprovecha la inmensa velocidad de búsqueda de terralibro.com
- Usted se beneficia de más de 200 milliones de títulos en los que busca terralibro.com.
- Usted gana comisión con cada título que se venda a través de su página y terralibro.com.
- Usted puede editar los datos que recibe de terralibro.com de manera libre y agregar servicios no disponibles en terralibro.com.
Qué tiene que hacer?
- Para que se muestren los resultados de terralibro.com en su página, su programador tiene que escribir un programa que lea nuestros datos por XML o CSV.
- Esta programación no es más complicada que la búsqueda y representación de los resultados en su página (si ya lo ofrece).
La programación no es demasiado compleja. - Nosotros le ofrecemos a su programador aquí en estas páginas, algunas recomendaciones y códigos fuente (en el lenguaje PHP), que facilitan considerablemente la programación en este lenguaje.
Por favor dirija cualquier pregunta o consulta a db.dev@terralibro.com. - Más abajo encontrará un programa más sencillo y uno más complejo; puede bajar ambos programas como download. Con ello puede integrar una búsqueda de manera muy sencilla directamente en su página web. Estos programas muestra pueden ser modificados ligeramente por su programador, para que se adapten a sus necesidades funcionales y de diseño.
Como funciona esto?
- Usted nos pide un nombre de usuario y una contraseña para el programa de afiliados.
- Lo prueba llamando la URL de búsqueda en nuestra página (ver abajo).
- Su programador lee las páginas correspondientes y usted implementa la búsqueda de acuerdo a sus deseos.
- Fertig.
- Registro al programa de afiliados..
- Ejemplo de implementación
- Herramientas para download en archivo ZIP (3KB)
Por favor dirija consultas y preguntas técnicas a db.dev@terralibro.com.
Información para programadores
Utilizamos los siguientes términos:
- Página de afiliado: Página web de nuestro afiliado a terralibro.com, es decir su página o la página que como programador quiere integrar como afiliada.
- Plataformas: Son plataformas que proveen con datos de libros a terralibro (p.e. amazon, abebooks, alibros, antbo, booklooker, iberlibro, etc.)
- Usuario: es el usuario de su página web (afiliado de terralibro.com), que por ejemplo busca un libro e ingresa sus datos de búsqueda esperando ver resultados en su página
Qué tengo que hacer?
La única dirección central es la URL:
https://www.terralibro.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
Si accede a esta URL en su buscador de internet (p.e. IE, Safari, Firefox) - el nombre de usuario y la contraseña la obtiene de nosotros o del afiliado- y en
Aquí ve resultados en formato XML (más información del formato XML https://www.w3c.org/XML/) para los criterios de búsqueda autor "Holl" y título "Jesus". Si aún no tiene experiencia con el formato XML, no se deje confundor por muchos de los detalles en w3c.org , en realidad no es para nada tan complejo como aparenta. Si utiliza el lenguaje de programción PHP en su páaina web, entonces puede utilizar el analizador sintáctico "XML-Parser" contenido en el programa para leer nuestros datos en formato XML. Otros programas de programación (Perl, Phyton, ASP etc.) también tienen XML-Parser integrados, que le aligeran considerablemente el trabajo y transmiten los datos que le entregamos ya las variables correspondientes. Los resultados están en el formato ISO-8859-1 (Westeuropa, latin1) del set de caracteres. Con "&format=xml8" puede convertir el formato a UTF-8. En este caso también los datos transmitidos (autor, título, …) deben ser codificados en UTF-8 ! Si no se siente confortable con el formato XML-Format (que nosotros recomendamos), puede consultar los datos en formato CSV, cambiando simplemente al final "&format=xml" por "&format=csv". Eso se va más o menos así (cambios de renglón con un espacio en blanco por delante agregados para facilitar la lectura):
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.terralibro.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.terralibro.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 ...
Se transmiten exactamente los mismos datos que en el formato XML, sólo que por renglón se representa un libro y cada campo es separado por "~||~".
Los siguientes datos se encuentran en el archivo XML (o CSV):
- id: Es un número de libro único en nuestra base de datos. Este número es v´ḹido por aproximadamente 3 horas,después el número es borrado de nuestra base de datos.
- author: autor del libro
- title: título del libro
- comment: Comentario/texto de descripción del libro, puede llegar a ser muy largo.
- isbn: número ISBN del libro, puede estar en blanco, entonces no se indica esta característica.
- year: año de publicación
- price: precio del libro
- currency: divisa en la que se indica el precio del libro.
- priceeur: precio convertido en Euro en caso de que la divisa no sea "EUR", calculamos el "priceeur" con el tipo de cambio del día. De algunas plataformas obtenemos los precios p.e. en US$, lo convertimos en EUR con el tipo de cambio diario. En este caso el precio en EUro es un aproximado.
- country: Lugar en donde el libro se encuentra fisicamente. Lo indicamos con abreviaciones para los paises (p.e. "D" para Alemania, "A" para Austria, etc.). Estas abreviaciones no siempre son exactas, ya que algunas plataformas no proporcionan el dato correspondiente o no lo saben.
- dealer: nombre del ofertante/vendedor. Con algunas plataformas este campo puede estar vacío o idéntico con el nombre de la plataforma.
- url: es la URL, en donde se pide el libro o donde se pueden ver más detalles de éste. El link proporcionado aquí es válido por aproximadamente 3 horas,después de este tiempo el libro es borrado de nuestra base de datos y el link ya no funciona.
- picurl: link a una imagen previa (puede estar en blanco o no disponible). La imagen previa es por lo general tan pequeña que se muestra con el resultado. El ink por lo general no lleva a una página de terralibro.com sino a la plataforma ofertante de donde viene el libro.
- paperback: valor si/no (0=no, 1= si), si el libro es de pasta blanda o no.
- hardcover: valor si/no (0=no, 1= si), si el libro es de pasta dura o no.
- signed: valor si/no (0=no, 1= si), si el libro está autografiado o no.
- firstedition: valor si/no (0=no, 1= si), si el libro es una primera edición o no.
- platform: nombre de la plataforma , de la que obtenemos los datos de los libros.
Por favor sonsidere que en el futuro podemos expander tanto el formatos XML como el CSV. En el formato XML se pueden agregar características adicionales, con el formato CSVse pueden añadir campos al final del renglón. Sus programas deben de estar diseñados de tal manera que se puedan adaptar a ello ya que de lo contrario a lo mejor ya no funcionen en el futuro.
La "id" representa un caso especial, que en el formato CSV-Format se presenta en el primer renglón, o en el formato XML como característica de "ResultList". La ID transmitida aquí denomina inequívocamente la búsqueda pasada a terralibro.com,nosotros la definimos como "Such-ID".
Como programador por favor implemete los siguientes pasos:
- Usted elabora un formulario de búsqueda que se más o menos corresponde con nnuestro formulario (campos para autor/título/palabra clave e ISBN). El diseño del formulario lo puede decidir usted mismo.
- Postula el formulario en una página de resultados.
- En esta página llama a nuestra URL (extquery.php) y transmite como parámetros valores de búsqueda de algún usuario.
- Con el analizador sintáctico (parse) lee nustros resultados y los escribe en su base de datos (p.e. en la base de datos libre mySQL). Se anota la identificación de búsqueda "Such-ID", también en la base de datos para que si vuelve a consultar los resultados (p.e. al hojear las páginas) no tenga que llamar a terralibro.com de nuevo, sino mostrar los datos almacenados temporalmente en su base de datos. Estos resultados guardados temporalmente los puede clasificar y mostrar a su libre albedrío.
- Después de un tiempo (a más tardar a las 3 horas) borra los datos guardados temporalmente.
Por favor considere que no es conveniente llamar a extquery.php cada vez que establezca una página ya que tiene como consecuencia que cada vez genera una nueva búsqueda con una nueva identificación Such-ID (y con ello completamente diferentes ID de libros). Tampoco podemos garantizar que los resultados sean los mismos cada vez que llame extquery.php o que se presenten en el mismo orden, ya que eso depende entre otros factores de la velocidad de respuesta de las plataformas (y son muchas). Con ello también es mucho más difícil tener una vista general del desarrollo de búsquedas y pedidos (clicks), que es algo en lo que nos fijamos y con ello puede disminuir su comisión de venta. Una llamada de extquery.php debe por lo tanto de corresponder con una búsqueda en específico.
Para los siguientes problemas le ofrecemos soluciones básicas en el lenguaje de programación PHP:
PHP tiene un XML-Parser integrado (veahttp://www.php.net/manual/de/ref.xml.php)
Es muy fácil
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.terralibro.com/extreq/meta/extquery.php?platform=test&password=test".
"&author=holl&title=jesus&clientip=".$_SERVER["REMOTE_ADDR"]."&format=xml");
Con este corto programa puede representar los resultados de búsqueda en una "salchicha". Con el nombre de usuario/contraseña "test" puede ejecutar pruebas; para este usuario no se paga comisión.
En su caso es conveniente que en vez de elegir "print" en "xml_startElement()" simplemente escriba los datos en su base de datos. Como ya mencionamos anteriormente la función "parseURL" sólo se debería utilizar UNA vez por búsqueda, es decir usted anota/memoriza al hojear los resultados la "SUCH-ID" y si esta identificación ya está disponible, extrae los resultados de su base de datos, de lo contrario llama a nuestro servidor y escribe los resultados en su base de datos.
Si ingresa parámetros de búsqueda en extquery.php provenientes del formulario de búsqueda, no olvide adaptarlos al formato HTML, es decir "…author=".rawurlencode($author)."&title=".rawurlencode($title)."&...".
Si en su página de internet no tiene disponible una base de datos o prefiere evitar el trabajo de programación y guardar los datos en una base de datos pero no quiere renunciar a la posibilidad de clasificar los resultados y mostrarlos en varias páginas,entonces puede utilizar nuestra "extquery.php". Puede llamar extquery.php alternativamente (después del primer llamado con autor/título, etc.) con su ID de búsqueda, y con ello tiene la posibilidad de clasificar y delimitar los resultados.
https://www.terralibro.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
- Such-ID: Ingrese aquí la ID de búsqueda retornada.
- start: Ingrese el número de libro (numerado empezando por el 1), a partir del cuál quiere tener la respuesta en formato XML o CSV.
- end: Ingrese el número de libro (nuemrado a partir del 1, este libro ya NO está contenido en los resultados) hasta el cuál quiere recibir los resultados en formato XML o CSV.
- order: Si no indica nada se clasificará de acuerdo a como vayan entrando los resultados. Otros valores son "author", "title" y "price". Con ello se clasificará de acuerdo a dichos criterios.
- platform: su nombre de usuario.
- password: su contraseña.
- author: autor (o intéprete) buscado.
- title: título buscado
- search: palabra clave/todo el texto.
- isbn: número ISBN o EAN.
- mediatype: 0 para libros, 1 para música.
- suchid: Ingrese aquí la ID de búsqueda retornada.
- start: Ingrese el número de libro (numerado empezando por el 1), a partir del cuál quiere tener la respuesta en formato XML o CSV.
- end: Ingrese el número de libro (nuemrado a partir del 1, este libro ya NO está contenido en los resultados) hasta el cuál quiere recibir los resultados en formato XML o CSV.
- order: Si no indica nada se clasificará de acuerdo a como vayan entrando los resultados. Otros valores son "author", "title" y "price". Con ello se clasificará de acuerdo a dichos criterios.
- clientip: Ingrese aquí la dirección de IP del cliente que busca el libro. Si no indica nada entonces no se transmitirán resultados. El ingreso de "-" causa que se utilice la dirección de IP del servidor que directamente ejecuta la búsquedas y que sea idéntica a la dirección de IP del cliente final. Por favor considere que para evitar búsquedas de avalancha la dirección de IP del cliente es decisiva. Si siempre se puede asumir la dirección de IP de su servidor esto resultará en un cantidad relativamente reducida de solicitudes a terralibro.com. Por eso recomendamos que siempre nos indique la dirección de IP del consumidor final.
- format: xml para el formato XML con ISO-8859-1 set de caracteres, xml8 para formato XML con UTF-8 set de caracteres, csv para formato CSV (ISO-8859-1 set de caracteres).
El programa ejemplo/muestra consiste de dos archivos PHP, el formulario (search.php) y la página de resultados (result.php). Como prueba puede invocar el formulario hier. El código fuente está disponible para su download en un archivo ZIP (3KB).
El programa muestra viene sin base de datos y soporta el ingreso de todos los criterios de búsqueda asi como la emisión de los resultados por página y la clasificación por los diversos criterios de búsqueda.
Nosotros enviamos los resultados, tan pronto los recibimos de las platafomras asociadas. Es decir, es posible que reciba una cierta cantidad de resultados, luego no reciba nada por un tiempo porque ninguna plataforma envía resultados), y luego vuelva a recibir algunos resultados o a lo mejor no, dependiendo de las plataformas. Por ello posiblemente haga sentido que de su parte, escriba los resultados en su base de datos en un procedimiento y los lea con otro, o al menos establezca n periodo de espera. Esto es fácil de aplicar si el escribir de los resultados lo ejecuta en un HTML-FRAME o IFRAME muy pequeño y despliega los resultados en otro Frame.
Por favor tome nota que debido a la transmisión asíncrona los resultados deben ser mostrados en su página el momento que llegan, o sea de inmediato. Para ello debe de considerar lo siguiente:
- El analizador sintáctico XML-Parser debe de escribir los datos ya sea en la base de datos o emitirlos inmediatamente.
- Los resultados/datos deben de terminar en un
flush();(en PHP; otros lenguajes de programación tienen algo parecido), para que sean transmitidos inmediatamente al buscador/browser del cliente - Tablas apenas son representadas, cuando la tabla ha sido configurada
</table>en su totalidad. Es decir cuando un libro queda registrado en un renglón de la tabla, hace sentido que para cada renglón (o sea para cada libro) se genere una propia tabla para completar dicha tabla original.
Por favor dirija sus preguntas técnicas a db.dev@terralibro.com.