Obtener carrito por su ID o CDC

Obtiene información completa de un carrito específico, incluyendo todas las mercaderías, cliente asociado y detalles de la transacción.

---

Entorno

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

Endpoint

GET /carritos/{id}

Ejemplo de solicitud

curl -X GET "https://api.guarani.app/carritos/{id}" \
-H "x-api-key: Bearer <access_token>" \
-H "Accept: application/json" | jq

Nota: Asegúrate de reemplazar {id} con el ID del carrito 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.

Buscar carrito por CDC

curl --location "https://api.guarani.app/carritos/cdc/{cdc}" \
  --header "Content-Type: application/json" \
  --header "x-api-key: Bearer <access_token>"

Reemplazá {cdc} por el Código de Control completo (44 caracteres) y <access_token> por tu token JWT válido.

---

Parámetros de ruta

Parámetro	Tipo	Requerido	Descripción
id	uuid	Sí	Identificador único del carrito a consultar. (ver carritos)

Para la búsqueda por CDC, usá GET /carritos/cdc/{cdc} donde {cdc} es el código de control del documento electrónico.

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": "77c11d48-1fbe-46fb-be80-d6500db28caf",
    "numero_documento": "001-002-0000123",
    "estado_carrito": 6,
    "fecha_emision_documento": "05/11/2025 14:43:30.155141 -03",
    "fecha_finalizado": "2025-05-11T14:43:30.030Z",
    "numero_timbrado": "12345678",
    "cdc": "01801580404001002000012312025110511153707634",
    "moneda": "PYG",
    "cotizacion": 1,
    "total": 30000,
    "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": "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": "355",
          "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
        }
      }
    ]
  }
}

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 generado por el sistema para identificación única.
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, BRL, ARS).
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 generado por el sistema para identificación única.
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).

Recursos adicionales

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