API REST de Gift Card Hero¶

La API REST te permite gestionar tarjetas de regalo de forma programática desde sistemas externos: CRM, paneles de analítica, plataformas de fidelidad, servicios de logística y mucho más.

Configuración de la API REST

URL base¶

Todas las peticiones a la API usan la siguiente URL base:

https://gifthero.syncu.be/api/external

Autenticación¶

Cada petición debe incluir un token Bearer en la cabecera Authorization:

Authorization: Bearer YOUR_API_TOKEN

Para obtener tu token de API, ve a For developers en la navegación de la izquierda, marca Enable REST API y guarda. Haz clic en Send me access token: el token se envía a la dirección de correo de contacto de la tienda que aparece en la página.

El token no caduca hasta que lo reemplaces o lo revoques. Trátalo como una contraseña: guárdalo en los ajustes secretos de tu integración y no lo pegues en chats, tickets ni documentos compartidos.

Gestionar tu token de API¶

Un solo token a la vez. Tu tienda tiene un único token de API. Todos los sistemas que llaman a la API (un TPV, un CRM, el servicio de un socio) usan ese mismo token.

Enviar un token nuevo reemplaza al anterior. Cada clic en Send me access token emite un token nuevo, y el anterior deja de funcionar de inmediato. Actualiza cada integración con el nuevo token en cuanto puedas. Si solo necesitas volver a consultar el token, busca el correo anterior en lugar de enviar uno nuevo.

Revocar un token. Si un token pudo haberse filtrado, o si un socio que lo tenía ya no trabaja contigo, haz clic en Revoke access token en la página For developers y confirma. El token deja de funcionar al instante y no se emite ninguno nuevo. Cuando estés listo, haz clic en Send me access token para emitir uno nuevo.

Desactivar la API REST. Desactivar Enable REST API y guardar también revoca el token. Después de volver a activar la API, envíate un token nuevo.

Lo que ve tu integración. Una petición con un token reemplazado o revocado recibe una respuesta 401:

{
  "error": {
    "statusCode": 401,
    "name": "UnauthorizedError",
    "message": "Error verifying token : The token has been revoked or replaced."
  }
}

La solución es siempre la misma: pon el token actual en la cabecera Authorization.

Los tokens emitidos antes de que se introdujeran los ID de token siguen funcionando hasta la primera vez que envíes un token nuevo o revoques el token.

Otros errores de autenticación:

Estado	Significado
`401`	La cabecera `Authorization` falta o no es de tipo `Bearer`, o el token no es válido
`402`	La tienda no tiene un plan activo de Gift Card Hero

Endpoints¶

Listar tarjetas de regalo¶

GET /gift-cards

Parámetros:

Parámetro	Tipo	Descripción
`status`	string	Filtra por estado de la tarjeta de regalo
`limit`	integer	Número máximo de resultados (máximo 250)
`since_id`	string	Devuelve los resultados posteriores a este ID de tarjeta de regalo
`fields`	string	Lista de campos a incluir, separados por comas

La petición se pasa a la lista de tarjetas de regalo de Shopify, así que se aplican los parámetros propios de Shopify para ella. Cada tarjeta de la respuesta incluye un objeto recipient (id, email, name) o null. El campo code aparece cuando Gift Card Hero tiene el código completo registrado (consulta Notas importantes).

Una petición HEAD /gift-cards devuelve 200 sin cuerpo. Algunos clientes HTTP la usan como comprobación previa.

Listar tarjetas de regalo con transacciones¶

GET /gift-cards/transactions

Devuelve las tarjetas de regalo, de la más reciente a la más antigua, cada una con hasta sus 50 transacciones más recientes. Admite paginación basada en cursor.

Paginación:

Parámetro	Tipo	Descripción
`limit`	integer	Tarjetas de regalo por página (predeterminado 50)
`page_info`	string	Cursor para la siguiente página de resultados

Filtros:

Filtro	Tipo	Descripción
`query`	string	Consulta de búsqueda, con la sintaxis de búsqueda de tarjetas de regalo de Shopify
`balance_status`	string	Uno de: `full`, `partial`, `empty`, `full_or_partial`
`created_at`	string	Filtra por fecha de creación
`expires_on`	string	Filtra por fecha de caducidad
`source`	string	Uno de: `manual`, `purchased`, `api_client`
`status`	string	Uno de: `disabled`, `enabled`, `expired`, `expiring`
`initial_value`	string	Filtra por valor inicial
`id`	string	Filtra por ID de tarjeta de regalo

Todos los filtros usan lógica AND cuando se combinan.

Respuesta:

Cada tarjeta de regalo tiene id, balance, currency, initial_value, created_at, updated_at, disabled_at, customer_id, recipient, note, expires_on, template_suffix, last_characters, order_id, transactions e issued_by. La respuesta no incluye el código de la tarjeta de regalo. Cada transacción tiene id, amount (negativo para un cargo), processed_at, note, pos_user y pos_order_name.

IDs de transacción:

transactions[].id es el ID numérico de Shopify de la transacción de la tarjeta de regalo: el número al final de su GID gid://shopify/GiftCardDebitTransaction/… o gid://shopify/GiftCardCreditTransaction/…. Las versiones anteriores de la API devolvían null aquí.

Campos del TPV:

Las tarjetas de regalo emitidas o canjeadas a través del TPV de Gift Card Hero incluyen el cajero que lo hizo. Estos campos se añaden a la respuesta estándar:

Campo	Tipo	Descripción
`transactions[].pos_user`	object or null	`{ "username": "woodgrove", "name": "Woodgrove" }` para un cargo hecho en el TPV; `null` en otro caso
`transactions[].pos_order_name`	string or null	Nombre del pedido introducido en el TPV para ese cargo, si lo hay; `null` en otro caso
`issued_by`	object or null	`{ "username", "name", "issued_at" }` para una tarjeta emitida en el TPV; `null` en otro caso

El registro de actividad del TPV no guarda los ID de transacción de Shopify, así que un cargo se asocia con un canje del TPV por tarjeta, importe y hora (el canje debe registrarse desde unos segundos antes hasta un minuto después de la transacción). Los pagos en línea, los cambios hechos en el panel de administración de Shopify y los cargos sin un registro correspondiente en el TPV reciben null. name es null si el usuario del TPV se ha eliminado desde entonces.

Obtener una tarjeta de regalo¶

GET /gift-cards/{gift_card_id}

Devuelve los detalles de una tarjeta de regalo por su ID, con su recipient y, cuando Gift Card Hero lo tiene, su code.

Crear una tarjeta de regalo¶

POST /gift-cards

Cuerpo de la petición:

{
  "note": "Loyalty reward",
  "initial_value": "50.00",
  "code": "ABCD-EFGH-IJKL-MNOP",
  "template_suffix": "custom"
}

Campo	Tipo	Obligatorio	Descripción
`note`	string	No	Nota interna de la tarjeta de regalo
`initial_value`	string	Sí	Saldo inicial
`code`	string	No	Código de tarjeta de regalo personalizado (debe ser único; se genera automáticamente si se omite)
`template_suffix`	string	No	Sufijo de plantilla de Shopify
`customer_id`	integer	No	Cliente de Shopify que es propietario de la tarjeta
`email`	string	No	Correo del cliente, que se usa cuando no se envía `customer_id`. Gift Card Hero busca al cliente o crea uno con la etiqueta `gifthero:import`

El cuerpo se pasa al endpoint de tarjetas de regalo de Shopify, que acepta más campos, como expires_on. La respuesta es la tarjeta de regalo de Shopify, con el code completo.

Importante: guarda el código completo de la respuesta de creación si lo necesitas más adelante. Las respuestas posteriores incluyen el code completo solo en las tarjetas que Gift Card Hero tiene registradas; en las demás solo se devuelven los últimos 4 caracteres (last_characters).

Actualizar el saldo de una tarjeta de regalo¶

PUT /gift-cards/{gift_card_id}/balance

Cuerpo de la petición:

{
  "balance": "100.00"
}

Establece el saldo de la tarjeta de regalo al valor indicado. Un valor con signo, como "+25.00" o "-10.00", se aplica como un ajuste sobre el saldo actual. Si el saldo no cambia, se devuelve el saldo actual y no se registra nada. Cuando la tienda tiene activado Increase limit, una recarga puede superar el límite estándar de tarjetas de regalo de Shopify.

Se trata de una corrección de saldo: no envía ninguna notificación al cliente ni registra una sucursal. Cuando un cliente gaste la tarjeta en una caja, usa Canjear una tarjeta de regalo en su lugar.

Canjear una tarjeta de regalo¶

POST /gift-cards/{gift_card_id}/redeem

Descuenta (canjea) una tarjeta de regalo desde una aplicación de TPV o de caja de terceros, fuera del pago de Shopify. El titular de la tarjeta recibe la notificación de canje de tu tienda (correo o SMS) con el nombre de la sucursal, o el comprador en su lugar, o ambos, si Who gets notified en los ajustes de Redemption notifications así lo indica. El canje aparece con su sucursal en los informes de Gift Card Hero. Usa este método en lugar de llamar directamente a giftCardDebit de Shopify: un cargo directo no envía sucursal ni notificación.

Canjear frente a actualizar el saldo: usa Actualizar el saldo de una tarjeta de regalo para fijar el saldo a un valor sin notificar a nadie. Usa Canjear cuando un cliente gaste la tarjeta y quieras que se registren la notificación y la sucursal.

Cuerpo de la petición:

{
  "amount": "1500.00",
  "branch": "Westgate",
  "reference": "pos-app:7f3c2b9e-0d1a-4c55-9b7e-2f8a6c1d3e4f",
  "note": "Table 12"
}

Campo	Tipo	Obligatorio	Descripción
`amount`	string	Sí	Importe a canjear. Debe ser mayor que 0 y no superior al saldo de la tarjeta, en la moneda de la tarjeta, con hasta 2 decimales
`branch`	string	Sí	Nombre de la sucursal o del local. Se muestra en el correo y el SMS de canje (cuando Include the store location está activado en Redemption notifications) y en los informes
`reference`	string	Sí	Tu ID único para este canje, de hasta 255 caracteres. Consulta Reintentos y duplicados
`note`	string	No	Se escribe en la transacción de la tarjeta de regalo en Shopify. Gift Card Hero añade `[ref:<reference>]` a la nota, para que puedas relacionar cada canje de la API con su referencia en el panel de administración de Shopify

Respuesta (200):

{
  "id": 661944893757,
  "last_characters": "7nsf",
  "amount": "1500.00",
  "currency": "KES",
  "balance_before": "5090.00",
  "balance": "3590.00",
  "branch": "Westgate",
  "reference": "pos-app:7f3c2b9e-0d1a-4c55-9b7e-2f8a6c1d3e4f",
  "processed_at": "2026-10-12T10:30:00Z",
  "notification": "queued",
  "duplicate": false
}

Campo	Descripción
`notification`	`queued`: la notificación de canje se entregó a los ajustes de Redemption notifications de tu tienda, que deciden si se envía (en cada canje, o solo cuando la tarjeta se agota). `disabled`: las notificaciones de canje están desactivadas en tu tienda
`duplicate`	`true` cuando esta `reference` ya se procesó y la respuesta es el resultado original

Errores:

Los errores usan el formato habitual: {"error": {"statusCode": 422, "name": "...", "message": "..."}}.

Estado	Significado	Qué hacer
`400`	`amount`, `branch` o `reference` falta o no es válido	Corrige el cuerpo de la petición
`401`	El token falta, no es válido, está revocado o lo reemplazó uno más nuevo	Revisa la cabecera `Authorization`. Si el token se revocó o reemplazó, solicita uno nuevo
`403`	A la app le falta un ámbito de acceso en tu tienda	El propietario de la tienda debe aprobar los permisos actualizados de la app en el panel de administración de Shopify
`404`	Tarjeta de regalo no encontrada	Comprueba el ID de la tarjeta de regalo
`409`	La `reference` ya se usó para otra tarjeta o importe, o una petición con esta `reference` todavía se está procesando	Para un canje nuevo, usa una `reference` nueva. Si una petición sigue procesándose, espera unos segundos y reintenta con la misma `reference`
`422`	La tarjeta está deshabilitada o caducada, o el importe supera el saldo. El `message` indica cuál. El saldo no cambia	Corrige la causa. La `reference` no se consume, así que reintenta con la misma
`429`	Shopify está limitando las peticiones a tu tienda	Espera un momento y reintenta con la misma `reference`
`500`	No se pudo confirmar el resultado con Shopify	Reintenta con la misma `reference`: la tarjeta no se descuenta dos veces

Una petición fallida (404 o 422) no consume la reference.

Reintentos y duplicados¶

Genera una reference por canje y reutilízala solo cuando reintentes ese mismo canje. Si una petición agota el tiempo de espera o falla por la red, reintenta con la misma reference. Esto siempre es seguro: la tarjeta nunca se descuenta dos veces, y recibes el resultado original con "duplicate": true.

Actualizar una tarjeta de regalo¶

PUT /gift-cards/{gift_card_id}

Solo se pueden actualizar los siguientes campos:

Campo	Tipo	Descripción
`expires_on`	string	Fecha de caducidad
`note`	string	Nota interna
`template_suffix`	string	Sufijo de plantilla de Shopify
`customer_id`	integer	Cliente de Shopify que es propietario de la tarjeta. Puedes enviar `email` en su lugar, como al crear una tarjeta

La respuesta incluye el code cuando Gift Card Hero lo tiene registrado.

Deshabilitar una tarjeta de regalo¶

POST /gift-cards/{gift_card_id}/disable

Deshabilita la tarjeta de regalo de forma permanente. Esta acción no se puede deshacer. Devuelve la tarjeta deshabilitada.

Buscar tarjetas de regalo¶

GET /gift-cards/search

Parámetros:

Parámetro	Tipo	Descripción
`order`	string	Orden de clasificación
`query`	string	Consulta de búsqueda, por ejemplo `last_characters:mnop`. Usa `recipient:name@example.com` para encontrar tarjetas enviadas a un destinatario
`limit`	integer	Número máximo de resultados
`fields`	string	Lista de campos a incluir, separados por comas

Campos indexados (disponibles para las consultas de búsqueda):

created_at, updated_at, disabled_at, balance, initial_value, amount_spent, last_characters

Asignar códigos de tarjeta de regalo a un pedido¶

POST /gift-cards/assign-to-order

Asigna tus propios códigos de tarjeta de regalo a un pedido de Shopify, para tiendas que generan códigos fuera de la app. Solo funciona cuando Skip gift codes generation está activado en los ajustes de Regular products as gift cards; en caso contrario devuelve 400. También devuelve 400 si orderId no es numérico o si un código ya existe en tu tienda, y 404 si no se encuentra el pedido.

Admite la asignación de un solo código o de varios códigos.

Código único:

{
  "orderId": "1234567890",
  "giftCode": "ABCD-EFGH-IJKL-MNOP"
}

Varios códigos:

{
  "orderId": "1234567890",
  "giftCodes": [
    { "lineItemId": "111", "code": "ABCD-EFGH-IJKL-MNOP" },
    { "lineItemId": "222", "code": "QRST-UVWX-YZ12-3456" }
  ]
}

Respuesta:

{
  "scheduled": true
}

scheduled es false cuando el pedido no tiene tarjetas de regalo que procesar.

Paginación¶

El endpoint de transacciones usa paginación basada en cursor. La respuesta incluye una cabecera Link con el cursor de la siguiente página:

Link: <https://gifthero.syncu.be/api/external/gift-cards/transactions?page_info=CURSOR>; rel="next"

La cabecera no aparece en la última página. Extrae el valor page_info de la cabecera Link y pásalo como parámetro de consulta en tu siguiente petición, con los mismos filtros. La URL de la siguiente página ya los contiene.

Notas importantes¶

Unicidad de los códigos: al crear tarjetas de regalo con códigos personalizados, cada código debe ser único. La API devuelve un error si se envía un código duplicado.
Visibilidad de los códigos: la respuesta de creación incluye el código completo. En las respuestas posteriores aparece un campo code solo en las tarjetas cuyo código completo Gift Card Hero tiene registrado (las que generó y los códigos que asignaste). En las demás solo se devuelven los últimos 4 caracteres (last_characters). El endpoint de transacciones nunca devuelve códigos.
Reintentos de canje: envía siempre una reference única al canjear una tarjeta de regalo, y reintenta con la misma reference tras un tiempo de espera. Consulta Reintentos y duplicados.
Límites de peticiones: las peticiones se pasan a Shopify, así que se aplican los límites de Shopify para tu tienda. Si recibes una respuesta 429, espera un momento y reintenta.
Colección de Postman: cubre los endpoints de tarjetas de regalo excepto /gift-cards/transactions y /gift-cards/assign-to-order.

Colección de Postman¶

Descarga la colección de Postman para explorar la API rápidamente:

Descargar la colección de Postman