API de Gestion Nube

La API permite integrar sistemas externos con Gestion Nube para automatizar procesos como sincronización de precios, catálogos y reportes. Todas las respuestas se entregan en JSON salvo las exportaciones de archivos.

URL base y versionado

• Producción: https://app.gestion.moda/api
• Sandbox o local: http://localhost/api
• Versión actual: v1 (todas las rutas están prefijadas con /api/v1)

Autenticación

La autenticación se realiza mediante tokens personales emitidos por Laravel Sanctum. Generá un token enviando tus credenciales registradas.

curl -X POST "https://app.gestion.moda/api/sanctum/token" \
  -H "Accept: application/json" \
  -d '{
    "email": "usuario@ejemplo.com",
    "password": "********",
    "device_name": "integracion-tienda",
    "abilities": ["products:read", "products:write", "prices:read", "prices:write", "inventory:read"]
  }'

• device_name identifica el token emitido.
• abilities es opcional. Si se omite, se asigna prices:read.
• Respuesta: token en texto plano. Guardalo porque no vuelve a mostrarse.
• Límite: 5 solicitudes por minuto (límite throttle:auth).

Permisos disponibles (abilities)

Incluí el token en todas las rutas protegidas usando el encabezado:

Authorization: Bearer <token>
Accept: application/json

Gestión de tokens

Estas rutas requieren autenticación y comparten el límite general de 60 solicitudes por minuto.

Usuario autenticado y chequeo rápido

Módulo de precios

Requiere el scope prices:read. Usa paginación estándar y cabeceras adicionales con totales.

Listar precios vigentes

GET /api/v1/precios/obtener

Parámetros de consulta:

• per_page: cantidad por página (1-200, por defecto 50).
• q: búsqueda por nombre o código.
• lista_id o price_list_id: fuerza una lista específica; si se omite se toma la lista base activa de la compañía.

{
  "price_list": {
    "id": 7,
    "descripcion": "Lista Mayorista",
    "is_base": false,
    "moneda": "ARS",
    "variacion": 15
  },
  "data": [
    { "id": 120, "code": "REM-001", "name": "Remera Oversize", "price": 11999.9 },
    { "id": 122, "code": "REM-002", "name": "Remera Boxy", "price": 12499.0 }
  ],
  "meta": {
    "current_page": 1,
    "per_page": 50,
    "total": 87,
    "last_page": 2,
    "from": 1,
    "to": 50,
    "has_more_pages": true
  },
  "links": {
    "first": "https://app.gestion.moda/api/v1/precios/obtener?page=1",
    "last": "https://app.gestion.moda/api/v1/precios/obtener?page=2",
    "prev": null,
    "next": "https://app.gestion.moda/api/v1/precios/obtener?page=2"
  }
}

Cabeceras útiles: X-Total-Count, X-Per-Page, X-Current-Page, X-Last-Page.

Listar listas de precios

GET /api/v1/precios/listas

Requiere la habilidad prices:read. Devuelve todas las listas de precios activas de la compañía.

{
  "data": [
    {
      "id": 1,
      "descripcion": "Lista Base Minorista",
      "is_base": true,
      "variacion": null,
      "moneda": "ARS"
    },
    {
      "id": 2,
      "descripcion": "Lista Mayorista",
      "is_base": false,
      "variacion": -15,
      "moneda": "ARS"
    }
  ]
}

Actualizar precio en lista base

PUT /api/v1/precios/{lista_id}/producto/{product_id}

Requiere la habilidad prices:write. Solo permite editar listas base (is_base = true). Las listas derivadas calculan precios automáticamente.

Parámetros del body (JSON):

• price (requerido): precio del producto. Si envías 0, el precio se elimina de la lista.
• aditional_price (opcional): precio adicional.

curl -X PUT "https://app.gestion.moda/api/v1/precios/1/producto/120" \
  -H "Authorization: Bearer TU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"price": 2500.00}'

{
  "message": "Precio actualizado correctamente",
  "price_list_id": 1,
  "product_id": 120,
  "product_code": "REM-001",
  "product_name": "Remera Oversize",
  "price": 2500.00,
  "aditional_price": null
}

Módulo de productos

Disponible con la habilidad products:read.

Listar productos

GET /api/v1/productos/obtener

Filtros disponibles:

• per_page, q, code
• category_id, provider_id
• active (1 o 0)
• include_stock y include_variants para anexar stock total y variantes por tienda.

Ver detalle

GET /api/v1/productos/ver/{id}. Admite los mismos flags para incluir stock y variantes.

{
  "id": 120,
  "code": "REM-001",
  "name": "Remera Oversize",
  "description": "Algodon 24/1",
  "retailer_price": 16999,
  "wholesaler_price": 11999,
  "unit_cost": 5400,
  "category": "Remeras",
  "provider": "Textiles SRL",
  "stock_total": 320,
  "variantes": [
    {
      "size_id": 4,
      "size": "M",
      "barcode": "7790000000012",
      "stock_por_tienda": [
        { "store_id": 1, "store_name": "Deposito Central", "stock_disponible": 120 },
        { "store_id": 2, "store_name": "Sucursal Palermo", "stock_disponible": 45 }
      ]
    }
  ]
}

Exportar catálogo

GET /api/v1/productos/exportar devuelve un archivo CSV (o XLSX si está disponible maatwebsite/excel). Respeta los mismos filtros que el listado y admite include_stock, include_variants. Esta ruta usa el limitador throttle:exports (10 solicitudes por minuto).

Actualizar producto

PUT /api/v1/productos/{id} o PATCH /api/v1/productos/{id}

Requiere la habilidad products:write. Permite actualizar los precios minorista y mayorista de un producto.

Campos disponibles (al menos uno requerido):

• retailer_price: precio minorista
• wholesaler_price: precio mayorista

curl -X PUT "https://app.gestion.moda/api/v1/productos/120" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "retailer_price": 18500,
    "wholesaler_price": 13000
  }'

Respuesta:

{
  "message": "Producto actualizado correctamente",
  "data": {
    "id": 120,
    "code": "REM-001",
    "name": "Remera Oversize",
    "retailer_price": 18500,
    "wholesaler_price": 13000,
    "unit_cost": 5400
  }
}

Actualizar precios (endpoint alternativo)

PUT /api/v1/productos/{id}/precios o PATCH /api/v1/productos/{id}/precios

Requiere la habilidad prices:write. Permite actualizar los precios de un producto incluyendo el costo unitario.

Campos disponibles (al menos uno requerido):

• retailer_price: precio minorista
• wholesaler_price: precio mayorista
• unit_cost: costo unitario

curl -X PUT "https://app.gestion.moda/api/v1/productos/120/precios" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "retailer_price": 18500,
    "wholesaler_price": 13000
  }'

Respuesta:

{
  "message": "Precios actualizados correctamente",
  "data": {
    "id": 120,
    "code": "REM-001",
    "name": "Remera Oversize",
    "retailer_price": 18500,
    "wholesaler_price": 13000,
    "unit_cost": 5400
  }
}

Nota: Si el producto está vinculado a TiendaNube o MercadoLibre, los cambios de precio se sincronizarán automáticamente.

Módulo de inventario

Disponible con la habilidad inventory:read. Permite consultar el stock disponible (available_quantity) de los productos.

Listar inventario

GET /api/v1/inventario/obtener

Filtros disponibles:

• product_id: filtrar por producto específico
• size_id: filtrar por talla
• store_id: filtrar por tienda/depósito
• code: filtrar por código de producto
• q: búsqueda por nombre o código
• include_physical: incluir stock físico y en producción
• per_page: paginación (1-200, por defecto 50)

{
  "data": [
    {
      "inventory_id": 1234,
      "product_id": 120,
      "product_code": "REM-001",
      "product_name": "Remera Oversize",
      "size_id": 4,
      "size_name": "M",
      "store_id": 1,
      "store_name": "Deposito Central",
      "available_quantity": 120,
      "barcode": "7790000000012",
      "sku": "REM-001-M"
    }
  ],
  "meta": { /* paginación estándar */ },
  "links": { /* links de navegación */ }
}

Inventario por producto

GET /api/v1/inventario/{product_id}

Devuelve el stock total del producto y el detalle por talla y tienda.

{
  "product_id": 120,
  "product_code": "REM-001",
  "product_name": "Remera Oversize",
  "stock_total": 320,
  "variantes": [
    {
      "size_id": 4,
      "size_name": "M",
      "barcode": "7790000000012",
      "sku": "REM-001-M",
      "stock_total_talla": 165,
      "stock_por_tienda": [
        { "inventory_id": 1234, "store_id": 1, "store_name": "Deposito Central", "available_quantity": 120 },
        { "inventory_id": 1235, "store_id": 2, "store_name": "Sucursal Palermo", "available_quantity": 45 }
      ]
    }
  ]
}

Paginación y formato

• Todas las colecciones devuelven los bloques meta y links propios de la paginación de Laravel.
• Los listados agregan cabeceras con totalizadores para facilitar integraciones.
• Los importes se devuelven como decimales. Ajustá el formateo según tu moneda.
• Las rutas autenticadas respetan la compañía activa del usuario (active_company) para garantizar el aislamiento multiempresa.

Límites de Solicitudes (Rate Limiting)

La API implementa límites de solicitudes para proteger el servicio y garantizar disponibilidad para todos los usuarios.

Límites por Tipo de Operación

Respuesta al Exceder Límite

Cuando se excede el límite, la API retorna código 429 Too Many Requests con el header Retry-After indicando segundos de espera.

{
  "message": "Demasiadas solicitudes. Intenta nuevamente en un minuto.",
  "retry_after": 60
}

Headers de respuesta:

HTTP/1.1 429 Too Many Requests
Retry-After: 60
Content-Type: application/json

Manejo de errores

Buenas prácticas y seguridad

• Usá siempre HTTPS en producción.
• Rotá y revocá tokens periódicamente.
• Limitate a las habilidades necesarias para cada integración.
• Respetá los límites: 60 solicitudes por minuto para el grupo general y 10 por minuto para exportaciones.
• No mezcles datos de distintas compañías: el active_company se aplica en todas las consultas.

Soporte

• Soporte técnico / integraciones: info@gestion.moda

Cuando abras un ticket, incluí el request-id y la marca de tiempo de la solicitud para acelerar el análisis.