Obtener una lista de los carritos

Lista todos los carritos 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

Ejemplo de solicitud

curl -X GET "https://api.guarani.app/carritos?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": "35b5143e-5414-4ab8-8570-144ebfcb6a56",
      "numero_documento": null,
      "estado_carrito": 1,
      "fecha_emision_documento": null,
      "fecha_finalizado": null,
      "numero_timbrado": null,
      "cdc": null,
      "moneda": "PYG",
      "cotizacion": 1,
      "total": 30000,
      "cliente": {
        "id": "ejemplo-uuid-cliente-123",
        "tipo_persona": 1,
        "tipo_documento": 1,
        "documento": "1234567",
        "nombre": "NOMBRE DE EJEMPLO",
        "nombre_fantasia": "NOMBRE DE EJEMPLO",
        "nacionalidad": "PRY",
        "fecha_nacimiento": "22/03/2007",
        "whatsapp": "+595981234567",
        "email": "[email protected]",
        "numero_casa": "0",
        "direccion": "DIRECCION DE EJEMPLO",
        "barrio": "BARRIO DE EJEMPLO",
        "ciudad": {
          "id": "67ef2e9f-0fa7-43e7-ad5e-87a694e56341",
          "codigo_sifen": "3556",
          "nombre": "SANTA RITA",
          "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-123",
          "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": 30000
                },
                "moneda": "PYG",
                "establecimiento_id": "ejemplo-uuid-establecimiento-123"
              }
            ]
          },
          "servicio": null,
          "precio_unitario": 30000,
          "precio_unitario_original": 30000,
          "total": 30000,
          "cantidad": 1,
          "iva": {
            "iva_tipo": 10,
            "monto": 2727.27272727,
            "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.
numero_documento	string	Número del documento asociado. Es null hasta que el carrito se finalice y se emita la factura.
estado_carrito	number	Estado actual del carrito. (ver tablas-referencias)
fecha_emision_documento	string	Fecha y hora de emisión del documento. Es null hasta que se finalice el carrito.
fecha_finalizado	string	Fecha y hora en formato ISO 8601 en que se finalizó el carrito. Es null mientras el carrito esté activo.
numero_timbrado	string	Número de timbrado utilizado para la facturación. Solo presente cuando el carrito está finalizado.
cdc	string	Código de Control (CDC) generado por SIFEN para la factura electrónica. Solo presente al finalizar el carrito.
moneda	string	Código de moneda en formato ISO 4217 (ej: PYG, USD, BRL, ARS).
cotizacion	number	Cotización de la moneda respecto a Guaraníes.
total	number	Monto total del carrito en la moneda especificada, incluyendo todos los items e impuestos.
cliente	object	Objeto con la información completa del cliente asociado al carrito.
items	array	Lista de productos/servicios agregados al carrito con todos 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.
departamento	object	Objeto con información del departamento 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.

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 Items

Campo	Tipo	Descripción
id	uuid	Identificador único del item en el carrito.
mercaderia	object	Objeto con información de la mercadería. Es null si el item es un servicio.
servicio	object	Objeto con información del servicio. Es null si el item es una mercadería.
precio_unitario	number	Precio unitario final del item en la moneda del carrito (puede incluir ajustes o descuentos).
precio_unitario_original	number	Precio unitario original del item sin ajustes.
total	number	Monto total de la línea (precio unitario × cantidad) en la moneda del carrito.
cantidad	number	Cantidad de unidades del producto o servicio.
iva	object	Objeto con información del IVA aplicado al item.

Campos de Mercadería

Campo	Tipo	Descripción
id	uuid	Identificador único de la mercadería.
codigo_original	string	Código original del proveedor o fabricante.
codigo_fabricante	string	Código asignado por el fabricante.
codigo_interno	string	Código interno de la mercadería. Ver tabla de código interno
codigo_barra	string	Código de barras (EAN/UPC) del producto.
descripcion	string	Descripción corta de la mercadería.
descripcion_larga	string	Descripción detallada de la mercadería.
observacion	string	Observaciones adicionales sobre la mercadería.
mercaderia_clasificacion_id	uuid	ID de la clasificación de la mercadería.
mercaderia_marca_id	uuid	ID de la marca de la mercadería.
imagen_url	string	URL de la imagen del producto. Es null si no tiene imagen.
unidades	object	Objeto con información de las unidades de medida de compra y venta.
precios	array	Array de objetos con información de precios por establecimiento.

Campos de Unidades (Mercadería)

Campo	Tipo	Descripción
unidad_medida_compra	object	Objeto con información de la unidad de medida para compras (ver unidades-medidas).
factor_conversion	number	Factor de conversión entre unidad de compra y venta.
unidad_medida_venta	object	Objeto con información de la unidad de medida para ventas (ver unidades-medidas).

Campos de Unidad de Medida

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 Precios (Mercadería)

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

Campos de Servicio

Campo	Tipo	Descripción
id	uuid	Identificador único del servicio.
descripcion	string	Descripción corta del servicio.
descripcion_larga	string	Descripción detallada del servicio.
observacion	string	Observaciones adicionales sobre el servicio.
codigo_interno	string	Código interno del servicio. Ver tabla de código interno
servicio_clasificacion_id	uuid	ID de la clasificación del servicio.
imagen_url	string	URL de la imagen del servicio. Es null si no tiene imagen.
unidad_medida	object	Objeto con información de la unidad de medida del servicio (ver unidades-medidas).
precio_unitario	object	Objeto con precios por tipo de IVA. Las claves son “0”, “5”, “10” representando el porcentaje de IVA.
moneda	string	Código de moneda en formato ISO 4217 (ej: PYG, USD).
establecimiento_id	uuid	ID del establecimiento al que pertenece este precio.

Campos de IVA

Campo	Tipo	Descripción
iva_tipo	number	Tipo de IVA aplicado. 5 = 5%, 10 = 10%, 0 = Exento.
monto	number	Monto del IVA en la moneda del carrito.
afectacion	number	Porcentaje de afectación del IVA sobre el precio base (usado para cálculos de facturación).

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.