Asociar Invoices a Customers

📘

Esta sección explica el proceso de creación de Invoices a través de la API REST de Toku. También puedes verlo en la documentación de la API aquí.

Luego de tener registrados a nuestros clientes en Toku como Customers y haber guardado sus ids, podemos cargar deudas asociados a ellos. A continuación se explica la creación de Invoices utilizando la API REST de Toku.

Un Invoice contiene la información de una deuda. La creación de un Invoice requiere del id único del Customer para poder relacionarlo a sus datos de contacto, el cual tiene la forma cus_lq1wGjwgFyqQm4ACZx0QjE84qKm8fff. Este ID debe ser capturado al crear el Customer en Toku, explicado en el paso previo de esta guía.

A continuación, vemos cómo crear un Invoice a traves de una request POST a la API.

POST /invoices

Parametros para crear Invoice

Nombre

Tipo

Descripción

Requerido

customer

string

ID del Customer entregado en su creación.

:radio-button: Si

product_id

string

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

:radio-button: Si

due_date

date

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

:white-circle: No

amount

float

Monto adeudado en CLP.

:white-circle: No

is_paid

boolean

Indica si el Invoice se encuentra pagado o no.

:white-circle: No

is_void

boolean

Indica si el Invoice se encuentra anulado o no. Los Invoices anulados se tratan como si hubiesen sido borrados.

:white-circle: No

link_payment

string

URL en el que se debe pagar el Invoice. Dejar en blanco en caso de usar el portal de pagos de Toku. Incluir solo en el case de que poseas tu propio procesador de pagos.

:white-circle: No

metadata

json

Valores adicionales específicos de cada cliente. Son tratados como valores de texto y que no pueden tener más de 256 caracteres cada uno. Debes agregarlos en la webapp de Toku antes de poder utilizarlos aquí.

:white-circle: No

❗️

Importante

link_payment es un campo opcional, el cual no debe enviarse en caso de utilizar el Portal de Pagos proporcionado por Toku. Solo debe enviarse en caso de utilizar un portal de pagos externo.

El Body del request debe ser de la siguiente forma:

{
  "customer": "cus_lq1wGjwgFyqQm4ACZx0QjE84qKm8fffa",
  "is_paid": false,
  "is_void": false,
  "amount": 1000,
  "product_id": "92792",
  "due_date": "2021-03-04",
  "link_payment": "https://portal.pagos.com/tu-empresa",
  "metadata": {
    "car_brand": "Toyota",
    "car_model": "Yaris"
  }
}

Como ves, el campo customer permite asociar este Invoice a los datos de contacto del Customer, y se usará para notificarte acciones tales como inscripciones o pagos realizados.

La respuesta recibida es de la forma:

{
  "customer": "cus_lq1wGjwgFyqQm4ACZx0QjE84qKm8fffa",
  "is_paid": false,
  "is_void": false,
  "amount": 1000,
  "product_id": "92792",
  "due_date": "2021-03-04",
  "link_payment": "https://portal.pagos.com/tu-empresa",
  "metadata": {
    "car_brand": "Toyota",
    "car_model": "Yaris"
  },
  "id": "in_5tswGjwgAxrQm4ACZx0QjE84qKm8fgsw"
}

El campo id identifica al Invoice creado, y es de la forma in_5tswGjwgAxrQm4ACZx0QjE84qKm8fgsw. Puede ser utilizado para consultar el estado de un Invoice en Toku o para anular el mismo en caso de que ya no deba ser cobrado. A continuación, vemos cómo obtener un Invoice creado en Toku a través de una request GET a la API.

GET /invoices/{id}

Una vez creado un Invoice, podemos consultar su estado. Debemos incluir en el path el ID del Invoice obtenido al momento de su creación, de la forma:

https://api.trytoku.com/invoices/in_5tswGjwgAxrQm4ACZx0QjE84qKm8fgsw

Parametros para obtener Invoice

Nombre

Tipo

Descripción

Requerido

id

string

Identificador único del Invoice.

:radio-button: Si

La respuesta recibida es de la forma:

{
  "customer": "cus_lq1wGjwgFyqQm4ACZx0QjE84qKm8fffa",
  "is_paid": false,
  "is_void": false,
  "amount": 1000,
  "product_id": "92792",
  "due_date": "2021-03-04",
  "link_payment": "https://portal.pagos.com/tu-empresa",
  "metadata": {
    "car_brand": "Toyota",
    "car_model": "Yaris"
  },
  "id": "in_5tswGjwgAxrQm4ACZx0QjE84qKm8fgsw"
}

A continuación, vemos cómo anular un Invoice creado en Toku a través de una request POST a la API.

POST /invoices/{id}/void

Luego de creado un Invoice podriamos queremos anularlo, en caso de que ya se haya pagado por otra vía o en definitiva no se quiere seguir con su cobro. Para esto, debemos marcar is_void como true. Se debe incluir en el path el ID del Invoice obtenido al momento de su creación, de la forma:

https://api.trytoku.com/invoices/in_5tswGjwgAxrQm4ACZx0QjE84qKm8fgsw/void

Parametros para anular Invoice

Nombre

Tipo

Descripción

Requerido

id

string

Identificador único del Invoice.

:radio-button: Si

La respuesta recibida es de la forma:

{
  "customer": "cus_lq1wGjwgFyqQm4ACZx0QjE84qKm8fffa",
  "is_paid": false,
  "is_void": true,
  "amount": 1000,
  "product_id": "92792",
  "due_date": "2021-03-04",
  "link_payment": "https://portal.pagos.com/tu-empresa",
  "metadata": {
    "car_brand": "Toyota",
    "car_model": "Yaris"
  },
  "id": "in_5tswGjwgAxrQm4ACZx0QjE84qKm8fgsw"
}

Como vemos, el Invoice ahora aparece como anulado, con is_void = true.


Siguientes pasos

Una vez creado un Invoice entrará en el proceso de cobro de Toku. Para recibir actualizaciones respecto de este proceso, es necesario que habilites un webhook en el que Toku pueda enviarte estas actualizaciones. Explicamos este proceso a continuación.