Editar item de un carrito

Actualiza la información de una mercadería o servicio específico dentro de un carrito existente. Útil para actualizar cantidades, precios o cambiar mercaderías en el carrito de compras.

Entorno

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

Endpoint

PUT /carritos/items/{id}

Ejemplo de solicitud

  # USD
curl -X PUT "https://api.guarani.app/carritos/items/{id}" \
  -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 PUT "https://api.guarani.app/carritos/items/{id}" \
  -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: Reemplaza {id} por el ID del ítem y <access_token> con un token JWT válido proporcionado por el equipo Guarani.
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 ítem dentro del carrito que se desea editar. (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.

Descripción de Campos

Campo	Tipo	Requerido	Tamaño	Descripción
mercaderia_id	uuid	No	36	ID de la mercadería, si el ítem corresponde a una mercaderia, no envia este campo si es servicio. (ver mercaderias)
servicio_id	uuid	No	36	ID del servicio, si el ítem corresponde a un servicio, no envia este campo si es mercaderia. (ver servicios)
precio_unitario	object	No	-	Objeto con los precios unitarios por tipo de IVA (0, 5, 10). Si se envía una mercadería es opcional cuando ya existe en el carrito; para servicios debe incluir al menos un valor.
precio_unitario_original	number	Sí	-	Precio original de la mercaderia o servicio.
cantidad	number	Sí	-	Cantidad de unidades de la mercaderia o servicio.
total	number	Sí	-	Total final del ítem después del descuento.

precio_unitario (objeto)

Campo	Tipo	Requerido	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": "200",
  "message": "Recurso actualizado con éxito.",
  "data": {
    "id": "90dc3f8e-965e-40d6-8f6e-a7cda122959f",
    "mercaderia": {
      "id": "ejemplo-uuid-mercaderia-123",
      "codigo_original": "PROD002",
      "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. (ver carritos)
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 y cómo manejarlos, consulta errores.