Gestión de Ventas

La API de E3 Stores permite consultar, actualizar y gestionar ventas del sistema de eCommerce. Incluye funcionalidades para consultar ventas por múltiples filtros, ID específico o referencia externa.

Características principales

Consulta por múltiples filtros: Estado, rango de fechas, métodos de pago, sitios, usuarios
Búsqueda avanzada: Por email, teléfono, código postal, nombre completo
Búsqueda por referencia externa: Integración con sistemas ERP
Información completa: Datos del cliente, productos, pagos, envíos
Estados personalizables: Sistema flexible de estados de venta
Paginación: Control de límites y offset para grandes volúmenes

Autenticación

Todos los endpoints requieren autenticación previa mediante el endpoint Auth:

curl -X GET \
  "https://demo.e3stores.cloud/Api/Auth/?username=TestApi&password=TestApi1357" \
  -H "Content-Type: application/json"

Respuesta exitosa:

{
  "status": "0",
  "message": "Success",
  "data": "5de3928b-6018-4b0c-9ebd-bc2c3e18f708"
}

El valor data es el hash que debe usarse en todas las consultas posteriores.

Endpoints disponibles

Endpoints de consulta (GET)

Endpoint	Descripción	Parámetros principales
`GET /Api/Sale/`	Consulta ventas con múltiples filtros	`hash`, `status`, `from`, `to`, `external_reference`, `email`, etc.
`GET /Api/Sale/{id}`	Obtiene venta específica por ID	`id`, `hash`

Endpoints de actualización (PUT)

Endpoint	Descripción	Parámetros principales
`PUT /Api/Sale/{id}`	Actualiza venta específica	`id`, `hash` + payload JSON

Consulta de ventas con filtros múltiples

URL y método

GET /Api/Sale/

Parámetros disponibles

Parámetro	Tipo	Requerido	Descripción	Ejemplo
`hash`	string	Sí	Token de autenticación	`5de3928b-6018-4b0c-9ebd-bc2c3e18f708`
`status`	Collection of integer	No	Estados de la venta (múltiples valores)	`1,3,6`
`from`	date	No	Fecha de inicio (formato YYYY-MM-DD)	`2024-12-01`
`to`	date	No	Fecha de fin (formato YYYY-MM-DD)	`2025-02-01`
`external_reference`	string	No	Referencia en sistema externo	`ERP-2024-001`
`subStatus`	integer	No	Sub-estado de la venta	`1`
`payMethodId`	integer	No	ID del método de pago	`31`
`siteId`	integer	No	ID del sitio	`1`
`limit`	integer	No	Número máximo de resultados	`50`
`offset`	integer	No	Número de registros a omitir (paginación)	`0`
`email`	string	No	Email del cliente	`juan@email.com`
`identification_number`	string	No	Número de documento del cliente	`12345678`
`last_digits_phone`	string	No	Últimos dígitos del teléfono	`6789`
`postal_code`	integer	No	Código postal	`1043`
`full_name`	string	No	Nombre completo del cliente	`Juan Pérez`

Sistema de estados

Los estados utilizan números enteros con la siguiente lógica:

Números positivos: Operaciones realizadas (distintos grados de aceptación)
Número 0: Operación pendiente
Números negativos: Operaciones rechazadas

Estado	Descripción
`0`	Pendiente
`1`	Confirmada
`2`	En proceso
`3`	Completada
`6`	Entregada
`-1`	Rechazada
`-2`	Cancelada

Ejemplos de peticiones

Consulta básica por estado y fecha:

curl -X GET \
  "https://demo.e3stores.cloud/Api/Sale/?status=3&from=2024-12-01&to=2025-02-01&hash=5de3928b-6018-4b0c-9ebd-bc2c3e18f708" \
  -H "Content-Type: application/json"

Consulta con múltiples estados:

curl -X GET \
  "https://demo.e3stores.cloud/Api/Sale/?status=1,3,6&siteId=1&hash=5de3928b-6018-4b0c-9ebd-bc2c3e18f708" \
  -H "Content-Type: application/json"

Consulta por email del cliente:

curl -X GET \
  "https://demo.e3stores.cloud/Api/Sale/?email=juan@email.com&hash=5de3928b-6018-4b0c-9ebd-bc2c3e18f708" \
  -H "Content-Type: application/json"

Consulta por referencia externa:

curl -X GET \
  "https://demo.e3stores.cloud/Api/Sale/?external_reference=ERP-2024-001&siteId=1&hash=5de3928b-6018-4b0c-9ebd-bc2c3e18f708" \
  -H "Content-Type: application/json"

Consulta con paginación:

curl -X GET \
  "https://demo.e3stores.cloud/Api/Sale/?status=3&limit=25&offset=50&hash=5de3928b-6018-4b0c-9ebd-bc2c3e18f708" \
  -H "Content-Type: application/json"

Búsqueda por datos del cliente:

curl -X GET \
  "https://demo.e3stores.cloud/Api/Sale/?identification_number=12345678&postal_code=1043&hash=5de3928b-6018-4b0c-9ebd-bc2c3e18f708" \
  -H "Content-Type: application/json"

Consulta de venta por ID específico

URL y método

GET /Api/Sale/{id}?hash={hash}

Parámetros requeridos

Parámetro	Tipo	Requerido	Descripción	Ejemplo
`id`	integer	Sí	ID de la venta	`11474`
`hash`	string	Sí	Token de autenticación	`5de3928b-6018-4b0c-9ebd-bc2c3e18f708`

Ejemplo de petición

curl -X GET \
  "https://demo.e3stores.cloud/Api/Sale/11474?hash=5de3928b-6018-4b0c-9ebd-bc2c3e18f708" \
  -H "Content-Type: application/json"

Actualización de venta

URL y método

PUT /Api/Sale/{id}?hash={hash}

Parámetros requeridos

Parámetro	Tipo	Requerido	Descripción	Ejemplo
`id`	integer	Sí	ID de la venta a actualizar	`11474`
`hash`	string	Sí	Token de autenticación	`5de3928b-6018-4b0c-9ebd-bc2c3e18f708`

Cuerpo de la petición (Body)

El cuerpo debe contener un objeto JSON con la estructura completa de la venta. Todos los campos son opcionales, pero se recomienda enviar la estructura completa:

{
  "Id": 11474,
  "Status": 3,
  "StatusText": "Completada",
  "OperationStatus": 1,
  "TrackingCode": "ARG1234567890",
  "Obeservations": "Venta procesada correctamente",
  "Message": "Entrega confirmada por el cliente"
}

Ejemplo de petición de actualización

curl -X PUT \
  "https://demo.e3stores.cloud/Api/Sale/11474?hash=5de3928b-6018-4b0c-9ebd-bc2c3e18f708" \
  -H "Content-Type: application/json" \
  -d '{
    "Id": 11474,
    "Status": 6,
    "StatusText": "Entregada",
    "TrackingCode": "ARG1234567890",
    "Obeservations": "Entregado el 15/01/2025 - Firmado por Juan Pérez"
  }'

Estructura de respuesta de ventas

Respuesta completa de ejemplo

{
  "Id": 12345,
  "InternalCode": "0001234567",
  "PayMethodId": 31,
  "PayMethod": {
    "Id": 31,
    "Name": "12 Cuotas sin Interés - Banco Ejemplo",
    "Description": "Tarjetas de Crédito Banco Ejemplo",
    "SiteControlName": "SPSV2",
    "ConfigControlName": "PMSPSV2.ascx",
    "Enable": true,
    "Selected": false
  },
  "Total": 25999.00,
  "Status": 3,
  "StatusText": "Completada",
  "OperationStatus": 0,
  "OperationStatusText": null,
  "UserId": 1001,
  "UserData": {
    "Id": 1001,
    "FirstName": "Juan Carlos",
    "LastName": "Pérez",
    "EMail": "juan.perez@email.com",
    "Access": false,
    "Address": "Av. Corrientes",
    "State": "1",
    "City": "100",
    "Country": "1",
    "Town": "1050",
    "PostalCode": "1043",
    "Phone": "1143216789",
    "IdNumber": "12345678",
    "StreetNumber": "1234",
    "AddressLine1": "Piso 5, Depto A",
    "Birthday": "1985-03-15T00:00:00"
  },
  "BillingAddress": {
    "Type": 1,
    "Default": false,
    "Name": "Juan Carlos Pérez",
    "Street": "Av. Corrientes",
    "Country": "1",
    "State": "1",
    "City": "100",
    "Town": "1050",
    "PostalCode": "1043",
    "Phone": "1143216789",
    "StreetNumber": "1234",
    "AddressLine1": "Piso 5, Depto A",
    "AddressLine2": "Entre San Martín y Maipú",
    "CountryName": "Argentina",
    "StateName": "Buenos Aires",
    "CityName": "Buenos Aires",
    "TownName": "Microcentro",
    "IdNumber": "12345678",
    "Email": "juan.perez@email.com"
  },
  "ShippingAddress": {
    "Type": 0,
    "Default": false,
    "Name": "Juan Carlos Pérez",
    "Street": "Av. Corrientes",
    "Country": "1",
    "State": "1",
    "City": "100",
    "Town": "1050",
    "PostalCode": "1043",
    "Phone": "1143216789",
    "StreetNumber": "1234",
    "AddressLine1": "Piso 5, Depto A",
    "AddressLine2": "Entre San Martín y Maipú",
    "CountryName": "Argentina",
    "StateName": "Buenos Aires",
    "CityName": "Buenos Aires",
    "TownName": "Microcentro",
    "IdNumber": "12345678",
    "Email": "juan.perez@email.com"
  },
  "CreationDate": "01/15/2025 14:30:25",
  "ModificationDate": "01/15/2025 14:45:10",
  "SiteId": 1,
  "ShippingCost": 2500.00,
  "ShippingId": 10,
  "GatewayResponseCode": "001234",
  "Currency": {
    "Id": 1,
    "Name": "Pesos",
    "Code": "ARS",
    "DisplayName": "$",
    "Value": 1.000000,
    "IsDefault": true,
    "SiteId": 1
  },
  "Items": [
    {
      "Id": 98765,
      "ItemId": 5001,
      "Code": "PROD-001",
      "Price": 23499.00,
      "Quantity": 1,
      "Name": "Smartphone Samsung Galaxy A54 128GB Negro",
      "IsItem": true,
      "SaleItemType": 0
    },
    {
      "Id": 98766,
      "ItemId": 0,
      "Code": "SHIP-001",
      "Price": 2500.00,
      "Quantity": 1,
      "Name": "Envío Express",
      "IsItem": false,
      "SaleItemType": 1
    }
  ],
  "ShippingMethod": {
    "Id": 10,
    "Name": "Envío Express",
    "Code": "SHIP-001",
    "Display": "CABA/GBA entrega en 24-48 horas hábiles"
  },
  "TrackingCode": "ARG1234567890",
  "Payments": 12
}

Referencia completa de campos

Campos principales de la venta

Campo	Tipo	Descripción
`Id`	int	ID único de la venta
`InternalCode`	string	Código interno de la venta
`PayMethodId`	int	ID del método de pago
`PayMethod`	PayMethod	Objeto completo del método de pago
`Total`	decimal	Total de la venta
`Status`	int	Estado de la venta
`StatusText`	string	Descripción del estado
`OperationStatus`	int	Estado de la operación
`OperationStatusText`	string	Descripción del estado de operación
`UserId`	int	ID del usuario
`UserData`	User	Objeto completo de datos del usuario
`BillingAddress`	Address	Dirección de facturación
`ShippingAddress`	Address	Dirección de envío
`CreationDate`	datetime	Fecha de creación
`ModificationDate`	datetime	Fecha de modificación
`Obeservations`	string	Observaciones
`Message`	string	Mensaje
`SiteId`	int	ID del sitio
`ShippingCost`	decimal	Costo de envío
`Lat`	string	Latitud (geolocalización)
`Lng`	string	Longitud (geolocalización)
`ShippingId`	int	ID del método de envío
`GatewayResponseCode`	string	Código de respuesta del gateway
`GatewayResponseMessage`	string	Mensaje de respuesta del gateway
`RetryAttempt`	int	Número de intentos de reintento
`IpFrom`	string	IP de origen de la venta
`Payments`	int	Número de cuotas
`GatewayOrderNumber`	string	Número de orden del gateway
`OtherCost`	decimal	Otros costos
`CurrencyId`	int	ID de la moneda
`Currency`	Currency	Objeto completo de la moneda
`VendorId`	int	ID del vendedor
`Taxes`	decimal	Impuestos
`Discount`	decimal	Descuento
`InvoiceNumber`	string	Número de factura
`TrackingCode`	string	Código de seguimiento
`CardName`	string	Nombre en la tarjeta
`DeliveryDate`	date	Fecha de entrega
`MarketingEventDate`	date	Fecha de evento de marketing
`MarketingPurchaseEventDate`	date	Fecha de evento de compra marketing
`MarketingCrossellEventDate`	date	Fecha de evento de cross-sell
`Items`	Collection of SaleItem	Colección de items de la venta
`Company`	string	Empresa
`IVA`	string	IVA
`NombreFantasia`	string	Nombre de fantasía
`SitioWeb`	string	Sitio web
`Truck`	string	Camión
`GatewayMessage`	string	Mensaje del gateway
`SetNewStatus`	string	Establecer nuevo estado
`SetNewOperationStatus`	string	Establecer nuevo estado de operación
`Preferences`	Collection of Preference	Preferencias
`ShippingMethod`	ShippingCostBase	Método de envío
`ExternalDate`	date	Fecha externa
`BoxWidth`	decimal	Ancho de la caja
`BoxLength`	decimal	Largo de la caja
`BoxHeight`	decimal	Alto de la caja
`BoxWeight`	decimal	Peso de la caja
`Volume`	decimal	Volumen
`BoxLengthUnits`	LengthUnits	Unidades de longitud
`BoxWeightUnits`	WeightUnits	Unidades de peso
`SubStatus`	int	Sub-estado
`ExternalReference`	string	Referencia externa
`SearchFirstLastName`	string	Búsqueda por nombre y apellido
`SearchEmail`	string	Búsqueda por email
`SearchPhone`	string	Búsqueda por teléfono
`SearchPostalCode`	string	Búsqueda por código postal
`TotalPaidAmount`	decimal	Monto total pagado
`TaxPayments`	decimal	Pagos de impuestos
`Providers`	Collection of Provider	Proveedores
`Utm`	string	UTM
`UtmParameters`	Dictionary	Parámetros UTM

Campos de UserData

Campo	Tipo	Descripción
`Id`	int	ID del usuario
`Username`	string	Nombre de usuario
`FirstName`	string	Nombre
`LastName`	string	Apellido
`EMail`	string	Email
`Access`	bool	Acceso habilitado
`Address`	string	Dirección
`State`	string	Provincia/Estado
`City`	string	Ciudad
`Country`	string	País
`Town`	string	Localidad
`PostalCode`	string	Código postal
`Phone`	string	Teléfono
`Mobile`	string	Celular
`IdNumber`	string	Número de documento
`StreetNumber`	string	Número de calle
`AddressLine1`	string	Línea adicional 1
`AddressLine2`	string	Línea adicional 2
`Birthday`	datetime	Fecha de nacimiento

Campos de dirección (BillingAddress/ShippingAddress)

Campo	Tipo	Descripción
`Type`	int	Tipo de dirección (0=Envío, 1=Facturación)
`Default`	bool	Dirección por defecto
`Name`	string	Nombre completo
`Street`	string	Calle
`Country`	string	País
`State`	string	Estado/Provincia
`City`	string	Ciudad
`Town`	string	Localidad
`PostalCode`	string	Código postal
`Phone`	string	Teléfono
`StreetNumber`	string	Número de calle
`AddressLine1`	string	Línea adicional 1
`AddressLine2`	string	Línea adicional 2
`CountryName`	string	Nombre del país
`StateName`	string	Nombre del estado
`CityName`	string	Nombre de la ciudad
`TownName`	string	Nombre de la localidad
`CountryCode`	string	Código del país
`StateCode`	string	Código del estado
`CityCode`	string	Código de la ciudad
`TownCode`	string	Código de la localidad
`IdNumber`	string	Número de documento
`Email`	string	Email

Campos de Items

Campo	Tipo	Descripción
`Id`	int	ID del item en la venta
`ItemId`	int	ID del producto
`Code`	string	Código del producto
`PriceCode`	string	Código de precio
`PriceId`	int	ID del precio
`Price`	decimal	Precio unitario
`Quantity`	int	Cantidad
`SaleId`	int	ID de la venta
`CurrencyId`	int	ID de la moneda
`IsItem`	bool	Es producto (true) o servicio (false)
`Name`	string	Nombre del producto
`ReferenceId`	int	ID de referencia
`SaleItemType`	int	Tipo de item (0=Producto, 1=Servicio)
`Currency`	Currency	Objeto de moneda
`IsCombo`	bool	Es combo
`ProviderId`	int	ID del proveedor
`Preferences`	Dictionary	Preferencias del item

Manejo de errores

Códigos de error comunes

Código	Descripción
400	Parámetros inválidos
401	Token (hash) inválido o expirado
404	Venta no encontrada
500	Error interno del servidor

Casos de uso comunes

1. Consulta de ventas del día

curl -X GET \
  "https://demo.e3stores.cloud/Api/Sale/?from=2025-01-15&to=2025-01-15&hash=YOUR_HASH" \
  -H "Content-Type: application/json"

2. Ventas pendientes de un sitio específico

curl -X GET \
  "https://demo.e3stores.cloud/Api/Sale/?status=0&siteId=1&hash=YOUR_HASH" \
  -H "Content-Type: application/json"

3. Búsqueda por método de pago

curl -X GET \
  "https://demo.e3stores.cloud/Api/Sale/?payMethodId=31&from=2025-01-01&hash=YOUR_HASH" \
  -H "Content-Type: application/json"

4. Paginación para reportes

curl -X GET \
  "https://demo.e3stores.cloud/Api/Sale/?status=3,6&limit=100&offset=0&hash=YOUR_HASH" \
  -H "Content-Type: application/json"

5. Actualización de estado y tracking

curl -X PUT \
  "https://demo.e3stores.cloud/Api/Sale/12345?hash=YOUR_HASH" \
  -H "Content-Type: application/json" \
  -d '{
    "Id": 12345,
    "Status": 6,
    "StatusText": "Entregada",
    "TrackingCode": "ARG1234567890",
    "Obeservations": "Entregado exitosamente"
  }'

Consideraciones importantes

Estados de venta

Los estados son altamente personalizables según las necesidades del cliente
Números positivos para ventas en proceso o completadas
Números negativos para ventas rechazadas o canceladas
El estado 0 se reserva para ventas pendientes

Fechas y horarios

Todas las fechas están en formato ISO
Los parámetros de fecha deben enviarse en formato YYYY-MM-DD
Las fechas de respuesta incluyen horario completo

Referencia externa

Útil para integración con sistemas ERP
Permite búsqueda rápida de ventas sincronizadas
Debe ser única por sitio

Autenticación y seguridad

El hash de autenticación puede tener expiración configurable
Se recomienda implementar renovación automática del token
Usar credenciales de prueba: TestApi / TestApi1357

Paginación y rendimiento

Usar limit y offset para manejar grandes volúmenes de datos
Valores recomendados: limit=50-100 para consultas normales
Monitorear el rendimiento en consultas de rangos de fechas amplios
Usar filtros específicos para optimizar las consultas

Búsquedas por datos del cliente

Los parámetros de búsqueda permiten encontrar ventas por información del cliente
identification_number: Busca por número de documento exacto
last_digits_phone: Busca por los últimos dígitos del teléfono
full_name: Búsqueda por nombre completo (puede ser parcial)
email: Búsqueda por email exacto

Características principales​

Autenticación​

Endpoints disponibles​

Endpoints de consulta (GET)​

Endpoints de actualización (PUT)​

Consulta de ventas con filtros múltiples​

URL y método​

Parámetros disponibles​

Sistema de estados​

Ejemplos de peticiones​

Consulta de venta por ID específico​

URL y método​

Parámetros requeridos​

Ejemplo de petición​

Actualización de venta​

URL y método​

Parámetros requeridos​

Cuerpo de la petición (Body)​

Ejemplo de petición de actualización​

Estructura de respuesta de ventas​

Respuesta completa de ejemplo​

Referencia completa de campos​

Campos principales de la venta​

Campos de UserData​

Campos de dirección (BillingAddress/ShippingAddress)​

Campos de Items​

Manejo de errores​

Códigos de error comunes​

Casos de uso comunes​

1. Consulta de ventas del día​

2. Ventas pendientes de un sitio específico​

3. Búsqueda por método de pago​

4. Paginación para reportes​

5. Actualización de estado y tracking​

Consideraciones importantes​

Estados de venta​

Fechas y horarios​

Referencia externa​

Autenticación y seguridad​

Paginación y rendimiento​

Búsquedas por datos del cliente​

Características principales

Autenticación

Endpoints disponibles

Endpoints de consulta (GET)

Endpoints de actualización (PUT)

Consulta de ventas con filtros múltiples

URL y método

Parámetros disponibles

Sistema de estados

Ejemplos de peticiones

Consulta de venta por ID específico

URL y método

Parámetros requeridos

Ejemplo de petición

Actualización de venta

URL y método

Parámetros requeridos

Cuerpo de la petición (Body)

Ejemplo de petición de actualización

Estructura de respuesta de ventas

Respuesta completa de ejemplo

Referencia completa de campos

Campos principales de la venta

Campos de UserData

Campos de dirección (BillingAddress/ShippingAddress)

Campos de Items

Manejo de errores

Códigos de error comunes

Casos de uso comunes

1. Consulta de ventas del día

2. Ventas pendientes de un sitio específico

3. Búsqueda por método de pago

4. Paginación para reportes

5. Actualización de estado y tracking

Consideraciones importantes

Estados de venta

Fechas y horarios

Referencia externa

Autenticación y seguridad

Paginación y rendimiento

Búsquedas por datos del cliente