TRtrytoku
Invoices

Editar Invoice

Actualiza los datos de una Invoice existente.

Solo modifica los campos presentes en el cuerpo; los omitidos se mantienen sin cambios. Devuelve la Invoice ya actualizada y responde 404 si no existe bajo la organización y Account autenticadas.

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

put/invoices/{encrypted_invoice_id}

Request

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

Path parameters

encrypted_invoice_idstring required

Identificador público de la Invoice a editar (in_...).

Example:in_9K0bTq3xR7yA2sVpLmZ4wE1nHdJf6UcQ

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

Request body

amountnumber

Monto de la Invoice, 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. Debe ser menor que 1.000.000.000.000.000 (10^15).

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

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

disable_automatic_paymentboolean

Excluye la Invoice 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

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

expiration_datestring

Fecha y hora de expiración de la Invoice; a partir de ese momento no se realizan más intentos de cobro. Se acepta YYYY-MM-DD HH:MM:SS (hora local de la organización) o una fecha ISO 8601 con zona horaria explícita.

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

Marca la Invoice como pagada: registra un pago externo por el monto total de la Invoice. Al editar una Invoice ya pagada, enviarlo en false elimina el pago registrado y la deja no pagada; no se puede desmarcar si el pago lo cobró Toku.

is_voidboolean

Indica si la Invoice está anulada.

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.

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.

payment_amountnumber

Monto del pago externo a registrar cuando la misma solicitud marca la Invoice como pagada con is_paid: true; si se omite, el pago se registra por el total de la Invoice. Su caso de uso habitual es una Invoice expresada en UF (CLF) que se cobra en pesos: sirve para dejar registrado el monto efectivamente cobrado en la moneda del cobro. No fija el monto pagado de la Invoice (paid_amount): ese valor lo calcula Toku a partir de los pagos registrados, así que enviar payment_amount sin is_paid: true se rechaza con 422. Para registrar un pago parcial se usa POST /external-transactions. Debe ser mayor que 0 y menor que 1.000.000.000.000.000 (10^15).

product_idstring

Identificador del producto de la organización asociado a la Invoice.

receipt_type'bill' | 'invoice' | 'no_receipt'

Documento tributario que se emite al cobrar: bill es una boleta, invoice una factura y no_receipt deja el cobro sin documento asociado.

sourcestring

Origen desde el que se creó la Invoice. Se informa cuando la carga proviene de una integración o de un proceso interno; en una creación por API se deja vacío.

subscriptionstring

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

Example request

{
  "amount": 19990,
  "customer": "cus_ejC08yLqOWoFhVx4Fx42E3IR9X50tNx2",
  "due_date": "2025-03-10",
  "expiration_date": "2025-03-10 00:00:00",
  "invoice_external_id": "F-2025-000123",
  "link_payment": "https://portal.pagos.com/tu-empresa",
  "metadata": {
    "sucursal": "Providencia"
  },
  "payment_amount": 10000,
  "product_id": "plan-oro-marzo-2025",
  "subscription": "sub_Y_EgOXMloD5-IJn6d9S2IxkNvp9p0iiP"
}

Response

Invoice ya actualizada.

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

No recorded changes to this operation across all 2 revisions of this API.