Primeros pasos

Las API de Giftpack permiten que tu backend cree y opere flujos de recompensas, incentivos, productos promocionales y elección por parte del destinatario. Giftpack gestiona la disponibilidad del catálogo, las experiencias de los destinatarios, la preparación de pedidos y las actualizaciones de entrega, mientras que tu sistema controla el disparador de negocio y los datos del cliente.

La URL base de producción es:

https://developer.giftpack.ai

Consulta la Referencia de la API para ver todos los esquemas de solicitud y respuesta. Utiliza esta guía para elegir la familia de recursos adecuada y entender cómo evolucionan los recursos después de crearlos.

Elegir un flujo

Modelo de recursos

Smart Gifting utiliza una campaign como contenedor del programa y un giftee para representar el ciclo de vida específico de cada destinatario:

Campaign -> Giftee -> Redemption -> Fulfillment -> Delivery

Los pedidos directos del catálogo utilizan un marketplace order como contenedor del pedido y un marketplace order receiver para representar el ciclo de vida específico de cada destinatario:

Marketplace Order -> Receiver -> Claim or Selection -> Fulfillment -> Delivery

No trates giftee y marketplace_order_receiver como conceptos intercambiables. Sus nombres de evento identifican familias de pedidos distintas, aunque sus estados de gestión logística puedan parecerse.

Ciclo de vida de una solicitud

Las solicitudes de creación y actualización devuelven el estado actual del recurso. Las acciones del destinatario, la preparación, el envío y la entrega continúan de forma asíncrona.

Para crear integraciones fiables:

• Guarda el ID del recurso devuelto.
• Suscríbete a la familia de eventos webhook correspondiente.
• Utiliza el id del evento webhook como clave de deduplicación.
• Concilia el estado mediante un endpoint GET cuando tu sistema detecte un evento omitido o retrasado.
• No reintentes automáticamente una solicitud que modifique el estado, salvo que la operación de la API documente explícitamente un contrato de idempotencia.

Primera solicitud

Después de crear una clave API en Giftpack, verifica el acceso con el catálogo de eventos webhook:

curl https://developer.giftpack.ai/v1/webhookeventtypes \
  --header 'Accept: application/json' \
  --header 'X-API-KEY: YOUR_API_KEY'

La respuesta enumera los tipos de eventos webhook que admite actualmente la API. Este endpoint, y no una lista codificada en el cliente, es el catálogo de eventos de referencia.

Siguientes pasos

1. Lee Autenticación y seguridad antes de almacenar o utilizar una clave API.
2. Selecciona un flujo en Guías de implementación.
3. Configura y verifica los webhooks antes de lanzar una integración en producción.
4. Consulta la Referencia de la API para conocer los campos obligatorios y los modelos de respuesta de cada endpoint.

Definiciones

Estas definiciones describen los objetos de dominio principales usados en integraciones API de Giftpack. Entender cómo se relacionan es clave antes de construir workflows. Giftpack opera en tres capas principales:

1. Capa de Engagement (Engagement Layer)
2. Capa de Comercio (Commerce Layer)
3. Capa de Supply y Operaciones (Supply & Operations Layer)

Recipient
  └─ may belong to Recipient Group
  └─ becomes Giftee when attached to Campaign

Campaign (Engagement Container)
  ├─ defines Redemption rules
  ├─ manages Giftee states
  └─ may generate Fulfillment Orders

Commerce Layer
  ├─ Marketplace Order (direct transaction)
  └─ Swag Order (inventory-based transaction)

Redemption
  ├─ Link-based
  ├─ Email-based
  └─ Transitions state before fulfillment

Autenticación y seguridad

Las operaciones principales de Giftpack bajo /v1 utilizan una clave API limitada a un workspace, enviada en la cabecera X-API-KEY. Las claves API solo deben utilizarse en aplicaciones de servidor de confianza.

Requisitos de acceso

La gestión de claves API está disponible en la configuración para desarrolladores. Tanto el workspace como el usuario actual deben tener acceso a la función Giftpack Open API y disponer de los permisos necesarios para la configuración de desarrolladores.

Si la página Developer no está disponible, pide a un administrador del workspace que confirme el plan contratado y tu rol antes de desarrollar la integración.

Crear y almacenar una clave

1. Inicia sesión en Giftpack.
2. Abre Developer Settings.
3. Crea una clave API para el entorno correspondiente.
4. Almacena la clave en un gestor de secretos del lado del servidor.

Nunca incluyas una clave API en JavaScript ejecutado en el navegador, una aplicación móvil, registros, capturas de pantalla, tickets de soporte ni en el control de versiones.

Utiliza credenciales distintas para staging y producción. Revoca de inmediato cualquier clave que pueda haber quedado expuesta.

Autenticar una solicitud

curl https://developer.giftpack.ai/v1/webhookeventtypes \
  --header 'Accept: application/json' \
  --header 'X-API-KEY: YOUR_API_KEY'

La clave API identifica el workspace. La autorización de los recursos se aplica en el servidor, por lo que disponer de un ID perteneciente a otro workspace no concede acceso a ese recurso.

Entorno y transporte

• Envía las solicitudes de producción a https://developer.giftpack.ai.
• Utiliza HTTPS en todas las solicitudes.
• Guarda las credenciales en un almacén de secretos específico para cada entorno.
• No reutilices una clave de producción en el desarrollo local.

Algunas operaciones de conectores en la Referencia de la API utilizan tokens bearer o autenticación específica del proveedor. Sigue el esquema de seguridad indicado en cada operación; no des por hecho que una clave API de Giftpack puede invocar un endpoint de conector.

Prácticas operativas

• Rota las credenciales de acuerdo con la política de seguridad de tu organización.
• Limita el acceso a la clave al servicio que la necesita.
• Oculta X-API-KEY en los registros de solicitudes y errores.
• Registra la operación, el ID del recurso, el estado HTTP y la marca de tiempo para facilitar los diagnósticos de soporte.
• Valida las firmas de los webhooks de forma independiente de la autenticación de las solicitudes a la API.

El contrato público no garantiza un límite de frecuencia universal ni una única política de reintentos para todas las operaciones. Utiliza las cabeceras específicas del endpoint y la Referencia de la API cuando estén disponibles, y ponte en contacto con Giftpack antes de planificar picos de tráfico de gran volumen.

Errores y recuperación

Las operaciones de Giftpack utilizan códigos de estado HTTP estándar. Las respuestas de error documentadas en la Referencia de la API utilizan application/problem+json.

Respuesta de problema

{
  "type": "about:blank",
  "title": "Bad Request",
  "status": 400,
  "detail": "Property email is required but is missing.",
  "instance": "https://developer.giftpack.ai/errors/example",
  "errors": [
    {
      "location": "body.email",
      "message": "The email field is required.",
      "value": null
    }
  ]
}

Campos

• type: URI que identifica el tipo de problema. Puede ser about:blank.
• title: resumen estable y legible del problema.
• status: estado HTTP asociado a esta respuesta.
• detail: explicación de este fallo concreto.
• instance: URI que identifica esta incidencia, cuando se proporciona.
• errors: información opcional de cada campo, con location, message y value.

No se garantiza que todos los campos estén presentes en todos los errores. Crea analizadores que toleren campos opcionales omitidos y campos futuros desconocidos.

Recuperación según el estado

La Referencia de la API es la fuente de autoridad para las respuestas documentadas de cada operación.

Seguridad de los reintentos

Por lo general, las solicitudes GET pueden reintentarse con un backoff exponencial limitado. Las solicitudes que modifican el estado requieren más precaución:

• No reintentes a ciegas solicitudes POST o PATCH después de un timeout.
• Comprueba primero si la operación documenta la idempotencia o devuelve un recurso que permita conciliar el estado.
• Conserva los ID devueltos antes de iniciar el paso siguiente.
• Utiliza tus propios campos de referencia de negocio cuando el endpoint los admita.
• Evita que varios workers envíen simultáneamente la misma operación lógica.

Un timeout de transporte significa que el cliente no recibió una respuesta; no demuestra que el servidor no completara la solicitud.

Datos de diagnóstico para soporte

Al escalar un problema, proporciona el endpoint, el método, la marca de tiempo UTC, el estado HTTP, los ID de recursos relevantes y una respuesta de problema con los datos sensibles ocultos. Nunca incluyas una clave API ni datos del destinatario sin ocultar.

Webhooks y eventos asíncronos

Los webhooks notifican las transiciones de los destinatarios y de la preparación que se producen después de que una solicitud a la API reciba respuesta. Utilízalos como señal principal del ciclo de vida y usa operaciones GET para conciliar el estado.

Catálogo de eventos

Obtén el catálogo actual en lugar de codificar una lista antigua:

curl https://developer.giftpack.ai/v1/webhookeventtypes \
  --header 'Accept: application/json' \
  --header 'X-API-KEY: YOUR_API_KEY'

El catálogo actual contiene dos familias de recursos.

giftee

Eventos del ciclo de vida de los destinatarios de pedidos de Smart Gifting, incluidas las campañas iniciadas mediante integraciones, los programas planificados y los flujos de recompensas automatizados.

• giftee.created
• giftee.launched
• giftee.preparing
• giftee.shipped
• giftee.delivered
• giftee.failed
• giftee.returned
• giftee.reviewed
• giftee.cancel
• giftee.resume
• giftee.delete

marketplace_order_receiver

Eventos del ciclo de vida de los destinatarios de pedidos realizados directamente a través de Gift Mall o Merchandise Catalog, fuera de los flujos de campañas de Smart Gifting.

• marketplace_order_receiver.created
• marketplace_order_receiver.launched
• marketplace_order_receiver.shipped
• marketplace_order_receiver.delivered
• marketplace_order_receiver.failed
• marketplace_order_receiver.returned
• marketplace_order_receiver.reviewed
• marketplace_order_receiver.delete

Contrato del payload

Cada entrega es un objeto JSON. data es una instantánea estructurada del recurso, no una cadena JSON escapada.

{
  "id": "123e4567-e89b-12d3-a456-426655440000",
  "type": "giftee.shipped",
  "data": {
    "id": "23e4567-e89b-12d3-a456-426655440000",
    "type": "giftee",
    "email": "recipient@example.com",
    "status": 12,
    "delivery_status": 2,
    "budget": 100,
    "campaign": {
      "id": "323e4567-e89b-12d3-a456-426655440000"
    },
    "recipient": {
      "id": "423e4567-e89b-12d3-a456-426655440000"
    },
    "delivery_tracking_code": "TRACKING-CODE"
  },
  "created_at": "2026-09-01 15:23:33"
}

• id es el ID permanente de la ocurrencia del evento y debe utilizarse como clave de deduplicación.
• type identifica la familia de recursos y la transición.
• data captura el estado del recurso cuando se produjo el evento. Los campos varían según la familia de recursos y la etapa del ciclo de vida.
• created_at indica el momento en que se produjo el evento. Las entregas pueden llegar desordenadas, por lo que debes utilizar este valor para ordenar las transiciones.
• Los eventos de eliminación conservan la última instantánea almacenada después de eliminar el recurso activo.

Verificación de la firma

Giftpack envía en X-Giftpack-Signature el resumen HMAC-SHA256 hexadecimal en minúsculas del cuerpo sin procesar de la solicitud.

const crypto = require('crypto');

function verifyGiftpackWebhook(rawBody, signature, secret) {
  if (!signature) return false;

  const expected = crypto.createHmac('sha256', secret).update(rawBody).digest('hex');
  const actualBuffer = Buffer.from(signature, 'utf8');
  const expectedBuffer = Buffer.from(expected, 'utf8');

  return (
    actualBuffer.length === expectedBuffer.length &&
    crypto.timingSafeEqual(actualBuffer, expectedBuffer)
  );
}

Verifica la firma antes de analizar o procesar el payload. Almacena los secretos de los webhooks en un gestor de secretos del lado del servidor.

Entrega y reintentos

• Giftpack envía una solicitud HTTP POST con un cuerpo JSON.
• Cualquier respuesta 2xx marca la entrega como correcta.
• Una solicitud puede permanecer abierta hasta 60 segundos.
• Las entregas fallidas se reintentan después de aproximadamente 1, 5 y 15 minutos, con un máximo de cuatro intentos de entrega, incluida la solicitud inicial.
• Pueden producirse entregas duplicadas. Procesa el id de forma idempotente.
• El orden de entrega no está garantizado.

Devuelve rápidamente una respuesta 2xx después de validar y aceptar el evento de forma persistente. Envía el trabajo costoso a una cola.

Estado del registro de eventos

Los registros de eventos y solicitudes de webhook utilizan estos estados numéricos:

• -1: fallido
• 0: en proceso
• 1: correcto

La respuesta detallada del evento incluye los datos estructurados de webhook_event_data, el número de intentos y los registros de cada solicitud para facilitar la resolución de problemas.

Lista de comprobación para producción

• Suscríbete únicamente a las familias de eventos que genere tu flujo.
• Verifica X-Giftpack-Signature con el cuerpo sin procesar y sin modificar.
• Deduplica por el id del evento.
• Almacena created_at y admite llegadas desordenadas.
• Devuelve 2xx solo después de aceptar el evento de forma segura.
• Supervisa los eventos que alcancen el estado fallido.
• Utiliza la acción de prueba del panel de control antes de habilitar un endpoint de producción.

Guías de implementación

Elige la familia de recursos que se corresponda con la forma en que el destinatario recibe la recompensa. La Referencia de la API sigue siendo la fuente de autoridad para todos los campos obligatorios y modelos de respuesta.

curl https://developer.giftpack.ai/v1/marketplaceorders \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: YOUR_API_KEY' \
  --data '{
    "marketplace_order_name": "September employee rewards",
    "marketplace_order_start_date": "2026-09-01",
    "marketplace_order_end_date": "2026-09-30",
    "marketplace_order_type": "Normal",
    "submit": false,
    "receivers": [
      {
        "member_id": "9a1232aa-238f-421c-82e7-45693d1b25b4",
        "country": "US",
        "gift_message": "Thank you for your contribution.",
        "email_notification": true,
        "sms_notification": false,
        "marketplace_feature": false,
        "donation_feature": false,
        "products": [
          {
            "marketplace_product_id": "961be65a-88d8-4040-8808-843ccf5da624",
            "marketplace_product_variant_id": "961be65a-a96a-412d-b22a-325f07d85647",
            "product_quantity": 1
          }
        ]
      }
    ]
  }'

curl https://developer.giftpack.ai/v1/pointrecipients/MEMBER_ID/points \
  --request PATCH \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: YOUR_API_KEY' \
  --data '{
    "credits": 1,
    "points": 100,
    "expired_at": "2027-09-01",
    "notes": "Annual recognition allocation"
  }'

Antes de producción

• Valida los campos obligatorios con la Referencia de la API actual.
• Realiza pruebas con destinatarios y credenciales que no sean de producción.
• Conserva todos los ID de recursos devueltos.
• Configura la familia de webhooks correspondiente.
• Verifica las firmas y deduplica los eventos.
• Define cómo conciliará tu sistema los timeouts antes de reintentar una solicitud que modifique el estado.