Cobro

Las cobros son compromisos de montos adeudados por un cliente y se generan de forma puntual o periódica a partir de una suscripción.

Existen cuatro tipos de cobros especificados en el parámetro type:

invoice es un cobro que esta asociado a una factura

one_time es un cobro único que no esta asociado a ningún otro objeto

subscription_creation es un cobro que esta asociado a una suscripción y se crea automáticamente cuando se genera una nueva suscripción

subscription_renewal es un cobro que esta asociado a una suscripción y se crea automáticamente cuando se renueva una nueva suscripción existente

Objeto de cobro

Cobro

string

read-onlyrequired

Identificador único del objeto.

Example:

col_zdhBDP4k3JiRHNQ4RBUHyHgu

items

array[object (Items) {9}]

optional

Lista de items del cobro, cada uno con un precio adjunto. Únicamente requerido y permitido si type=one_time.

string

read-onlyrequired

Identificador único del objeto.

Example:

si_d7d2UrHwSG5A5YkYF7vfZmFf

name

string

read-onlyrequired

Nombre del producto del producto, al momento de asociarlo a la suscripción.

Example:

Nombre del producto

unit_price

string

optional

Precio unitario a cobrar del item. Al asociar un precio a un object, si no se define, se utiliza el precio unitario configurado en el precio.

Example:

20000.00

quantity

integer

required

Cantidad a cobrar del item.

>= 1

Example:

subtotal

string

read-onlyoptional

Subtotal a cobrar del item antes, antes de descuentos.

Example:

20000.00

total

string

read-onlyoptional

Total a cobrar del item, despues de descuentos.

Example:

20000.00

product

object (Producto)

read-onlyoptional

Producto asociado al item.

price

object (Precio)

read-onlyoptional

Precio asociado al item.

price

string

write-onlyrequired

El ID del objeto de precio.

Example:

price_1Q8VwAGkNzLGa86BS12312

discounts

array [object {4}]

optional

Lista de descuentos del cobro, cada uno con un cupon adjunto. Únicamente requerido y permitido si type=one_time.

string

read-onlyrequired

Identificador único del objeto.

Example:

sd_aYbDFQaOd7TmBl0I58D5ax8l

code

string

required

Código del cupon de descuento. Debe estar previamente creado en Treli.

Example:

10OFF

amount

string

read-onlyrequired

Valor en dinero del descuento, representado como una cadena flotante con dos decimales.

Example:

10000.00

percent

string | null

read-onlyoptional

Valor en porcentaje del descuento, representado como una cadena flotante con dos decimales. Únicamente aplica si el cupón type=percent

Example:

10.00

description

string

read-onlyrequired

Descripción del cobro. Se define automáticamente según el ´type´ del cobro.

Example:

Cobro de factura

subtotal

string | null

read-onlyrequired

Subtotal del cobro, antes de descuentos e impuestos, representado como una cadena flotante con dos decimales. null para los cobros de tipo factura (type=invoice)

total

string

optional

Valor total a cobrar del cobro, antes de descuentos e impuestos, representado como una cadena flotante con dos decimales. Únicamente puedes especificar el total para cobros de type=invoice, de lo contrario, se calcula automáticamente según los items del cobro.

status

enum<string>

read-onlyrequired

Un cobro que aún no haya sido pagado y aún no haya vencido, tendrá estado pending.

Despúes del due_date del cobro, tendrá estado past_due.

Un cobro puede pasar a estado uncollectible, despúes de past_due si sigue sin pagarse en una fecha límite posterior (según tu configuración de reintentos y recordatorios).

Allowed values:

pendingpaidpast_dueuncollectiblevoided

currency

enum<string>

required

Código de moneda ISO de tres letras, en mayúsculas.

>= 3 characters<= 3 characters

Allowed values:

COPUSDBRLMXNPENARSCLP

Example:

COP

created_date

string <date-time>

read-onlyrequired

Fecha en la cual se creó el objeto.

Example:

2024-11-15 16:44:50

paid_date

string <date-time> | null

read-onlyoptional

Fecha en la cual se pagó el cobro.

voided_at_date

string <date-time> | null

read-onlyoptional

Fecha en la cual se anuló el cobro.

due_date

string <date-time> | null

read-onlyoptional

Fecha de vencimiento del cobro.

collection_method

enum<string>

required

Define como se cobrará el cobro.

Allowed values:

chargecollect

days_until_due

integer | null

write-onlyoptional

Número de días desde la creación del cobro hasta su vencimiento. Válido solo para cobros concollection_method=collect

collection_rule_id

string | null

optional

El ID de la regla de cobro que definirá el comportamiento del cobro. La regla de cobro debe estar creada previamente en tu cuenta de Treli. Válido solo para cobros concollection_method=collect.

payment_method

string

write-onlyoptional

ID del método de pago que se utilizará para cobrar el cobro. Debe pertenecer al cliente asociado al cobro. Si no se define ninguno, el cobro utilizará el método de pago predeterminado del cliente, en caso de que exista. Sólo permitido si collection_method=charge.

type

enum<string>

required

El tipo de cobro. invoice y one_time son los únicos tipos de cobro que pueden ser especificados al momento de crear un cobro.

Para los cobros asociados a suscripciones, el tipo es definido automáticamente (subscription_creation y subscription_renewal)

Allowed values:

invoicesubscription_creationsubscription_renewalone_time

is_test

boolean

read-onlyrequired

Tiene el valor false si el objeto existe en modo en producción o el valor true si el objeto existe en modo de prueba

Example:

false

tag

string | null

optional

Etiqueta asociada a la suscripción.

source

string

required

Fuente por la cual se genero la suscripción

meta_data

object | null

optional

Conjunto de pares clave-valor que se pueden asociar a un objeto. Esto puede ser útil para almacenar información adicional sobre el objeto en un formato estructurado. Las claves se pueden eliminar publicando un valor vacío en los metadatos.

payment_settings

null

optional

invoice_settings

object

optional

Objeto con ajustes de facturación especificos para el cobro, distintos a los definidos en la configuración general de facturación. Unicamente disponible si haces uso de la automatización contable en Treli para la generación automática de facturas.

invoice_document_id

string

required

invoice_cost_center

string

required

invoice_retentions

object

required

reteica

string

required

retefte

string

required

collection_attempts

integer

read-onlyrequired

Número de intentos de cobro realizados para este cobro, según la configuración de recordatorios y reintentos. Solo los reintentos automáticos incrementan el recuento. En otras palabras, los intentos de pago manuales no afectan el programa de reintentos.

Para collection_method=charge, si se devuelve un error con un código de no reintentable o se han sobrepasado la cantidad de reintentos permitidos al método de pago, el cobro ya no podrá reintentarse a menos que se obtenga un nuevo método de pago. Los reintentos se seguirán programando y el número de intentos seguirá incrementándose, pero solo se ejecutarán si se obtiene un nuevo método de pago.

collecting

boolean

required

Controla si Treli debe realizar reintentos automaticos de cobro. Cuando finalizan los reintentos programados según la configuración de recordatorios y reintentos, el valor pasa a false.

next_collection_attempt_date

string <date-time> | null

read-onlyoptional

Una fecha en el futuro en la que se realizará el próximo reintento de cobro, según la configuración de recordatorios y reintentos.

payment_method_gateway

string

read-onlyoptional

Pasarela de pago asociada a el método de pago utilizado en el cobro.

payment_method_type

string

read-onlyoptional

Tipo de método de pago utilizado en el cobro.

paid_out_of_band

boolean

required

Booleano que representa si un cobro se marcó como pagado por fuera de Treli.

out_of_band_proof

string <uri> | null

optional

URL del soporte de pago. Válido solo para cobros conpaid_out_of_vand=true.

customer

string

required

Identificación del cliente asociado al cobro.

billing_address

object

read-onlyoptional

Dirección de facturación del cobro. Se define automáticamente al crear el cobro, según la dirección de facturación del cliente.

address_1

string

required

address_2

null

required

city

string

required

state

string

required

postcode

null

required

country

string

required

subscription

string | null

read-onlyoptional

ID de la suscripción asociada al cobro. Únicamente si collection_type=subscription_creation o collection_type=subscription_renewal

invoice

string | null

read-onlyoptional

ID de la factura asociada al cobro. Cobros contype=invoice siempre van a tener una factura asociada.

Cobros contype=one_time, subscription_renewal y subscription_creation tendrán una factura asociada si haces uso de la automatización contable en Treli para la generación automática de facturas.

invoice_number

string | null

read-onlyoptional

Número de la factura asociada al cobro. Cobros detype=invoice siempre van a tener una factura asociada.

Cobros contype=one_time, subscription_renewal y subscription_creation tendrán una factura asociada si haces uso de la automatización contable en Treli para la generación automática de facturas.

checkout_url

string

read-onlyrequired

URL en la cual tu cliente puede realizar el pago del cobro.

Objeto de cobro#

Objeto de cobro