Faturamento Automático

Integración nativa · Solo lectura (pull) · Sincroniza automáticamente cada 60 min (configurable) + bajo demanda · Conciliación en tiempo real por webhook

El Faturamento Automático es el producto de suscripciones y facturación recurrente de Kobana. Cuando tu operación factura por allí, el Dunning se conecta a él para cobrar las facturas abiertas — trayendo los clientes y las facturas generadas hacia la regla, el portal y los acuerdos.

Requisitos previos

• Una cuenta en el Faturamento Automático con clientes y facturas.
• Un token de API (API token) del Faturamento Automático.
• Acceso al panel del Faturamento Automático para registrar el webhook entrante (opcional, pero recomendado para la conciliación en tiempo real).

Cómo conectar

:::note Sin pantalla dedicada en el panel (todavía) Hoy solo el Gateway de Kobana tiene una pantalla de conexión lista en el panel. Para este ERP, la conexión se hace por la API (rutas /api/v1/integrations/...) — los pasos de abajo describen el flujo de autorización; la pantalla self-service equivalente en el panel está en el roadmap. :::

El Faturamento Automático usa clave estática — pegas un token, sin redirección.

1. En el panel del Faturamento Automático, copia el token de API.
2. En el Dunning, abre Configuraciones → Integraciones y elige el Faturamento Automático.
3. Pega el token de API y selecciona el ambiente (producción o sandbox).
4. Haz clic en Conectar. El Dunning valida el token con una llamada de prueba; un token inválido es rechazado antes de guardar.
5. Para la conciliación en tiempo real: el setup devuelve la URL de webhook del Dunning. Registra un webhook en el panel del Faturamento Automático apuntando a esa URL y pega el signing secret del endpoint en el campo indicado — es él quien valida la firma de cada entrega.

Mapeo de campos (origen → Dunning)

Campo en el Faturamento Automático	Campo en el Dunning
Factura (invoice)	Cobro
total	Valor original
amount_remaining (saldo abierto)	Valor actual
amount_paid / paid_at	Valor pagado / fecha del pago
due_date	Vencimiento
finalized_at / created_at	Fecha de emisión
number	Número del documento
hosted_invoice_url / invoice_pdf_url	URL de pago
Status open	pending (o overdue si está vencida)
Status paid	paid (baja + salida de la regla)
Status void / uncollectible	cancelled (write-off sale de la regla)
Status draft	ignorada (aún no es cobrable)
Cliente de la cuenta de cobro	Persona en la cartera
document_number, name, legal_name	Documento, nombre, razón social
emails, phones	E-mails y teléfonos de la persona
custom_metadata (campos personalizados)	customData.kobanaBilling.custom_metadata

Los campos personalizados (custom_metadata) que defines en el Faturamento Automático, tanto en el cliente como en la factura, viajan hacia el Dunning bajo la clave customData.kobanaBilling. La sincronización fusiona ese bloque y preserva el resto del customData de la persona/cobro — es decir, los campos que hayas definido por la API del Dunning no se sobrescriben en cada ronda de sync.

Tiempo real y pull

Cuando una factura es pagada, el Dunning da de baja el cobro y lo retira de la regla; las facturas canceladas (void/uncollectible) salen definitivamente. Con el webhook registrado, esos cambios llegan en tiempo real (invoice.paid, invoice.voided, entre otros); sin él, la sincronización cada 60 min (o el botón de sincronizar) mantiene todo consistente.

Qué no hace / limitaciones

• No emite facturas. La emisión y la regla de facturación siguen en el Faturamento Automático.
• No escribe de vuelta. Es pull-only: dar de baja o cancelar en el Dunning no altera la factura de origen.
• Las facturas en borrador no entran mientras no sean finalizadas.
• Sin webhook, hay retraso de hasta un ciclo de sincronización.

Cómo desconectar o reconfigurar

Rehaz el setup para cambiar el token. Una reconfiguración sin informar el signing secret no borra el secreto ya registrado — evita derribar en silencio la validación de firma de los webhooks. Para rotar credenciales, genera un nuevo token/endpoint en el panel de origen y actualízalo en el Dunning.

Solución de problemas

• La sincronización está desactualizada. Revisa el intervalo (por defecto 60 min) y usa Sincronizar ahora.
• Una factura pagada no dio de baja. Verifica en el log de integración si el webhook invoice.paid llegó y si el signing secret es correcto; sin webhook, el próximo pull lo regulariza.
• Un cliente no apareció. El sync de clientes corre junto; las cuentas de cobro sin cliente asociado son omitidas.
• Un cobro aparece duplicado. El Dunning deduplica por externalId (billing:invoice:{id}); la duplicidad real solo ocurre si el mismo título viene de otro origen.
• Los webhooks devuelven error de firma. El signing secret registrado en el Dunning no coincide con el del endpoint — vuelve a registrar el secret en el setup/reconfiguración.

Seguridad

El token de API está cifrado en reposo y nunca es devuelto por la API. El signing secret de los webhooks se preserva entre reconfiguraciones para no interrumpir la validación de firma.