March 19, 2026

API de gigstack: Endpoint registered payment para automatizar facturación en 2026

El proceso tradicional de facturación es una pesadilla operativa. Registrar un pago, crear manualmente una factura, lidiar con errores, buscar datos del cliente, y repetir. gigstack cambia esta ecuación con su endpoint registered payment que invierte completamente la lógica: un pago exitoso genera automáticamente la factura.

El endpoint: POST /v2/payments/register

El endpoint se encuentra en https://api.gigstack.io/v2/payments/register y acepta peticiones POST con autenticación Bearer Token (JWT). Tu token lo obtienes desde app.gigstack.pro/settings.

Ejemplo básico: registrar un pago con factura automática

Una sola llamada al API registra el pago y genera la factura PUE automáticamente:

curl -X POST https://api.gigstack.io/v2/payments/register   -H "Authorization: Bearer YOUR_JWT_TOKEN"   -H "Content-Type: application/json"   -d '{
    "client": { "id": "client_1234567890" },
    "automation_type": "pue_invoice",
    "currency": "MXN",
    "payment_form": "03",
    "items": [{
      "id": "service_1234567890",
      "quantity": 1,
      "unit_price": 1000
    }]
  }'

El campo automation_type controla qué sucede después del registro:

pue_invoice: Genera factura PUE (pago en una exhibición) inmediatamente
ppd_invoice_and_complement: Genera factura PPD y complemento de pago al confirmar
none: Solo registra el pago sin facturar

Campos requeridos del request

Cada petición necesita cuatro campos obligatorios:

client: Objeto con el id del cliente, o un objeto search para buscarlo por RFC/email con auto_create: true
currency: Código ISO 4217 ("MXN", "USD")
items: Array de productos con quantity, unit_price, product_key (clave SAT) y taxes
payment_form: Forma de pago SAT — "03" (transferencia), "04" (tarjeta crédito), "01" (efectivo)

Impuestos: configuración de IVA, ISR e IEPS

Cada item puede llevar su configuración de impuestos:

{
  "items": [{
    "quantity": 1,
    "unit_price": 1000,
    "product_key": "80141503",
    "unit_key": "E48",
    "description": "Servicios de consultoría",
    "taxes": [{
      "type": "IVA",
      "rate": 0.16,
      "withholding": false
    }]
  }]
}

El campo rate va en decimal (0.16 = 16%), y withholding: true indica retención.

Respaldo inteligente: autofactura automática

Si la información fiscal del cliente está incompleta, gigstack no falla. En su lugar:

Detecta los datos faltantes (RFC, razón social, régimen fiscal)
Genera un portal personalizado de autofactura
Notifica al cliente por email o WhatsApp para completar sus datos
Procesa la factura automáticamente una vez recibidos

Controla las notificaciones con send_email: false si prefieres manejar la comunicación tú mismo.

Idempotencia: evita pagos duplicados

Usa el campo idempotency_key con un identificador único de tu sistema. Si envías la misma key dos veces, gigstack devuelve el pago existente sin crear duplicados:

{
  "idempotency_key": "order_12345_payment",
  "client": { "id": "client_abc" },
  ...
}

Split payments para marketplaces

Si operas un marketplace, puedes dividir el pago entre tu plataforma y el vendedor usando transfer_data:

{
  "transfer_data": {
    "master": 30,
    "connect": "EMP800101ABC",
    "master_to": "client",
    "connect_to": "master"
  }
}

Esto divide automáticamente: 30% para tu plataforma, 70% para el vendedor conectado. Cada parte recibe su propia factura.

Respuesta exitosa

Una respuesta 200 devuelve el pago completo con su factura generada:

{
  "id": "payment_1234567890",
  "status": "succeeded",
  "total": 1160,
  "subtotal": 1000,
  "taxes": 160,
  "invoices": ["invoice_1234567890"],
  "client": {
    "name": "Juan Pérez",
    "tax_id": "PEGJ800101ABC"
  }
}