TRtrytoku
Invoices

Listar Invoices de un Customer

Changed on

Devuelve todas las Invoices de un Customer dentro de la Account autenticada.

Similar a GET /customers/{customer_encrypted_id}/invoices, pero acotado a la Account autenticada y responde 404 cuando el Customer no tiene Invoices. Se usa para revisar el detalle de cobros de un Customer puntual.

Límite de tasa: 20 solicitudes por segundo. Al superarlo, la API responde 429. Ver Límites de tasa.

get/invoices/customer/{customer_encrypted_id}

Request

  • Base URL
    https://api.trytoku.com
  • URL
    https://api.trytoku.com/invoices/customer/{customer_encrypted_id}
  • Auth
    API key in header x-api-key

Path parameters

customer_encrypted_idstring required

Identificador público del Customer (cus_...) cuyas Invoices se listan.

Example:cus_ejC08yLqOWoFhVx4Fx42E3IR9X50tNx2

Headers

x-account-keystring

Llave de API de una Account, para operar sobre esa Account en lugar de la principal.

x-api-versionstring date

Versión del API para esta petición, como cualquier fecha YYYY-MM-DD. Fija el contrato de la respuesta; si se omite, se deriva de la fecha de creación de la organización.

Example:2026-10-08

Response

Invoices que pertenecen al Customer.

accountstring

Identificador público de la Account de cobro a la que pertenece la Invoice.

amountnumber

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.

currency_code'CLP' | 'CLF' | 'MXN' | 'BRL' | 'USD'

Moneda, en código ISO 4217. 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.

customerstring required

Identificador público del Customer dueño de la Invoice.

disable_automatic_paymentboolean

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.

due_datestring required

Fecha de vencimiento de la Invoice, en formato YYYY-MM-DD.

expiration_action'EXPIRE' | 'VOID' | 'DELETE'

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.

expiration_datestring date-time

Fecha y hora de expiración de la Invoice. A partir de ese momento no se realizan más intentos de cobro.

idstring required

Identificador público de la Invoice.

id_receiptinteger

Identificador del recibo asociado a la Invoice.

invoice_external_idstring

Identificador único de la deuda externo a Toku. Permite distinguir dos Invoices del mismo producto que vencen el mismo día.

is_paidboolean

Indica si la Invoice está pagada.

is_voidboolean

Indica si la Invoice está anulada. Las Invoices anuladas se tratan como si hubiesen sido borradas.

link_paymentstring

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.

max_collection_attemptsinteger

Cantidad máxima de intentos de cobro antes de que la Invoice expire.

metadataobject

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.

paid_amountnumber

Monto ya pagado de la Invoice. Se usa para reflejar pagos parciales.

product_idstring required

Identificador interno del producto que genera la Invoice. Puede ser un número de contrato o de propuesta.

receipt_typestring

Tipo de recibo a emitir para la Invoice: bill (boleta), invoice (factura) o no_receipt (sin recibo).

remaining_collection_attemptsinteger

Intentos de cobro que quedan disponibles. Se reinicia por completo si cambia max_collection_attempts.

sourcestring

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.

status'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' required

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.

subscriptionstring required

Identificador público de la Subscription a la que pertenece la Invoice.

Example response

[
  {
    "account": "acc_gzD0XoUTFxbUFcItpWOCqN686noSd9HQ",
    "amount": 19990,
    "customer": "cus_ejC08yLqOWoFhVx4Fx42E3IR9X50tNx2",
    "due_date": "2025-03-10",
    "expiration_date": "2025-03-10T03:00:00Z",
    "id": "in_9K0bTq3xR7yA2sVpLmZ4wE1nHdJf6UcQ",
    "invoice_external_id": "F-2025-000123",
    "link_payment": "https://portal.pagos.com/tu-empresa",
    "max_collection_attempts": 3,
    "metadata": {
      "sucursal": "Providencia"
    },
    "product_id": "plan-oro-marzo-2025",
    "receipt_type": "bill",
    "remaining_collection_attempts": 3,
    "source": "integration_etl",
    "subscription": "sub_Y_EgOXMloD5-IJn6d9S2IxkNvp9p0iiP"
  }
]

Changes