REST API esperada para clientes

Este documento describe la API REST que consume la clase cCliente mediante cClienteApiGateway. El objetivo es reemplazar el acceso directo a la base de datos para operaciones CRUD de clientes, manteniendo compatible la interfaz VB6 existente.

Configuracion del cliente VB6

La aplicacion lee la configuracion desde GetSetting(App.EXEName, "REST", ...) o desde variables de entorno.

Setting	Variable de entorno	Descripcion
ClientesHabilitada	MG_API_CLIENTES_HABILITADA	Habilita el uso de la API. Valores aceptados: 1, SI, TRUE, YES.
BaseUrl	MG_API_BASE_URL	URL base de la API, por ejemplo https://api.midominio.com.
Token	MG_API_TOKEN	Token bearer opcional.
TimeoutMs	MG_API_TIMEOUT_MS	Timeout en milisegundos. Default: 30000.

Tambien puede configurarse desde VB6 llamando:

Call ConfigurarApiClientes("https://api.midominio.com", "token-opcional", True, 30000)

Convenciones generales

• El cliente envia Accept: application/json.
• Para POST y PUT, el cliente envia Content-Type: application/json.
• Si hay token configurado, el cliente envia Authorization: Bearer {token}.
• Las fechas deben enviarse como yyyy-mm-dd o null.
• Los importes y coordenadas deben enviarse como numeros JSON.
• Para errores, la API debe devolver JSON con al menos uno de estos campos: message, mensaje, error o detail.

Ejemplo de error:

{
  "message": "No se puede eliminar el cliente porque tiene pedidos asociados."
}

Formato de respuesta aceptado

Para objetos individuales, el cliente acepta cualquiera de estas formas:

{
  "idCliente": 123,
  "nroCliente": 123,
  "razonSocial": "CLIENTE S.A."
}

{
  "data": {
    "idCliente": 123,
    "nroCliente": 123,
    "razonSocial": "CLIENTE S.A."
  }
}

Tambien acepta el objeto dentro de cliente o item.

Para colecciones, el cliente acepta un array directo:

[
  {
    "idCliente": 123,
    "nroCliente": 123,
    "razonSocial": "CLIENTE S.A."
  }
]

O envuelto en alguno de estos campos: items, data, clientes, results.

{
  "items": [
    {
      "idCliente": 123,
      "nroCliente": 123,
      "razonSocial": "CLIENTE S.A."
    }
  ]
}

Endpoints

Obtener defaults de cliente

Usado durante Class_Initialize de cCliente.

GET /clientes/defaults?idSucursal={idSucursal}

Respuesta 200 OK:

{
  "idCamionPorDefecto": 1,
  "idListaPorDefecto": 1,
  "idRCClientePorDefecto": "1021",
  "idZonaPorDefecto": 1,
  "idCpLocalidadPorDefecto": "3080",
  "idSubCpLocalidadPorDefecto": "0",
  "cliIdVendedorPorDefecto": 0,
  "cliIdCobradorPorDefecto": 0,
  "idCondicionVenta": 1,
  "nombreCondicion": "CONTADO"
}

El cliente VB6 tambien acepta estos alias en la respuesta: idFletero, idLista, idReferenciaContable, idZona, cpLocalidad, cpSubCp, idVendedor, idCobrador, idCondicion.

Obtener cliente por ID

Usado por SeleccionarXId.

GET /clientes/{idCliente}

Respuesta 200 OK: objeto ClienteDetalle.

Respuesta 404 Not Found: cliente inexistente.

Listar clientes

Usado por Listar, ListarParametrizado, ListarHojaRutaP y el listado filtrado de frmClientes.

GET /clientes

Query params opcionales:

Parametro	Tipo	Uso
nroClienteDesde	number	Filtro por numero de cliente desde.
nroClienteHasta	number	Filtro por numero de cliente hasta.
razonSocial	string	Filtro por razon social. El cliente actual envia el texto ya URL-encoded.
razonSocialModo	string	prefijo o contiene, segun el comportamiento historico por base.
apellido	string	Filtro por apellido.
apellidoModo	string	prefijo o contiene, segun el comportamiento historico por base.
domicilio	string	Filtro por domicilio, equivalente a busqueda contiene.
cpLocalidad	string	Codigo postal/localidad.
cpSubCp	string	Subcodigo postal/localidad.
idDepartamento	number	Filtro por departamento.
idProvincia	number	Filtro por provincia.
idVendedor	number	Filtro por vendedor.
relacionVendedor	string	VPD para vendedor por defecto, VZ para vendedor por zona/ruta.
modeloPreventaDespacho	number	Modelo usado para interpretar VZ como zona o ruta.
idZona	number	Filtro de zona para hoja de ruta/preventa.
idFletero	number	Filtro por camion/fletero.
idLista	number	Filtro por lista de precios.
idOrdenCargaAlta	number	Filtro por orden de carga de alta.
idTipoCliente	number	Filtro por tipo de cliente.
estado	number	Estado del cliente.
iva	number	Categoria de IVA.
cuit	string	Filtro por CUIT, equivalente a busqueda por prefijo.
tipoDni	number	Tipo de DNI.
dni	number	Numero de DNI.
fechaAltaDesde	date	Fecha de alta desde, formato yyyy-mm-dd.
fechaAltaHasta	date	Fecha de alta hasta, formato yyyy-mm-dd.
fechaEstadoDesde	date	Fecha de estado desde, formato yyyy-mm-dd.
fechaEstadoHasta	date	Fecha de estado hasta, formato yyyy-mm-dd.
clientesSinRuta	boolean/number	1 para clientes que no tienen ruta asociada.
filtrosAtributos	string	Texto descriptivo de filtros de atributos especiales enviados por el control VB6. Si se soportan atributos en API, conviene reemplazarlo por un contrato estructurado compatible.
offset	number	Primer registro de la pagina.
limit	number	Cantidad de registros de la pagina.
order	string	Campo de orden, por ejemplo nrocliente o razonsocial.

Respuesta 200 OK: coleccion de clientes. Para listados paginados, se recomienda devolver tambien el total en total, totalRegistros, totalRows o count.

Campos minimos para listados generales:

{
  "idCliente": 123,
  "nroCliente": 123,
  "razonSocial": "CLIENTE S.A.",
  "domicilio": "AV. SIEMPREVIVA 742",
  "nroZona": 10,
  "zona": "CENTRO",
  "cpLocalidadCompuesta": "3080-0",
  "localidad": "SAN FRANCISCO"
}

Campos minimos para hoja de ruta/preventa:

{
  "idCliente": 123,
  "nroCliente": 123,
  "razonSocial": "CLIENTE S.A.",
  "ordenPreventa": 5
}

Crear cliente

Usado por Ingresar.

POST /clientes
Content-Type: application/json

Body: objeto ClienteWrite.

Respuesta recomendada:

• 201 Created
• Body: ClienteDetalle creado.

Si el numero de cliente ya existe, devolver 409 Conflict.

Actualizar cliente

Usado por Modificar.

PUT /clientes/{idCliente}
Content-Type: application/json

Body: objeto ClienteWrite.

Respuesta recomendada:

• 200 OK
• Body: ClienteDetalle actualizado.

Si el cliente no existe, devolver 404 Not Found. Si el numero de cliente entra en conflicto con otro cliente, devolver 409 Conflict.

Eliminar cliente

Usado por Eliminar.

DELETE /clientes/{idCliente}

Respuesta recomendada:

• 204 No Content si elimina correctamente.
• 404 Not Found si no existe.
• 409 Conflict si no se puede eliminar por dependencias.

Para restricciones de integridad, la API debe resolver las validaciones que antes hacia cCliente contra Pedidos, Facturas, fleteros, vendedores, Parametros, impuestos, horarios de visita y atributos especiales.

Ejemplo 409 Conflict:

{
  "message": "Cliente cargado en pedido 12345."
}

Modelo ClienteWrite

Estos son los campos que el cliente VB6 envia actualmente en POST /clientes y PUT /clientes/{idCliente}.

{
  "idCliente": 123,
  "nroCliente": 123,
  "razonSocial": "CLIENTE S.A.",
  "apellido": "",
  "nombre": "",
  "nemotecnico": "CLI123",
  "tipoDni": 3,
  "dni": 0,
  "domicilio": "AV. SIEMPREVIVA 742",
  "domicilioCalle": "AV. SIEMPREVIVA",
  "domicilioNumero": "742",
  "tipoTelefono1": "T",
  "caracteristica1": "03564",
  "telefono1": "123456",
  "tipoTelefono2": "",
  "caracteristica2": "",
  "telefono2": "",
  "tipoTelefono3": "",
  "caracteristica3": "",
  "telefono3": "",
  "tipoTelefono4": "",
  "caracteristica4": "",
  "telefono4": "",
  "email": "cliente@example.com",
  "cpLocalidad": "3080",
  "cpSubCp": "0",
  "cpCuadra": "",
  "iva": 1,
  "cuit": "30123456789",
  "vencimientoCuit": null,
  "ganancias": 0,
  "ingresosBrutos": 0,
  "inscripcionIB": "",
  "estado": 1,
  "fechaEstado": "2026-05-24",
  "fechaAlta": "2026-05-24",
  "fechaEdicion": null,
  "idBaja": 0,
  "idZona": 1,
  "idFletero": 0,
  "idLista": 1,
  "idCompPref": 0,
  "idTipoCliente": 0,
  "limiteCredito": 0,
  "limiteCreditoDias": 0,
  "fleteAsegurado": 0,
  "ordenHojaRuta": 0,
  "ordenPreventa": 0,
  "idProvincia": 0,
  "idReferenciaContable": "1021",
  "idCondicion": 1,
  "idVendedor": 0,
  "idCobrador": 0,
  "contacto": "",
  "observaciones": "",
  "latitud": 0,
  "longitud": 0
}

Modelo ClienteDetalle

Para GET /clientes/{idCliente}, POST /clientes y PUT /clientes/{idCliente}, la respuesta debe incluir como minimo los campos de ClienteWrite. Para evitar accesos adicionales desde VB6, conviene incluir tambien las descripciones ya resueltas:

{
  "idCliente": 123,
  "nroCliente": 123,
  "razonSocial": "CLIENTE S.A.",
  "localidad": "SAN FRANCISCO",
  "provincia": "CORDOBA",
  "zona": "CENTRO",
  "lista": "LISTA GENERAL",
  "compPref": "FACTURA",
  "fletero": "REPARTO 1",
  "baja": "",
  "tipoCliente": "GENERAL",
  "referenciaContable": "VENTAS",
  "condicionNombre": "CONTADO"
}

El cliente VB6 acepta nombres camelCase y algunos nombres historicos en minuscula, por ejemplo razonsocial, idcliente, nrocliente, idcondicion.

Codigos HTTP esperados

Codigo	Uso esperado
200 OK	Lectura, listado o actualizacion exitosa con body.
201 Created	Alta exitosa con body del cliente creado.
204 No Content	Baja exitosa.
400 Bad Request	Parametros invalidos o body mal formado.
401 Unauthorized	Token ausente o invalido.
403 Forbidden	Usuario sin permiso.
404 Not Found	Cliente inexistente.
409 Conflict	Conflicto de integridad o numero duplicado.
422 Unprocessable Entity	Validacion de negocio.
500 Internal Server Error	Error inesperado.

Reglas de negocio que deberian vivir en la API

• Validar numero de cliente duplicado.
• Asignar o validar proximo numero si la politica queda centralizada en backend.
• Resolver defaults por sucursal.
• Resolver relaciones descriptivas: zona, lista, comprobante preferido, fletero, motivo de baja, tipo de cliente, localidad, provincia, referencia contable y condicion de venta.
• Validar baja contra pedidos, facturas, fleteros, vendedores, parametros, impuestos asociados, horarios de visita y atributos especiales.
• Registrar novedades de alta, modificacion y baja si esas novedades forman parte de la integridad funcional.