Sincroniza facturas en Quentli

Usa esta guía cuando tu sistema administra un plan de pagos y quieres que Quentli cobre cada adeudo. En Quentli, un adeudo se representa con una factura o solicitud de pago (llamado Invoice en la API). Este flujo es apropiado para créditos, colegiaturas, membresías con importes definidos o cualquier cobro que debas programar desde tu sistema.

Haz estas llamadas desde tu servidor. Nunca expongas tu API key de Quentli en el navegador o una aplicación móvil.

Antes de comenzar

Necesitas una API key, un endpoint HTTPS para recibir webhooks y un identificador estable de tu cliente. Guarda los IDs que devuelve Quentli junto con los IDs de tu sistema:

customerId para el cliente.
paymentMethodId para la tarjeta guardada, si usarás cobros automáticos.
subscriptionId para el plan de pagos.
invoiceId para cada adeudo.

1. Crea o identifica al cliente

Crea el cliente una vez y conserva la relación con el identificador externo de tu sistema.

POST /v1/customers

{
  "input": {
    "name": "Ana Rodríguez",
    "username": "cliente-123",
    "email": "ana@ejemplo.com",
    "phoneNumber": "+525555123456"
  }
}

2. Recopila una tarjeta para los cargos recurrentes

Si Quentli realizará cargos automáticos, primero pide al cliente que registre una tarjeta mediante una sesión de inscripción. Quentli recopilará los datos de la tarjeta en el Portal de Clientes; tu sistema nunca recibe ni envía los datos de tarjeta por API.

POST /v1/setup-sessions

{
  "input": {
    "customer": {
      "name": "Ana Rodríguez",
      "externalId": "cliente-123",
      "email": "ana@ejemplo.com"
    },
    "displayMode": "CUSTOMER_PORTAL",
    "returnUrl": "https://miapp.com/metodo-de-pago-agregado",
    "cancelUrl": "https://miapp.com/metodo-de-pago-cancelado"
  }
}

Redirige al cliente a la url de la respuesta. También puedes usar el modo iframe si necesitas conservarlo dentro de tu experiencia. Obtén el paymentMethodId con el webhook PAYMENT_METHOD_CREATED o consulta los métodos de pago guardados:

GET /v1/customers/{customerId}/payment_methods

3. Crea la suscripción y asocia la tarjeta

La suscripción agrupa el plan de pagos y define el método de cobranza. Asocia explícitamente el paymentMethodId que recibiste en el paso anterior.

POST /v1/subscriptions

{
  "input": {
    "description": "Crédito cliente-123",
    "customerId": "cus_1234567890",
    "collectionMethod": "AUTOMATIC",
    "onlyAutomaticCollection": false,
    "paymentMethodId": "pm_1234567890"
  }
}

Usa onlyAutomaticCollection: false si quieres que el cliente pueda pagar por efectivo o transferencia además del cargo automático. Si lo estableces en true, Quentli solo ofrecerá métodos automáticos.

4. Crea una factura por cada adeudo

Crea una factura por cada vencimiento que exista en tu sistema. El monto se expresa en centavos y dueDate usa formato ISO 8601 en UTC.

POST /v1/invoices

{
  "input": {
    "customerId": "cus_1234567890",
    "subscriptionId": "sub_1234567890",
    "dueDate": "2026-09-15T15:00:00.000Z",
    "collectionMethod": "AUTOMATIC",
    "items": [
      {
        "concept": {
          "displayName": "Parcialidad 1 de 4",
          "amount": 25000,
          "currency": "MXN"
        },
        "quantity": 1
      }
    ]
  }
}

Repite esta operación para cada parcialidad, con su propio importe y fecha de vencimiento. Si ya conoces todos los vencimientos y usas conceptos existentes, también puedes crear las facturas predefinidas al crear la suscripción. Crear una factura por llamada es más conveniente cuando tu sistema es quien sincroniza los adeudos.

Al hacer esta solicitud, Quentli intentará el cargo cuando llegue la fecha dueDate (a partir de las 09:00AM horario de Ciudad de México). De manera predeterminada, Quentli intentará el cargo 7 veces, una vez cada 24 horas.

5. Recibe eventos

Configura webhooks para mantener tu sistema sincronizado. Para este flujo, consume sugerimos consumir los siguientes eventos:

Evento	Uso recomendado
`PAYMENT_COMPLETED`	Conciliar el pago y sus facturas relacionadas.
`PAYMENT_METHOD_CREATED`	Guardar o asociar la tarjeta que el cliente registró.
`PAYMENT_ATTEMPT_FAILED`	Mostrar o iniciar tu flujo de seguimiento ante un rechazo.
`INVOICE_PAID`	Marcar el adeudo como liquidado cuando se paga con un método integrado a Quentli.

Consulta la guía de Webhooks para ver los payloads y configurar tu endpoint.

6. Obtén referencias de efectivo y transferencia (opcional)

Solicita la instrucción del método que vas a mostrar al cliente. La llamada crea un pago pendiente o reutiliza uno existente del mismo tipo e importe.

POST /v1/invoices/{invoiceId}/payments

{
  "input": {
    "paymentType": "CASH"
  }
}

La respuesta de efectivo incluye payment.cashPaymentInstructions.reference y, cuando aplica, expiresAt:

Respuesta de efectivo

{
  "payment": {
    "id": "p_1234567890",
    "amount": 25000,
    "currency": "MXN",
    "isCompleted": false,
    "type": "CASH",
    "cashPaymentInstructions": {
      "reference": "12345678901234567890",
      "expiresAt": "2026-09-15T15:00:00.000Z"
    }
  }
}

Para una transferencia, cambia el tipo a TRANSFER. La respuesta incluye la CLABE, el banco y la referencia en payment.transferInstruction:

POST /v1/invoices/{invoiceId}/payments

{
  "input": {
    "paymentType": "TRANSFER"
  }
}

7. Informa pagos recibidos fuera de Quentli (opcional)

Si cobras una factura mediante un proveedor externo, informa a Quentli que ya fue liquidada para que no intente cobrar la tarjeta:

POST /v1/invoices/{invoiceId}/mark-paid

No necesitas hacer este cuando el pago llega por una referencia de efectivo o transferencia generada por Quentli; Quentli ya concilia ese pago con la factura pendiente y evita el cobro automático correspondiente.

Flujo completo

Tu sistema crea o identifica al cliente.
El cliente registra su tarjeta en una sesión de inscripción.
Tu sistema recibe el método de pago y crea la suscripción.
Tu sistema crea y sincroniza una factura por cada adeudo.
Tu sistema configura el endpoint de webhooks para recibir actualizaciones del cobro.
Tu sistema solicita la referencia de efectivo o transferencia que deba mostrar al cliente.
Quentli cobra, concilia métodos alternativos y envía webhooks.
Tu sistema procesa cada evento de forma idempotente y actualiza el estado comercial del adeudo.

Para validar este flujo sin datos de producción, consulta Prueba tu integración en sandbox.

Conceptos

Guías

Endpoints

Schemas

Antes de comenzar

1. Crea o identifica al cliente

2. Recopila una tarjeta para los cargos recurrentes

3. Crea la suscripción y asocia la tarjeta

4. Crea una factura por cada adeudo

5. Recibe eventos

6. Obtén referencias de efectivo y transferencia (opcional)

7. Informa pagos recibidos fuera de Quentli (opcional)

Flujo completo

​Antes de comenzar

​1. Crea o identifica al cliente

​2. Recopila una tarjeta para los cargos recurrentes

​3. Crea la suscripción y asocia la tarjeta

​4. Crea una factura por cada adeudo

​5. Recibe eventos

​6. Obtén referencias de efectivo y transferencia (opcional)

​7. Informa pagos recibidos fuera de Quentli (opcional)

​Flujo completo

Antes de comenzar

1. Crea o identifica al cliente

2. Recopila una tarjeta para los cargos recurrentes

3. Crea la suscripción y asocia la tarjeta

4. Crea una factura por cada adeudo

5. Recibe eventos

6. Obtén referencias de efectivo y transferencia (opcional)

7. Informa pagos recibidos fuera de Quentli (opcional)

Flujo completo