Creación de pedidos

3.1.3. Creación de pedidos#

Esta página contiene toda la documentación del videotutorial que explica la creación de un pedido sencillo a través de la API y la comprobación de su estado.

3.1.3.1. Vídeo#

3.1.3.2. Requisitos#

Necesario para esta serie de tutoriales:

  • Un backend comercial Taler
    Si necesita ayuda para utilizar el backend de comerciante por primera vez, puede ver el tutorial Taler merchant introduction.
  • Una instancia de cartera Taler
    Las instrucciones de configuración están disponibles en https://wallet.taler.net.
  • Un software de gestión de API REST o conocimientos de programación pertinentes
    En esta serie de vídeos, vamos a utilizar el software gratuito Insomnia, disponible para su descarga en https://insomnia.rest.

3.1.3.3. Aviso de backend de demostración#

Para este tutorial, puede utilizar su propio servicio de backend comercial o el servicio de demostración en línea de https://backend.demo.taler.net/instances/sandbox/.

3.1.3.4. Procesamiento de pagos comerciales#

  1. Creación de una orden de pago

Los pagos en Taler giran en torno a una orden, que es una descripción legible por máquina de la transacción comercial para la que se va a realizar el pago. Antes de aceptar un pago Taler como comerciante debe crear dicha orden.

Esto se hace enviando un objeto JSON al punto final de la API /private/orders. En el campo order deben aparecer al menos los siguientes campos:

  • importe: La cantidad a pagar, como una cadena en el formato CURRENCY:DECIMAL_VALUE, por ejemplo EUR:10 para 10 Euros o KUDOS:1.5 para 1.5 KUDOS.

  • resumen: Un resumen legible por humanos de lo que trata el pago. El resumen debe ser lo suficientemente corto como para caber en los títulos, aunque no se impone un límite estricto.

  • fulfillment_url: Una URL que se mostrará una vez completado el pago. En el caso de productos digitales, debe ser una página que muestre el producto adquirido. Cuando el pago se realiza correctamente, el monedero añade automáticamente el order_id como parámetro de consulta, así como el session_sig para los pagos vinculados a sesión (que se explican más adelante).

Los pedidos pueden tener muchos más campos, vea El Formato de Pedido de Taler. Al enviar un pedido por POST, también puede especificar detalles adicionales, como una anulación de la duración del reembolso e instrucciones para la gestión del inventario. Estos son raramente necesarios y no se tratan en este tutorial; por favor, consulte el Manual de referencia para más detalles.

Un fragmento mínimo de Python para crear un pedido tendría el siguiente aspecto:

>>> import requests
>>> body = dict(order=dict(amount="KUDOS:10",
...                        summary="Donation",
...                        fulfillment_url="https://example.com/thanks.html"),
...             create_token=False)
>>> response = requests.post("https://backend.demo.taler.net/instances/sandbox/private/orders",
...               json=body,
...               headers={"Authorization": "Bearer secret-token:sandbox"})
<Response [200]>

El backend completará algunos detalles que faltan en el pedido, como la dirección de la instancia comercial. Los detalles completos se denominan condiciones del contrato.

Nota

La solicitud anterior desactiva el uso de testigos de reclamación estableciendo la opción create_token en false. Si necesita tokens de reclamación, debe ajustar el código para construir el URI taler://pay/ que se indica a continuación para incluir el token de reclamación.

Después de enviar con éxito un POST a /private/orders, se devolverá un JSON con sólo un campo order_id con una cadena que representa el ID del pedido. Si también obtiene un token de reclamación, vuelva a comprobar que ha utilizado la solicitud tal y como se ha descrito anteriormente.

Junto con la instancia del comerciante, el identificador de pedido identifica de forma única el pedido dentro de un backend de comerciante. Usando el ID de pedido, puedes construir trivialmente el URI taler://pay/ respectivo que debe proporcionarse al monedero. Sea ejemplo.com el nombre de dominio donde los puntos finales públicos de la instancia son accesibles. El URI de pago de Taler es entonces simplemente taler://pay/example.com/$ORDER_ID/ donde $ORDER_ID debe ser reemplazado por el ID de la orden que fue devuelta.

Puede poner el URI taler:// como destino de un enlace para abrir el monedero Taler a través del esquema taler://, o ponerlo en un código QR. Sin embargo, para una tienda web, lo más sencillo es redirigir el navegador a https://example.com/orders/$ORDER_ID. Esa página activará el monedero Taler. Aquí el backend genera la lógica correcta para activar el monedero, soportando los distintos tipos de monederos Taler existentes. En lugar de construir la URL anterior a mano, también es posible obtenerla comprobando el estado del pago como se describe en la siguiente sección.

Al construir manualmente esta URL, asegúrese de proporcionar el token de reclamación (a menos que se haya deshabilitado) y si el backend se ejecuta sin TLS, utilice taler+http:// (tenga en cuenta que esto último sólo es compatible con los monederos que se ejecutan en modo de depuración).

Nota

Una forma trivial de obtener la payment_redirect_url correcta es comprobar el estado del pago (ver más abajo). Así que si todavía no está seguro de cómo construirlo, puede simplemente pedir al backend que lo haga por usted. Sin embargo, en producción probablemente deberías construirlo manualmente y evitar la petición extra al backend.

  1. Comprobación del estado del pago y requerimiento de pago

Dado el ID del pedido, se puede comprobar el estado de un pago con el punto final /private/orders/$ORDER_ID. Si el cliente aún no ha completado el pago, /private/orders/$ORDER_ID proporcionará al frontend una URL (con el nombre payment_redirect_url) que activará el monedero del cliente para ejecutar el pago. Esta es básicamente la URL https://example.com/orders/$ORDER_ID de la que hablamos antes.

>>> import requests
>>> r = requests.get("https://backend.demo.taler.net/instances/sandbox/private/orders/" + order_id,
...                  headers={"Authorization": "Bearer secret-token:sandbox"})
>>> print(r.json())

Si el campo order_status en la respuesta es paid, no obtendrá una payment_redirect_url y en su lugar información sobre el estado del pago, incluyendo:

  • contract_terms: Las condiciones contractuales completas del pedido.

  • refunded: true si se ha concedido un reembolso (posiblemente parcial) por esta compra.

  • importe_devuelto: Importe reembolsado

Una vez que el frontend ha confirmado que el pago se ha realizado correctamente, normalmente necesita activar la lógica empresarial para que el comerciante cumpla las obligaciones del contrato.

Nota

No es necesario seguir consultando para notar cambios en el estado de la transacción del pedido. Los puntos finales admiten sondeos largos, simplemente especifique un parámetro de consulta timeout_ms con el tiempo máximo que desea esperar a que el estado del pedido cambie a paid.

3.1.3.5. Más tutoriales#

Para ver tutoriales adicionales, puede navegar por este sitio o dirigirse a https://docs.taler.net para obtener la documentación más reciente sobre los servicios Taler.