Herramientas para desarrolladores¶

La página For developers ofrece acceso a la API, la configuración de webhooks, el modo headless y opciones avanzadas de integración. Ábrela desde For developers en la navegación de la izquierda.

Los cambios en las casillas y en las URL de webhooks de esta página se aplican cuando haces clic en Save en la barra de guardado. Los botones de token y Generate Secret actúan de inmediato. Enable headless mode también necesita Save.

Herramientas para desarrolladores

Storefront API¶

La Storefront API es una interfaz de JavaScript (window.GiftHeroAPI) para crear tu propia interfaz de selección y compra de tarjetas de regalo en tu tienda online.

Enable storefront API — actívala para cargar la API de JavaScript en la página de producto de tu tarjeta de regalo. La interfaz de tarjeta de regalo que genera la app se desactiva en esa página, así que tu desarrollador construye la interfaz.
Disable gift card page animation — aparece cuando la storefront API está activada. Elimina la página animada de tarjeta de regalo de la app, para que puedas crear una página personalizada.

La API no lee saldos. Recoge las opciones de la tarjeta de regalo (importe, diseño, mensaje, destinatario) y añade la tarjeta al carrito.

Referencia completa de la API: Storefront API

REST API¶

La REST API te permite integrar Gift Card Hero con sistemas externos: CRM, paneles de analíticas, plataformas de fidelidad y más.

Activación¶

Marca Enable REST API y guarda. Después haz clic en Send me access token: Gift Card Hero envía el token de acceso a la API a la dirección de correo de contacto de la tienda que aparece en la página.

Tu tienda tiene un único token de API a la vez, compartido por todas las integraciones que lo usan:

Send me access token emite un token nuevo. El anterior deja de funcionar de inmediato, así que actualiza tus integraciones con el nuevo token. Para volver a consultar el token, busca el correo anterior.
Revoke access token desactiva el token actual sin emitir uno nuevo: úsalo si el token pudo haberse filtrado o si un socio ya no necesita acceso.
Desactivar Enable REST API también revoca el token.

Detalles: Gestionar tu token de API

En la página hay un enlace a la Postman collection para explorar la API rápidamente. Show available API endpoints muestra los endpoints principales en la propia página.

Endpoints disponibles¶

Método	Endpoint	Descripción
`POST`	`/api/external/gift-cards`	Crear una tarjeta de regalo
`POST`	`/api/external/gift-cards/{id}/disable`	Desactivar una tarjeta de regalo
`GET`	`/api/external/gift-cards`	Listar tarjetas de regalo (filtrable por estado)
`GET`	`/api/external/gift-cards/{id}`	Obtener una tarjeta de regalo
`GET`	`/api/external/gift-cards/search?query=...`	Buscar tarjetas de regalo (por ejemplo, `last_characters:mnop`)
`PUT`	`/api/external/gift-cards/{id}`	Actualizar una tarjeta de regalo
`PUT`	`/api/external/gift-cards/{id}/balance`	Actualizar el saldo de una tarjeta de regalo
`POST`	`/api/external/gift-cards/{id}/redeem`	Canjear una tarjeta de regalo desde una app de POS o de caja (envía la notificación de canje y registra la sucursal)
`GET`	`/api/external/gift-cards/transactions`	Tarjetas de regalo con sus transacciones, paginadas
`POST`	`/api/external/gift-cards/assign-to-order`	Asignar tus propios códigos de tarjeta de regalo a un pedido

Referencia completa de la API: Referencia de la REST API

Webhooks¶

Configuración de webhooks

Gift Card Hero puede enviar solicitudes HTTP POST a tu servidor cuando ocurren eventos específicos de tarjetas de regalo.

Los ajustes de webhooks aparecen en esta página una vez que Enable REST API está activado.

Configurar un secreto de webhook¶

Haz clic en Generate Secret para crear un secreto de firma. Cópialo del banner de inmediato, porque solo se muestra una vez. Úsalo en tu servidor para verificar que los datos recibidos vienen de Gift Card Hero. La firma se envía en el encabezado X-GiftHero-Signature (HMAC-SHA256).

Haz clic en Regenerate Secret para rotar el secreto, por ejemplo si se ha filtrado. El secreto anterior deja de funcionar al instante, así que actualiza tu servidor con el nuevo.

Endpoints de webhooks¶

Configura las URL de tu servidor para estos tipos de webhook:

Campo de la página	Cuándo se activa
Order with gift card webhook URL	Las tarjetas de regalo de un pedido son procesadas por Gift Card Hero
Gift card payment webhook URL	Se crea un pedido que se pagó con una tarjeta de regalo
Gift card balance webhook URL	Por ahora no se envía (consulta la guía de integración)

Introduce la URL de tu endpoint en cada campo y guarda. Una URL nueva o modificada debe empezar por https:// y ser accesible desde internet; las direcciones de red privada se rechazan al guardar.

Guía de integración completa: Guía de integración de webhooks

Custom Code Editor¶

Añade CSS personalizado a los componentes de tienda de Gift Card Hero sin modificar tu tema de Shopify directamente.

Haz clic en Open custom code editor. Se abre la pestaña Custom code en Settings.

Editor de código personalizado

Tu CSS se añade a las páginas de producto de tarjeta de regalo, a la página de tarjeta de regalo y a las páginas de los productos de tarjetas físicas y de importe personalizado. No se añade al resto de tu tienda. Úsalo para ajustar el aspecto del constructor de tarjetas de regalo y de la página de tarjeta de regalo. Haz clic en Save en la barra de guardado para aplicar los cambios.

Solo CSS

El editor solo acepta CSS. Al guardar se rechaza el CSS que contenga </style. El JavaScript personalizado que se configuró para tu tienda antes de este cambio sigue funcionando, pero ya no se puede editar aquí. Para cambiarlo, contacta con soporte.

Guardar datos de tarjetas de regalo en un metafield¶

Marca Save a gift card data to a metafield para guardar los datos de cada tarjeta (diseño, mensaje, remitente) en un metafield de Shopify de tu tienda:

Namespace: gift_hero
Key: cards_data

Los datos se indexan por los últimos cuatro caracteres del código de la tarjeta. Así quedan disponibles en las plantillas de correo de Shopify durante la generación de la tarjeta y en tus propias plantillas Liquid.

Disable gift card page animation for templates with suffix — desactiva la página animada de tarjeta de regalo de la app para las tarjetas que tengan un sufijo de plantilla asignado (consulta template_suffix en la REST API), para que se muestre tu propia plantilla.

Modo headless¶

Activa el modo headless para tiendas personalizadas o headless de Shopify que no usan el sistema de temas estándar de Shopify.

Haz clic en Enable headless mode (la etiqueta de estado cambia a Enabled). Aparece un fragmento de código con valores de ejemplo que debes sustituir por los de tu tienda:

Marcador	Sustitúyelo por
`[MONEY_FORMAT]`	La cadena de formato de moneda de tu tienda
`[PRODUCT_ID]`	El ID numérico de Shopify de tu producto de tarjeta de regalo
`[MYSHOPIFY_DOMAIN]`	El dominio `.myshopify.com` de tu tienda
`[ADD_TO_CART_CALLBACK]`	Tu función JavaScript personalizada para añadir al carrito
`[LOCALE]`	El código de idioma de tus traducciones (por ejemplo, `en`, `fr`). `en` es el predeterminado

Copia el fragmento e intégralo en el código de tu tienda personalizada.

Guía de configuración completa: Guía de integración headless

Cumplimiento personalizado¶

Esta sección aparece solo en las tiendas que usan la opción de cumplimiento propio. Con ella, Gift Card Hero se encarga por completo de crear y entregar las tarjetas de regalo de un pedido, en lugar del cumplimiento automático de tarjetas de regalo de Shopify.

Desactiva primero el cumplimiento automático en Shopify

En los ajustes de checkout (procesamiento de pedidos) de Shopify, elige Don't fulfill any of the order's line items automatically. La página enlaza a Check settings y a una guía de Shopify. No cumplas tú mismo las tarjetas de regalo de un pedido: deben seguir sin cumplir.

La etiqueta muestra el estado actual (Enabled o Disabled). Haz clic en Enable custom fulfilment o Disable custom fulfilment para cambiarlo.