Servicio web (WebService)


Este documento está dirigido a libreros, editores o cualquier otro tipo de agente comercial que desee ofrecer la venta y descarga de libros digitales en la web.


Lista de servicios web

1. API de sincronización de catálogo.

1.1 Creación de archivos de actualización.

1.2 Recuperación de archivos XML u Onix.

1.3 Verificación de los metadatos de un libro digital.

2. API de venta y de descarga de un libro digital.

2.1 Simulación de venta.

2.2 Venta de un libro digital.

2.3 Descarga de un libro digital.

2.4 Anulación de una venta.

2.5 Venta anticipada o preventa.

2.6 Obtener el estado de una descarga


1. API de sincronización de catálogo

Los siguientes servicios web permiten la actualización cotidiana del catálogo de libros digitales, recuperando automáticamente todas las modificaciones efectuadas después de la última sincronización de la organización. Las actualizaciones se dividen en archivos que contienen un máximo de 50 libros digitales.


El conjunto de metadatos (ONIX) se entregaran siempre de forma completa (no se entrega una parte de los metadatos de un libro digital).


Ver la descripción de los especificaciones ONIX.


Pasos:

  1. Llamada WS Creación de archivos de actualización (1.1), recepción de la lista de URL, con archivos XML u Onix;

  2. Para cada URL de la lista, llamar a cada URL para descargar el archivo (1.2) y tratar su contenido.



1.1 Creación de archivos de actualización

Este servicio web crea en la plataforma Cantook los archivos XML u ONIX que sirven para actualizar el catálogo de las tiendas/bibliotecas.


Declaración

Dirección : /api/organisations/[organisation_id]/publications/lists

Formatos : xml, onix

Método : POST

Seguridad : HTTP/BASIC (nombre de usuario y contraseña)


Parámetros

organisation_id : Obligatorio

Número de organización. Ofrecido al inscribirse.


reset_at : Opcional

Fecha/Hora. Formato ISO 8601 Basic. Presente: devuelve todos los cambios realizados después de esta fecha/hora.Por omisión: devuelve los cambios realizados después de la primera invocación


format : Opcional

onix / xml - El valor por defecto es "xml".


Respuestas

201 : OK

0 a X url- El listado se ha creado correctamente. El cuerpo de la respuesta contendrá un vector de URL. Ver la descripción en la sección 1 y el servicio web 1.2.


401 : access_denied

Acceso al recurso denegado.


404 : not_found

No se ha podido encontrar la organización.

Nota: se ha invocado la URL con el método HTTP GET en vez de POST.


415 : invalid_format

El formato solicitado no es compatible.


415 : invalid_date

La fecha especificada en reset_at es incorrecta.



1.2 Recuperación de archivos XML u Onix

La URL de recuperación de archivos XML u ONIX se ofrece en la respuesta del servicio web de creación de archivos de actualización (ver 1.1). No tendrá que generar estas direcciones.


Aquí está la descripción detallada de invocación de la URL.


Declaración

Dirección : /api/organisations/[organisation_id]/publications/lists/[list_id].[xml|onix]

Formatos : xml, onix

Método : GET

Seguridad : HTTP/BASIC (nombre de usuario y contraseña)


Parámetros

organisation_id : Obligatorio

Número de organización. Ofrecido al inscribirse.


list_id : Obligatorio

Identificador de la lista.


Respuestas

200 : texto/xml - El contenido XML (metadatos) de los libros digitales.


401 : access_denied

Acceso al recurso denegado.


404 : not_found

No se ha podido encontrar la organización.



1.3 Verificación de los metadatos de una publicación

Este servicio web permite recibir los metadatos completos de un libro digital concreto.


Declaración

Dirección : /api/organisations/[organisation_id]/publications/[isbn].[xml|onix]

Formatos : xml, onix

Método : GET

Seguridad : HTTP/BASIC (nombre de usuario y contraseña)


Parámetros

organisation_id : Obligatorio

Número de organización. Se ofrece al inscribirse.


isbn : Obligatorio

ISBN/EAN del libro digital.


Respuestas

200 : OK

texto/xml - XML del libro digital.


401 : access_denied

Acceso al recurso denegado.


404 : not_found

No se ha podido encontrar la publicación.



2. Venta y descarga de publicaciones

Los servicios web de venta y de descarga de publicaciones de Cantook responden a tres necesidades:

Simular la venta de una publicación para comprobar su validez.

  1. Efectuar la venta de un libro digital.

  2. Obtener el enlace de descarga de un libro digital.


2.1 Simulación de venta

Como el catálogo de la librería no está sincronizado en tiempo real con el de la plataforma Cantook, es posible que haya algunas diferencias entre los dos catálogos en el momento exacto de una venta. Este servicio web permite al librero verificar que todos los parámetros requisitos para efectuar una venta siguen siendo válidos, y confirmar que la venta es posible.


Después de esta simulación, la venta no se registra en la plataforma. La venta debe ser efectuada mediante el servicio Venta de una publicación


Declaración

Dirección : /api/organisations/[organisation_id]/publications/[isbn]/sales/new

Método : GET

Seguridad : HTTP/BASIC (nombre de usuario y contraseña)


Parámetros

Organisation_id : Obligatorio

Número de organización. Se ofrece al inscribirse.


isbn : Obligatorio

ISBN del libro digital.


format : Obligatorio

Formato del libro digital vendido (pdf/epub/mobi/audio/proof).


cost : Obligatorio

Precio de venta en céntimos (p. ej., 19,99 $ => 1999).


protection : Obligatorio

Tipo de protección del libro digital vendido (none/watermark/acs4/acs4_timelimited/drm/drm_timelimited).


drm_type : Opcional

Tipo de DRM del libro digital vendido (acs/lcp/urms).


country : Obligatorio

País sobre el que validar el precio de la organización. Valor por defecto: el país de la organización. Formato ISO 3166-1 Alpha-3 (esp, can, fra, ita) ISO 3166-1 Alpha-2 (es, ca, fr, it).


cost_without_taxes : Opcional

Precio sin impuestos, en el país del cliente, en céntimos (ej.: 19,99 $ => 1999)


price_type : Obligatorio

El tipo de precio ONIX que será considerado para validar el precio de la publicación. Se aceptarán los valores 01, 02, 03, 04, 41 y 42 de la Lista 58.


currency : Obligatorio

La divisa que se considerará para validar el precio de la publicación. Use códigos de divisa de 3 letras.


Respuestas

200 : valid

La simulación se ha realizado correctamente.


400 : cannot_sell

La organización no puede vender este libro digital.


400 : missing_isbn

El ISBN no está en la solicitud.


400 : missing_format

El formato no está en la petición.


400 : invalid_format

El formato ofrecido no está disponible para este libro digital.


400 : invalid_sale_parameters

Parametros cost, country, currency o price_type alguno/s no son validos.


400 : missing_cost

El precio no está en la petición.


400 : invalid_cost

El precio no se corresponde con el precio introducido en la plataforma.


400 : missing_protection

El tipo de protección no está en la petición.


400 : invalid_protection

Esta protección no está disponible en este formulario


400 : invalid_country

El código de país no es válido.


400 : invalid_price_type

El tipo de precio no es válido.


400 : invalid_currency

El código de divisa no es válido.


401 : access_denied

Acceso al recurso denegado.


404 : not_found

No se ha encontrado la organización.


503 : service_unavailable

El servidor tiene problemas de conexión.


Notas

Si se produce un error de tipo 400, se crea un informe detallado del error en un vector.



2.2 Venta de un libro digital


Este servicio web permite efectuar una venta en la plataforma Cantook. La venta registrada de esta manera asocia, para una transacción en una fecha precisa, el comerciante, el usuario, y un fichero digital de un libro en la plataforma. El editor podrá consultar los detalles de la venta en las estadísticas.


Solo la respuesta 201 (created) confirma que la venta se ha registrado correctamente y que es posible pasar a la etapa siguiente del proceso de compra.


Nota: muchos de los parámetros utilizados tras efectuar la venta se requieren en el servicio de descarga de la publicación. Ya que los dos servicios pueden invocarse en momentos distintos, los valores deben seguir accesibles para poder ser utilizarlos después.


Declaración

Dirección : /api/organisations/[organisation_id]/publications/[isbn]/sales

Método : POST

Seguridad : HTTP/BASIC (nombre de usuario y contraseña)


Parámetros

organisation_id : Obligatorio

Número de organización. Se ofrece al inscribirse.


isbn : Obligatorio

ISBN de la publicación.


format : Obligatorio

Formato de la publicación vendida (pdf/epub/mobi/audio/proof).


cost : Obligatorio

Precio de venta en céntimos (p. ej., 19,99 $ => 1999).


protection : Obligatorio

Tipo de protección del libro digital vendido. (none/watermark/acs4/acs4_timelimited/drm/drm_timelimited).


drm_type : Opcional

Tipo de DRM del libro digital vendido (acs/lcp/urms).


customer_id : Obligatorio

Número único del cliente. Solo se aceptan caracteres alfanuméricos («-» y «_» también se aceptan).


transaction_id : Obligatorio

Número único de transacción / cesta de la compra. Se pueden hacer varias ventas con el mismo número de transacción, siempre y cuando se trate de la misma cesta de la compra. Solo se aceptan caracteres alfanuméricos («-» y «_» también se aceptan).


credit_card_prefix : Opcional

Los 4 primeros números de la tarjeta de crédito utilizados por el cliente. Esto permite al editor validar si el territorio de venta (determinado por estos 4 primeros caracteres) se respeta.


sale_state : Opcional

Estado de la venta. Por defecto, una venta siempre está en estado "activo". Valor posible:

- active

- test


country : Obligatorio

País sobre el que validar el precio de la organización. Valor por defecto: el país de la organización. Formato ISO 3166-1 Alpha-3 (esp, can, fra, ita) ISO 3166-1 Alpha-2 (es, ca, fr, it).


cost_without_taxes : Opcional

Precio sin impuestos, en el país del cliente, en céntimos (ej.: 19,99 $ => 1999)


price_type : Obligatorio

El tipo de precio ONIX que será considerado para validar el precio de la publicación. Se aceptarán los valores 01, 02, 03, 04, 41 y 42 de la Lista 58.


currency : Opcional

La divisa que se considerará para validar el precio de la publicación. Use códigos de divisa de 3 letras.


aggregator : Opcional

Es el id del agregador al que pertenece la tienda sobre la que se hace la venta.


uname : Opcional

Nombre y apellido del usuario. El valor de este parámetro aparecerá en el texto de la marca de agua que se depositará en este archivo. Si este parámetro se ofrece durante la venta, el plazo de generación de la copia de la marca de agua por la plataforma será más corto en el momento en el que el cliente desee descargar su archivo.


Respuestas

201 : created

La venta se ha realizado con éxito.


400 : cannot_sell

La organización no puede vender este libro digital.


400 : missing_isbn

El ISBN no estaba en la petición.


400 : missing_format

El formato no estaba en la petición.


400 : invalid_format

El formato ofrecido no está disponible para este libro digital.


400 : invalid_sale_parameters

Parametros cost, country, currency o price_type alguno/s no son validos.



400 : missing_cost

El precio no estaba en la petición.


400 : invalid_cost

El precio no se corresponde con el precio introducido en la plataforma.


400 : missing_customer_id

El número único de cliente no estaba en la petición.


400 : missing_transaction_id

El número único de la transacción no estaba en la petición.


400 : missing_protection

El tipo de protección no estaba en la petición.


400 : invalid_protection

Esta protección no estaba disponible en este formulario


400 : invalid_sale_state

El estado de venta no es válido.


400 : invalid_country

El código de país no es válido.


400 : invalid_price_type

El tipo de precio no es válido.


400 : invalid_currency

El código de divisa no es válido.


401 : duplicate

La venta ya existe en la Plataforma.


401 : access_denied

Acceso al recurso denegado.


404 : not_found

No se ha podido encontrar la organización.


503 : service_unavailable

El servidor tiene problemas de conexión.


Notas

  1. Las ventas efectuadas a través de esta API son facturables. Sin embargo, para realizar una venta de prueba (por ejemplo, tras el desarrollo de la conexión al servicio web), se puede añadir el parámetro “sale_state=test”, de esta forma la venta no se contabilizará.

  2. Si se produce un error de tipo 400, se crea un informe detallado del error en un vector.



2.3 Obtener el enlace de descarga de un libro digital

Para proteger el archivo del cliente, el enlace de descarga no puede generarse por adelantado y enviárselo al cliente. Los enlaces de descarga tiene un período de validez, y solo pueden ser obtenidos por el vendedor del libro digital. El vendedor ofrece su propio enlace de descarga al cliente, y cuando el cliente utiliza este enlace, el vendedor utiliza este servicio web para redirigir a su cliente al archivo.


Pasos tras la solicitud de descarga:

  1. El usuario hace clic sobre el enlace ofrecido para descargar su libro.

  2. La página del sitio web recibe la solicitud de descarga, vuelve a trazar los datos para generar el URL que usará con este servicio web. Esta recibe de vuelta una URL de descarga con caducidad.

  3. La página intermediaria del sitio web redirige automáticamente al usuario a la URL de descarga recibida:

  4. Comienza la descarga.


Declaración

Dirección : /api/organisations/[organisation_id]/customers/[customer_id] /transactions/[transaction_id]/publications/[isbn]/download_links/[format]

Método : GET

Seguridad : HTTP/BASIC (nombre de usuario y contraseña)


Parámetros

organisation_id : Obligatorio

Número de organización. Ofrecido durante de la inscripción.


customer_id : Obligatorio

El número de cliente.


transaction_id : Obligatorio

El número único de transacción / cesta de la compra.


isbn : Obligatorio

El ISBN del libro digital.


format : Obligatorio

El formato de la publicación vendida (pdf/epub/mobi/audio/proof).


uname : Opcional

Nombre y apellido del usuario. El valor de este parámetro aparecerá en el texto de la marca de agua que se depositará en este archivo.


Respuestas

200 : OK

URL con caducidad del archivo para descargar (caducidad de 1 minuto). Redirige al usuario a esta URL.


400 : missing_transaction_id

El número de transacción no estaba de la petición.


401 : access_denied

Acceso al recurso denegado.


404 : not_found

No se ha podido encontrar la organización.



2.4 Anulación de una venta

Los libreros pueden utilizar este servicio web para anular una venta. Para que la venta pueda anularse, el librero deberá proporcionar al servicio los valores de la venta original. Solo las ventas cuyo libro digital no haya sido descargado (el archivo con marca de agua no se ha descargado o el acsm asociado al libro protegido con DRM no ha sido descargado) se podrán anular.


Declaración

Dirección : /api/organisations/[organisation_id]/publications/[publication_id]/sales/cancel?customer_id=[customer_id]&transaction_id=[transaction_id]&amount=[amount]&reason=[reason]

Método : POST

Seguridad : HTTP/BASIC (nombre de usuario y contraseña)


Parámetros

organisation_id : Obligatorio

ID de la organización que realiza la venta.


publication_id : Obligatorio

Identificador (ISBN, EAN o clave interna) del libro digital.


customer_id : Obligatorio

La customer_id de la venta a anular.


transaction_id : Obligatorio

La transaction_id de la venta a anular.


amount : Obligatorio

El importe de la anulación, que debe debe ser el mismo que el de la venta original.


reason : Opcional

La razón de la anulación(opcional). Se mostrará al editor..



Respuestas

200 : OK

Token - La anulación se ha registrado, y se ha entregado un código de referencia.


400 : refund_unauthorized

No se ha autorizado la anulación porque el contenido ha sido descargado por el usuario.


400 : already_refunded

La venta ya ha sido cancelada anterioremente.


400 : already_fulfilled

La venta ya ha sido descargada.


400 : cost_mismatch

El importe no coincide con el de la venta original.


401

Ha habido un problema con la autenticación del usuario, o el usuario no tiene derecho a efectuar una anulación.


404

No se ha encontrado la venta.



2.5 Venta anticipada o preventa


Los libreros pueden ofrecer a sus clientes la posibilidad de comprar por adelantado las publicaciones que se ofrecen en venta anticipada. Para efectuar una venta anticipada el librero deberá utilizar el servicio web preencargo. Cuando el libro digital esté disponible para la venta, habrá que generar la venta real correspondiente a la venta anticipada mediante el servico web de venta. El identificador del cliente (customer_id) debe coincidir con el utilizado para la venta anticipada. Una vez la venta se haya generado, el libro digital se descarga mediante el servicio web


Descarga de una publicación.


Publicaciones disponibles en venta anticipada o preventa

Se pueden aplicar las siguientes reglas para determinar qué publicaciones están disponibles en venta anticipada:


Estado: <ProductAvailability>40</ProductAvailability> (no disponible para la venta)


Fecha a partir de la cual es posible hacer los preencargos:

<PublishingDate>

<PublishingDateRole>09</PublishingDateRole>

<DateFormat>14</DateFormat>

<Date>20131107T000000-0500</Date>

</PublishingDate>

La fecha de disponibilidad está detallada en el flujo ONIX de la siguiente manera (la fecha debe ser futura):

<SupplyDate>

<SupplyDateRole>02</SupplyDateRole>

<DateFormat>14</DateFormat>

<Date>2012-10-25T00:00:00-04:00</Date>

</SupplyDate>


Declaración

Dirección : /api/organisations/[organisation_id]/publications/[publication_id]/preorders?for=[format]&customer_id=[customer_id]

Método : POST

Seguridad : HTTP/BASIC (nombre de usuario y contraseña)


Parámetros

organisation_id : Obligatorio

ID de la organización que realiza la venta.


publication_id : Obligatorio

Identificador (ISBN, EAN o clave interna) de la publicación.


for : Obligatorio

epub/pdf/mobi/audio/proof.


customer_id : Obligatorio

La customer_id de la venta a anular.


Respuestas

200 : created

La venta anticipada se ha guardado.


401

Problema de autenticación del usuario.


404

No se encuentra la publicación.



2.6 Obtener el estado de una descarga

Este servicio web permite ver si el cliente ha descargado un título o no.


Declaración

Dirección : /api/organisations/{organisation_id}/customers/{customer_id}/transactions/{transaction_id}/publications/{isbn}/formats/{format}/status


Parámetros

Todos los parámetros de la URL deben ser idénticos a los usados en el servicio web Venta de una publicación.


Respuesta

La respuesta seguirá esta estructura:

<status>

<transaction>

<id>transaction_id</id>

<customer>

<id>customer_id</id>

</customer>

<publications>


<publication>

<format>

<nature>epub</nature>

<keytype>isbn</keytype>

<value>9780000000001</value>

<protectiontype>watermark</protectiontype>

</format>

<fulfillment>complete</fulfillment>

<refundable>false<refundable>

</publication>

</publications>

</transaction>

</status>


Notas

La etiqueta <fulfillment> marca el estado de la descarga del usuario final:

en caso de protección por marca de agua: "completo" e "incompleto" se refieren al comienzo de la descarga del archivo

en caso de protección ACS4 DRM: "completo" e "incompleto" se refieren a la activación de la licencia en Adobe Digital Edition u otro software compatible.


Las etiquetas restantes se corresponden con la información ofrecida durante la llamada al servicio.