Sucursales

Registro y gestión de las sucursales de la empresa. Los ids de departamento, distrito y ciudad provienen de los catálogos de Consultas - Sucursales.

Listar sucursales

Obtener el listado completo de sucursales registradas

GET ip:puerto/empresa/sucursales

Comportamiento

Recorre cada sucursal registrada y normaliza el campo estado:

• Si la sucursal ya tiene estado definido, se conserva su valor actual.
• Si no tiene estado (registros antiguos), se le asigna estado: "A" (activa) por defecto, sin modificar el registro en disco.

Ejemplo de la respuesta

{
  "status": true,
  "data": [
    {
      "codigo": "001",
      "direccion": "AV MADAME ELISA LYNCH ESQ BERNARDINO CABALLERO",
      "numeroCasa": 1,
      "complementoDireccion1": "",
      "complementoDireccion2": "",
      "departamento": 12,
      "departamentoDescripcion": "CENTRAL",
      "distrito": 154,
      "distritoDescripcion": "FERNANDO DE LA MORA",
      "ciudad": 5044,
      "ciudadDescripcion": "FERNANDO DE LA MORA",
      "telefono": "021510036",
      "email": "juan.velazquez@inpaco.com.py",
      "denominacion": "CASA CENTRAL",
      "estado": "A"
    }
  ]
}

Referencia API: listarSucursales

Registrar sucursal

Registrar una nueva sucursal

POST ip:puerto/empresa/sucursales

Body (JSON)

Campo	Tipo	Obligatorio	Detalle
codigo	string numérica	Sí	1 a 3 dígitos numéricos. Ej: "005"
denominacion	string	Sí	Texto libre, 1 a 30 caracteres
departamento	number (id)	Sí	Id numérico de departamento (ver Consultas - Sucursales)
distrito	number (id)	Sí	Id numérico de distrito
ciudad	number (id)	Sí	Id numérico de ciudad
direccion	string	Sí	Texto libre, 1 a 150 caracteres
telefono	string numérica	Sí	Solo dígitos, 6 a 15 caracteres
email	string	Sí	Formato de email válido, 3 a 80 caracteres
numeroCasa	number	No	Hasta 6 dígitos. Si se omite, se guarda como 0
complementoDireccion1	string	No	Texto libre, máximo 150 caracteres
complementoDireccion2	string	No	Texto libre, máximo 150 caracteres

Validaciones aplicadas

• Obligatoriedad de codigo, denominacion, departamento, distrito, ciudad, direccion, telefono, email.
• codigo: debe cumplir /^\d{1,3}$/; no puede repetirse (rechaza si ya existe una sucursal con el mismo código).
• denominacion: 1 a 30 caracteres (tras trim()).
• departamento / distrito / ciudad: deben ser ids numéricos existentes en los catálogos correspondientes; si el id no existe, se rechaza con No se encontró el <campo> con el id <valor>.
• direccion: 1 a 150 caracteres (tras trim()).
• numeroCasa: numérico, mayor o igual a 0, hasta 6 dígitos. Si no viene o viene vacío, se guarda 0.
• complementoDireccion1 / complementoDireccion2: opcionales, máximo 150 caracteres; solo se incluyen en el registro final si tienen contenido no vacío tras trim().
• telefono: debe cumplir /^\d{6,15}$/ (solo dígitos, 6 a 15 caracteres).
• email: debe cumplir /^[^\s@]+@[^\s@]+\.[^\s@]+$/, entre 3 y 80 caracteres; se guarda en minúsculas.

Comportamiento adicional al guardar

• departamentoDescripcion, distritoDescripcion y ciudadDescripcion se resuelven automáticamente a partir del id enviado (no se envían en el body).
• El nuevo registro se guarda siempre con estado: "A".

Ejemplo de request - Datos completos

{
  "codigo": "005",
  "denominacion": "SUCURSAL SAN LORENZO",
  "departamento": 12,
  "distrito": 164,
  "ciudad": 5044,
  "direccion": "AV MARISCAL LOPEZ Y RUTA 2",
  "numeroCasa": 1234,
  "complementoDireccion1": "EDIFICIO TORRE NORTE",
  "complementoDireccion2": "PISO 3",
  "telefono": "021777888",
  "email": "sucursal.sanlorenzo@inpaco.com.py"
}

Ejemplo de request - Solo campos obligatorios

{
  "codigo": "006",
  "denominacion": "SUCURSAL LUQUE",
  "departamento": 12,
  "distrito": 159,
  "ciudad": 5044,
  "direccion": "RUTA AEROPUERTO KM 5",
  "telefono": "021999000",
  "email": "sucursal.luque@inpaco.com.py"
}

En este caso, numeroCasa se guarda como 0, y complementoDireccion1 / complementoDireccion2 no se incluyen en el registro final.

Ejemplos de la respuesta

{
  "status": true,
  "message": "Sucursal registrada correctamente",
  "data": {
    "codigo": "006",
    "direccion": "RUTA AEROPUERTO KM 5",
    "numeroCasa": 0,
    "departamento": 12,
    "departamentoDescripcion": "CENTRAL",
    "distrito": 159,
    "distritoDescripcion": "LUQUE",
    "ciudad": 5044,
    "ciudadDescripcion": "FERNANDO DE LA MORA",
    "telefono": "021999000",
    "email": "sucursal.luque@inpaco.com.py",
    "denominacion": "SUCURSAL LUQUE",
    "estado": "A"
  }
}

{
  "status": false,
  "requestId": "<uuid>",
  "message": "<detalle del error, ej: 'Ya existe una sucursal registrada con el código 006'>",
  "data": []
}

Referencia API: crearSucursal

Actualizar sucursal

Actualizar parcialmente los datos de una sucursal ya registrada

PATCH ip:puerto/empresa/sucursales/{codigo}

codigo: código de la sucursal a actualizar. Se normaliza a 3 dígitos para la búsqueda (ej: 1, "1" y "001" identifican la misma sucursal). No es editable: si se envía en el body, se ignora.

Body (JSON) - Todos los campos son opcionales, se actualiza solo lo enviado

Campo	Tipo	Detalle
estado	string	Solo se permite "A" (activa) o "I" (inactiva)
denominacion	string	Texto libre, 1 a 30 caracteres
departamento	number (id)	Id numérico de departamento; se resuelve departamentoDescripcion automáticamente
distrito	number (id)	Id numérico de distrito; se resuelve distritoDescripcion automáticamente
ciudad	number (id)	Id numérico de ciudad; se resuelve ciudadDescripcion automáticamente
direccion	string	Texto libre, 1 a 150 caracteres
numeroCasa	number	Hasta 6 dígitos. Si se envía vacío/null, se guarda como 0
complementoDireccion1	string	Máximo 150 caracteres; se quita del registro si se envía vacío
complementoDireccion2	string	Máximo 150 caracteres; se quita del registro si se envía vacío
telefono	string numérica	Solo dígitos, 6 a 15 caracteres
email	string	Formato de email válido, 3 a 80 caracteres

Validaciones aplicadas

• Si no se recibe ningún campo de la lista permitida, se rechaza con No se recibió ningún campo válido para actualizar.
• Cada campo enviado se valida con las mismas reglas de formato/longitud que Registrar sucursal, pero solo se aplican a los campos presentes en el body.
• estado: debe ser exactamente "A" o "I", cualquier otro valor se rechaza.
• departamento / distrito / ciudad: igual que en el registro, deben ser ids existentes en los catálogos; si no existen, se rechaza con No se encontró el <campo> con el id <valor>.
• Si el codigo de la URL no corresponde a ninguna sucursal registrada, se rechaza con No se encontró una sucursal registrada con el código <código>.

Ejemplo de request - Inactivar una sucursal

PATCH ip:puerto/empresa/sucursales/5

{
  "estado": "I"
}

Ejemplo de request - Actualizar dirección y ubicación

PATCH ip:puerto/empresa/sucursales/5

{
  "direccion": "NUEVA DIRECCION 456",
  "numeroCasa": 10,
  "departamento": 12,
  "distrito": 159,
  "ciudad": 5044
}

Ejemplos de la respuesta

{
  "status": true,
  "message": "Sucursal actualizada correctamente",
  "data": {
    "codigo": "005",
    "direccion": "NUEVA DIRECCION 456",
    "numeroCasa": 10,
    "departamento": 12,
    "departamentoDescripcion": "CENTRAL",
    "distrito": 159,
    "distritoDescripcion": "LUQUE",
    "ciudad": 5044,
    "ciudadDescripcion": "FERNANDO DE LA MORA",
    "telefono": "021777888",
    "email": "sucursal.sanlorenzo@inpaco.com.py",
    "denominacion": "SUCURSAL SAN LORENZO",
    "estado": "A"
  }
}

{
  "status": false,
  "requestId": "<uuid>",
  "message": "<detalle del error, ej: 'No se encontró una sucursal registrada con el código 999'>",
  "data": []
}

Referencia API: actualizarSucursal