Introducción

En lugar de construir un portal de recompensas separado o coordinar proveedores manualmente, puedes orquestar eventos de regalo (gifting events) directamente desde tus sistemas empresariales existentes, como CRM, HRIS o plataformas internas de operaciones. La API permite que tu aplicación dispare, gestione y supervise estos momentos de engagement de forma programática, mientras Giftpack gestiona la ejecución logística (fulfillment), disponibilidad, logística y cumplimiento.

Giftpack no está estructurado como una API tradicional de e-commerce. En vez de centrarse en catálogos de productos y transacciones de checkout, el sistema modela los regalos (gifting) como eventos relacionales. La identidad del destinatario, el momento y el contexto de negocio se tratan como entradas de primer nivel junto con el artículo enviado. Esto permite que las integraciones se alineen de forma natural con disparadores reales, como onboarding, aniversarios, cierre de oportunidades, campañas de retención o hitos de engagement de clientes.

La API ofrece visibilidad del ciclo de vida en cada etapa del proceso, incluido el estado de redemption, el progreso de fulfillment y el seguimiento de entrega (delivery tracking). Estos endpoints permiten que tus sistemas midan resultados, automaticen acciones de seguimiento e incorporen los regalos (gifting) en flujos de reporting y operaciones.

Concepto Central

A nivel de sistema, Giftpack sigue este modelo de ciclo de vida:

Intent → Campaign → Recipient → Redemption → Fulfillment → Tracking

Cada etapa representa una transición de estado en el ciclo de engagement:

• Intent define el disparador de negocio o propósito.
• Campaign actúa como contenedor de engagement.
• Recipient representa la identidad que participa en la campaña.
• Redemption captura la acción del destinatario.
• Fulfillment gestiona el proceso operativo de ejecución logística.
• Tracking proporciona visibilidad posterior y analítica.

Diagrama del ciclo de vida

EVENTO DE NEGOCIO
    │
    ▼
[ Intent ]
    │
    │  (API síncrona)
    ▼
[ Campaign Created ]
    │
    │  (API síncrona)
    ▼
[ Recipient Attached ]
    │
    │  (API síncrona)
    ▼
[ Redemption Link Issued ]
    │
    │  ────── Acción del usuario (asíncrona) ──────
    ▼
[ Redemption Claimed ]
    │
    │  (Webhook: giftee.preparing)
    ▼
[ Shipment Processing ]
    │
    │  (Webhook: giftee.shipped)
    ▼
[ Tracking / Delivered ]
    │
    │  (Webhook: giftee.delivered / giftee.failed / giftee.returned)
    ▼
[ Final Tracking State ]
    │
    │  (Webhook: giftee.reviewed)
    ●

Este modelo se aplica de forma consistente a campañas de regalos inteligentes (smart gifting) AutoMatch™, órdenes de marketplace (marketplace orders), flujos de artículos promocionales (swag workflows) y casos de automatización empresarial. Entender este modelo es clave para construir integraciones confiables en entornos asíncronos y orientados a eventos.

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

Todas las solicitudes a la Giftpack Integration API deben autenticarse con una API Key válida.

La autenticación es obligatoria en todos los endpoints y se aplica por límite de workspace. Las solicitudes no autorizadas o mal autenticadas se rechazan antes de ejecutar la lógica de negocio.

Claves API

Cada workspace de Giftpack puede generar una o más API Keys desde el panel de Giftpack.

Las API Keys se usan para:

• Autenticar solicitudes API
• Identificar el workspace de origen
• Aplicar autorización a nivel de recurso
• Aplicar controles de uso y límites de tasa

Las API Keys son workspace-scoped. No pueden acceder a recursos fuera del workspace de origen.

Giftpack no comparte API Keys entre workspaces.

Obtener una API Key

Para generar una API Key:

1. Inicia sesión en el panel de Giftpack
2. Ve a Integration Hub → API Keys
3. Genera una nueva API Key en Giftpack Integration

Las API Keys se activan inmediatamente al crearse. Los eventos de creación de keys se registran para auditoría y trazabilidad.

Uso de la API Key

Incluye tu API Key en el header X-API-KEY en cada solicitud.

GET /v1/recipients HTTP/1.1
Host: developer.giftpack.ai
X-API-KEY: YOUR_API_KEY

Las solicitudes sin API Key válida devolverán error de autenticación. La autenticación ocurre antes del procesamiento de la solicitud y la evaluación de recursos.

Modelo de autorización

La autorización se aplica a nivel de workspace. Una API Key solo puede acceder a:

• Recipients
• Campaigns
• Marketplace Orders
• Swag Orders
• Credits
• Providers
• Otros recursos de su propio workspace

El acceso entre workspaces está estrictamente prohibido. Las decisiones de autorización se aplican en servidor y no pueden sobrescribirse con parámetros de cliente.

Gestión del ciclo de vida de keys

Las integraciones empresariales deben implementar controles adecuados del ciclo de vida de keys.

Prácticas recomendadas:

• Usar API Keys separadas para staging y producción
• Rotar API Keys periódicamente
• Revocar API Keys de inmediato si se sospecha compromiso
• Evitar compartir API Keys entre equipos o sistemas

Si una API Key se revoca, todas las solicitudes posteriores con esa key serán rechazadas.

Giftpack no rota API Keys automáticamente. La gestión de keys es responsabilidad del integrador.

Seguridad de transporte

Todas las solicitudes API deben realizarse por HTTPS.

• Versión mínima de TLS: TLS 1.2
• Solicitudes HTTP sin cifrar son rechazadas

Todos los datos en tránsito se cifran con TLS estándar de la industria.

Esto incluye:

• Datos de Recipient
• Información de envío
• Metadatos de órdenes
• Headers de autenticación

Giftpack no soporta conexiones de transporte inseguras.

Limitación de tasa

Las solicitudes API están sujetas a rate limiting para asegurar estabilidad y uso justo. Si se excede el límite, la API devolverá:

• Estado HTTP 429
• Código de error RATE_LIMIT_EXCEEDED

Las integraciones deben:

• Implementar lógica de reintento
• Usar estrategias de exponential backoff
• Evitar polling agresivo

Para cargas empresariales de alto volumen o picos, contacta a Giftpack para ajustar configuración de rate.

Privacidad de datos y manejo de PII

Las APIs de Giftpack pueden procesar información personal identificable (PII), incluyendo:

• Nombres de recipients
• Direcciones de correo
• Direcciones de envío

Responsabilidades del desarrollador:

• Asegurar base legal para el procesamiento de datos
• Obtener consentimiento cuando aplique
• Cumplir regulaciones relevantes (p. ej., GDPR, CCPA)
• Minimizar almacenamiento de datos innecesarios

Giftpack procesa datos únicamente para ejecutar flujos de gifting y rewards. Giftpack no usa datos de recipients para publicidad ni perfilado no relacionado.

Consideraciones de logging y auditoría

Para entornos empresariales, las integraciones deben:

• Registrar outbound API requests
• Registrar códigos de respuesta y estados de error
• Monitorear fallos de autenticación anómalos
• Monitorear eventos inesperados de rate-limit

Giftpack mantiene logging interno de:

• Intentos de autenticación
• Uso de keys
• Eventos relevantes de seguridad

Respuestas de error de autenticación

Los errores de autenticación y autorización siguen una estructura consistente.

{
  "error_code": "UNAUTHORIZED",
  "message": "Invalid or missing API key",
  "action": "Verify your API key and include it in the X-API-KEY header"
}

Códigos de error comunes relacionados con autenticación:

• UNAUTHORIZED
• FORBIDDEN
• RATE_LIMIT_EXCEEDED

Mejores prácticas de seguridad

Para despliegues de producción:

• Guardar API Keys en variables de entorno seguras
• No exponer API Keys en frontend o aplicaciones client-side
• No subir API Keys al control de versiones
• Restringir acceso interno a keys de producción
• Priorizar integraciones server-to-server

Si sospechas que una API Key está comprometida:

1. Revoca la key de inmediato
2. Genera una key de reemplazo
3. Revisa logs recientes de API para detectar uso anómalo

Manejo de Errores y Mapa de Estados

La Giftpack API usa códigos HTTP convencionales y devuelve payloads de error estructurados.

Todas las respuestas de error incluyen un código de error legible por máquina y un request_id. Registra siempre el request_id al contactar soporte.

Formato de Respuesta de Error

Todos los errores siguen esta estructura:

{
  "error": {
    "code": "invalid_request",
    "message": "Recipient email is required.",
    "request_id": "req_123"
  }
}

Campos

• code – Identificador de error legible por máquina
• message – Explicación legible para humanos
• request_id – Identificador único de trazabilidad para depuración

El request_id debe conservarse en tus logs para troubleshooting operativo.

Códigos de Estado HTTP

Giftpack usa semántica estándar de estados HTTP:

• 200 / 201 – Solicitud exitosa
• 400 – Validación fallida o solicitud mal formada
• 401 – API Key ausente o inválida
• 403 – Permisos insuficientes
• 404 – Recurso no encontrado
• 409 – Conflicto (ej. recurso duplicado o violación de estado)
• 429 – Límite de tasa excedido
• 5xx – Error interno del servidor

Guía de Reintentos

No todos los errores deben reintentarse.

Seguro para Reintentar

• 429 (Límite de tasa excedido)
• 5xx (Errores del servidor)

Usa exponential backoff al reintentar. Evita reintentos inmediatos y agresivos.

No Reintentar

• 400 (Errores de validación)
• 401 / 403 (Fallas de autenticación o permisos)
• 404 (Referencia de recurso inválida)
• 409 (Conflictos de lógica de negocio)

Estos errores indican problemas del lado cliente que deben corregirse antes de reenviar.

Estado Asíncrono vs Estado HTTP

Una respuesta HTTP exitosa no garantiza que el fulfillment haya finalizado.

Por ejemplo:

• 201 Created confirma que se creó un campaign
• No confirma redemption
• No confirma shipment
• No confirma delivery

Las operaciones de Giftpack suelen progresar de forma asíncrona.

Para determinar el estado del lifecycle:

• Consulta el estado del recurso vía endpoints GET
• O escucha eventos webhook

Trata siempre un HTTP exitoso como aceptación de solicitud, no como finalización de negocio.

Consideraciones de Idempotencia

Si tu integración realiza reintentos, asegúrate de que solicitudes duplicadas no generen efectos secundarios no deseados.

Cuando aplique:

• Usa external identifiers únicos
• Guarda tus propios request tracking IDs
• Evita reintentos ciegos sobre errores 4xx

Giftpack puede rechazar creación duplicada de recursos según la lógica del endpoint.

Comportamiento de Rate Limiting

Cuando se exceden los límites de tasa:

• Se devuelve estado HTTP 429
• Reintenta después de una espera

Las integraciones deben:

• Implementar exponential backoff
• Evitar bucles de polling cerrados
• Preferir actualizaciones por webhook en lugar de polling GET frecuente

Soporte y Diagnóstico

Si encuentras errores inesperados:

• Registra el payload completo del error
• Registra el request_id
• Proporciona el request_id al contactar soporte de Giftpack

Esto permite una trazabilidad rápida en logs de servidor.

Webhooks y Eventos Asíncronos

Los flujos de Giftpack son asíncronos.

Una respuesta API exitosa confirma que la solicitud fue aceptada. Las actualizaciones de lifecycle como redemption, fulfillment, shipping y delivery se comunican por eventos webhook.

Las integraciones de producción deben tratar webhooks como el mecanismo principal de actualización de estado. El polling de endpoints de estado debe usarse solo para reconciliación o recuperación.

Tipos de Eventos Soportados

Los tipos de evento webhook se gestionan y muestran en el dashboard de Giftpack. Para ver o configurar los triggers disponibles:

https://giftpack.ai/app/developer/webhooks

La UI del dashboard es la fuente de verdad sobre eventos disponibles en producción.

Ejemplos soportados actualmente:

• giftee.created
• giftee.launched
• giftee.preparing
• giftee.shipped
• giftee.delivered
• giftee.failed
• giftee.returned
• giftee.reviewed

La disponibilidad puede evolucionar. Revisa siempre el dashboard al configurar producción.

Configuración de Webhook

Los webhooks se configuran por workspace desde el dashboard. Cada configuración incluye:

• name
• endpoint
• event_types
• toggle active
• secret key con alcance de workspace

Ejemplo:

{
  "name": "Giftpack Delivery Updates",
  "endpoint": "https://example.com/webhooks/giftpack",
  "event_types": [
    "giftee.created",
    "giftee.shipped",
    "giftee.delivered"
  ]
}

Puede haber múltiples configuraciones por workspace.

Modelo de Entrega

La entrega webhook sigue un modelo at-least-once.

Esto significa:

• Un mismo evento puede entregarse más de una vez
• El orden de entrega no está estrictamente garantizado
• Debes implementar handlers idempotentes

Una entrega se considera exitosa cuando tu endpoint responde con cualquier código HTTP 2xx.

Respuestas no-2xx provocarán intentos adicionales.

Contrato del Endpoint Receptor

Tu endpoint webhook debe:

• Aceptar POST con payload JSON
• Responder 2xx para confirmar éxito
• Completar dentro de una ventana de timeout razonable
• Manejar duplicados de forma segura

Ejemplo de ack:

HTTP/1.1 200 OK
Content-Type: application/json

{"ok": true}

Usa el webhook event ID como clave de deduplicación.

Log de Eventos e Intentos de Entrega

Giftpack ofrece un log completo de eventos webhook en el dashboard. Cada evento incluye:

• Metadatos del evento
• Payload en bruto
• Estado de entrega
• Conteo de intentos
• Diagnóstico request/response por intento

Estados en logs:

• 0 – failed
• 1 – processing
• 2 – success

El API de detalle de evento expone:

• Webhook event (evento lógico)
• Webhook event requests (intentos individuales)

Ejemplo de detalle:

{
  "webhook_event_id": "wev_01H...",
  "webhook_setting_id": "whs_01H...",
  "webhook_event_type": "giftee.shipped",
  "webhook_event_resource_type": "giftee",
  "webhook_event_resource_id": "gft_01H...",
  "webhook_event_status": 2,
  "webhook_event_attempts": 1,
  "webhook_event_data": "{...raw payload...}",
  "webhook_event_created_at": "2026-02-20T02:00:00.000Z",
  "webhook_event_updated_at": "2026-02-20T02:00:01.000Z"
}

Cada intento incluye:

• endpoint destino
• estado HTTP
• headers de respuesta
• body de respuesta
• timestamp

Este log habilita trazabilidad completa y facilita depuración.

Consola de Prueba de Webhooks

Giftpack proporciona una consola de prueba integrada. Permite:

• Seleccionar endpoint webhook
• Elegir tipo de evento
• Enviar payload simulado
• Ver la respuesta en vivo del endpoint

Esto habilita:

• Validación end-to-end
• Inspección de payload
• Diagnóstico inmediato de respuesta

Ejemplo de respuesta:

{
  "event_data": {
    "type": "giftee.created",
    "resource_type": "giftee",
    "resource_id": "gft_01H..."
  },
  "response_http_status": "200",
  "response_http_headers": {"content-type": "application/json"},
  "response_http_body": "{\"ok\":true}"
}

La consola está pensada para desarrollo y validación previa a producción.

Requisitos de Transporte

Aunque la UI actual pueda permitir http y https, en producción debes usar siempre HTTPS.

HTTPS garantiza:

• Transporte cifrado
• Protección contra interceptación
• Cumplimiento de requisitos enterprise

Mejores Prácticas de Integración

Para un manejo webhook confiable:

• Usa procesamiento idempotente
• Registra todos los eventos entrantes
• Guarda IDs de evento para deduplicación
• Evita procesamiento síncrono largo en el handler
• Desplaza trabajo pesado a background jobs
• Monitorea intentos de entrega fallidos

La integración basada en webhook es la fuente autoritativa del lifecycle. No asumas que respuestas API síncronas representan estado final.

Verificación de Firma Webhook

Para asegurar que los eventos vienen de Giftpack y no fueron alterados, cada request webhook se firma con un secret por workspace.

Las integraciones de producción deben verificar la firma.

Formato del Header de Firma

Cada request incluye:

X-GIFTPACK-SIGNATURE: t=1708459200,v1=abcdef1234567890...

Componentes

• t — timestamp Unix (segundos)
• v1 — firma HMAC SHA-256

Generación:

HMAC_SHA256(secret, `${timestamp}.${raw_body}`)

Debe usarse el raw body exactamente como se recibe.

Proceso de Verificación

Pasos:

1. Extraer header X-GIFTPACK-SIGNATURE
2. Parsear t y v1
3. Obtener raw body antes de parsear JSON
4. Calcular:

expected_signature = HMAC_SHA256(secret, `${timestamp}.${raw_body}`)

1. Comparar con timing-safe comparison
2. Rechazar si:

• La firma no coincide
• El timestamp es demasiado antiguo (recomendado: > 5 minutos)

Protección contra Replay Attacks

Para prevenir replay attacks:

• Validar timestamp reciente (±300 segundos)
• Guardar event IDs procesados y rechazar duplicados
• No aceptar payloads sin firma

Ventana ejemplo:

current_time - timestamp <= 300 seconds

Ejemplo (Node.js)

const crypto = require('crypto');

function verifySignature(rawBody, signatureHeader, secret) {
  if (!signatureHeader) return false;

  const elements = signatureHeader.split(',');
  const timestamp = elements.find(e => e.startsWith('t='))?.split('=')[1];
  const signature = elements.find(e => e.startsWith('v1='))?.split('=')[1];

  if (!timestamp || !signature) return false;

  const payload = `${timestamp}.${rawBody}`;

  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload, 'utf8')
    .digest('hex');

  const isValid = crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signature)
  );

  const currentTime = Math.floor(Date.now() / 1000);
  const tolerance = 300;

  if (Math.abs(currentTime - Number(timestamp)) > tolerance) {
    return false;
  }

  return isValid;
}

Ejemplo Express:

app.post('/webhooks/giftpack',
  express.raw({ type: 'application/json' }),
  (req, res) => {
    const signature = req.headers['x-giftpack-signature'];
    const isValid = verifySignature(
      req.body.toString(),
      signature,
      process.env.GIFTPACK_WEBHOOK_SECRET
    );

    if (!isValid) {
      return res.status(400).send('Invalid signature');
    }

    const event = JSON.parse(req.body.toString());

    // Process event safely

    res.status(200).json({ ok: true });
});

Gestión de Secrets

Los webhook secrets:

• Son únicos por configuración
• Deben guardarse de forma segura (variables de entorno)
• Nunca deben exponerse en código client-side
• Deben rotarse si se sospecha compromiso

Si rotas un secret, actualiza tu integración de inmediato.

Manejo de Fallas

Si falla la verificación:

• Devuelve estado HTTP no-2xx
• No proceses el payload
• Registra el fallo para monitoreo de seguridad

Fallos repetidos pueden indicar:

• Secret incorrecto
• Endpoint mal configurado
• Tráfico malicioso

Recordatorio del Modelo de Entrega

La entrega webhook sigue at-least-once. Los eventos duplicados son posibles.

Construido por Casos

Giftpack API está diseñado alrededor de workflows de negocio reales.

En lugar de navegar endpoints directamente, elige primero el caso de negocio que vas a implementar. Cada caso describe:

• Intención de negocio
• Secuencia API
• Lifecycle esperado
• Eventos webhook relevantes

La verificación de firma webhook se documenta en Webhooks y Eventos Asíncronos.

Create Campaign
      ↓
Add Giftee
      ↓
Generate Redemption Link
      ↓
Recipient Claims
      ↓
Order Processing
      ↓
Shipped
      ↓
Delivered / Failed / Returned

POST /v1/campaigns

POST /v1/giftees

POST /v1/campaigns/{campaignId}/giftees/{gifteeId}/redeemlink

giftee.created
giftee.launched
giftee.preparing
giftee.shipped
giftee.delivered
giftee.failed
giftee.returned
giftee.reviewed

Select Product
      ↓
Create Marketplace Order
      ↓
Preparing
      ↓
Shipped
      ↓
Delivered / Failed / Returned

GET /v1/providers/{providerCode}/products

GET /v1/providers/{providerCode}/products/{productId}

POST /v1/marketplaceorders

giftee.preparing
giftee.shipped
giftee.delivered
giftee.failed
giftee.returned

Enable Points
      ↓
Allocate Points
      ↓
Recipient Redeems
      ↓
Giftee Created
      ↓
Fulfillment Lifecycle

POST /v1/pointrecipients/{memberId}/enablepointfeature

PATCH /v1/pointrecipients/{memberId}/points

giftee.created
giftee.preparing
giftee.shipped
giftee.delivered
giftee.failed
giftee.returned