> ## Documentation Index
> Fetch the complete documentation index at: https://docs.quentli.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Sincroniza facturas en Quentli

> Sincroniza adeudos de tu sistema con Quentli para programar cobros, ofrecer alternativas de pago y recibir notificaciones.

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.

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

## 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.

```json POST /v1/customers theme={null}
{
  "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](/api/guias/sesiones-de-inscripcion). 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.

```json POST /v1/setup-sessions theme={null}
{
  "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:

```text theme={null}
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.

```json POST /v1/subscriptions theme={null}
{
  "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.

```json POST /v1/invoices theme={null}
{
  "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.

<Tip>
  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.
</Tip>

## 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](/api/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.

```json POST /v1/invoices/{invoiceId}/payments theme={null}
{
  "input": {
    "paymentType": "CASH"
  }
}
```

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

```json Respuesta de efectivo theme={null}
{
  "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`:

```json POST /v1/invoices/{invoiceId}/payments theme={null}
{
  "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:

```text theme={null}
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

1. Tu sistema crea o identifica al cliente.
2. El cliente registra su tarjeta en una sesión de inscripción.
3. Tu sistema recibe el método de pago y crea la suscripción.
4. Tu sistema crea y sincroniza una factura por cada adeudo.
5. Tu sistema configura el endpoint de webhooks para recibir actualizaciones del cobro.
6. Tu sistema solicita la referencia de efectivo o transferencia que deba mostrar al cliente.
7. Quentli cobra, concilia métodos alternativos y envía webhooks.
8. 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](/api/guias/prueba-tu-integracion-en-sandbox).