API Productos - Sage ACICloud

Obtener Lista de Productos

Endpoint: GET /api/acicloud/products
Controller: ACIcloudController::products
Autenticación: Bearer Token requerido
Middleware: check.activate.organization

Características del Endpoint

✅ Filtrado Avanzado: Múltiples filtros y operadores
✅ Paginación: Resultados paginados automáticamente
✅ Ordenamiento: Ordenar por cualquier campo
✅ Multi-tenant: Respeta el contexto de organización activa

Parámetros de Query (Opcionales)

Parámetro	Tipo	Requerido	Descripción	Ejemplo
`page`	integer	❌	Página a obtener	`2`
`per_page`	integer	❌	Registros por página (máx 100)	`50`
`sort`	string	❌	Campo para ordenar	`"code"`
`order`	string	❌	Dirección del ordenamiento	`"asc"`
`filter`	object	❌	Filtros aplicados	`{}`

Ejemplo de Request con Filtros

GET /api/acicloud/products?filter[description][operator]=contains&filter[description][value]=Laptop&filter[active][operator]=equals&filter[active][value]=1

Respuesta de Éxito

{
  "current_page": 1,
  "data": [
    {
      "ProductID": "PROD001",
      "Description": "Producto de prueba estándar",
      "QtyOnHand": "50.00000",
      "Price1": "49.9900",
      "Price2": "45.9900",
      "ItemType": "physical",
      "Location": "Almacén Principal",
      "Weight": "1.5000",
      "SalesDescription": "Este es un producto de prueba para ventas",
      "PartNumber": "PN-10001",
      "TaxType": 10,
      "UnitMeasure": "Unidad",
      "IsActive": 1,
      "UPC_SKU": "SKU-001-ABC",
      "LastUnitCost": "19.9900"
    }
  ],
  "per_page": 10,
  "total": 500,
  "last_page": 50
}

Crear Producto

Endpoint: POST /api/acicloud/product
Request Class: ProductImpRequest
Controller: ACIcloudController::productsImp
Autenticación: Bearer Token requerido

Campos de Request

Campo	Tipo	Requerido	Descripción	Ejemplo
`ProductID`	string	✅	Código único del producto	`"PROD001"`
`Description`	string	✅	Descripción del producto	`"Laptop Dell Inspiron 15"`
`Price1`	decimal	✅	Precio de venta principal	`1200.00`
`Price2`	decimal	❌	Precio alternativo 2	`1100.00`
`Price3`	decimal	❌	Precio alternativo 3	`1050.00`
`TaxType`	integer	✅	Tipo de impuesto	`1`
`UnitMeasure`	string	✅	Unidad de medida	`"EA"`
`GL_Sales_Acct`	string	❌	Cuenta contable de ventas	`"4100"`
`Custom_field1`	string	❌	Campo personalizado 1	`"Categoría A"`

Tipos de Impuesto Válidos

1 - ITBMS 7%
10 - ITBMS 10%
15 - ITBMS 15%
0 - Exento

Ejemplo de Request

{
  "ProductID": "PROD001",
  "Description": "Laptop Dell Inspiron 15",
  "Price1": 1200.00,
  "Price2": 1100.00,
  "Price3": 1050.00,
  "TaxType": 1,
  "UnitMeasure": "EA",
  "GL_Sales_Acct": "4100",
  "Custom_field1": "Electrónicos"
}

Respuesta de Éxito

{
  "success": true,
  "message": "Producto creado exitosamente",
  "data": {
    "ProductID": "PROD001",
    "Description": "Laptop Dell Inspiron 15",
    "sage_id": "SAGE_PROD_001",
    "created_at": "2025-08-16 10:30:00",
    "sync_status": "completed"
  }
}

Ajuste de Inventario

Endpoint: POST /api/acicloud/inventory_adjust
Controller: ACIcloudController::inventoryAdjust
Autenticación: Bearer Token requerido

Campos de Request

Campo	Tipo	Requerido	Descripción	Ejemplo
`adjustment_number`	string	✅	Número de ajuste	`"ADJ-2025-001"`
`date`	string	✅	Fecha del ajuste (YYYY-MM-DD)	`"2025-08-16"`
`reason`	string	✅	Razón del ajuste	`"Physical count adjustment"`
`items`	array	✅	Lista de ajustes por producto	`[]`
`items[].product_code`	string	✅	Código del producto	`"PROD001"`
`items[].adjustment_quantity`	decimal	✅	Cantidad de ajuste (+/-)	`-2.00`

Ejemplo de Request

{
  "adjustment_number": "ADJ-2025-001",
  "date": "2025-08-16",
  "reason": "Ajuste por conteo físico",
  "items": [
    {
      "product_code": "PROD001",
      "current_quantity": 25.00,
      "physical_quantity": 23.00,
      "adjustment_quantity": -2.00,
      "reason": "Unidades dañadas encontradas"
    }
  ]
}

Códigos de Respuesta

Código	Descripción
200	Consulta exitosa
201	Producto/Ajuste creado exitosamente
400	Datos de entrada inválidos
401	No autorizado
404	Producto no encontrado
409	Código de producto duplicado
422	Error de validación
500	Error interno del servidor

Ejemplos cURL

Obtener Lista de Productos

curl -X GET "https://api.docucenter.com/api/acicloud/products?page=1&per_page=25" \
  -H "Authorization: Bearer YOUR_TOKEN"

Crear Producto

curl -X POST "https://api.docucenter.com/api/acicloud/product" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "ProductID": "PROD001",
    "Description": "Laptop Dell Inspiron 15",
    "Price1": 1200.00,
    "TaxType": 1,
    "UnitMeasure": "EA"
  }'

Ajustar Inventario

curl -X POST "https://api.docucenter.com/api/acicloud/inventory_adjust" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "adjustment_number": "ADJ-2025-001",
    "date": "2025-08-16",
    "reason": "Conteo físico",
    "items": [
      {
        "product_code": "PROD001",
        "adjustment_quantity": -2.00
      }
    ]
  }'

Notas Técnicas

Multi-tenant: Todos los endpoints respetan el contexto de organización
Sincronización: Productos y ajustes se sincronizan con Sage ACICloud
Validación: Validación estricta de códigos únicos y tipos
Inventario: Control de stock en tiempo real
Contabilidad: Integración con cuentas contables
Filtrado: Múltiples operadores disponibles (contains, equals, greater_than, etc.)

Gestión de Inventario

Stock Tracking: Seguimiento de stock actual, reservado y disponible
Niveles Mínimos/Máximos: Control de reorden automático
Ajustes: Sistema completo de ajustes de inventario
Costeo: Manejo de costos promedio y FIFO
Dimensiones: Información física para logística