4. Entidad Ventas: Registro y gestión de transacciones

La entidad Ventas en WoowUp permite registrar y gestionar todas las transacciones realizadas por los clientes, vinculando esta información a sus perfiles. Esto es crucial para el análisis del comportamiento de compra y para personalizar campañas de marketing.

4.1 Flujo de envío de ventas

En caso de que el proceso de ventas esté desincronizado con el proceso de clientes, es necesario cumplir nuevamente con la lógica de creación o actualización de un cliente dependiendo de si ya existe en WoowUp. Sigue el siguiente flujo:

Verificar si el cliente existe (GET user exist):
Antes de registrar una venta, es importante verificar si el cliente que realizó la compra ya está registrado en WoowUp. Usa el GET user exist para verificar esto.
Actualizar o crear el cliente según su existencia:
- Si el cliente existe (response: true), actualiza su información si es necesario con el endpoint PUT user.
- Si el cliente no existe (response: false), crea un nuevo cliente con el endpoint POST user.
Registrar la venta (POST purchase):
Una vez actualizado o creado del cliente, procede a registrar la venta en WoowUp. Se debe enviar al menos un identificador del cliente como el document o email del cliente, la lista de productos comprados, y los montos asociados.

4.2 Creación de una venta (POST purchase)

Para crear una venta, asegúrate de enviar la información correcta y completa en la solicitud a WoowUp. El proceso de creación de una venta sigue estos pasos clave, con estos campos incluídos en el cuerpo de la consulta:

Identificador del cliente:
Debes proporcionar uno de los identificadores principales del cliente, como su email, document, telephone, o service_uid, para asociar correctamente la venta con su perfil.
Productos comprados:
La venta debe incluir una lista de productos con sus respectivos sku, product_name, unit_price y quantity.
Montos de la venta:
Debes enviar el monto total de la venta, así como los detalles de cualquier descuento aplicado, impuestos, o cargos adicionales.
Fecha de la venta:
Asegúrate de enviar la fecha y hora exacta de la transacción con el campo createtime, en formato YYYY-MM-DD hh:mm:ss.

Campos de la entidad Ventas

Campo

Tipo

Descripción

Ejemplo

Obligatorio

document	`String`	Documento o cédula del cliente	36872489	Si
email	`String`	Email del cliente	[email protected]	Si
invoice_number	`String`	Número de la Factura (ID)	FAC0230321	Si
createtime	`String`	Fecha y Hora de la Venta	2020-01-23 16:32:05	Si
channel	`Enum`	Canal de venta ["web", "in-store"]	in-store	Si
branch_name	`String`	Código de la tienda donde se realizó la venta. Se debe utilizar el campo 'name' del archivo de Tiendas.	A101	Si
points	`Integer`	Puntos otorgados de la venta	100	No
shipping	`Float`	Costo de Envío	500	No
gross	`Float`	Subtotal (Sin impuestos, sin envíos y sin descuentos)	9000	No
tax	`Float`	Impuestos de la Factura	1400	No
discount	`Float`	Descuento de la factura	2000	No
total	`Float`	Total de la Factura	9400	Si
payment_type	`Enum`	Medio de pago ['credit', 'debit', 'mercadopago', 'todopago', 'cash', 'other']	debit	Si
payment_brand	`String`	Marca de la Tarjeta	Visa	No
payment_bank	`String`	Banco emisor de la tarjeta	Banco Galicia	No
payment_installments	`Integer`	Cantidad de cuotas	6	No
payment_total	`Float`	Total por medio de pago	9400	No
seller_name	`String`	Nombre del Vendedor	Gil Gunderson	No
seller_email	`String`	Email del vendedor	[email protected]	No
seller_external_id	`String`	Id externo del vendedor	10	No
SKU	`String`	Código del producto (productReferenceCode de Vtex)	AB123324	Si
product_name	`String`	Nombre del producto	Celular Moto Z	Si
brand	`String`	Marca del producto	Motorola	No
quantity	`Integer`	Cantidad de unidades	2	Si
unit_price	`Float`	Precio unitario del producto (Sin impuestos y descuentos)	1000	Si
variations	`String`	Características por las que se puede agrupar productos. Por ejemplo: color, talle, temporada (Formato llave valor, separados por pipes "\|")	Color: Blanco \| Talle: XXXL	No

Ejemplo:

curl --request POST \ 
--url https://api.woowup.com/apiv3/purchases \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \ 
--header 'cache-control: no-cache' \
--header 'Authorization: Basic <tu_api_key>' \
--data {
"document": "123456789",
"invoice_number": "FAC-0000856789",
"channel": "in-store",
"purchase_detail": [
    {
      "sku": "2907362",
      "product_name": "Pantalón Negro",
      "quantity": 1,
      "unit_price": 1999.00,
      "variations": [
        {
          "name": "Talla",
          "value": "XS"
        }
      ]
    },
    {
      "sku": "4874645",
      "product_name": "Remera Manga Corta Blanca",
      "quantity": 1,
      "unit_price": 1200.00,
      "variations": [
        {
          "name": "Talla",
          "value": "S"
        }
      ]
    }
  ],
  "prices": {
    "cost": 2043.00,
    "shipping": 120.00,
    "gross": 3199.00,
    "tax": 199.00,
    "discount": 100.00,
    "total": 3219.00
  },
  "payment":{
    "type":"credit",
    "brand":"Visa",
    "bank": "Example Bank",
    "total": 3219.00,
    "installments": 12,
    "card_first_digits": "123456"
  },
  "branch_name": "A101",
  "seller":{
    "name": "Seller Relles",
    "email": "[email protected]",
    "external_id": "0001"
  },
  "createtime": "2024-07-23 14:35:22",
  "approvedtime": "2024-07-23 15:01:48",
  "custom_attributes": { 
    "fecha_max_cambio": "2024-08-23"
  }
}'

Respuesta:

{
    "payload": [],
    "message": "purchase successfully saved",
    "code": "ok",
    "time": "170ms"
}

4.3 Consulta de una venta (GET purchase)

Es posible consultar la información detallada de una venta registrada en WoowUp utilizando el endpoint GET purchase. Este proceso te permite acceder a los datos de una transacción en función de su número de factura (invoice_number), lo que resulta útil para verificar detalles específicos de una compra.

Paso a paso para consultar una venta:

Identificador de la venta:
Para realizar la consulta, es necesario proporcionar como parámetro el identificador único de la venta, que puede ser el invoice_number (número de la factura). Este valor debe estar asociado a una venta previamente registrada.

Solicitud GET:
La solicitud se realiza utilizando el endpoint GET /purchases/?invoice_number={invoice_number}, donde se sustituye {invoice_number} por el número de la factura de la venta que deseas consultar.

Ejemplo:

curl --request GET \ 
--url https://api.woowup.com/v3/purchases/?invoice_number=FAC-0000856789 \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \ 
--header 'Authorization: Basic <tu_api_key>'

Respuesta:
Si la venta existe, recibirás una respuesta en formato JSON que contiene todos los detalles de la transacción, incluyendo el cliente asociado, productos comprados, totales, y métodos de pago.

Ejemplo de respuesta:

{
    "payload": [
        {
            "service_uid": "123456789",
            "document": "123456789",
            "email": "[email protected]",
            "telephone": "11223344",
            "invoice_number": "FAC-0000856789",
            "channel": "in-store",
            "purchase_detail": {
                "items": [
                    {
                        "product_id": "2907362",
                        "product_name": "pantalón negro",
                        "quantity": 1,
                        "price": 1999,
                        "manufacturer_warranty_date": null,
                        "extension_warranty_date": null,
                        "custom_attributes": []
                    },
                    {
                        "product_id": "4874645",
                        "product_name": "remera manga corta blanca",
                        "quantity": 1,
                        "price": 1200,
                        "manufacturer_warranty_date": null,
                        "extension_warranty_date": null,
                        "custom_attributes": []
                    }
                ]
            },
            "prices": {
                "total": 3219,
                "gross": 3199,
                "discount": 100,
                "shipping": 120,
                "tax": 199,
                "cost": 2043
            },
            "points": 0,
            "downloadtime": "2024-07-23 14:35:22",
            "createtime": "2024-07-23 14:35:22",
            "metadata": null,
            "custom_attributes": {
                "fecha_max_cambio": "2024-08-23 00:00:00"
            },
            "cancel_transaction_id": null,
            "branch": {
                "id": 94848,
                "name": "A101"
            },
            "payment": {
                "type": "credit",
                "brand": "Visa",
                "name": "Example Bank"
            },
            "purchase_operator": {
                "name": "Seller Relles",
                "email": "[email protected]"
            },
            "pickup_store": null,
            "promotions": null
        }
    ],
    "message": "ok",
    "code": "ok",
    "time": "40ms"
}

4.4 Actualización de las ventas (PUT purchase)

La actualización de una venta en WoowUp se realiza utilizando el mismo proceso que la creación de una venta (POST), pero cambiando el método a PUT. Esto te permite modificar la información de una venta previamente registrada, como los productos comprados, montos, o datos del cliente.

4.5 Eliminación de una venta (DELETE purchase)

Si necesitas eliminar una venta registrada en WoowUp, puedes utilizar el método DELETE. Esto permite remover completamente la información de una transacción, lo cual puede ser necesario en caso de errores o registros duplicados.

Debes identificar la venta mediante el número de factura (invoice_number) en el body.

Ejemplo:

curl -X DELETE \
--url https://api.woowup.com/apiv3/purchases \
--header 'Accept: application/json' \
--header 'Authorization: Basic XXXXXXXXXXXXXXXXXXXX' \
--header 'Content-Type: application/json' \
--data '{
    "invoice_number": "FAC-0000856789"
}'

Respuesta:

{
    "payload": [],
    "message": "ok",
    "code": "ok",
    "time": "98ms"
}

4.3 Atributos extendidos en las ventas

Al igual que con los clientes, es posible enviar atributos personalizados en las ventas para agregar información adicional sobre la transacción. Estos atributos pueden utilizarse para análisis avanzados y segmentación.

Ejemplo con atributos personalizados:

 "custom_attributes": { 
    "fecha_max_cambio": "2024-08-23",
    "cupon_descuento": "15OFF",
    "pago_con_ahora12": "Si"
  }