Finalizar carrito

Completa la compra del carrito. 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/finalizar/{id}

Ejemplo de solicitud

Condición de venta Contado

curl -X POST "https://api.guarani.app/carritos/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/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 que deseas finalizar. (ver carritos)

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": "VRL0912011",
  "message": "Venta registrada correctamente.",
  "data": {
    "id": "af997616-5db9-4cbf-a740-ddafe00f620f",
    "numero_documento": null,
    "estado_carrito": 2,
    "fecha_emision_documento": null,
    "fecha_finalizado": "11/11/2025 08:04:53.436606 -03",
    "numero_timbrado": null,
    "cdc": null,
    "moneda": "PYG",
    "cotizacion": 1,
    "total": 300000,
    "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": "01/01/1990",
      "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": 7000,
                "5": 0,
                "10": 3300
              },
              "moneda": "PYG",
              "establecimiento_id": "ejemplo-uuid-establecimiento-123"
            }
          ]
        },
        "servicio": null,
        "precio_unitario": 10300,
        "precio_unitario_original": 10300,
        "total": 10300,
        "cantidad": 1,
        "iva": {
          "iva_tipo": 10,
          "monto": 309,
          "afectacion": 30
        }
      }
    ]
  }
}

Descripción de campos de respuesta

Campos principales de la respuesta

Campo	Tipo	Descripción
id	uuid	Identificador único del carrito finalizado.
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_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 del documento. Es null hasta que se genere el documento.
cdc	string	Código de Control (CDC) del documento electrónico. Es null hasta que se genere el documento.
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	Objeto con los datos completos del cliente.
items	array	Array con los items del carrito con información completa de mercaderías/servicios.

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.
mercaderia	object	Objeto con datos completos de la mercadería (null si es servicio).
servicio	object	Objeto con datos del servicio (null si es mercadería).
precio_unitario	number	Precio unitario del item.
precio_unitario_original	number	Precio unitario original del item.
total	number	Total del item (precio_unitario * cantidad).
cantidad	number	Cantidad de unidades.
iva	object	Objeto con información del IVA.

Campos del objeto mercaderia

Campo	Tipo	Descripción
id	uuid	Identificador único de la mercadería.
codigo_original	string	Código original de la mercadería.
codigo_fabricante	string	Código del fabricante.
codigo_interno	string	Código interno de la mercadería.
codigo_barra	string	Código de barras de la mercadería.
descripcion	string	Descripción de la mercadería.
descripcion_larga	string	Descripción extendida de la mercadería.
observacion	string	Observaciones de la mercadería.
mercaderia_clasificacion_id	uuid	Identificador de la clasificación de la mercadería.
mercaderia_marca_id	uuid	Identificador de la marca de la mercadería.
imagen_url	string	URL de la imagen de la mercadería.
unidades	object	Objeto con información de unidades de medida (compra y venta).
precios	array	Array con información de precios por establecimiento.

Campos del objeto unidades

Campo	Tipo	Descripción
unidad_medida_compra	object	Objeto con información de la unidad de medida de compra.
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 de venta.

Campos del objeto precios (array)

Campo	Tipo	Descripción
precio_unitario	object	Objeto con precios discriminados por tipo de IVA (0, 5, 10).
moneda	string	Código de moneda ISO 4217.
establecimiento_id	uuid	Identificador del establecimiento al que pertenece el precio.

Campos del objeto unidad_medida_compra y unidad_medida_venta

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.