Buscar carritos

Busca carritos en el sistema usando criterios de búsqueda. Permite encontrar carritos por cliente, moneda u otros datos específicos.

---

Entorno

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

Endpoint

GET /carritos/search?q={query}&page=1&limit=100

Ejemplo de solicitud

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

Nota: Asegúrate de reemplazar {query} por el parametro a buscar 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 consulta

Parámetro	Tipo	Requerido	Descripción
query	string	Sí	Parámetro de busqueda
page	integer	No	Número de página. Por defecto: 1.
limit	integer	No	Resultados por página. Por defecto: 100

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-123",
      "numero_documento": "001-002-0000123",
      "estado_carrito": 5,
      "fecha_emision_documento": "11/11/2025 08:04:53.436606 -03",
      "fecha_finalizado": "2025-11-11T08:04:43.537Z",
      "numero_timbrado": "12345678",
      "cdc": "01801580404001002000012312025110511153707634",
      "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": "",
        "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 (UUID).
numero_documento	string	Número del documento asociado al carrito.
estado_carrito	number	Estado 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 que se finalizó el carrito.
numero_timbrado	string	Número de timbrado de la SET asociado a la factura.
cdc	string	Código de Control (CDC) generado por SIFEN.
moneda	string	Código de moneda ISO 4217.
cotizacion	number	Cotización de la moneda respecto a Guaraníes.
total	number	Monto total del carrito.
cliente	object	Datos del cliente asociado al carrito.
items	array	Lista de items (mercaderías o servicios) incluidos en el carrito.

Estructura del objeto cliente

Campo	Tipo	Descripción
id	uuid	Identificador único del cliente (UUID).
tipo_persona	number	Tipo de persona (1: física, 2: jurídica).
tipo_documento	number	Tipo de documento del cliente (1: CI, 2: RUC, 3: pasaporte, etc).
documento	string	Número de documento del cliente.
nombre	string	Nombre completo del cliente.
nombre_fantasia	string	Nombre de fantasía o comercial del cliente.
nacionalidad	string	Código de nacionalidad (ISO 3166-1 alpha-3).
fecha_nacimiento	string	Fecha de nacimiento del cliente en formato DD/MM/YYYY.
whatsapp	string	Número de WhatsApp con código de país.
email	string	Correo electrónico del cliente.
numero_casa	string	Número de casa o domicilio.
direccion	string	Dirección completa del cliente.
barrio	string	Barrio donde reside el cliente.
ciudad	object	Objeto con datos de la ciudad del cliente.

Estructura del objeto ciudad

Campo	Tipo	Descripción
id	uuid	Identificador único de la ciudad (UUID).
codigo_sifen	string	Código de la ciudad según SIFEN.
nombre	string	Nombre de la ciudad.
distrito	object	Objeto con datos del distrito.

Estructura del objeto distrito

Campo	Tipo	Descripción
id	uuid	Identificador único del distrito (UUID).
nombre	string	Nombre del distrito.
codigo_sifen	string	Código del distrito según SIFEN.
departamento	object	Objeto con datos del departamento.

Estructura del objeto departamento

Campo	Tipo	Descripción
id	uuid	Identificador único del departamento (UUID).
nombre	string	Nombre del departamento.
codigo_sifen	string	Código del departamento según SIFEN.

Estructura del objeto item

Campo	Tipo	Descripción
id	uuid	Identificador único del item (UUID).
mercaderia	object	Datos de la mercadería (null si es un servicio).
servicio	object	Datos del servicio (null si es una mercadería).
precio_unitario	number	Precio unitario actual del item.
precio_unitario_original	number	Precio unitario original sin descuentos aplicados.
total	number	Monto total del item (precio_unitario × cantidad).
cantidad	number	Cantidad de unidades del item.
iva	object	Información del IVA aplicado al item.

Estructura del objeto mercadería

Campo	Tipo	Descripción
id	uuid	Identificador único de la mercadería (UUID).
codigo_original	string	Código original del producto.
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 del producto.
descripcion	string	Descripción breve 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 (null si no tiene).
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.

Estructura del objeto 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).

Estructura del objeto unidad de medida

Campo	Tipo	Descripción
id	uuid	Identificador único de la unidad de medida (UUID).
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.

Estructura del objeto 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	string	ID del establecimiento al que pertenece este precio.

Estructura del objeto servicio

Campo	Tipo	Descripción
id	uuid	Identificador único del servicio (UUID).
descripcion	string	Descripción breve 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 (null si no tiene).
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	string	ID del establecimiento al que pertenece este precio.

Estructura del objeto IVA

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

Estructura del objeto pagination

Campo	Tipo	Descripción
total_registros	number	Cantidad total de registros encontrados.
pagina	number	Número de página actual.
total_paginas	number	Cantidad total de páginas disponibles.

Recursos adicionales

Para más información sobre posibles errores relacionados, consulta la sección errores.