Obtener una lista de los carritos libres

Lista todos los carritos libres de compras registrados en el sistema. Incluye información del cliente, estado del carrito y totales calculados.

---

Entorno

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

Endpoint

GET /carritos/libre

Ejemplo de solicitud

curl -X GET "https://api.guarani.app/carritos/libre?page=1&limit=100" \
-H "x-api-key: Bearer <access_token>" \
-H "Accept: application/json" | jq

Nota: Asegúrate de reemplazar <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.

---

Encabezados de la solicitud

Encabezado	Valor	Descripción
x-api-key	Bearer <access_token>	Token de autenticación necesario para acceder al recurso.
Accept	application/json	Indica que la respuesta debe devolverse en formato JSON.

Ejemplo de respuesta

{
  "success": true,
  "codigo": "200",
  "message": "Operación realizada correctamente.",
  "data": [
    {
      "id": "ejemplo-uuid-carrito-libre-123",
      "total": 95000,
      "moneda": "PYG",
      "cotizacion": 1,
      "numero_documento": null,
      "estado_carrito": 2,
      "fecha_finalizado": "18/02/2026 13:28:08.298492 -03",
      "cdc": null,
      "fecha_emision": null,
      "cliente": {
        "id": "ejemplo-uuid-cliente-123",
        "tipo_persona": 1,
        "tipo_documento": 0,
        "documento": "1234567",
        "nombre": "NOMBRE DE EJEMPLO",
        "nombre_fantasia": "NOMBRE DE EJEMPLO",
        "nacionalidad": "PRY",
        "fecha_nacimiento": "09/05/1989",
        "whatsapp": "+595981234567",
        "email": "[email protected]",
        "direccion": "DIRECCION DE EJEMPLO",
        "numero_casa": "0",
        "barrio": "BARRIO DE EJEMPLO",
        "ciudad": {
          "id": "67ef2e9f-0fa7-43e7-ad5e-87a694e56341",
          "nombre": "SANTA RITA",
          "codigo_sifen": "3556",
          "distrito": {
            "id": "78d49201-91f9-4e6c-aadb-4927f56767c0",
            "nombre": "SANTA RITA",
            "codigo_sifen": "209",
            "departamento": {
              "id": "750d3163-6a53-45df-b349-e8139d1ff3a9",
              "nombre": "ALTO PARANA",
              "codigo_sifen": "11"
            }
          }
        }
      },
      "items": [
        {
          "id": "ejemplo-uuid-item-carrito-libre-123",
          "codigo_interno": "01-ABC1234",
          "descripcion": "DESCRIPCION DE EJEMPLO",
          "cantidad": 1,
          "unidad_medida": {
            "id": "5f49c6c1-d622-4f5b-9d8b-2d1636b584ab",
            "codigo_sifen": "77",
            "representacion": "UNI",
            "descripcion": "Unidad"
          },
          "precio_unitario": 95000,
          "precio_unitario_detalle": {
            "0": 0,
            "5": 0,
            "10": 95000
          },
          "total": 95000,
          "iva": {
            "iva_tipo": 10,
            "monto": 8636.36363636,
            "afectacion": 100
          }
        }
      ]
    }
  ],
  "pagination": {
    "total_registros": 1,
    "pagina": 1,
    "total_paginas": 1
  }
}

Descripción de campos de respuesta

Campos principales

Campo	Tipo	Descripción
id	uuid	Identificador único del carrito.
total	number	Monto total del carrito en la moneda especificada.
moneda	string	Código de moneda en formato ISO 4217 (ej: PYG, USD).
cotizacion	number	Cotización de la moneda respecto a Guaraníes.
numero_documento	string	Número del documento. Es null hasta que se emita la factura.
estado_carrito	number	Estado del carrito. (ver tablas-referencias)
fecha_finalizado	string	Fecha en que se finalizó el carrito. Es null mientras esté activo.
cdc	string	Código de Control (CDC). Es null hasta que se genere el documento.
fecha_emision	string	Fecha de emisión del documento. Es null hasta que se genere.
cliente	object	Información completa del cliente asociado al carrito.
items	array	Lista de ítems del carrito con sus detalles.

Campos del Cliente

Campo	Tipo	Descripción
id	uuid	Identificador único del cliente.
tipo_persona	number	Tipo de persona. 1 = Persona Física, 2 = Persona Jurídica.
tipo_documento	number	Tipo de documento de identidad. 1 = Cédula, 2 = Pasaporte, 3 = RUC, etc.
documento	string	Número del documento de identidad del cliente.
nombre	string	Nombre completo del cliente (razón social para personas jurídicas).
nombre_fantasia	string	Nombre comercial o fantasía del cliente.
nacionalidad	string	Código de nacionalidad en formato ISO 3166-1 alpha-3 (ej: PRY, ARG, BRA).
fecha_nacimiento	string	Fecha de nacimiento del cliente en formato DD/MM/YYYY.
whatsapp	string	Número de WhatsApp del cliente en formato internacional.
email	string	Dirección de correo electrónico del cliente.
numero_casa	string	Número de casa o edificio de la dirección del cliente.
direccion	string	Dirección completa del cliente.
barrio	string	Nombre del barrio donde reside el cliente.
ciudad	object	Objeto con información de la ciudad del cliente.

Campos de Ciudad

Campo	Tipo	Descripción
id	uuid	Identificador único de la ciudad.
codigo_sifen	string	Código de la ciudad según el catálogo SIFEN.
nombre	string	Nombre de la ciudad.
distrito	object	Objeto con información del distrito al que pertenece la ciudad.

Campos de Distrito

Campo	Tipo	Descripción
id	uuid	Identificador único del distrito.
nombre	string	Nombre del distrito.
codigo_sifen	string	Código del distrito según el catálogo SIFEN.
departamento	object	Objeto con información del departamento al que pertenece el distrito.

Campos de Departamento

Campo	Tipo	Descripción
id	uuid	Identificador único del departamento.
nombre	string	Nombre del departamento.
codigo_sifen	string	Código del departamento según el catálogo SIFEN.

Campos de cada ítem

Campo	Tipo	Descripción
id	uuid	Identificador único del item.
codigo_interno	string	Código interno del item.
descripcion	string	Descripción del item.
cantidad	number	Cantidad de unidades.
unidad_medida	object	Unidad de medida del item.
precio_unitario	number	Precio unitario del item.
precio_unitario_detalle	object	Precios discriminados por tipo de IVA (0, 5, 10).
total	number	Monto total del item (precio_unitario × cantidad).
iva	object	Información del IVA aplicado al item.

Estructura del objeto unidad_medida (ítem)

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

Estructura del objeto iva (ítem)

Campo	Tipo	Descripción
iva_tipo	number	Tipo de IVA aplicado (0: exento, 5: 5%, 10: 10%).
monto	number	Monto de IVA calculado para el item.
afectacion	number	Porcentaje de afectación del IVA sobre el precio total.

Campos de Paginación

Campo	Tipo	Descripción
total_registros	number	Cantidad total de carritos encontrados en la base de datos.
pagina	number	Número de la página actual.
total_paginas	number	Cantidad total de páginas disponibles según el límite solicitado.

Recursos adicionales

Para más información sobre posibles errores y cómo manejarlos, consulta errores.