Facturar cuando cobras con tu propia pasarela

Si tu aplicación cobra con su propia cuenta de Stripe (o con otra pasarela) y usa UTILIA OS solo para facturar, el recorrido es más corto: no hacen falta tarjetas guardadas, autorizaciones ni el aplicativo Pagos con tarjeta. Basta con Finanzas.

Permisos de la aplicación: crm:invoices:write y crm:invoices:issue para emitir, crm:invoices:send si UTILIA OS envía los correos, y crm:invoices:rectify para las rectificativas (lo concede un Super Administrador, con un motivo).

1. Emitir la factura ya cobrada

Para una venta a un consumidor de hasta 400 €, emite una simplificada con el precio que cobraste (pricesIncludeTax: true) y el bloque payment. La factura nace cobrada y, si se envía, el cliente recibe un solo correo con la plantilla de factura pagada.

const factura = await sdk.invoices.create({
  type: 'SIMPLIFIED',
  user: { externalId: 'user_01HXYZ', email: 'ana@example.com' },
  taxSystem: 'IGIC',
  pricesIncludeTax: true,
  lines: [{ name: 'Plan Básico mensual', quantity: 1, unitPrice: 39.99, taxType: 'IGIC_7' }],
  payment: { method: 'CARD', reference: 'pi_3QabcDEF' },
  consumerResidence: { region: 'CANARIAS', evidence: 'País de la tarjeta: ES; código postal de facturación: 38' },
  idempotencyKey: 'pedido-4471',
});
// factura.totalAmount: 39.99 (base 37,37 más 2,62 de IGIC)
// factura.paymentRegistered: true

Si tu organización está en el régimen del pequeño empresario del IGIC (REPEP), la línea va con taxType: 'EXEMPT' y sin causa: el total es 39,99 € sin cuota y la factura lleva «Exención franquicia fiscal». Los detalles están en Facturas.

2. Devolver el dinero en tu pasarela

La devolución la haces tú, en tu cuenta. UTILIA OS no puede ni debe mover ese dinero. Guarda el identificador de la devolución.

3. Emitir la rectificativa con la devolución

const resultado = await sdk.invoices.rectifications.create(factura.id, {
  userId: 'user_01HXYZ',
  idempotencyKey: 'devolucion-pedido-4471',
  cause: 'REFUND',
  refund: { reference: 're_3QabcDEF' },
});
// resultado.rectification.rectificationCode: 'R5'
// resultado.rectification.totalAmount: -39.99
// resultado.originalInvoice.status: 'RECTIFIED'
// resultado.refund.source: 'EXTERNAL_GATEWAY'

Para una devolución parcial, añade amount con el importe devuelto, impuestos incluidos. La clave de idempotencia es obligatoria: si la respuesta trae operationStatus: 'review_required', repite la misma llamada con la misma clave para terminarla. Un contracargo se rectifica igual, con cause: 'CHARGEBACK', solo si la venta queda sin efecto.

4. Recibir los avisos

Todos llegan solo a tu aplicación.