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

❗️

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

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

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.