Actualizaciones de la API Invoices
In previous versions of the Stripe API, Invoices didn’t have statuses. Instead, there was a series of booleans, like closed
, paid
, and forgiven
.
Hemos introducido estados en las facturas para mejorar la correlación de las facturas de Stripe con los flujos financieros. Ahora, todos los objetos Invoice tienen una propiedad status
. El campo status
puede tener los valores draft
, open
, paid
, void
y uncollectible
.
- El estado
draft
indica que la factura puede cambiar. - El estado
open
indica que la factura está finalizada, que ya no puede cambiar y que está lista para el pago. - El estado
paid
indica que se ha pagado el total de la factura. - El estado
void
indica que la factura ya no es válida. - El estado
uncollectible
indica que es muy poco probable que se abone la factura y que podría considerarse una deuda incobrable.
Para obtener más información sobre estos estados y las transiciones de uno a otro, consulta la guía de facturación.
Modelos de cronogramas de facturación
En esta sección, se presentan los cronogramas tanto de las facturas por compras puntuales como de las facturas por suscripciones, y se muestran los estados por los que pueden pasar ambos tipos de facturas.
Ejemplo de factura puntual
Veamos un ejemplo del cronograma que puede seguir una factura puntual. Esta secuencia de eventos no presenta cambios respecto del cronograma de facturación preexistente, excepto que Stripe ahora expone el campo status
para representar con más claridad el estado de una factura.
- Nov 16: Through the API, you might create an invoice that represents shipping 12 widgets to a customer. Stripe sends an
invoice.created
webhook, notifying you of the recently-created invoice. Looking at the API, you see that the invoice hasstatus='draft'
. - 26 nov.: después de una revisión, el contador finaliza la factura a través del Dashboard de Stripe. Mientras se finaliza la factura, su estado se actualiza a
status='open'
y se define el campofinalized_at
. Stripe envía un webhookinvoice.finalized
para avisarte que la factura fue finalizada. - 26 nov.: segundos después, Stripe envía la factura por correo electrónico y comienza a hacer reintentos. Para ayudar a tu sistema de CRM a realizar un seguimiento del envío de facturas, Stripe envía un webhook
invoice.sent
cada vez que se envía una factura. - 01 dic.: el cliente hace click en el enlace recibido por correo electrónico y paga la factura a través de una página de pago de facturas alojadas. Lamentablemente, el pago se hace con una tarjeta de crédito vencida. El pago da error, y Stripe envía el webhook
invoice.payment_failed
para notificarte del error. - 03 dic.: el cliente intenta pagar nuevamente con otra tarjeta de crédito. Esta vez, el pago se realiza correctamente. Stripe envía el webhook
invoice.paid
para avisarte del pago, guarda la tarjeta y establece la factura enstatus='paid'
. Si está configurado, Stripe también le envía un recibo al cliente por correo electrónico como constancia del pago de la factura.
Ejemplo de factura de suscripción
Veamos un ejemplo de un cronograma de una factura generada por una suscripción.
- 13 de nov.: mediante el Dashboard, creas una suscripción recurrente para un cliente, configurada para cobro automático. La suscripción tiene un período de prueba de 20 días, de modo que la primera factura se creará en 20 días (el 3 de dic.). Stripe envía un webhook
customer.subscription.created
.
- ** 30 de noviembre **: Tres días antes de que finalice la prueba, Stripe envía un webhook de
customer.subscription.trial_will_end
. Tres días antes de cargar la tarjeta de crédito sería un buen momento para enviar un correo electrónico de recordatorio de prueba.
- 03 dic.: al final del período de prueba, se crea una factura
status='draft'
. Stripe envía un webhookinvoice.created
para avisarte que acabas de crear una factura. - Dec 03: Approximately one hour later, the invoice is automatically finalized. This entails updating the
status
as'open'
, settingfinalized_at
, and sending aninvoice.finalized
webhook. - 03 dic.: inmediatamente después, Stripe intenta cobrarle a la tarjeta del cliente guardada. El pago se realiza correctamente. Stripe envía el webhook
invoice.paid
para avisarte del pago, guarda la tarjeta y establece la factura enstatus='paid'
.
Nuevos métodos de API
Stripe ha lanzado un conjunto de API nuevas para administrar el estado de las facturas. Estas son las nuevas opciones, detalladas en la lista de comprobación de actualización a continuación:
- Envío de una factura: Stripe automáticamente envía y reenvía facturas por correo electrónico. Este punto de conexión, disponible a través de la API de Stripe, te permite enviar facturas al cliente cuando quieras.
- Finalización de una factura: en el ejemplo anterior, el contador finaliza la factura usando el Dashboard de Stripe. Esta funcionalidad también está disponible a través de la API de Stripe.
- Invalidación de una factura: una vez que se ha finalizado la factura, esta no puede ser eliminada. La invalidación se utiliza para indicar que la factura fue emitida por error. Puedes invalidar una factura por un error en el nombre de tu empresa y crear luego una factura completamente nueva en su reemplazo.
- Eliminación de una factura en borrador: esta acción solo es aplicable a facturas en borrador. Las facturas eliminadas no pueden verse a través del Dashboard ni a través de la API. No se puede deshacer la eliminación.
- Marca de una factura como incobrable: es posible que tu departamento contable quiera llevar un registro de “deudas dudosas”, es decir, una lista de facturas que se consideran incobrables. Puedes usar esta API para etiquetar las facturas correspondientes.
Lista de comprobación de actualización
En las siguientes secciones, se enumeran los cambios funcionales en el objeto Invoice
y en los webhooks relacionados con facturas.
Objeto Invoice
Stripe ha agregado varios campos a Invoice
para ayudar a los usuarios a entender mejor el estado y el comportamiento de este objeto.
finalized_at
El nuevo campo finalized_at
indica el momento en que la factura fue finalizada. Esto está disponible para solicitudes hechas en todas las versiones de API.
status
El nuevo campo status
está disponible para solicitudes hechas en todas las versiones de API. Reemplaza varios valores booleanos en la factura, por ejemplo:
- Para solicitudes hechas con la versión 2018-11-08 o una versión posterior, se quitó el valor booleano
paid=true
. Revisa el valor equivalentestatus='paid'
. - Para solicitudes hechas con la versión 2018-11-08 o una versión posterior, se quitó el valor booleano
forgiven=true
. Revisa el valor equivalentestatus='uncollectible'
.
auto_advance
El nuevo campo auto_advance
indica si el cobro automático está activo. El campo auto_advance
se puede actualizar para los estados 'draft'
y 'open'
. De lo contrario, auto_advance
siempre será false
.
Si auto_advance=false
, Stripe no:
- Emitirá automáticamente facturas en borrador
- Enviará automáticamente los primeros correos electrónicos (o de recordatorio) de las facturas
collection_method='send_invoice'
- Intento (o reintento) automático de los primeros pagos de facturas
collection_method='charge_automatically'
Aún con auto_advance=false
, Stripe concilia automáticamente las transferencias de crédito entrantes. Si una transferencia hace referencia a una factura, la transferencia de crédito se concilia con esa factura. Si no se proporciona una factura, Stripe busca facturas impagas e intenta saldarlas.
Para las facturas con estados 'uncollectible'
, 'void'
y 'paid'
, el campo auto_advance
siempre es false
.
En versiones anteriores a 2018-11-08, sigue existiendo el campo closed
, que equivale a la inversa de auto_advance
. Por ejemplo, auto_advance=true
es equivalente a closed=false
(y viceversa). Las facturas creadas con versiones anteriores de API seguirán teniendo closed=false
como valor predeterminado.
Webhooks
Con esta actualización, hemos introducido tres nuevos webhooks:
invoice.finalized
: enviado cuando se finaliza una factura.invoice.voided
: enviado cuando se invalida una factura.invoice.marked_uncollectible
: enviado cunado una factura se marca como incobrable.
El webhook existente invoice.created
se envía apenas se crea la factura. Si tu administrador de webhooks necesita diferenciar entre facturas puntuales y facturas generadas por una suscripción, comprueba si existe la propiedad invoice.subscription
en el cuerpo del webhook.
Estos webhooks preexistentes no se modifican:
invoice.sent
: enviado cuando se remite una factura al usuario por correo electrónico, ya sea automáticamente, a través de la API o desde el Dashboard.invoice.deleted
: enviado cuando se elimina una facturadraft
, ya sea a través de la API o desde el Dashboard.invoice.paid
oinvoice.payment_failed
: enviado si el intento de pago de una factura se efectúa con éxito o da error.