Skip to main content
Las facturas nativas usan las mismas rutas /invoices que las facturas heredadas, pero tienen un formato de solicitud y un ciclo de vida distintos. Esta guía mapea los campos y las acciones que debes cambiar al migrar una integración.
Las rutas compartidas dirigen a las facturas nativas a partir de Api-Version-Date: 2026-10-24. Los ejemplos nativos de abajo usan Api-Version-Date: 2026-11-02-1, con los nombres de campo de variante actuales y las reglas de bloqueo de cliente. Envía ese encabezado en cada solicitud nativa. Mantén las llamadas heredadas en una versión publicada anterior, como 2026-10-15-1. Versiones de la API explica cómo los encabezados prevalecen sobre las versiones fijadas en las credenciales.

Qué cambia

La API nativa no lista ni obtiene las facturas heredadas inv_. Sigue consultando las facturas heredadas existentes con la versión anterior de la API. Crear una factura nativa crea una factura independiente. No convierte ni liquida una factura heredada.

Antes de migrar

Comprueba estas diferencias antes de trasladar un flujo. Mantenlo en la API heredada si necesita una función que la API nativa no ofrece.

Mapea la solicitud de creación

Una creación heredada envía un plan y, opcionalmente, etiquetas que dividen su precio. Una creación nativa envía un ítem por cada variante facturada. Estos ejemplos fijan un precio combinado de los ítems de 19.99 USD. La variante nativa existente representa el cargo de configuración de 15 USD. La comisión de servicio de 4.99 USD es un cargo personalizado de pago único sin producto. Ambas APIs aceptan precios en unidades de moneda. Usa 4.99 para 4.99 USD. Enviar 499 factura 499 USD.
La solicitud nativa crea un borrador. Envíalo con POST /invoices/{id}/send para emitirlo y enviarlo por email. member_id identifica a un cliente (mber_), no una suscripción (mem_). En las versiones nativas anteriores a 2026-10-27-2, usa plan_id, plan y plan_type en lugar de variant_id, variant y billing_type. Las líneas de la respuesta también usan plan_id en esas versiones anteriores.

Mantén bloqueados los importes emitidos

PATCH /invoices/{id} edita los ítems y los datos de facturación de un borrador. Enviar items reemplaza la lista completa usando los precios actuales de las variantes. Omitirlo conserva los ítems y precios guardados.
  • Cancela un envío programado antes de editar ítems o datos de facturación.
  • A partir de 2026-11-02-1, no puedes reemplazar ni eliminar el cliente asignado a un borrador. Un borrador sin cliente todavía puede recibir uno. Anula el borrador antes de crear una factura nueva para otra persona.
  • email_address y customer_name son entradas exclusivas de la creación.
  • Los importes e ítems emitidos están bloqueados. Una actualización que solo contenga memo y/o recipient_emails está permitida en facturas draft, open y uncollectible, incluido un borrador programado.

Emite, envía y cobra

Una creación heredada elige el comportamiento de cobro con collection_method. Las facturas nativas usan llamadas separadas después de crear el borrador:
  1. Emítela con POST /invoices/{id}/issue para calcular el impuesto final y abrirla para el pago sin enviar el email inicial de la factura.
  2. O envíala con POST /invoices/{id}/send. Esto emite el borrador. Envía un email a los destinatarios, salvo que cobre de inmediato un método guardado. Enviar una factura open la vuelve a enviar por email. send_at programa el envío de un borrador. POST /invoices/{id}/unschedule cancela esa programación.
  3. Cobra un método guardado estableciendo payment_method_id en el borrador. Para un total positivo, emitir o enviar cobra en un charge_at futuro; si no lo hay, en un due_at futuro; y si tampoco, de inmediato. charge_at debe ser en el futuro y no puede ser anterior a send_at.
Enviar un borrador que cobra de inmediato omite el email inicial de la factura. Enviarlo con un cobro posterior envía el email ahora. Un cobro automático fallido puede desencadenar un email con un enlace de pago aunque hayas usado Issue Invoice. Cobra un método de pago guardado explica el flujo. Una respuesta open no confirma el pago. Espera a payment.succeeded antes de completar el pedido. Para cobrar o reintentar una factura abierta, usa Charge Invoice. Volver a emitirla o enviarla no inicia otro cobro. En una variante recurrente, collection_method en Issue Invoice o Send Invoice controla las renovaciones. charge_automatically cobra automáticamente los pagos futuros. send_invoice crea y envía por email una factura nueva en cada periodo. No sustituye a payment_method_id para cobrar la primera factura. Consulta Factura una suscripción.

Mapea la respuesta

Para descargar un PDF, llama a POST /invoices/{id}/generate_pdf y obtendrás un enlace de corta duración.

Abre el checkout de la factura

checkout_link contiene el ID de la factura y un token firmado separados por un .. Pasa el valor completo como link a POST /checkout_sessions para abrir una sesión para esta factura. Para obtener una URL para el cliente, sigue Crea la URL del checkout alojado. El campo solo está presente mientras el checkout está disponible: la factura debe estar open. Los compradores empresariales y las membresías canceladas no pueden usar este checkout. Tu clave necesita payment:charge, o invoice:create/invoice:update cuando la factura no tiene un método de pago guardado. Es null en una factura en borrador, pagada, anulada o incobrable, y para compradores empresariales.

Mapea los estados

Las facturas nativas también pueden devolver authorized, pending o unresolved. No trates todos los estados fuera del enum heredado como pagados o fallidos. Estados y ciclo de vida los explica.

Mapea los endpoints

Mapea los webhooks

Las facturas nativas envían eventos de pago para su ID pay_. Los eventos invoice.* describen las facturas heredadas. Los eventos de pago también cubren pagos no relacionados con facturas. Haz coincidir el ID de pago del evento con los ID de facturas nativas que almacenas. Webhooks muestra cómo completar pedidos a partir de payment.succeeded.

Permisos

member:basic:read expone los nombres de los clientes y los ID de miembros/membresías. member:email:read expone email_address y recipient_emails. Los campos de método de pago y dirección requieren payment:basic:read.

Lista de comprobación de la migración

  1. Consulta Antes de migrar para ver los flujos de trabajo que deben quedarse en la API heredada.
  2. Fija las llamadas nativas a una versión publicada que coincida con sus nombres de campo, como 2026-11-02-1 para estos ejemplos.
  3. Construye items a partir de variantes elegibles, comprobando cantidades, precios, moneda y requisitos de producto.
  4. Sustituye la creación heredada en una sola llamada por crear y después emitir o enviar. Elige cobros con método guardado para la primera factura y un método de cobro para las renovaciones.
  5. Mapea las fechas de vencimiento, los envíos programados y las comisiones al comprador según su comportamiento, no solo según sus nombres de campo.
  6. Mantén separados los ID nativos pay_ y los heredados inv_. Mantén las lecturas heredadas en la versión anterior.
  7. Lee los importes desde los objetos de dinero y abre el checkout con el checkout_link firmado.
  8. Gestiona overdue y los estados de pago adicionales.
  9. Completa los pedidos a partir de payment.succeeded para el ID de pago de la factura.
  10. Concede los permisos que usa tu flujo, incluidos los de variante/producto en línea y los de lectura de clientes.

Próximos pasos

Guía de facturas

Crea, emite, envía y cobra facturas nativas.

Referencia de la API de facturas

Cada endpoint y campo de las facturas nativas.

API de facturas heredada

Los endpoints a los que llama tu integración actual.

Versiones de la API

Cómo funcionan Api-Version-Date y las versiones fijadas.