December 10, 2025

gigstack Connect: Automatiza Split Fiscal para Marketplaces y Plataformas con Múltiples Actores

El Problema Fiscal Que Frena a Marketplaces y Plataformas

Si operas un marketplace, plataforma de movilidad, fintech o cualquier ecosistema con múltiples actores (vendedores, compradores, repartidores, creadores), enfrentas una pesadilla fiscal que la mayoría de plataformas resuelve mal:

📄 2-3 facturas por cada transacción: Tu comisión + venta del vendedor + compra del cliente
⏱️ 20-40 horas semanales de equipo fiscal procesando splits manualmente
❌ 15-25% de facturas con errores en distribución de montos o RFCs
😤 Vendedores frustrados esperando facturas de liquidaciones
🚨 Riesgo SAT: Complementos de pago mal aplicados o faltantes
💸 Escalabilidad limitada: No puedes crecer sin contratar un equipo fiscal completo

La realidad brutal: La mayoría de marketplaces facturan manualmente cada split o usan workarounds que no cumplen 100% con SAT.

El costo oculto: Plataformas con 500 transacciones/mes pierden $40,000-80,000 MXN mensuales en tiempo de equipo fiscal + errores + oportunidad perdida.

¿Qué es gigstack Connect?

gigstack Connect es la infraestructura fiscal automatizada para plataformas multi-actor. Permite gestionar múltiples equipos (teams) con diferentes RFCs desde una sola cuenta mediante un parámetro API simple.

Cómo funciona (REST API directo):

// Sin gigstack Connect - Solo facturas tu propio RFC
POST https://api.gigstack.io/v2/invoices/income
Authorization: Bearer YOUR_API_KEY

{
  "client": {"id": "client_abc"},
  "items": [...]
}
// ✅ Genera factura para TU RFC

// Con gigstack Connect - Facturas cualquier RFC del grupo
POST https://api.gigstack.io/v2/invoices/income?team=team_vendedor_xyz
Authorization: Bearer YOUR_API_KEY

{
  "client": {"id": "client_abc"},
  "items": [...]
}
// ✅ Genera factura para RFC del vendedor
// Mismo API key, diferentes RFCs

Beneficios clave:

✅ Un solo API key gestiona múltiples RFCs (teams)
✅ Parámetro ?team= simple en cualquier endpoint
✅ Funciona en 35+ endpoints de la API gigstack
✅ Sin complejidad adicional - solo agregar query param
✅ Seguridad por billing account - solo teams del mismo grupo

Casos de Uso Reales por Industria

🏪 Marketplaces (E-commerce Multi-Vendor)

Desafío: 500 vendedores, 2,000 transacciones/mes. Necesitas facturar:

Compra del cliente final
Venta de cada vendedor
Comisión de la plataforma

Solución con gigstack Connect (REST API):

// 1. Crear factura de venta (vendedor → cliente)
await fetch('https://api.gigstack.io/v2/invoices/income?team=team_vendedor_123', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    automation_type: 'payment',
    client: { id: 'cliente_abc' },
    currency: 'MXN',
    payment_method: 'PUE',
    payment_form: '03',
    use: 'P01',
    items: [{
      description: 'Producto vendido',
      quantity: 1,
      unit_price: 850, // 85% para vendedor
      product_key: '43211500',
      unit_key: 'H87',
      taxes: [{ type: 'IVA', rate: 0.16 }]
    }]
  })
});

// 2. Crear factura de comisión (plataforma → vendedor)
await fetch('https://api.gigstack.io/v2/invoices/income', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    automation_type: 'payment',
    client: { id: 'vendedor_123' }, // Vendedor es cliente de la plataforma
    currency: 'MXN',
    payment_method: 'PUE',
    payment_form: '03',
    use: 'G03',
    items: [{
      description: 'Comisión plataforma',
      quantity: 1,
      unit_price: 150, // 15% comisión
      product_key: '80141503',
      unit_key: 'E48',
      taxes: [{ type: 'IVA', rate: 0.16 }]
    }]
  })
});

// Ambos CFDIs generados automáticamente
// Sin intervención manual, sin errores

Resultados medibles:

📉 Tiempo de equipo fiscal: de 160 a 8 horas/mes (95% reducción)
💰 Ahorro anual: $280,000 MXN en nómina
🚀 Retención vendedores: +23% (mejor experiencia)
🕒 Tiempo de liquidación: de 7 días a instantáneo

🚕 Plataformas de Movilidad (Repartidores/Conductores)

Desafío: 200 repartidores activos, 5,000 entregas/mes.

Solución con gigstack Connect:

// Factura automática por cada entrega usando team del repartidor
await fetch('https://api.gigstack.io/v2/payments/register?team=team_repartidor_456', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    client: { id: 'plataforma_principal' },
    automation_type: 'pue_invoice',
    currency: 'MXN',
    payment_form: '03',
    items: [{
      id: 'service_entrega',
      quantity: 1,
      unit_price: 45 // Por entrega
    }]
  })
});

// gigstack automáticamente:
// ✅ Genera factura del repartidor a la plataforma
// ✅ Timbra CFDI 4.0
// ✅ Envía email al repartidor
// ✅ Actualiza liquidación semanal

Resultados:

📉 Tickets de soporte: de 180 a 12 mensuales (93% reducción)
💰 Errores de liquidación: de 12% a 0%
🚀 Satisfacción repartidores: +38 puntos NPS

Implementación Técnica: REST API de gigstack Connect

Setup básico (10 minutos)

1. Obtén API key de tu team principal:

Dashboard gigstack → Settings → API
Copia tu Bearer token

2. Lista teams disponibles:

curl -X GET "https://api.gigstack.io/v2/teams" \
  -H "Authorization: Bearer YOUR_API_KEY"

3. Usa parámetro ?team= en cualquier endpoint:

// Listar clientes de otro team
GET https://api.gigstack.io/v2/clients?team=team_xyz789

// Crear factura para otro team
POST https://api.gigstack.io/v2/invoices/income?team=team_abc123

// Registrar pago de otro team
POST https://api.gigstack.io/v2/payments/register?team=team_def456

Código de ejemplo completo (Node.js)

// Helper class para multi-team
class GigstackConnect {
  constructor(apiKey) {
    this.apiKey = apiKey;
    this.baseUrl = 'https://api.gigstack.io/v2';
  }

  async request(endpoint, teamId = null, options = {}) {
    const url = teamId 
      ? `${this.baseUrl}${endpoint}?team=${teamId}`
      : `${this.baseUrl}${endpoint}`;
    
    const response = await fetch(url, {
      ...options,
      headers: {
        'Authorization': `Bearer ${this.apiKey}`,
        'Content-Type': 'application/json',
        ...options.headers
      }
    });
    return response.json();
  }

  // Crear factura para cualquier team
  async createInvoice(teamId, data) {
    return this.request('/invoices/income', teamId, {
      method: 'POST',
      body: JSON.stringify(data)
    });
  }

  // Listar clientes de cualquier team
  async listClients(teamId) {
    return this.request('/clients', teamId);
  }
}

// Uso
const connect = new GigstackConnect(process.env.GIGSTACK_API_KEY);

// Factura para vendedor
const invoice = await connect.createInvoice('team_vendedor_123', {
  automation_type: 'payment',
  client: { id: 'cliente_abc' },
  currency: 'MXN',
  payment_method: 'PUE',
  payment_form: '03',
  use: 'P01',
  items: [{
    description: 'Venta marketplace',
    quantity: 1,
    unit_price: 850,
    product_key: '43211500',
    unit_key: 'H87',
    taxes: [{ type: 'IVA', rate: 0.16 }]
  }]
});

console.log('CFDI generado:', invoice.data.uuid);