February 12, 2026

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

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

Crea una cuenta en gigstack.pro
Ve a Configuración → API
Genera tu API Key
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:

Ve a Configuración → Webhooks en gigstack
Agrega la URL de tu endpoint
Selecciona los eventos que quieres recibir
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

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

SaaS: Facturación de suscripciones

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

Marketplace: Facturación de comisiones

Vendedor realiza una venta
Calculas tu comisión
Generas factura de ingreso por la comisión

Plataforma de servicios: Factura por transacción

Usuario contrata un servicio
El proveedor completa el servicio
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.