Agregar un item al carrito

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

---

Entorno

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

Endpoint

POST /carritos/{id}/items

Ejemplo de solicitud HTTP (cURL)

# USD
curl -X POST "https://api.guarani.app/carritos/{id}/items" \
  -H "Content-Type: application/json" \
  -H "x-api-key: Bearer <access_token>" \
  -d '{
    "mercaderia_id": "ejemplo-uuid-mercaderia-123",
    "precio_unitario": {
      "0": 9.59,
      "5": 0,
      "10": 4.10
    },
    "precio_unitario_original": 13.69,
    "cantidad": 1,
    "total": 13.69
  }' | jq

# PYG
curl -X POST "https://api.guarani.app/carritos/{id}/items" \
  -H "Content-Type: application/json" \
  -H "x-api-key: Bearer <access_token>" \
  -d '{
    "mercaderia_id": "ejemplo-uuid-mercaderia-123",
    "precio_unitario": {
      "0": 70000,
      "5": 0,
      "10": 30000
    },
    "precio_unitario_original": 100000,
    "cantidad": 1,
    "total": 100000
  }' | jq

Nota: Se envía mercaderia_id o servicio_id, pero no ambos. 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)

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
mercaderia_id	uuid	No	36	ID de la mercadería, si el ítem corresponde a un producto. (ver mercaderias)
servicio_id	uuid	No	36	ID del servicio, si el ítem corresponde a un servicio. (ver servicios)
precio_unitario	objeto	Sí	-	Precio por unidad del producto o servicio.
precio_unitario_original	number	Sí	-	Precio original del producto o servicio.
cantidad	number	Sí	-	Cantidad de unidades del producto o servicio.
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 IVA 0%
5	number	No	-	Precio con IVA 5%
10	number	No	-	Precio con IVA 10%

Ejemplo de respuesta

{
  "success": true,
  "codigo": "201",
  "message": "Recurso creado con éxito.",
  "data": {
    "id": "90dc3f8e-965e-40d6-8f6e-a7cda122959f",
    "mercaderia": {
      "id": "ejemplo-uuid-mercaderia-123",
      "codigo_original": "CODIGO ORIGINAL DE EJEMPLO",
      "codigo_fabricante": "CODIGO FABRICANTE DE EJEMPLO",
      "codigo_interno": "01-1234567",
      "codigo_barra": "CODIGO DE BARRAS DE EJEMPLO",
      "descripcion": "DESCRIPCION DE EJEMPLO",
      "descripcion_larga": "DESCRIPCION LARGA DE EJEMPLO",
      "observacion": "OBSERVACION DE EJEMPLO",
      "mercaderia_clasificacion_id": "ejemplo-uuid-clasificacion-mercaderia-123",
      "mercaderia_marca_id": "ejemplo-uuid-marca-123",
      "imagen_url": null,
      "unidades": {
        "unidad_medida_compra": {
          "id": "5f49c6c1-d622-4f5b-9d8b-2d1636b584ab",
          "codigo_sifen": "77",
          "representacion": "UNI",
          "descripcion": "Unidad"
        },
        "factor_conversion": 1,
        "unidad_medida_venta": {
          "id": "5f49c6c1-d622-4f5b-9d8b-2d1636b584ab",
          "codigo_sifen": "77",
          "representacion": "UNI",
          "descripcion": "Unidad"
        }
      },
      "precios": [
        {
          "precio_unitario": {
            "0": 0,
            "5": 0,
            "10": 100000
          },
          "moneda": "PYG",
          "establecimiento_id": "ejemplo-uuid-establecimiento-123"
        }
      ]
    },
    "servicio": null,
    "precio_unitario": 100000,
    "precio_unitario_original": 100000,
    "total": 100000,
    "cantidad": 1,
    "iva": {
      "iva_tipo": 10,
      "monto": 2727.2727275,
      "afectacion": 28.03738318
    }
  }
}

Descripción de Campos de Respuesta

Campos principales

Campo	Tipo	Descripción
id	uuid	UUID único del item creado en el carrito.
mercaderia	objeto	Información completa de la mercadería (null si es servicio).
servicio	objeto	Información completa del servicio (null si es mercadería).
precio_unitario	number	Precio final por unidad aplicado.
precio_unitario_original	number	Precio original por unidad antes de descuentos o ajustes.
total	number	Monto total del item (precio_unitario × cantidad).
cantidad	number	Cantidad de unidades del producto o servicio.
iva	objeto	Información del cálculo del IVA aplicado.

Campos de mercaderia (objeto)

Campo	Tipo	Descripción
id	uuid	UUID de la mercadería.
codigo_interno	string	Código interno de la mercadería. Ver tabla de código interno
codigo_original	string	Código original del fabricante o proveedor.
codigo_fabricante	string	Código asignado por el fabricante.
codigo_barra	string	Código de barras del producto.
descripcion	string	Nombre o descripción corta de la mercadería.
descripcion_larga	string	Descripción extendida de la mercadería.
observacion	string	Observaciones o notas adicionales.
mercaderia_clasificacion_id	uuid	UUID de la clasificación o categoría de la mercadería.
mercaderia_marca_id	uuid	UUID de la marca de la mercadería.
imagen_url	string	URL de la imagen del producto (puede ser null si no dispone).
unidades	object	Objeto con información de unidades de compra/venta y factor de conversión.
precios	array	Lista de precios por establecimiento, incluye valores por tipo de IVA y moneda correspondiente

Campos de unidades (mercadería)

Campo	Tipo	Descripción
unidad_medida_compra	object	Datos de la unidad de medida utilizada para comprar la mercadería. (ver unidades-medidas)
factor_conversion	number	Factor de conversión entre la unidad de compra y la de venta (ej.: 1 caja = 12 unidades).
unidad_medida_venta	object	Datos de la unidad de medida utilizada para vender la mercadería. (ver unidades-medidas)

Campos de precios (mercadería)

Cada elemento del arreglo precios posee la siguiente estructura:

Campo	Tipo	Descripción
precio_unitario	object	Objeto con precios por tipo de IVA. Las claves son "0", "5" y "10" representando el porcentaje.
moneda	string	Código de moneda en formato ISO 4217 (ej.: PYG, USD).
establecimiento_id	uuid	UUID del establecimiento al que pertenece este precio.

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.