{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/toku/json-schema/toku-list-invoices-schema.json",
  "title": "ListInvoices",
  "x-generated": "2026-11-10",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/toku-invoices-api-openapi.yml#/components/schemas/ListInvoices",
  "properties": {
    "items": {
      "items": {
        "$ref": "#/$defs/DTOInvoice"
      },
      "title": "Items",
      "type": "array"
    },
    "next_cursor": {
      "title": "Next Cursor",
      "type": "string"
    }
  },
  "required": [
    "items",
    "next_cursor"
  ],
  "type": "object",
  "$defs": {
    "CurrencyIso": {
      "description": "Moneda, en código [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html). Cubre las monedas de los países donde Toku opera —`CLP` (peso chileno), `MXN` (peso mexicano) y `BRL` (real)— más `USD` y `CLF`, la Unidad de Fomento chilena. La moneda determina cuántos decimales admiten los montos: `CLP` no admite decimales, `MXN`, `BRL` y `USD` admiten dos, y `CLF` cuatro.",
      "enum": [
        "CLP",
        "CLF",
        "MXN",
        "BRL",
        "USD"
      ],
      "title": "CurrencyIso",
      "type": "string"
    },
    "DTOInvoice": {
      "description": "Representa una deuda emitida a un cliente.\n\nUna deuda es el documento de cobro asociado a un cliente y a una suscripción. Registra el monto adeudado, su estado de pago y los datos necesarios para cobrarla.",
      "properties": {
        "account": {
          "description": "Identificador público de la Account de cobro a la que pertenece la Invoice.",
          "title": "Account",
          "type": "string"
        },
        "amount": {
          "description": "Monto adeudado, expresado en la moneda indicada en `currency_code`. La cantidad de decimales admitida la define la moneda: CLP no acepta decimales, MXN y BRL aceptan 2, y CLF acepta 4.",
          "title": "Amount",
          "type": "number"
        },
        "currency_code": {
          "allOf": [
            {
              "$ref": "#/$defs/CurrencyIso"
            }
          ],
          "description": "Moneda de la Invoice. Si no se envía, se toma la de la Account de cobro. Determina cuántos decimales admite el monto."
        },
        "customer": {
          "description": "Identificador público del Customer dueño de la Invoice.",
          "title": "Customer",
          "type": "string"
        },
        "disable_automatic_payment": {
          "default": false,
          "description": "Indica si la Invoice está excluida del cobro automático. Permite cargarla sin que se mande a cobrar aunque el Customer tenga un método de pago automático activo.",
          "title": "Disable Automatic Payment",
          "type": "boolean"
        },
        "due_date": {
          "description": "Fecha de vencimiento de la Invoice, en formato `YYYY-MM-DD`.",
          "title": "Due Date",
          "type": "string"
        },
        "expiration_action": {
          "allOf": [
            {
              "$ref": "#/$defs/InvoiceExpirationAction"
            }
          ],
          "description": "Acción que se ejecuta sobre la Invoice cuando expira."
        },
        "expiration_date": {
          "description": "Fecha y hora de expiración de la Invoice. A partir de ese momento no se realizan más intentos de cobro.",
          "format": "date-time",
          "title": "Expiration Date",
          "type": "string"
        },
        "general_status": {
          "description": "Estado general de la deuda de cara al cliente, derivado de su estado interno. Valores posibles: `paid`, `partially_paid`, `unpaid`, `void`, `expired`.",
          "title": "General Status",
          "type": "string"
        },
        "id": {
          "description": "Identificador público de la Invoice.",
          "title": "Id",
          "type": "string"
        },
        "id_receipt": {
          "description": "Identificador del recibo asociado a la Invoice.",
          "title": "Id Receipt",
          "type": "integer"
        },
        "in_progress": {
          "description": "Indica si la deuda tiene un cobro en curso, es decir, un pago que aún no se confirma ni se rechaza.",
          "title": "In Progress",
          "type": "boolean"
        },
        "invoice_external_id": {
          "description": "Identificador único de la deuda externo a Toku. Permite distinguir dos Invoices del mismo producto que vencen el mismo día.",
          "title": "Invoice External Id",
          "type": "string"
        },
        "is_paid": {
          "default": false,
          "description": "Indica si la Invoice está pagada.",
          "title": "Is Paid",
          "type": "boolean"
        },
        "is_void": {
          "default": false,
          "description": "Indica si la Invoice está anulada. Las Invoices anuladas se tratan como si hubiesen sido borradas.",
          "title": "Is Void",
          "type": "boolean"
        },
        "link_payment": {
          "description": "URL donde se debe pagar la Invoice. Se deja vacía para usar el portal de pagos de Toku; se completa solo si se desea utilizar un procesador de pagos externo.",
          "title": "Link Payment",
          "type": "string"
        },
        "max_collection_attempts": {
          "description": "Cantidad máxima de intentos de cobro antes de que la Invoice expire.",
          "title": "Max Collection Attempts",
          "type": "integer"
        },
        "metadata": {
          "additionalProperties": {
            "type": "string"
          },
          "description": "Valores adicionales definidos por la organización. Se tratan como texto y no pueden superar los 256 caracteres cada uno. Deben declararse en la webapp de Toku antes de poder usarse.",
          "title": "Metadata",
          "type": "object"
        },
        "paid_amount": {
          "description": "Monto ya pagado de la Invoice. Se usa para reflejar pagos parciales.",
          "title": "Paid Amount",
          "type": "number"
        },
        "product_id": {
          "description": "Identificador interno del producto que genera la Invoice. Puede ser un número de contrato o de propuesta.",
          "title": "Product Id",
          "type": "string"
        },
        "receipt_type": {
          "description": "Tipo de recibo a emitir para la Invoice: `bill` (boleta), `invoice` (factura) o `no_receipt` (sin recibo).",
          "title": "Receipt Type",
          "type": "string"
        },
        "refund_data": {
          "allOf": [
            {
              "$ref": "#/$defs/RefundData"
            }
          ],
          "description": "Datos de la devolución asociada a la Invoice. Es nulo si la Invoice no tiene devoluciones.",
          "title": "Refund Data"
        },
        "remaining_collection_attempts": {
          "description": "Intentos de cobro que quedan disponibles. Se reinicia por completo si cambia `max_collection_attempts`.",
          "title": "Remaining Collection Attempts",
          "type": "integer"
        },
        "source": {
          "description": "Origen desde el que se creó la Invoice, por ejemplo una carga masiva, una integración o una Subscription recurrente. Es nulo cuando no se informó al crearla.",
          "title": "Source",
          "type": "string"
        },
        "status": {
          "allOf": [
            {
              "$ref": "#/$defs/InvoiceStatus"
            }
          ],
          "description": "Estado detallado de la Invoice, incluyendo si tiene un cobro en curso."
        },
        "subscription": {
          "description": "Identificador público de la Subscription a la que pertenece la Invoice.",
          "title": "Subscription",
          "type": "string"
        }
      },
      "required": [
        "id",
        "customer",
        "subscription",
        "product_id",
        "due_date",
        "status",
        "general_status",
        "in_progress"
      ],
      "title": "DTOInvoice",
      "type": "object"
    },
    "InvoiceExpirationAction": {
      "description": "Acción que se ejecuta sobre una Invoice cuando expira: marcarla como expirada (`EXPIRE`), anularla (`VOID`) o eliminarla (`DELETE`). `EXPIRE` es legado: se mantiene por compatibilidad, pero deja la Invoice en el estado `EXPIRED`, que está deprecado. Para nuevas integraciones usa `VOID` o `DELETE`.",
      "enum": [
        "EXPIRE",
        "VOID",
        "DELETE"
      ],
      "title": "InvoiceExpirationAction",
      "type": "string"
    },
    "InvoiceStatus": {
      "description": "Estado detallado de una Invoice. Combina el avance del pago (sin pagar, parcialmente pagada, pagada) con la existencia de un cobro en curso, y cubre además los estados terminales de anulación y eliminación. `EXPIRED` está deprecado: solo lo alcanzan las Invoices con acción de expiración `EXPIRE`.",
      "enum": [
        "DELETED",
        "VOID",
        "UNPAID",
        "PAID",
        "PARTIALLY_PAID",
        "EXTERNALLY_PAID",
        "UNPAID_PAYMENT_IN_PROGRESS",
        "PARTIALLY_PAID_PAYMENT_IN_PROGRESS",
        "UNPAID_NON_BLOCKING_PAYMENT_IN_PROGRESS",
        "PARTIALLY_PAID_NON_BLOCKING_PAYMENT_IN_PROGRESS",
        "UNPAID_PARTIAL_PAYMENT_IN_PROGRESS",
        "PARTIALLY_PAID_PARTIAL_PAYMENT_IN_PROGRESS",
        "EXPIRED"
      ],
      "title": "InvoiceStatus",
      "type": "string"
    },
    "RefundData": {
      "properties": {
        "id_transaction_payment": {
          "title": "Id Transaction Payment",
          "type": "string"
        },
        "id_transaction_refund": {
          "title": "Id Transaction Refund",
          "type": "string"
        },
        "refund_amount": {
          "title": "Refund Amount",
          "type": "number"
        },
        "refund_reason": {
          "title": "Refund Reason",
          "type": "string"
        },
        "refund_status": {
          "$ref": "#/$defs/RefundStatus"
        }
      },
      "required": [
        "refund_status",
        "refund_amount",
        "refund_reason",
        "id_transaction_payment",
        "id_transaction_refund"
      ],
      "title": "RefundData",
      "type": "object"
    },
    "RefundStatus": {
      "description": "Resultado de la devolución asociada a una Invoice.",
      "enum": [
        "success",
        "failed"
      ],
      "title": "RefundStatus",
      "type": "string"
    }
  }
}