Devs

gigstack API: Documentación Completa para Developers México 2026

Documentación técnica de la API de gigstack. Endpoints, autenticación, ejemplos de código y mejores prácticas para integrar facturación CFDI.

· Gabriel Paredes

La API de gigstack te permite integrar facturación electrónica CFDI 4.0 en cualquier aplicación. Esta documentación cubre todo lo que necesitas saber para empezar a integrar: autenticación, endpoints disponibles, estructuras de datos y ejemplos prácticos.

Primeros Pasos

Obtener API Key

Accede a app.gigstack.pro/settings?subtab=api para generar tu JWT token. Este token se incluye en todas las peticiones para autenticarte.

Base URL

Todas las peticiones van a: https://api.gigstack.io/v2

Headers requeridos

Cada petición debe incluir:

  • Authorization: Bearer tu_jwt_token
  • Content-Type: application/json

Recursos de la API

Clientes (Clients)

Gestiona los datos fiscales de tus clientes con validación automática ante el SAT.

POST /clients - Crear cliente

Body:

{ "legal_name": "Empresa Ejemplo SA de CV", "rfc": "EEJ920318M5A", "tax_system": "601", "email": "facturacion@ejemplo.com", "zip_code": "06600" }

La API valida que el RFC y razón social coincidan con el registro del SAT antes de guardar.

GET /clients - Listar clientes

Retorna lista paginada con cursor. Usa ?limit=50&next=cursor para paginar.

GET /clients/:id - Obtener cliente específico

PATCH /clients/:id - Actualizar cliente

DELETE /clients/:id - Eliminar cliente

Servicios (Services)

Catálogo de productos o servicios que facturas, con claves SAT preconfiguradas.

POST /services - Crear servicio

{ "name": "Suscripción mensual Pro", "description": "Acceso a plataforma plan profesional", "price": 999, "product_key": "43232408", "unit_key": "E48", "taxes": [{ "type": "IVA", "rate": 0.16, "inclusive": false }] }

Los campos product_key y unit_key son claves del catálogo del SAT.

Facturas (Invoices)

Creación, consulta y cancelación de CFDIs.

POST /invoices - Crear factura

{ "client": "client_id", "items": [{ "description": "Servicio de consultoría", "quantity": 10, "unit_price": 500, "product_key": "80101500", "unit_key": "E48", "taxes": [{ "type": "IVA", "rate": 0.16 }] }], "payment_form": "03", "payment_method": "PUE", "use": "G03", "currency": "MXN", "notes": "Proyecto fase 1" }

Campos importantes:

  • payment_form: Cómo pagó el cliente (03=transferencia, 04=tarjeta crédito)
  • payment_method: PUE (pago único) o PPD (pago diferido)
  • use: Uso del CFDI según catálogo SAT (G01, G03, P01, etc.)

GET /invoices - Listar facturas

Filtros disponibles: ?status=active&from=2026-01-01&to=2026-01-31

GET /invoices/:id - Obtener factura con XML y PDF

POST /invoices/:id/cancel - Cancelar factura

{ "motive": "02", "replacement_uuid": "uuid-factura-sustituta" }

Motivos de cancelación: 01=Comprobante con errores, 02=Comprobante con errores con relación, 03=No se llevó a cabo, 04=Operación nominativa relacionada.

Pagos (Payments)

Registra pagos para generar complementos automáticamente.

POST /payments - Registrar pago

{ "client": "client_id", "amount": 5000, "payment_form": "03", "currency": "MXN", "related_invoices": [{ "uuid": "uuid-factura-ppd", "amount": 5000 }] }

Si el pago corresponde a una factura PPD, gigstack genera automáticamente el Complemento de Pago.

Webhooks

Recibe notificaciones cuando ocurren eventos en tu cuenta.

POST /webhooks - Crear webhook

{ "url": "https://tuapp.com/webhooks/gigstack", "events": ["invoice.created", "invoice.cancelled", "payment.received"] }

Eventos disponibles:

  • invoice.created - Factura timbrada exitosamente
  • invoice.cancelled - Factura cancelada
  • invoice.cancellation_pending - Esperando aceptación de cancelación
  • invoice.cancellation_rejected - Receptor rechazó cancelación
  • payment.received - Pago registrado
  • complement.created - Complemento de pago generado
  • client.created - Nuevo cliente registrado

Payload del webhook:

{ "event": "invoice.created", "timestamp": "2026-01-15T10:30:00Z", "data": { "id": "inv_abc123", "uuid": "folio-fiscal-uuid", "total": 1160, "client": {...}, "items": [...] } }

Códigos del SAT Frecuentes

Claves de Producto

  • 43232408 - Servicios de software
  • 80101500 - Servicios de consultoría de negocios
  • 81112101 - Servicios de software como servicio (SaaS)
  • 82101500 - Servicios de publicidad
  • 43211500 - Software funcional específico de la empresa

Claves de Unidad

  • E48 - Unidad de servicio
  • ACT - Actividad
  • H87 - Pieza
  • EA - Elemento

Formas de Pago

  • 01 - Efectivo
  • 03 - Transferencia electrónica
  • 04 - Tarjeta de crédito
  • 28 - Tarjeta de débito
  • 99 - Por definir (para PPD)

Usos de CFDI

  • G01 - Adquisición de mercancías
  • G03 - Gastos en general
  • P01 - Por definir
  • S01 - Sin efectos fiscales

Manejo de Errores

La API retorna errores con estructura consistente:

{ "error": true, "message": "El RFC no existe en el padrón del SAT", "code": "INVALID_RFC", "details": { "field": "rfc", "value": "ABC123456XXX" } }

Códigos de error comunes:

  • INVALID_RFC - RFC no válido o no existe
  • LEGAL_NAME_MISMATCH - Razón social no coincide con SAT
  • INVALID_TAX_SYSTEM - Régimen fiscal incorrecto
  • INSUFFICIENT_STAMPS - Sin timbres disponibles
  • DUPLICATE_INVOICE - Factura duplicada (idempotencia)

Rate Limits

La API tiene límites por defecto:

  • 100 requests por minuto para endpoints de lectura
  • 30 requests por minuto para creación de facturas

Headers de respuesta incluyen: X-RateLimit-Remaining y X-RateLimit-Reset

Para límites mayores, contacta a soporte.

SDKs y Librerías

Próximamente: SDKs oficiales para Node.js, Python y PHP. Mientras tanto, usa cualquier cliente HTTP con los ejemplos de esta documentación.

Soporte

Para dudas técnicas sobre la API:

Visita app.gigstack.pro para obtener tus credenciales y empezar a integrar.