Agregar un item al carrito libre

Agrega una nueva mercadería o servicio al carrito de compras libre. Permite incluir mercaderías o servicios con sus respectivos precios y cantidades.

---

Entorno

URL base: https://api.guarani.app

Endpoint

POST /carritos/libre/{id}/items

Ejemplo de solicitud HTTP (cURL)

# USD
curl -X POST "https://api.guarani.app/carritos/libre/{id}/items" \
  -H "Content-Type: application/json" \
  -H "x-api-key: Bearer <access_token>" \
  -d '{
    "codigo_interno": "01-ABC1245",
    "descripcion": "Producto o servicio libre",
    "precio_unitario": {
      "0": 9.59,
      "5": 0,
      "10": 4.10
    },
    "cantidad": 1,
    "unidad_medida_id": "5f49c6c1-d622-4f5b-9d8b-2d1636b584ab",
    "total": 13.69
  }' | jq

# PYG
curl -X POST "https://api.guarani.app/carritos/libre/{id}/items" \
  -H "Content-Type: application/json" \
  -H "x-api-key: Bearer <access_token>" \
  -d '{
    "codigo_interno": "01-ABC1245",
    "descripcion": "Producto o servicio libre",
    "precio_unitario": {
      "0": 0,
      "5": 0,
      "10": 95000
    },
    "cantidad": 2,
    "unidad_medida_id": "5f49c6c1-d622-4f5b-9d8b-2d1636b584ab",
    "total": 190000
  }' | jq

Nota: El codigo interno es 01- para productos y 02- para servicios. Nota: Asegúrate de reemplazar {id} con el ID del carrito y <access_token> con un token JWT válido proporcionado por el equipo Guaraní. Importante:
Es imprescindible incluir un token de acceso válido en el encabezado x-api-key para autenticar y autorizar el uso de este endpoint. Sin este token, la solicitud será rechazada.

---

Parámetros de ruta

Parámetro	Tipo	Requerido	Descripción
id	uuid	Sí	ID del carrito que se desea agregar el item. (ver carritos-libre)

Encabezados de la Solicitud

Encabezado	Valor	Descripción
Content-Type	application/json	Indica que los datos se envían en formato JSON.
x-api-key	Bearer <access_token>	Token de autenticación necesario para acceder al recurso.

Cuerpo de la solicitud

Campo	Tipo	Requerido	Tamaño	Descripción
codigo_interno	string	Sí	10	Código interno del producto o servicio. Ver tabla de código interno
descripcion	string	Sí	255	Descripción del producto o servicio.
precio_unitario	objeto	Sí	-	Precio por unidad del producto o servicio.
cantidad	number	Sí	-	Cantidad de unidades del producto o servicio.
unidad_medida_id	uuid	Sí	-	ID de la unidad de medida del producto o servicio. (ver unidades-medidas)
total	number	Sí	-	Total del precio después de calcular el precio unitario con la cantidad.

precio_unitario (objeto)

Campo	Tipo	Requerido	Tamaño	Descripción
0	number	No	-	Precio con exento de IVA
5	number	No	-	Precio con 5% de IVA
10	number	No	-	Precio con 10% de IVA

Ejemplo de respuesta

{
  "success": true,
  "codigo": "201",
  "message": "Recurso creado con éxito.",
  "data": {
    "id": "ejemplo-uuid-item-carrito-libre-123",
    "codigo_interno": "01-ABC1245",
    "descripcion": "DESCRIPCION DE EJEMPLO",
    "cantidad": 2,
    "precio_unitario": 95000,
    "precio_unitario_detalle": {
      "0": 0,
      "5": 0,
      "10": 95000
    },
    "total": 190000,
    "unidad_medida": {
      "id": "5f49c6c1-d622-4f5b-9d8b-2d1636b584ab",
      "codigo_sifen": "77",
      "representacion": "UNI",
      "descripcion": "Unidad"
    },
    "iva": {
      "iva_tipo": 10,
      "monto": 17272.72727273,
      "afectacion": 100
    }
  }
}

Descripción de Campos de Respuesta

Campos principales

Campo	Tipo	Descripción
id	uuid	UUID único del item creado en el carrito.
codigo_interno	string	Código interno del producto o servicio.
descripcion	string	Descripción del producto o servicio.
cantidad	number	Cantidad de unidades del producto o servicio.
precio_unitario	number	Precio por unidad aplicado en la moneda del carrito.
precio_unitario_detalle	object	Precios por tipo de IVA. Claves "0", "5", "10" (porcentaje de IVA).
total	number	Monto total del item (precio_unitario × cantidad).
unidad_medida	object	Objeto con información de la unidad de medida (ver Campos de unidad_medida).
iva	object	Información del cálculo del IVA aplicado (ver Campos de iva).

Campos de unidad_medida (objeto)

Campo	Tipo	Descripción
id	uuid	Identificador único de la unidad de medida.
codigo_sifen	string	Código de la unidad de medida según el catálogo SIFEN.
representacion	string	Representación abreviada de la unidad (ej.: “UNI”, “KG”, “LT”).
descripcion	string	Descripción completa de la unidad de medida.

Campos de iva (objeto)

Campo	Tipo	Descripción
iva_tipo	number	Tipo de IVA aplicado: 0%, 5% o 10%.
monto	number	Monto del IVA calculado en la moneda correspondiente.
afectacion	number	Porcentaje de afectación del IVA sobre el precio total.

Recursos adicionales

Para más información sobre posibles errores de carritos, consulta las siguientes secciones: errores.