openapi: 3.0.0
info:
  title: E3 Stores Complete API
  version: 1.0.0
  description: |
    API completa para el sistema E3 Stores - Gestión de productos, inventario, ventas y usuarios
    
    ## Autenticación
    
    1. Primero obtén el hash usando el endpoint `/Auth`
    2. Usa ese hash en los demás endpoints como parámetro `hash`
    
    ## Flujo de uso
    
    1. **Autenticación**: `GET /Auth?username=TestApi&password=TestApi1357`
    2. **Consultar inventario**: `GET /Inventory/Get?hash=HASH_OBTENIDO&code=e3-10001-55`
    3. **Actualizar inventario**: `PUT /Inventory?hash=HASH_OBTENIDO`
    4. **Consultar productos**: `GET /product?hash=HASH_OBTENIDO`
    5. **Consultar ventas**: `GET /Sale?hash=HASH_OBTENIDO&status=1`
    6. **Consultar usuarios**: `GET /user/{id}?hash=HASH_OBTENIDO`
    
  contact:
    name: E3 Stores API Support
    url: https://demo.e3stores.cloud
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT

servers:
  - url: https://{host}/api
    description: Instancia de E3 Stores — editá el host con el dominio de tu tienda
    variables:
      host:
        default: docs.e3stores.cloud
        description: >-
            Dominio de tu tienda E3 Stores (por ejemplo, tu-tienda.e3stores.cloud).
            Podés editarlo en el panel de prueba para apuntar a tu propia instancia.

paths:
  /Auth/:
    get:
      tags:
        - Autenticación
      summary: Login - Endpoint de autenticación
      description: |
        ### Endpoint de autenticación
        
        **Descripción:** 
        The API endpoint makes an HTTP GET request to retrieve authentication information using the provided username and password as query parameters. 
        
        ### Response
        The response is in JSON format with the following schema:
        ```json
        {
            "type": "object",
            "properties": {
                "status": {
                    "type": "string"
                },
                "message": {
                    "type": "string"
                },
                "data": {
                    "type": "string"
                },
                "site": {
                    "type": "integer"
                }
            }
        }
        ```
      parameters:
        - name: username
          in: query
          required: true
          schema:
            type: string
            example: TestApi
          description: Nombre de usuario para autenticación
        - name: password
          in: query
          required: true
          schema:
            type: string
            example: TestApi1357
          description: Contraseña del usuario
      responses:
        '200':
          description: Autenticación exitosa
        '401':
          description: Credenciales inválidas

  /inventory:
    get:
      tags:
        - Inventario
      summary: Inventory - Todos los endpoints de Inventory disponibles
      description: |
        ### Todos los endpoints de Inventory disponibles
        
        ## Endpoints de consulta (GET)
        
        | Endpoint | Descripción | Parámetros principales |
        |----------|-------------|----------------------|
        | `GET api/Inventory/Get?hash={hash}&code={code}&pricelistId={pricelistId}&siteId={siteId}&includePreferences={includePreferences}` | Método de consulta con preferencias | `hash`, `code`, `pricelistId`, `siteId`, `includePreferences` |
        
        ## Endpoints de modificación (POST/PUT)
        
        | Endpoint | Descripción | Parámetros principales |
        |----------|-------------|----------------------|
        | `PUT api/Inventory?hash={hash}&mode={mode}` | Actualiza producto existente | `hash`, `mode` |
        
        **Casos de uso:**
        1. **Consulta con preferencias**: Usando endpoint `/Inventory/Get`
        2. **Actualización de inventario**: Usando endpoint PUT `/Inventory`
        
        ```json
        [
          {
            "InternalId": "number",
            "Code": "string",
            "Stock": "number",
            "Price": "number",
            "OfferPrice": "number",
            "Taxes": "null or object",
            "ForSale": "boolean",
            "Published": "boolean",
            "IsItem": "boolean",
            "ParentItemId": "number",
            "ParentItemCode": "string",
            "PriceListId": "number",
            "PriceListCode": "string or null",
            "PriceMode": "number",
            "PrecioOriginal": "string",
            "DepStock": "null or object",
            "Properties": [
              {
                "Key": "string",
                "Value": "string"
              }
            ],
            "Name": "string",
            "Code2": "string",
            "ExternalReference": "string",
            "SiteId": "number",
            "ExtendedWarranty": "null or object"
          }
        ]
        ```
      parameters:
        - name: hash
          in: query
          required: true
          schema:
            type: string
            example: "5de3928b-6018-4b0c-9ebd-bc2c3e18f708"
          description: Token de autenticación obtenido del endpoint /Auth
        - name: code
          in: query
          required: false
          schema:
            type: string
            example: "e3-10001-55"
          description: Código específico del producto
        - name: siteId
          in: query
          required: false
          schema:
            type: integer
            example: 1
          description: ID del sitio
        - name: pricelistId
          in: query
          required: false
          schema:
            type: integer
            example: 0
          description: ID de la lista de precios
        - name: includePreferences
          in: query
          required: false
          schema:
            type: boolean
            example: true
          description: Incluir preferencias/propiedades del producto
      responses:
        '200':
          description: Inventario obtenido exitosamente
        '400':
          description: Parámetros inválidos
        '401':
          description: Token (hash) inválido o expirado
        '500':
          description: Error interno del servidor

  /Inventory/Get:
    get:
      tags:
        - Inventario
      summary: Inventory Get - Método de consulta con preferencias
      description: |
        ### Endpoint GET para consulta con preferencias
        
        **Estructura completa:** `GET api/Inventory/Get?hash={hash}&code={code}&pricelistId={pricelistId}&siteId={siteId}&includePreferences={includePreferences}`
        
        **Descripción:** Método de consulta con preferencias
        
        **Parámetros principales:** `hash`, `code`, `pricelistId`, `siteId`, `includePreferences`
        
        Este endpoint permite obtener información específica del inventario con soporte completo para preferencias.
      parameters:
        - name: hash
          in: query
          required: true
          schema:
            type: string
            example: "5de3928b-6018-4b0c-9ebd-bc2c3e18f708"
          description: Token de autenticación
        - name: code
          in: query
          required: false
          schema:
            type: string
            example: "e3-10001-55"
          description: Código del producto
        - name: pricelistId
          in: query
          required: false
          schema:
            type: integer
            example: 0
          description: ID de la lista de precios
        - name: siteId
          in: query
          required: false
          schema:
            type: integer
            example: 1
          description: ID del sitio
        - name: includePreferences
          in: query
          required: false
          schema:
            type: boolean
            example: true
          description: Incluir preferencias del producto
      responses:
        '200':
          description: Inventario obtenido exitosamente
        '400':
          description: Parámetros inválidos
        '401':
          description: Token (hash) inválido o expirado
        '500':
          description: Error interno del servidor

  /Inventory:
    put:
      tags:
        - Inventario
      summary: Inventory PUT - Actualiza producto existente
      description: |
        ### Endpoint PUT para actualizar producto existente
        
        **Estructura completa:** `PUT api/Inventory?hash={hash}&mode={mode}`
        
        **Descripción:** Actualiza producto existente
        
        **Parámetros principales:** `hash`, `mode`
        
        Este endpoint permite actualizar información del inventario de productos existentes.
      parameters:
        - name: hash
          in: query
          required: true
          schema:
            type: string
            example: "5de3928b-6018-4b0c-9ebd-bc2c3e18f708"
          description: Token de autenticación
        - name: mode
          in: query
          required: false
          schema:
            type: string
            example: "update"
          description: Modo de actualización
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                Code:
                  type: string
                  example: "e3-10001-55"
                  description: Código del producto
                Stock:
                  type: integer
                  example: 100
                  description: Cantidad en stock
                Price:
                  type: number
                  format: decimal
                  example: 15999.00
                  description: Precio del producto
                OfferPrice:
                  type: number
                  format: decimal
                  example: 12999.00
                  description: Precio de oferta
                ForSale:
                  type: boolean
                  example: true
                  description: Disponible para venta
                Published:
                  type: boolean
                  example: true
                  description: Producto publicado
                SiteId:
                  type: integer
                  example: 1
                  description: ID del sitio
            example:
              Code: "e3-10001-55"
              Stock: 100
              Price: 15999.00
              OfferPrice: 12999.00
              ForSale: true
              Published: true
              SiteId: 1
      responses:
        '200':
          description: Inventario actualizado exitosamente
        '400':
          description: Datos de entrada inválidos
        '401':
          description: Token (hash) inválido o expirado
        '404':
          description: Producto no encontrado
        '500':
          description: Error interno del servidor

  /product:
    get:
      tags:
        - Productos
      summary: Producto - Traer todos los datos del producto - Parámetros
      description: |
        ### Endpoint para obtener datos de productos con múltiples parámetros
        
        Este endpoint permite obtener información de productos aplicando múltiples filtros y parámetros de ordenamiento.
      parameters:
        - name: hash
          in: query
          required: true
          schema:
            type: string
            example: "5de3928b-6018-4b0c-9ebd-bc2c3e18f708"
          description: Token de autenticación
        - name: parentId
          in: query
          required: false
          schema:
            type: integer
            example: 0
          description: ID del producto padre
        - name: order
          in: query
          required: false
          schema:
            type: string
            example: ""
          description: Campo por el cual ordenar
        - name: ascending
          in: query
          required: false
          schema:
            type: boolean
            example: true
          description: Orden ascendente (true) o descendente (false)
        - name: term
          in: query
          required: false
          schema:
            type: string
            example: "aylen"
          description: Término de búsqueda
        - name: mode
          in: query
          required: false
          schema:
            type: string
            example: "default"
          description: Modo de búsqueda
        - name: status
          in: query
          required: false
          schema:
            type: string
            example: ""
          description: Estado del producto
        - name: fields
          in: query
          required: false
          schema:
            type: string
            example: "PostalCode"
          description: Campos específicos a incluir
        - name: filtersand
          in: query
          required: false
          schema:
            type: string
            example: ""
          description: Filtros con operador AND
        - name: filtersor
          in: query
          required: false
          schema:
            type: string
            example: ""
          description: Filtros con operador OR
        - name: creationDateFrom
          in: query
          required: false
          schema:
            type: string
            format: date
            example: "2024-01-01"
          description: Fecha de creación desde
        - name: creationDateTo
          in: query
          required: false
          schema:
            type: string
            format: date
            example: "2024-12-31"
          description: Fecha de creación hasta
      responses:
        '200':
          description: Productos obtenidos exitosamente
        '400':
          description: Parámetros inválidos
        '401':
          description: Token (hash) inválido o expirado
        '500':
          description: Error interno del servidor

  /Sale/:
    get:
      tags:
        - Ventas
      summary: Ordenes - Traer ordenes por status / Traer orden por ExternalReference
      description: |
        ### Endpoint para obtener órdenes filtradas por estado o referencia externa
        
        Este endpoint puede ser usado de dos formas:
        
        1. **Traer ordenes por status**: Usando parámetros `status`, `from`, `to`
        2. **Traer orden por ExternalReference**: Usando parámetros `external_reference`, `siteId`
        
        Este endpoint devuelve información detallada sobre órdenes de acuerdo a su estado y un rango de fechas específico.
        
        La respuesta contiene un array JSON con información detallada de la orden, incluyendo ID de orden, método de pago, monto total, datos del usuario, direcciones de facturación y envío, fechas de creación y modificación, costo de envío, detalles de moneda, artículos en la orden, método de envío y otros detalles relevantes.
      parameters:
        - name: hash
          in: query
          required: true
          schema:
            type: string
            example: "5de3928b-6018-4b0c-9ebd-bc2c3e18f708"
          description: Token de autenticación
        - name: status
          in: query
          required: false
          schema:
            type: string
            example: "1"
          description: Estados de la venta (para buscar por status)
        - name: from
          in: query
          required: false
          schema:
            type: string
            format: date
            example: "2024-12-01"
          description: Fecha de inicio (formato YYYY-MM-DD)
        - name: to
          in: query
          required: false
          schema:
            type: string
            format: date
            example: "2025-02-01"
          description: Fecha de fin (formato YYYY-MM-DD)
        - name: external_reference
          in: query
          required: false
          schema:
            type: string
            example: "1286630500231"
          description: Referencia en sistema externo (para buscar por referencia externa)
        - name: siteId
          in: query
          required: false
          schema:
            type: integer
            example: 1
          description: ID del sitio (usado con external_reference)
        - name: subStatus
          in: query
          required: false
          schema:
            type: integer
            example: 1
          description: Sub-estado de la venta
        - name: payMethodId
          in: query
          required: false
          schema:
            type: integer
            example: 17
          description: ID del método de pago
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            example: 50
          description: Número máximo de resultados
        - name: offset
          in: query
          required: false
          schema:
            type: integer
            example: 0
          description: Número de registros a omitir (paginación)
        - name: email
          in: query
          required: false
          schema:
            type: string
            example: "usuario@email.com"
          description: Email del cliente
        - name: identification_number
          in: query
          required: false
          schema:
            type: string
            example: "12345678"
          description: Número de documento del cliente
        - name: last_digits_phone
          in: query
          required: false
          schema:
            type: string
            example: "6789"
          description: Últimos dígitos del teléfono
        - name: postal_code
          in: query
          required: false
          schema:
            type: integer
            example: 1043
          description: Código postal
        - name: full_name
          in: query
          required: false
          schema:
            type: string
            example: "Juan Pérez"
          description: Nombre completo del cliente
      responses:
        '200':
          description: Lista de ventas obtenida exitosamente
        '400':
          description: Parámetros inválidos
        '401':
          description: Token (hash) inválido o expirado
        '500':
          description: Error interno del servidor

  /Sale/{orderId}:
    get:
      tags:
        - Ventas
      summary: Ordenes - traer orden por ID
      description: |
        ### Endpoint para obtener una orden específica por ID
        
        Este endpoint devuelve información detallada sobre una orden específica identificada por su ID.
      parameters:
        - name: orderId
          in: path
          required: true
          schema:
            type: integer
            example: 11474
          description: ID de la orden
        - name: hash
          in: query
          required: true
          schema:
            type: string
            example: "5de3928b-6018-4b0c-9ebd-bc2c3e18f708"
          description: Token de autenticación
        - name: from
          in: query
          required: false
          schema:
            type: string
            format: date
            example: "2024-12-01"
          description: Fecha de inicio (formato YYYY-MM-DD)
        - name: to
          in: query
          required: false
          schema:
            type: string
            format: date
            example: "2025-02-01"
          description: Fecha de fin (formato YYYY-MM-DD)
      responses:
        '200':
          description: Venta obtenida exitosamente
        '401':
          description: Token (hash) inválido o expirado
        '404':
          description: Venta no encontrada
        '500':
          description: Error interno del servidor

  /user/{userId}:
    get:
      tags:
        - Usuarios
      summary: Usuario - Datos de un usuario particular
      description: |
        ### Endpoint para obtener datos de un usuario específico
        
        Este endpoint devuelve información detallada sobre un usuario específico identificado por su ID.
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            type: integer
            example: 3042
          description: ID del usuario
        - name: hash
          in: query
          required: true
          schema:
            type: string
            example: "5de3928b-6018-4b0c-9ebd-bc2c3e18f708"
          description: Token de autenticación
        - name: term
          in: query
          required: false
          schema:
            type: string
            example: "aylen"
          description: Término de búsqueda
        - name: fields
          in: query
          required: false
          schema:
            type: string
            example: "1044"
          description: Campos específicos a incluir en la respuesta
      responses:
        '200':
          description: Usuario obtenido exitosamente
        '401':
          description: Token (hash) inválido o expirado
        '404':
          description: Usuario no encontrado
        '500':
          description: Error interno del servidor