Finalizar carrito libre

Completa la compra del carrito libre. Permite configurar el método de pago (contado o crédito) y finalizar la transacción.

Entorno

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

Endpoint

POST /carritos/libre/finalizar/{id}

Ejemplo de solicitud

Condición de venta Contado

curl -X POST "https://api.guarani.app/carritos/libre/finalizar/{id}" \
  -H "Content-Type: application/json" \
  -H "x-api-key: Bearer <access_token>" \
  -d '{
    "condicion_venta": 1,
    "total": 100000,
    "venta_contado": {
      "monto": 100000
    },
    "observacion": "Pago en efectivo"
  }' | jq

Condición de venta Crédito

curl -X POST "https://api.guarani.app/carritos/libre/finalizar/{id}" \
  -H "Content-Type: application/json" \
  -H "x-api-key: Bearer <access_token>" \
  -d '{
    "condicion_venta": 2,
    "total": 200000,
    "venta_credito": {
      "entrega_inicial": 50000,
      "plazo": 180
    },
    "observacion": "Financiado en 6 meses"
  }' | jq

Nota: Asegúrate de reemplazar {id} con el ID del carrito que deseas finalizar 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 carrito libre que deseas finalizar. (ver carritos-libre)

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

condicion_venta Contado

Campo	Tipo	Requerido	Tamaño	Descripción
condicion_venta	number	Sí	1	Condición de venta. (1: Contado, 2: Crédito)
total	number	Sí	-	Total del carrito.
venta_contado	object	Sí	-	Objeto con los datos de la venta en contado.
observacion	string	No	-	Observación de la venta (opcional).

venta_contado

Campo	Tipo	Requerido	Tamaño	Descripción
monto	number	Sí	-	Monto de la venta en contado.

condicion_venta Crédito

Campo	Tipo	Requerido	Tamaño	Descripción
condicion_venta	number	Sí	1	Condición de venta. (1: Contado, 2: Crédito)
total	number	Sí	-	Total del carrito.
venta_credito	object	Sí	-	Objeto con los datos de la venta en crédito.
observacion	string	No	-	Observación de la venta (opcional).

venta_credito

Campo	Tipo	Requerido	Tamaño	Descripción
entrega_inicial	number	Sí	-	Monto de la entrega inicial.
plazo	number	Sí	-	Plazo de la venta crédito en días.

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": 1,
      "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-ABC1247",
        "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
        }
      }
    ]
  }
}

Descripción de campos de respuesta

Campos principales de la respuesta

Campo	Tipo	Descripción
id	uuid	Identificador único del carrito finalizado.
total	number	Monto total del carrito.
moneda	string	Código de moneda ISO 4217.
cotizacion	number	Cotización de la moneda respecto a Guaraníes.
numero_documento	string	Número del documento electrónico generado. Es null hasta que se genere el documento.
estado_carrito	number	Estado del carrito. (ver tablas-referencias)
fecha_finalizado	string	Fecha y hora en que se finalizó el carrito.
cdc	string	Código de Control (CDC) del documento electrónico. Es null hasta que se genere el documento.
fecha_emision	string	Fecha y hora de emisión del documento. Es null hasta que se genere el documento.
cliente	object	Objeto con los datos completos del cliente.
items	array	Array con los items del carrito.

Campos del objeto cliente

Campo	Tipo	Descripción
id	uuid	Identificador único del cliente.
tipo_persona	number	Tipo de persona. (ver tablas-referencias)
tipo_documento	number	Tipo de documento. (ver tablas-referencias)
documento	string	Número de documento del cliente.
nombre	string	Nombre completo del cliente.
nombre_fantasia	string	Nombre de fantasía del cliente.
nacionalidad	string	Código de nacionalidad (ej: “PRY”).
fecha_nacimiento	string	Fecha de nacimiento del cliente (formato DD/MM/YYYY).
whatsapp	string	Número de WhatsApp del cliente.
email	string	Correo electrónico del cliente.
numero_casa	string	Número de casa del cliente.
direccion	string	Dirección del cliente.
barrio	string	Barrio del cliente.
ciudad	object	Objeto con información de la ciudad, distrito y departamento.

Campos del objeto ciudad

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

Campos del objeto distrito

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

Campos del objeto departamento

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

Campos de items

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	Total del item (precio_unitario * cantidad).
iva	object	Objeto con información del IVA.

Campos del objeto unidad_medida

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 corta de la unidad (ej: “UNI”).
descripcion	string	Descripción de la unidad de medida.

Campos del objeto iva

Campo	Tipo	Descripción
iva_tipo	number	Tipo de IVA aplicado. 10 = 10%, 5 = 5%, 0 = Exento.
monto	number	Monto del IVA calculado.
afectacion	number	Porcentaje de afectación del IVA.

Recursos adicionales

Para más información sobre posibles errores de carritos, consulta las siguientes secciones: errores.