Guía de Migración: API v1 a v2 de gigstack#

📋 Tabla de Contenidos#

🚀 Resumen de Cambios#

🔗 Cambios en la URL Base#

v1 (Antigua)#

https://https://gigstack-cfdi-bjekv7t4.uc.gateway.dev/v1

v2 (Nueva)#

Production: https://api.gigstack.io/v2
Staging: https://api.gigstack.io/v2 (usar API key de test)

⚠️ Acción Requerida#

🔐 Cambios en Autenticación#

v1#

v2#

📝 Cómo Obtener tu Token#

Ejemplo de Actualización#

📦 Cambios en Estructura de Respuestas#

v1 - Respuestas Inconsistentes#

// Algunas respuestas devolvían el objeto directamente
{
  "id": "client_123",
  "name": "Juan Pérez"
}

// Otras envolvían en diferentes estructuras
{
  "success": true,
  "result": { ... }
}

v2 - Respuestas Estandarizadas#

✅ Respuesta Exitosa (Objeto Único)#

{
  "message": "Description of action",
  "data": {
    "id": "client_123",
    "name": "Juan Pérez",
    "rfc": "XAXX010101000"
  }
}

📋 Respuesta de Lista (Paginada)#

{
  "message": "Items retrieved successfully",
  "data": [
    { "id": "client_1", "name": "Cliente 1" },
    { "id": "client_2", "name": "Cliente 2" }
  ],
  "next": "cursor_for_next_page",
  "has_more": true,
  "total_results": 150
}

❌ Respuesta de Error#

{
  "message": "Error description",
  "error": "Specific error details"
}

⚠️ Acción Requerida#

🔀 Cambios en Endpoints#

Recursos Principales#

⚠️ Cambio Importante: Products → Services#

🆕 Nuevas Funcionalidades en v2#

1. gigstack Connect (Multi-tenant)#

2. Validación EFOS Automática#

{
  "message": "Client created successfully",
  "data": {
    "id": "client_123",
    "rfc": "XAXX010101000",
    "efos_status": "valid",
    "efos_checked_at": "2025-10-02T10:30:00Z"
  }
}

3. Paginación con Cursores#

4. Soporte Completo CFDI 4.0#

5. Webhooks Mejorados#

{
  "event": "invoice.stamped",
  "timestamp": "2025-10-02T10:30:00Z",
  "data": {
    "invoice_id": "inv_123",
    "uuid": "12345678-1234-1234-1234-123456789012",
    "status": "stamped",
    "pdf_url": "https://...",
    "xml_url": "https://..."
  }
}

🛠️ Pasos para Migrar#

Paso 1: Preparación#

Paso 2: Configuración del Entorno#

Paso 3: Actualiza tu Código#

3.1 Actualiza la Autenticación#

3.2 Actualiza el Manejo de Respuestas#

3.3 Actualiza Endpoints Renombrados#

3.4 Actualiza Paginación#

Paso 4: Prueba Exhaustivamente#

Paso 5: Deploy Gradual#

💡 Ejemplos de Migración#

Ejemplo 1: Crear Cliente#

Ejemplo 2: Listar Facturas con Paginación#

Ejemplo 3: Crear Servicio (antes Producto)#

Ejemplo 4: gigstack Connect (Multi-team)#

⏰ Deprecación de v1#

Línea de Tiempo#

Recomendaciones#

📞 Soporte y Recursos Adicionales#

Documentación#

Colecciones y Herramientas#

Soporte#

Comunidad#

✅ Checklist de Migración#

Preparación#

Código#

Pruebas#

Deploy#

🎉 ¡Migración Exitosa!#

📚 Referencia: Documentación v1#