Skip to main content

Products API

Endpoints to manage product inventory, from its creation, listing, details, and update.

Create a product​

Endpoint

POST /v1/products/

name and price fields are required. currency is optional; if not present CRC will be saved.

curl --location 'https://api.4geeks.io/v1/products/' \
--form 'name="Producto #1"' \
--form 'price="55"' \
--form 'currency="USD"'

Response will return the product id which you can make all the queries you need, such as using the product in Payment Links, to generate Payment logs, and future services provided by 4Geeks.

{
"code": 201,
"title": "Complete registration",
"content": "The registration was successfully completed.",
"type": "success",
"data": {
"id": "5c46d97b-22d5-4917-8833-3a61385d7c27"
}
}

Recurrence​

La recurrencia funciona para servicios como Payment Links, y el cual le brinda la funcionalidad de recurrencia en su cobro

Hay dos tipos de recurrencia:

1- Recurrencia por dia especifico de cobro

La cual se caracteriza por realizar el cobro en un dia especifico del mes a los clientes que tengas asociado a un Payment Link, los días pueden ir del 1 al 28 del mes

Ejemplo: Si deseas crear un producto de cobro a un cliente y este debe pagar todos los meses específicamente los días 15

2- Recurrencia por periodo

La característica de este tipo de recurrencia es que a diferencia de la anterior esta puede ser configurada en periodos de meses.

Ejemplo: Si deseas crear un producto de cobro bimensual a un cliente, este cliente al pagar se le enviara una nueva notificación dentro de 2 meses, y asi sucesivamente.

Este tipo de recurrencia puede tener los valores de 1,2,3,4,6,12 los cuales son valores en meses.

Como configurar la recurrencia

Para configurar la recurrencia se debe hacer cuando se crea un producto nuevo. La recurrencia es un objeto json que contiene la configuración de periodo o dia de cobro, asi como el tipo.

Ejemplos:

Recurrencia por dia especifico de cobro

{
"recurrence": "specific_billing_day",
"payday": 1
}
note

payday es el dia de cobro y recurrence el tipo de recurrencia

Recurrencia por periodo

{
"recurrence": "period",
"duration_period": 1
}
note

duration_period en este caso es el periodo en meses los valores permitidos son 1,2,3,4,6,12

Bueno, una ves generado el JSON se puede proceder a crear un producto:

curl --location 'https://api.4geeks.io/v1/products/' \
--form 'name="Membresia Mensual Gym Musculitos"' \
--form 'price="8500"' \
--form 'recurrence="{
\"recurrence\": \"period\",
\"duration_period\": 1
}"'
note

En caso de que su sistema no permita enviar un archivo JSON puedes convertirlo a un objeto de tipo String para el envió

Respuesta del servidor

{
"code": 201,
"title": "Complete registration",
"content": "The registration was successfully completed.",
"type": "success",
"data": {
"id": "73931315-cf8c-46bd-9f89-9b5b16612534"
}
}

Si realizamos la consulta de los detalles obtendremos lo siguiente:

{
"id": "73931315-cf8c-46bd-9f89-9b5b16612534",
"name": "Membresia Mensual Gym Musculitos",
"short_description": null,
"description": null,
"stock": 0,
"price": 8500.0,
"currency": "crc",
"is_physical": false,
"bar_code": null,
"sku": null,
"recurrence": {
"recurrence": "period",
"duration_period": 1
},
"images": {
"images": [],
"default": ""
},
"payment_link": false,
"test": true,
"total_price": 8500.0,
"taxes": []
}
note

Como se indico anteriormente la recurrencia solo puede ser configurada cuando se crea el producto

Impuestos​

note

Los impuestos pueden ser asociados al producto cuando se crear o se actualiza el producto

Crear un impuesto: POST /v1/taxes/

curl --location 'https://api.4geeks.io/v1/taxes/' \
--form 'name="Servicios Educativos Especial"' \
--form 'value="13"
note

El campo value es un porcentaje que permite también decimales, la lectura correcta seria impuesto del 13% a Servicios Educativos Especial

Respuesta del servidor

{
"code": 201,
"title": "Complete registration",
"content": "The registration was successfully completed.",
"type": "success",
"data": {
"id": 9
}
}

Listado de impuestos: GET /v1/taxes/

curl --location 'https://api.4geeks.io/v1/taxes/'

Respuesta del servidor

[
{
"id": 1,
"name": "iva",
"value": 3
},
{
"id": 8,
"name": "Servicios Educativos",
"value": 15
},
{
"id": 9,
"name": "Servicios Educativos Especial",
"value": 13
}
]

Actualización de impuestos: PUT /v1/taxes/

note

Los impuestos pueden ser actualizados uno por uno, o en bloque

Actualización de un único impuesto, se envía el siguiente JSON:

{
"taxes":{
"id": 1,
"name": "iva",
"value": 10.0
}
}

Actualización en bloques de impuestos, se envía el siguiente JSON:

{
"taxes": [
{
"id": 1,
"name": "iva",
"value": 10.0
},
{
"id": 9,
"name": "Servicios Educativos Especial",
"value": 13.0
},
{
"name": "Membresias IVA",
"value": 15.0
}
]
}

Ejemplo enviando el segundo JSON:

curl --location --request PUT 'localhost:8001/v1/taxes/' \
--data '{
"taxes": [
{
"id": 1,
"name": "iva",
"value": 10.0
},
{
"id": 9,
"name": "Servicios Educativos Especial",
"value": 13.0
},
{
"name": "Membresias IVA",
"value": 15.0
}
]
}'
note

En caso de que envies un impuesto sin ID este impuesto sera tomado como uno nuevo y se procederá a su creación, siempre y cuando el nombre no se encuentre en uso ya

Respuesta del servidor

{
"code": 200,
"title": "Completed operation",
"content": "Taxes were created or updated correctly",
"type": "success"
}

Como agregar un impuesto a un producto:

Para agregar los impuestos a un producto se le pasan estos de la siguiente manera:

"taxes": "1,9"

En un objeto de tipo String separados por ,

Tomaremos el producto que actualizamos anteriormente y ahora le agregaremos los 2 impuestos:

curl --location --request PUT 'https://api.4geeks.io/v1/products/5c46d97b-22d5-4917-8833-3a61385d7c27/' \
--form 'taxes: "1,9"'

respuesta del servidor

{
"code": 200,
"title": "Updated product",
"content": "The product was successfully updated.",
"type": "success",
"data": {
"id": "5c46d97b-22d5-4917-8833-3a61385d7c27",
"name": "Producto #1",
"short_description": "Producto dedicado a todas las edades",
"description": null,
"stock": 0,
"price": 55.0,
"currency": "USD",
"is_physical": false,
"bar_code": null,
"sku": null,
"recurrence": null,
"images": {
"images": [],
"default": ""
},
"payment_link": false,
"test": true,
"total_price": 73.15,
"taxes": [
{
"id": 1,
"name": "iva",
"value": 20.0
},
{
"id": 9,
"name": "Servicios Educativos Especial",
"value": 13.0
}
]
}
}
note

Puedes enviar el campo taxes de la misma forma a la hora de crear el producto

note

El campo total_price indica el precio del producto con los impuestos sumados

Imágenes en los productos​

Se deben enviar los archivo para las imágenes, esto puede ser enviado por medio de FormData

note

Los productos pueden tener 5 imágenes, 1 imagen principal y 4 secundarias

Ejemplo, quiero que mi producto tenga 3 imágenes:

curl --location --request PUT 'https://api.4geeks.io/v1/products/5c46d97b-22d5-4917-8833-3a61385d7c27/' \
--form 'image_default=@"/D:/Descargas/imagen_principal.png"' \
--form 'images=@"/D:/Descargas/imagen_3.png"' \
--form 'images=@"/D:/Descargas/imagen_2.jpg"'

respuesta del servidor

{
"code": 200,
"title": "Updated product",
"content": "The product was successfully updated.",
"type": "success",
"data": {
"id": "5c46d97b-22d5-4917-8833-3a61385d7c27",
"name": "Producto #1",
"short_description": "Producto dedicado a todas las edades",
"description": null,
"stock": 0,
"price": 55.0,
"currency": "USD",
"is_physical": false,
"bar_code": null,
"sku": null,
"recurrence": null,
"images": {
"default": "https://storage.googleapis.com/g-payments.appspot.com/img/2875-Producto%20%231-1677265824-default.png",
"images": [
{
"image": "https://storage.googleapis.com/g-payments.appspot.com/img/2875-Producto%20%231-1677265826-image%201.png"
},
{
"image": "https://storage.googleapis.com/g-payments.appspot.com/img/2875-Producto%20%231-1677265828-image%202.jpeg"
}
]
},
"payment_link": false,
"test": true,
"total_price": 73.15,
"taxes": [
{
"id": 1,
"name": "iva",
"value": 20.0
},
{
"id": 9,
"name": "Servicios Educativos Especial",
"value": 13.0
}
]
}
}
note

En caso de querer modificar una imagen deben volverse a enviar todos los archivos

note

En caso en caso de querer eliminar las imágenes se envían los campos imagen_default y images con un objeto de tipo string vació ""

Get a product​

Endpoint

GET /v1/products/<id>/

Los detalles de un producto se pueden consultar de la siguiente manera:

curl --location 'https://api.4geeks.io/v1/products/5c46d97b-22d5-4917-8833-3a61385d7c27/'

Respuesta del servidor

{
"id": "5c46d97b-22d5-4917-8833-3a61385d7c27",
"name": "Producto #1",
"short_description": null,
"description": null,
"stock": 0,
"price": 55,
"currency": "USD",
"is_physical": false,
"bar_code": null,
"sku": null,
"recurrence": null,
"images": {
"images": [],
"default": ""
},
"payment_link": false,
"test": true,
"total_price": 55,
"taxes": []
}

Como notaras hay muchos mas campos que cuando se creo el producto, todos estos campos son configurables y opcionales cuando se crea el producto o cuando se actualiza

note

La recurrencia solo puede ser configurada cuando se crea el producto

Update a product​

Endpoint

PUT /v1/products/<id>/

La actualización de un producto se realiza de la siguientes maneras

Imagina el caso en el que quieras actualizar la descripción corta del producto entonces realizarías la siguiente consulta:

Se envía el nombre del campo en este caso short_description con el valor que queremos darle, en este caso Producto dedicado a todas las edades

note

Puedes enviar multiples campos a la ves

curl --location --request PUT 'https://api.4geeks.io/v1/products/5c46d97b-22d5-4917-8833-3a61385d7c27/' \
--form 'short_description="Producto dedicado a todas las edades"'

El servidor te retornara la siguiente respuesta y en caso de necesitarlo en el campo data te devuelve los valores actualizados del producto

{
"code": 200,
"title": "Updated product",
"content": "The product was successfully updated.",
"type": "success",
"data": {
"id": "5c46d97b-22d5-4917-8833-3a61385d7c27",
"name": "Producto #1",
"short_description": "Producto dedicado a todas las edades",
"description": null,
"stock": 0,
"price": 55.0,
"currency": "USD",
"is_physical": false,
"bar_code": null,
"sku": null,
"recurrence": null,
"images": {
"images": [],
"default": ""
},
"payment_link": false,
"test": true,
"total_price": 55.0,
"taxes": []
}
}

Como notaras el campo short_description se actualizo correctamente

List products​

Endpoint

GET /v1/products/

Para consultar la lista de productos se realiza la siguiente consulta:

curl --location 'https://api.4geeks.io/v1/products/'

Respuesta del servidor

[
{
"id": "5c46d97b-22d5-4917-8833-3a61385d7c27",
"name": "Producto #1",
"short_description": "Producto dedicado a todas las edades",
"description": null,
"stock": 0,
"price": 55,
"currency": "USD",
"is_physical": false,
"bar_code": null,
"sku": null,
"recurrence": null,
"images": {
"images": [],
"default": ""
},
"payment_link": false,
"test": true,
"total_price": 55,
"taxes": []
},
{
"id": "b9028ee4-959d-49ac-a2d0-c2b6fa6056dd",
"name": "Producto #2",
"short_description": "Producto para niños",
"description": "Pack de juguetes infantiles",
"stock": 0,
"price": 155,
"currency": "USD",
"is_physical": false,
"bar_code": null,
"sku": null,
"recurrence": null,
"images": {
"images": [],
"default": ""
},
"payment_link": false,
"test": true,
"total_price": 155,
"taxes": []
}
]