TRtrytoku
Invoices

Buscar Invoice por identificadores externos

Changed on

Busca una única Invoice a partir de identificadores externos.

Se usa cuando no se tiene el identificador público de Toku pero sí el identificador externo con el que se cargó la Invoice. Debes enviar al menos un parámetro de búsqueda; la combinación debe identificar a una sola Invoice dentro de la Account autenticada.

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

get/invoices/lookup

Request

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

Query parameters

invoice_external_idstring

Identificador externo de la Invoice definido por la organización.

Example:F-2025-000123

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

Invoice que coincide con los identificadores indicados.

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

  • a6ef070075b1Revision changes
    • breaking

      for the header request parameter x-account-key, default value was added

    • breaking

      removed the required property from the response with the status

    • warning

      removed the optional property / from the response with the status

    • warning

      removed the optional property / from the response with the status

    • info

      api operation id get_invoices-lookup removed and replaced with lookup_invoice

    • info

      api tag Invoices added

    • info

      added the new optional header request parameter x-api-version

    • info

      the query request parameter invoice_external_id became optional

    • info

      added the non-success response with the status

    • info

      added the non-success response with the status

    • info

      added the non-success response with the status

    • info

      the response property / became required for the status

    • info

      the response property / became required for the status

    • info

      added the required property to the response with the status

    • info

      added the required property to the response with the status