{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/toku/json-schema/toku-invoice-schema.json",
  "title": "Invoice",
  "description": "Deuda de un Customer: el monto que se le cobra, en qué estado de pago está y con qué datos se cobra.\n\nToda Invoice cuelga de un Customer y de una Subscription. La Subscription se indica por su identificador, si ya existe, o por el `product_id` del producto que la genera; en ese caso Toku la crea junto con la Invoice.\n\nDentro de una misma Subscription el `invoice_external_id` no se repite: es la clave con la que Toku decide si crea una Invoice nueva o actualiza la que ya existía.",
  "x-generated": "2026-11-10",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/toku-customers-api-openapi.yml#/components/schemas/Invoice",
  "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"
    },
    "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"
    },
    "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"
  ],
  "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"
    },
    "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"
    }
  }
}