☁️ API Sage ACICloud - DocuCenter

Esta es la documentación completa de la API para la integración con Sage 50cloud a través del servicio ACICloud, basada en la implementación real del controlador ACIcloudController.php.

Nota Importante

Esta API proporciona sincronización bidireccional completa con Sage 50cloud, incluyendo clientes, productos, inventarios, ventas, compras y contabilidad general.

🔐 Autenticación

La API utiliza autenticación Bearer Token (Laravel Sanctum):

Authorization: Bearer {token}
Content-Type: application/json
X-Organization-ID: {organization_id}

🌐 Base URL

POST /api/acicloud/{endpoint}

1. 📋 Módulo de Facturas

Obtener Facturas

POST /api/acicloud/invoices

Request Class: ACIcloudInvoicesExpRequest

Método del Controlador: invoices(ACIcloudInvoicesExpRequest $request, ACIcloudServiceContract $ACIcloudService)

Parámetros de Filtrado Soportados:

{
  "order_column": "Date|Total|SalesInvoiceNumber",
  "order_direction": "asc|desc",
  "limit": 50,
  "filter_match": "and|or",
  "f": [
    {
      "column": "TransactionID|SalesInvoiceNumber|CustomerID|CustomerName|Date|ShipDate|Total|TaxID",
      "operator": "eq|ne|gt|gte|lt|lte|like|not_like|between|not_between|in|not_in",
      "query_1": "valor_filtro",
      "query_2": "valor_filtro_2"
    }
  ]
}

📊 Campos Disponibles para Filtrado:

TransactionID - ID de transacción
SalesInvoiceNumber - Número de factura
CustomerID - ID del cliente
CustomerName - Nombre del cliente
Date - Fecha de la factura
ShipDate - Fecha de envío
Total - Total de la factura
TaxID - ID de impuesto

2. 👥 Módulo de Clientes (Customers)

Obtener Clientes

POST /api/acicloud/customers

Request Class: ACIcloudCustomersExpRequest

Método del Controlador: customers(ACIcloudCustomersExpRequest $request, ACIcloudServiceContract $ACIcloudService)

Crear Cliente

POST /api/acicloud/customers-imp

Request Class: CustomersImpRequest

Método del Controlador: customersImp(CustomersImpRequest $request, ACIcloudServiceContract $ACIcloudService)

Estructura del Request:

{
  "CustomerID": "CUST001",
  "Customer_Bill_Name": "Nombre del Cliente",
  "AddressLine1": "Dirección línea 1",
  "AddressLine2": "Dirección línea 2",
  "City": "Ciudad",
  "State": "PA",
  "Zip": "12345",
  "Country": "Panamá",
  "Telephone1": "+507 1234-5678",
  "Email": "cliente@email.com",
  "RUC": "1234567890123",
  "DV": "12",
  "Custom_field3": "Campo personalizado 3",
  "Custom_field4": "Campo personalizado 4",
  "Custom_field5": "Campo personalizado 5"
}

✅ Reglas de Validación para Clientes:

CustomerID: Requerido, string, único, máximo 20 caracteres
Customer_Bill_Name: Requerido, string, máximo 39 caracteres
AddressLine1, AddressLine2, City, Country: Opcionales, string
State: Opcional, string, máximo 2 caracteres
Zip: Opcional, string, máximo 12 caracteres
Telephone1: Opcional, string, máximo 20 caracteres
Email: Opcional, string, máximo 64 caracteres
RUC: Opcional, alfanumérico con guiones y guiones bajos, máximo 40 caracteres
DV: Opcional, alfanumérico con guiones y guiones bajos, máximo 40 caracteres
Custom_field3/4/5: Opcionales, alfanuméricos con guiones y guiones bajos, máximo 40 caracteres

Obtener Clientes Importados

POST /api/acicloud/get-customers-imp

Request Class: ACIcloudCustomersImpRequest

Método del Controlador: getCustomersImp(ACIcloudCustomersImpRequest $request, ACIcloudServiceContract $ACIcloudService)

3. 🏪 Módulo de Proveedores (Vendors)

Obtener Proveedores

POST /api/acicloud/vendors

Request Class: ACIcloudVendorsExpRequest

Crear Proveedor

POST /api/acicloud/vendors-imp

Request Class: VendorsImpRequest

Obtener Proveedores Importados

POST /api/acicloud/get-vendors-imp

Request Class: ACIcloudVendorsImpRequest

4. 📦 Módulo de Productos (Products)

Obtener Productos

POST /api/acicloud/products

Request Class: ACIcloudProductRequest

Crear Producto

POST /api/acicloud/products-imp

Request Class: ProductsImpRequest

Ajuste de Inventario

POST /api/acicloud/inventory-adjust

Request Class: InventoryadjustImpRequest

5. 💰 Módulo de Ventas (Sales)

Obtener Estado de Orden de Venta

GET /api/acicloud/sales-order-status/{salesOrderNumber}

Método del Controlador: salesOrderStatus(string $salesOrderNumber, ACIcloudServiceContract $ACIcloudService)

Crear Orden de Venta

POST /api/acicloud/sales-order

Request Class: SalesOrderRequest

Estructura del Request:

{
  "SalesOrderNumber": "SO-2025-001",
  "CustomerID": "CUST001",
  "CustomerPO": "PO-REF-123",
  "CustomerName": "Cliente Ejemplo",
  "Subtotal": 100.00,
  "TaxID": "TAX001",
  "OrderTax": 7.00,
  "NetDue": 107.00,
  "ARAccount": "1200",
  "ShipToName": "Cliente Ejemplo",
  "ShipToAddressLine1": "Calle Principal 123",
  "ShipToAddressLine2": "Apto 2B",
  "ShipToCity": "Ciudad de Panamá",
  "ShipToState": "PA",
  "ShipToZip": "0000",
  "ShipToCountry": "Panamá",
  "SalesRepID": "REP001",
  "Items": [
    {
      "SalesOrderNumber": "SO-2025-001",
      "Taxable": 1,
      "ItemOrd": "1",
      "ItemId": "PROD001",
      "Description": "Producto Ejemplo",
      "Quantity": 2,
      "UnitPrice": 50.00,
      "NetLine": 100.00,
      "JobId": "JOB001",
      "JobPhaseID": "PHASE1",
      "JobCostCodeID": "CODE1"
    }
  ]
}

✅ Reglas de Validación para Orden de Venta:

SalesOrderNumber: Requerido, string, único, máximo 20 caracteres
CustomerID: Requerido, string, máximo 50 caracteres
CustomerName: Requerido, string, máximo 39 caracteres
Subtotal, OrderTax, NetDue: Requeridos, decimal con 4 decimales
Items.*.Taxable: Requerido, entero, valores permitidos: 1 o 2
Items.*.ItemId: Requerido, string, máximo 20 caracteres
Items.*.Description: Requerido, string, máximo 160 caracteres
Items.*.Quantity: Requerido, decimal con 5 decimales
Items.*.UnitPrice, Items.*.NetLine: Requeridos, decimal con 4 decimales

6. 💼 Módulo de Trabajos/Proyectos (Jobs)

Obtener Trabajos

POST /api/acicloud/jobs

Request Class: ACIcloudJobsExpRequest

Crear Trabajo

POST /api/acicloud/jobs-imp

Request Class: JobsImpRequest

7. 📊 Módulo de Contabilidad (Accounting)

Crear Entrada de Diario General

POST /api/acicloud/general-journal-entry

Request Class: GJEImpRequest

Obtener Entradas de Diario General

POST /api/acicloud/general-journal-entries

Request Class: GeneralJournalEntriesImpRequest

8. 💳 Módulo de Pagos (Payments)

Crear Recibo de Cliente

POST /api/acicloud/customer-receipt-imp

Request Class: CustomerReceiptImpRequest

Crear Nota de Crédito de Cliente

POST /api/acicloud/customer-credit-memo-imp

Request Class: CustomerCreditMemoImpRequest

🔍 Características Avanzadas de Filtrado

Sistema de Filtros con DataViewer Trait

Todos los endpoints que utilizan Request classes que extienden el trait DataViewer soportan filtrado avanzado:

📋 Parámetros Base de Filtrado:

{
  "order_column": "nombre_columna",
  "order_direction": "asc|desc",
  "limit": 50,
  "filter_match": "and|or",
  "f": [
    {
      "column": "nombre_columna",
      "operator": "operador",
      "query_1": "valor",
      "query_2": "valor_opcional"
    }
  ]
}

⚙️ Operadores Disponibles:

eq: Igual a
ne: No igual a
gt: Mayor que
gte: Mayor o igual que
lt: Menor que
lte: Menor o igual que
like: Contiene (búsqueda parcial)
not_like: No contiene
between: Entre dos valores (requiere query_1 y query_2)
not_between: No entre dos valores (requiere query_1 y query_2)
in: En lista de valores
not_in: No en lista de valores

📝 Ejemplo de Filtrado Complejo:

{
  "order_column": "Date",
  "order_direction": "desc",
  "limit": 100,
  "filter_match": "and",
  "f": [
    {
      "column": "Date",
      "operator": "between",
      "query_1": "2025-01-01",
      "query_2": "2025-12-31"
    },
    {
      "column": "Total",
      "operator": "gte",
      "query_1": "100.00"
    },
    {
      "column": "CustomerName",
      "operator": "like",
      "query_1": "Cliente"
    }
  ]
}

📊 Códigos de Respuesta HTTP

200 OK: Operación exitosa
201 Created: Recurso creado exitosamente
400 Bad Request: Error en la validación de parámetros
401 Unauthorized: Token de autenticación inválido
403 Forbidden: Sin permisos para acceder al recurso
404 Not Found: Recurso no encontrado
422 Unprocessable Entity: Error de validación de datos
500 Internal Server Error: Error interno del servidor

❌ Estructura de Respuesta de Error

{
  "success": false,
  "message": "Descripción del error",
  "errors": {
    "field_name": [
      "Mensaje de error específico del campo"
    ]
  }
}

⚡ Límites de Rate Limiting

100 requests por minuto por organización
5,000 requests por día por organización

📝 Notas Técnicas

Inyección de Dependencias: Todos los métodos del controlador utilizan inyección de dependencias para el servicio ACIcloudServiceContract
Validación Automática: Las Request classes manejan automáticamente la validación antes de llegar al controlador
Trait DataViewer: Proporciona capacidades avanzadas de filtrado y paginación
Delegación al Servicio: El controlador delega toda la lógica de negocio al servicio ACIcloud
Documentación LRD: Los comentarios @lrd:start/@lrd:end son para generación automática de documentación

🔄 Sincronización

Los datos se sincronizan en tiempo real
Se mantiene un log de auditoría de todas las operaciones
Los conflictos se resuelven con el principio "último en escribir gana"

📞 Soporte y Contacto

Para más información sobre la integración con Sage ACICloud:

Email: desarrollo@apconpanama.me
GitHub: Reportar Issues
Documentación: APCON

Desarrollado por APCON
Integración empresarial con Sage 50cloud