Devs

Tutorial 2026: Guía de la API de gigstack para Desarrolladores

Documentación práctica para integrar facturación CFDI en tu aplicación usando la API de gigstack. Ejemplos de código, autenticación, webhooks y mejores prácticas.

· Santiago Carranca

Si estás desarrollando una aplicación, plataforma o sistema que necesita emitir facturas CFDI en México, la API de gigstack te permite integrar facturación en horas, no meses. Esta guía te lleva desde la autenticación hasta la emisión de tu primera factura programáticamente.

Visión General de la API

La API de gigstack es RESTful, usa JSON para requests y responses, y sigue convenciones estándar de la industria.

Características principales:

  • REST API: Endpoints intuitivos y predecibles
  • JSON: Formato de datos universal
  • HTTPS: Todas las comunicaciones encriptadas
  • Webhooks: Notificaciones en tiempo real
  • SDKs: Librerías para Node.js, Python, PHP, Ruby
  • Sandbox: Ambiente de pruebas sin costo

Paso 1: Obtén tus Credenciales

  1. Crea una cuenta en gigstack.pro
  2. Ve a Configuración → API
  3. Genera tu API Key
  4. Guarda la clave de forma segura (solo se muestra una vez)

Tipos de credenciales:

  • API Key de Sandbox: Para desarrollo y pruebas
  • API Key de Producción: Para facturas reales

Usa siempre Sandbox durante desarrollo. Las facturas de prueba no se timbran con el SAT.

Paso 2: Configura la Autenticación

Todas las requests deben incluir tu API Key en el header:

Authorization: Bearer tu_api_key_aqui

Ejemplo con cURL:

curl -X GET "https://api.gigstack.pro/v1/invoices" -H "Authorization: Bearer sk_test_xxx"

Ejemplo con JavaScript (Node.js):

const response = await fetch('https://api.gigstack.pro/v1/invoices', { headers: { 'Authorization': 'Bearer sk_test_xxx' } });

Paso 3: Estructura de la API

URL Base:

  • Sandbox: https://api.sandbox.gigstack.pro/v1
  • Producción: https://api.gigstack.pro/v1

Endpoints principales:

  • POST /invoices - Crear factura
  • GET /invoices/{id} - Obtener factura
  • GET /invoices - Listar facturas
  • POST /invoices/{id}/cancel - Cancelar factura
  • POST /payments - Registrar pago (complemento)
  • GET /customers - Listar clientes
  • POST /customers - Crear cliente
  • POST /validate/rfc - Validar RFC con SAT

Paso 4: Crea tu Primera Factura

Request POST a /invoices:

Campos requeridos:

  • customer: Datos del receptor (RFC, nombre, CP, régimen)
  • items: Conceptos a facturar
  • payment_form: Forma de pago (código SAT)
  • payment_method: PUE o PPD

Ejemplo de body JSON:

{ "customer": { "rfc": "XAXX010101000", "legal_name": "Cliente de Prueba", "zip_code": "06600", "tax_regime": "601" }, "items": [{ "description": "Servicio de consultoría", "quantity": 1, "unit_price": 10000, "product_key": "80111600", "unit_key": "E48" }], "payment_form": "03", "payment_method": "PUE", "use": "G03" }

Response exitosa:

{ "id": "inv_abc123", "status": "stamped", "uuid": "ABC12345-1234-1234-1234-123456789ABC", "total": 11600, "pdf_url": "https://...", "xml_url": "https://..." }

Paso 5: Valida RFC antes de Facturar

Evita rechazos validando el RFC del cliente antes de crear la factura:

Request POST a /validate/rfc:

{ "rfc": "XAXX010101000" }

Response:

{ "valid": true, "legal_name": "NOMBRE REGISTRADO EN SAT", "tax_regime": "601", "zip_code": "06600" }

Usa esta información para autocompletar los datos del cliente en tu interfaz.

Paso 6: Configura Webhooks

Recibe notificaciones cuando ocurren eventos importantes:

  1. Ve a Configuración → Webhooks en gigstack
  2. Agrega la URL de tu endpoint
  3. Selecciona los eventos que quieres recibir
  4. Guarda la configuración

Eventos disponibles:

  • invoice.created - Factura creada
  • invoice.stamped - Factura timbrada
  • invoice.cancelled - Factura cancelada
  • invoice.failed - Error al timbrar
  • payment.received - Pago registrado
  • payment_complement.created - Complemento generado

Estructura del webhook:

{ "event": "invoice.stamped", "data": { "id": "inv_abc123", "uuid": "...", "total": 11600 }, "timestamp": "2026-02-12T10:30:00Z" }

Verificación de firma:

Cada webhook incluye un header X-Gigstack-Signature para verificar autenticidad. Compara con el hash HMAC de tu webhook secret.

Paso 7: Manejo de Errores

La API usa códigos HTTP estándar:

  • 200: Éxito
  • 400: Error en la request (datos inválidos)
  • 401: No autorizado (API Key inválida)
  • 404: Recurso no encontrado
  • 422: Error de validación (ej: RFC inválido)
  • 500: Error del servidor

Estructura de error:

{ "error": { "code": "invalid_rfc", "message": "El RFC proporcionado no existe en el padrón del SAT", "field": "customer.rfc" } }

Errores comunes y soluciones:

  • invalid_rfc: Verifica el RFC con el endpoint de validación
  • invalid_product_key: Usa una clave del catálogo SAT
  • certificate_expired: Renueva tu CSD en el SAT

Ejemplos de Código

Node.js con SDK:

const Gigstack = require('gigstack'); const client = new Gigstack('sk_test_xxx'); const invoice = await client.invoices.create({ customer: { rfc: 'XAXX010101000', legal_name: 'Cliente', zip_code: '06600', tax_regime: '601' }, items: [{ description: 'Producto', quantity: 1, unit_price: 1000, product_key: '43211500', unit_key: 'H87' }], payment_form: '03', payment_method: 'PUE' }); console.log(invoice.uuid);

Python:

import gigstack client = gigstack.Client('sk_test_xxx') invoice = client.invoices.create( customer={'rfc': 'XAXX010101000', ...}, items=[{'description': 'Producto', ...}] ) print(invoice.uuid)

PHP:

$gigstack = new Gigstack\Client('sk_test_xxx'); $invoice = $gigstack->invoices->create([ 'customer' => ['rfc' => 'XAXX010101000', ...], 'items' => [['description' => 'Producto', ...]] ]); echo $invoice->uuid;

Casos de Uso Comunes

E-commerce: Factura por cada venta

  1. Cliente completa compra en tu tienda
  2. Tu backend llama a POST /invoices
  3. Recibes webhook de confirmación
  4. Envías factura al cliente

SaaS: Facturación de suscripciones

  1. Tu sistema de billing procesa el cobro mensual
  2. Llamas a POST /invoices con los datos del cliente
  3. La factura se genera y envía automáticamente

Marketplace: Facturación de comisiones

  1. Vendedor realiza una venta
  2. Calculas tu comisión
  3. Generas factura de ingreso por la comisión

Plataforma de servicios: Factura por transacción

  1. Usuario contrata un servicio
  2. El proveedor completa el servicio
  3. Generas factura del proveedor al usuario

Rate Limits y Buenas Prácticas

Límites:

  • Sandbox: 100 requests por minuto
  • Producción: 1,000 requests por minuto
  • Contacta soporte si necesitas más

Buenas prácticas:

  • Idempotencia: Usa el header Idempotency-Key para evitar duplicados
  • Reintentos: Implementa backoff exponencial para errores 5xx
  • Caché: Guarda datos de clientes frecuentes para evitar validaciones repetidas
  • Webhooks: Usa webhooks en lugar de polling para estados

Testing en Sandbox

El ambiente Sandbox permite probar sin afectar producción:

  • Las facturas no se timbran con el SAT
  • Puedes usar RFCs de prueba
  • Los emails no se envían (o van a tu email de prueba)
  • Sin límite de facturas de prueba

RFC de prueba:

Usa XAXX010101000 para pruebas generales.

Documentación Adicional

  • Referencia completa: docs.gigstack.pro
  • Catálogo de claves SAT: Disponible en la documentación
  • Colección Postman: Descargable desde el panel
  • Ejemplos de código: Repositorio en GitHub

Soporte para Developers

Si tienes dudas durante la integración:

  • Documentación: docs.gigstack.pro
  • Email técnico: dev@gigstack.pro
  • Slack: Comunidad de desarrolladores
  • GitHub: Issues y ejemplos

Empieza a Integrar

La API de gigstack te permite agregar facturación CFDI a cualquier aplicación en horas. Obtén tu API Key, prueba en Sandbox, y lleva tu integración a producción cuando estés listo.

Visita gigstack.pro, genera tus credenciales, y emite tu primera factura programáticamente hoy.