API Sage ACICloud - Módulo Clientes

Crear Cliente

Endpoint: POST /api/acicloud/customer
Request Class: CustomersImpRequest
Autenticación: Bearer Token requerido

Parámetros de Request

Campo	Tipo	Requerido	Descripción	Validación	Ejemplo
CustomerID	string	✅	ID único del cliente	Máx. 20 caracteres, único	"CUST001"
Customer_Bill_Name	string	✅	Nombre de facturación	Máx. 39 caracteres	"Empresa Ejemplo S.A."
AddressLine1	string	❌	Dirección línea 1	-	"Calle 50, Edificio Torre"
AddressLine2	string	❌	Dirección línea 2	-	"Piso 15, Oficina 1501"
City	string	❌	Ciudad	-	"Ciudad de Panamá"
State	string	❌	Estado/Provincia	Máx. 2 caracteres	"PA"
Zip	string	❌	Código postal	Máx. 12 caracteres	"0000"
Country	string	❌	País	-	"Panamá"
Telephone1	string	❌	Teléfono principal	Máx. 20 caracteres	"+507 1234-5678"
Email	string	❌	Correo electrónico	Máx. 64 caracteres	"cliente@empresa.com"
RUC	string	❌	RUC del cliente	Alfanumérico, máx. 40	"1234567890123"
DV	string	❌	Dígito verificador	Alfanumérico, máx. 40	"12"
Custom_field3	string	❌	Campo personalizado 3	Alfanumérico, máx. 40	"Sector Financiero"
Custom_field4	string	❌	Campo personalizado 4	Alfanumérico, máx. 40	"VIP"
Custom_field5	string	❌	Campo personalizado 5	Alfanumérico, máx. 40	"Corporativo"

Reglas de Validación Detalladas

CustomerID

• Requerido: Sí
• Tipo: String
• Máximo: 20 caracteres
• Único: Debe ser único en la base de datos
• Ejemplo válido: "CUST001", "EMP-2025-001"

Customer_Bill_Name

• Requerido: Sí
• Tipo: String
• Máximo: 39 caracteres
• Ejemplo válido: "Empresa Ejemplo S.A."

RUC y DV

• Patrón: /^[a-zA-Z0-9_-]*$/
• Descripción: Solo letras, números, guiones y guiones bajos
• Ejemplo válido RUC: "1234567890123"
• Ejemplo válido DV: "12"

Ejemplo de Request Completo

{
  "CustomerID": "CUST001",
  "Customer_Bill_Name": "Empresa Ejemplo S.A.",
  "AddressLine1": "Calle 50, Edificio Torre Global",
  "AddressLine2": "Piso 15, Oficina 1501",
  "City": "Ciudad de Panamá",
  "State": "PA",
  "Zip": "0000",
  "Country": "Panamá",
  "Telephone1": "+507 1234-5678",
  "Email": "contacto@empresaejemplo.com",
  "RUC": "1234567890123",
  "DV": "12",
  "Custom_field3": "Sector_Financiero",
  "Custom_field4": "Cliente_VIP",
  "Custom_field5": "Corporativo"
}

Ejemplo de Request Mínimo

{
  "CustomerID": "CUST002",
  "Customer_Bill_Name": "Cliente Básico"
}

Obtener Clientes

Endpoint: GET /api/acicloud/customers
Request Class: ACIcloudCustomersExpRequest
Autenticación: Bearer Token requerido

Parámetros de Consulta

Campo	Tipo	Requerido	Descripción
order_column	string	No	Columna para ordenamiento
order_direction	string	No	asc o desc
limit	integer	No	Registros por página
f	array	No	Filtros avanzados

Ejemplo de Request

{
  "limit": 50,
  "order_column": "Customer_Bill_Name",
  "order_direction": "asc",
  "f": [
    {
      "column": "Customer_Bill_Name",
      "operator": "like",
      "query_1": "Empresa"
    }
  ]
}

Respuesta

{
  "success": true,
  "data": {
    "customers": [
      {
        "CustomerID": "CUST001",
        "Customer_Bill_Name": "Empresa Ejemplo S.A.",
        "Email": "contacto@empresaejemplo.com",
        "Telephone1": "+507 1234-5678",
        "City": "Ciudad de Panamá",
        "RUC": "1234567890123"
      }
    ],
    "pagination": {
      "current_page": 1,
      "per_page": 50,
      "total": 150
    }
  }
}

Obtener Clientes Importados

Endpoint: GET /api/acicloud/customers_imp
Request Class: ACIcloudCustomersImpRequest
Autenticación: Bearer Token requerido

Obtiene la lista de clientes que han sido importados desde DocuCenter a Sage ACICloud.

Ejemplo de Respuesta

{
  "success": true,
  "data": {
    "customers_imported": [
      {
        "CustomerID": "CUST001",
        "Customer_Bill_Name": "Empresa Ejemplo S.A.",
        "import_date": "2025-08-12T10:30:00Z",
        "status": "imported",
        "sage_sync_status": "synced"
      }
    ]
  }
}

Códigos de Respuesta

Código	Descripción
200	Operación exitosa
201	Cliente creado exitosamente
400	Datos de request inválidos
401	No autorizado
422	Error de validación
500	Error interno del servidor

Ejemplos cURL

Crear Cliente

curl -X POST "https://api.docucenter.com/api/acicloud/customer" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "CustomerID": "CUST001",
    "Customer_Bill_Name": "Empresa Ejemplo S.A.",
    "Email": "contacto@empresa.com",
    "RUC": "1234567890123"
  }'

Obtener Clientes

curl -X GET "https://api.docucenter.com/api/acicloud/customers" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "limit": 10,
    "order_column": "Customer_Bill_Name"
  }'

Notas Técnicas

• El CustomerID debe ser único en toda la organización
• Los campos personalizados (Custom_field3-5) son útiles para categorización
• La validación del RUC sigue el patrón panameño estándar
• Compatible con el sistema multi-tenant de DocuCenter