Gestionar tarjetas regalo
Las tarjetas regalo permiten a nuestros clientes disfrutar de una cantidad de dinero para realizar compras dentro de nuestro tienda en el futuro.
Cada tarjeta tiene asignada un código único y puede ser canjeada por cualquier persona en posesión de la tarjeta.
#1/ Configurar tarjetas regalo
En la sección Apps de nuestra cuenta, instalamos la aplicación 'Tarjetas regalo' (se requiere la opción Premium).
Un producto de 'Tarjeta regalo' se creará automáticamente en la base de datos de productos.
Este producto está asociado a su tipo impositivo por defecto. El IVA normalmente se devenga en el momento de la venta de la tarjeta, pero el impacto fiscal será nulo, ya que el IVA pagado en la venta de la tarjeta se deduce cuando se canjee su valor.
En la configuración de la aplicación, podemos ingresar un período de validez que se aplicará a todas las tarjetas de regalo vendidas.
Si no introducimos una fecha, las tarjetas de regalo se podrán canjear indefinidamente.
Se puede cambiar el período de validez cuando vendamos una tarjeta regalo o en la misma aplicación para tarjetas ya vendidas.
#2/ Vender tarjetas regalo
Creamos una venta y hacemos clic en el botón 'Tarjeta regalo' en los detalles de la venta.
Introducimos el importe de la tarjeta en la sección 'Vender tarjeta regalo'.
El campo 'Validez' se completará automáticamente, pero se puede cambiar en cualquier momento. Lo dejamos vacío para una validez por tiempo ilimitado.
El campo 'Código' permite añadir el código de una tarjeta regalo física impresa. Lo dejamos vacío para generar un código automáticamente.
Hacemos clic en el botón 'Añadir un producto' para confirmar la creación de la tarjeta regalo: el producto de la tarjeta regalo se añadirá a la venta con el importe seleccionado y encontraremos el código de la tarjeta en el campo S/N (número de serie).
Hacemos clic en el botón superior derecho 'Volver a la venta'.
Finalizamos la venta como es habitual, escogiendo el método de pago utilizado para comprar la tarjeta.
Para vender tarjetas regalo desde nuestro sitio web, consultamos la sección 6 (API).
En Internet se puede comprar lotes de tarjetas regalo físicas impresas con códigos de barras individuales, que podremos personalizar con la imagen de nuestra marca.
Si el campo S/N no está disponible en Ventas, vamos a 'Configuración/Usuarios/Gestión de accesos' y activamos el permiso:'Gestionar números de serie de productos'.
#3/ Canjear tarjetas regalo
Creamos una venta y añadimos los productos comprados por el cliente.
Hacemos clic en el botón 'Tarjeta regalo' en los detalles de la venta.
Escaneamos o introducimos el código de la tarjeta regalo en la sección 'Usar tarjeta regalo' y confirmamos. Se añadirá a la venta una línea de crédito por el valor de la tarjeta regalo.
Para completar la venta: Si el importe total de la venta es positivo, cobramos al cliente con otro medio de pago el importe restante, Si el importe total de la venta es negativo, añadimos una nueva tarjeta regalo a la venta para compensarla a 0. Cerramos la venta con cualquier método de pago.
Si no queremos generar una nueva tarjeta regalo, podemos usar una cuenta de crédito del cliente en la tienda. El importe negativo de la venta se pagará con el método de pago CRED que se registrará como crédito en la cuenta del cliente. Más información.
#4 / Seguimiento de tarjetas regalo
En la aplicación 'Tarjeta regalo' podemos ver las tarjetas regalo emitidas, usadas y vencidas.
Se puede filtrar y exportar resultados en CSV.
En nuestros informes: La facturación vinculada al producto 'Tarjeta regalo' es la cantidad total de tarjetas regalo emitidas, La facturación negativa vinculada al producto 'Crédito/Tarjeta regalo' es la cantidad total de tarjetas de regalo canjeadas.
#5 / Impresión de tarjetas regalo
Si no utilizamos tarjetas regalo físicas impresas, se puede imprimir una tarjeta regalo en PDF o con su impresora de recibos.
a/ Formato PDF
– Instalamos la aplicación 'Documentos PDF' en la sección Apps de nuestra cuenta.
– Descargamos la plantilla 'Tarjeta regalo', completamos y personalizamos en un editor de texto.
– Guardamos el archivo en .odt y lo cargamos en la aplicación 'Documentos PDF'.
Cuando vendamos una tarjeta regalo, encontraremos un menú desplegable 'Acción' en la parte superior derecha de la venta. Seleccionamos la plantilla 'Tarjeta regalo' para generar una tarjeta regalo en PDF.
b/ Formato recibo
– En 'Configuración/Usuarios/Gestión de accesos', activamos el permiso: 'Imprimir tickets individuales por cada línea de artículo de la venta'.
– En 'Configuración/Impresión/Taquilla', añadimos el siguiente código y lo modificamos con nuestros datos:
#@@@@@@= =@@@@@@#
+@@@*..-*#. .#*-..*@@@*
=@@@- -= == -@@@+
:#@@#- #@@@@% -*@@#-
-##############****##############-
*@@@@@@@@@@@@@: :@@@@@@@@@@@@@#
*@@@@@@@@@@@@@: :@@@@@@@@@@@@@#
-+*************************-
#@@@@@@@@@@: :@@@@@@@@@@%
#@@@@@@@@@@: :@@@@@@@@@@%
#@@@@@@@@@@: :@@@@@@@@@@%
*@@@@@@@@@@: :@@@@@@@@@@#
<hibou_use_font_b>
<hibou_font_size>2|2
<hibou_bold>
HIBOUTIK
</hibou_bold>
<hibou_font_size>1|1
30 plaza Mayor - 01234 MICIUDAD
123 456 789 - contact@hiboutik.com
-------------------------------------------
### <hibou_print_product_serial>###
-------------------------------------------
<hibou_font_size>2|2
<hibou_bold>
TARJETA REGALO
-- <hibou_print_price_product> EUR --
</hibou_bold>
<hibou_font_size>1|2
Code: <hibou_print_product_serial>
<hibou_font_size>1|1
Válida hasta <hibou_print_product_comment>
-------------------------------------------
### <hibou_print_product_serial>###
-------------------------------------------
<hibou_print_this_code128_barcode><hibou_print_product_serial>
<hibou_use_font_a>
Generará el <hibou_print_date_time> - # <hibou_print_num_order_unique>
<hibou_cut_paper_partial>
En la sección de Pago de la venta de la tarjeta regalo, hacemos clic en el botón 'Taquilla' para imprimir la tarjeta regalo como un recibo.
#6/ API
La aplicación ofrece una API para vender tarjetas regalo desde una herramienta distinta de la caja, por ejemplo una página de venta online con pago por Stripe, y para consultar las tarjetas disponibles.
Esta sección está dirigida a la persona que desarrolla nuestro sitio web o nuestra integración.
Las tarjetas creadas con la API son idénticas a las vendidas en caja: mismo producto 'Tarjeta regalo', código en el campo S/N, fecha de validez en el comentario del producto, seguimiento en la aplicación.
a/ Activar la API
En la aplicación, abrimos la Configuración y, en la sección API, hacemos clic en 'Generar una clave'.
Se muestran la dirección de la API y la clave de nuestra cuenta.
– La clave da acceso a las tarjetas regalo de nuestra cuenta: la mantenemos en secreto y solo la usamos desde un servidor, nunca en una página web visible para nuestros clientes.
– El botón 'Regenerar la clave' desactiva inmediatamente la clave anterior: debemos actualizar nuestras integraciones.
– Mientras no se haya generado ninguna clave, la API está desactivada para nuestra cuenta.
b/ Llamar a la API
Todas las solicitudes usan la siguiente dirección, con la acción deseada:
https://cartescadeaux.hiboutik.net/api/?account=account&action=...
La barra / antes del ? es obligatoria.
La clave se envía en el encabezado HTTP Authorization (o en el encabezado X-Api-Key):
Authorization: Bearer NUESTRA_CLAVE
Las respuestas están en formato JSON.
c/ Comprobar la configuración: action=config
GET https://cartescadeaux.hiboutik.net/api/?account=account&action=config
Respuesta:
{
"product_id": 7,
"product_label": "Tarjeta regalo",
"validity_days": 365,
"vat_rate": 0.2,
"can_sell": true
}
validity_days es el período de validez por defecto, en días (0: validez ilimitada).
can_sell vale false si el tipo de IVA del producto 'Tarjeta regalo' es 0: en ese caso la API no permite crear tarjetas.
d/ Añadir una tarjeta regalo a una venta: action=add
La tarjeta se añade a una venta abierta de nuestra cuenta, creada por ejemplo con la API de Hiboutik (POST /sales/).
POST https://cartescadeaux.hiboutik.net/api/?account=account&action=add
Content-Type: application/json
{ "sale_id": 1001, "amount": 50 }
Parámetros, en JSON o en formulario:
– sale_id (obligatorio): número de la venta, que debe seguir abierta.
– amount (obligatorio): importe de la tarjeta con IVA incluido, por ejemplo 50 o 49.90.
– code (opcional): código de una tarjeta regalo física impresa, que debe ser único (de 3 a 64 caracteres: letras, cifras, - y _). Sin código, se genera uno automáticamente.
– validite (opcional): fecha de vencimiento en formato AAAA-MM-DD. Sin este parámetro, se aplica el período de validez por defecto. Si se envía vacío, la tarjeta tiene validez ilimitada.
Respuesta (código HTTP 201):
{
"card": {
"code": "1001hi555",
"amount": 50,
"validite": "2027-11-16",
"sale_id": 1001,
"line_item_id": 555,
"product_id": 7
}
}
La tarjeta se puede canjear una vez cerrada la venta, es decir, pagada. A partir de ese momento se puede usar en caja como se indica en la sección 3.
Mientras la venta no esté finalizada, la tarjeta no aparece entre las tarjetas disponibles.
e/ Listar las tarjetas disponibles: action=list
Una tarjeta está disponible cuando se ha vendido (venta cerrada), todavía no se ha canjeado y no está archivada.
Por defecto, las tarjetas cuya fecha de validez ha pasado no se listan.
GET https://cartescadeaux.hiboutik.net/api/?account=account&action=list
Filtros opcionales:
– code: una tarjeta concreta, por ejemplo para comprobar una tarjeta antes de aceptarla.
– sale_id: las tarjetas vendidas en una venta.
– include_expired=1: incluir las tarjetas vencidas, marcadas con "expired": true.
– limit (100 por defecto, 500 como máximo) y offset: paginación.
Respuesta:
{
"total": 1,
"limit": 100,
"offset": 0,
"cards": [
{
"code": "1001hi555",
"amount": 50,
"validite": "2027-11-16",
"expired": false,
"date_sold": "2026-11-16 14:05:12",
"sale_id": 1001,
"line_item_id": 555,
"store_id_sold": 1
}
]
}
Una tarjeta con validez ilimitada tiene un campo validite vacío ("").
f/ Consultar una tarjeta: action=card
Devuelve una tarjeta concreta, sea cual sea su estado, por ejemplo para mostrar la tarjeta a su destinatario.
GET https://cartescadeaux.hiboutik.net/api/?account=account&action=card&code=1001hi555
Respuesta:
{
"card": {
"code": "1001hi555",
"amount": 50,
"validite": "2027-11-16",
"expired": false,
"date_sold": "2026-11-16 14:05:12",
"sale_id": 1001,
"line_item_id": 555,
"store_id_sold": 1,
"status": "available",
"date_used": ""
}
}
status indica el estado de la tarjeta:
– pending: la venta de la tarjeta todavía no está cerrada (pago pendiente).
– available: la tarjeta se puede canjear.
– expired: la fecha de validez ha pasado.
– used: la tarjeta ya se ha canjeado (fecha en date_used).
– archived: la tarjeta se ha archivado en la aplicación.
g/ Errores
En caso de error, la API devuelve un código HTTP y un mensaje:
{ "error": "sale_closed", "error_description": "La vente est déjà clôturée." }
El mensaje error_description está en francés: nos basamos en el código error.
– 401 unauthorized: clave ausente o no válida para esta cuenta.
– 404 sale_not_found: venta no encontrada.
– 404 card_not_found: tarjeta no encontrada.
– 409 sale_closed: la venta ya está cerrada.
– 409 code_in_use: este código ya está asignado a otra tarjeta.
– 409 vat_zero: el tipo de IVA del producto 'Tarjeta regalo' es 0.
– 409 not_configured: producto 'Tarjeta regalo' no encontrado. Abrimos la aplicación en Hiboutik para volver a crearlo.
– 422 invalid_sale_id, invalid_amount, invalid_code, invalid_validite: parámetro ausente o no válido.
– 502 hiboutik_error: no se ha podido añadir la tarjeta a la venta.