aranda-skills 0.1.0

Cliente Python para consumir las skills de la API de Aranda ASMS

aranda-skills

Cliente Python para consumir las skills de la API de Aranda ASMS como simples funciones. El desarrollador no maneja URLs, headers ni tokens en cada llamada: configura una vez y llama funciones.

Cada skill del directorio skills/ está expuesta como una función del paquete aranda_skills.

Instalación

pip install aranda-skills

Desde el repositorio (modo editable, para desarrollo):

pip install -e .

Configuración

La conexión (URL base, token, SSL, timeout) se resuelve en este orden de prioridad:

1. Parámetros pasados explícitamente.
2. Variables de entorno con prefijo ARANDA_.
3. Archivo .env en el directorio de trabajo.
4. Valores por defecto.

Opción A — variables de entorno / .env

ARANDA_BASE_URL=https://proyectos.arandasoft.com/asmsapi/api/v9
ARANDA_TOKEN=Bearer eyJ0...
# Opcionales:
ARANDA_VERIFY_SSL=false
ARANDA_TIMEOUT=30

No hace falta nada más; las funciones funcionan directamente:

import aranda_skills as aranda

proyectos = aranda.get_projects()

Opción B — en código

import aranda_skills as aranda

aranda.configure(
    base_url="https://proyectos.arandasoft.com/asmsapi/api/v9",
    token="Bearer eyJ0...",   # el prefijo "Bearer " es opcional
)

proyectos = aranda.get_projects()

Uso

import aranda_skills as aranda

aranda.configure(token="Bearer eyJ0...")

# Catálogos
aranda.get_item_types()
aranda.get_urgency()
aranda.get_impact()
aranda.get_registry_types()

# Navegación de configuración
proyectos  = aranda.get_projects()
servicios  = aranda.get_services(project_id=1, item_type=1)
categorias = aranda.get_categories_by_service(item_type=1, service_id=4)
modelo     = aranda.get_model(item_type=1, category_id=17, service_id=4)
estados    = aranda.get_states(model_id=2, item_type=1)

# Personas
companias = aranda.get_companies(project_id=1, item_type=1)
clientes  = aranda.get_customers(project_id=1, item_type=1, company_id=3, service_id=4)
grupos    = aranda.get_groups_by_state(service_id=4, state_id=110)
resp      = aranda.get_responsible(group_id=10, project_id=1)

# Crear un caso
caso = aranda.create_item(
    author_id=682,
    category_id=17,
    company_id=3,
    customer_id=494,
    description="No hay conexión a internet en piso 3",
    item_type=1,          # 1=Incidente, 2=Problema, 3=Cambio, 4=Requerimiento
    model_id=2,
    project_id=1,
    service_id=4,
    state_id=2,
    subject="Sin internet",
    urgency_id=5,         # opcional
)

Múltiples instancias / multi-tenant

Si necesitas hablar con varias instancias de Aranda a la vez, crea clientes independientes y pásalos con client=:

from aranda_skills import ArandaClient, get_projects

cli_a = ArandaClient(base_url="https://instancia-a/...", token="token-a")
cli_b = ArandaClient(base_url="https://instancia-b/...", token="token-b")

get_projects(client=cli_a)
get_projects(client=cli_b)

# Como context manager (cierra la conexión al salir):
with ArandaClient(token="...") as cli:
    get_projects(client=cli)

Manejo de errores

from aranda_skills import ArandaAPIError, ArandaConfigError
import aranda_skills as aranda

try:
    aranda.get_projects()
except ArandaConfigError:
    ...  # falta el token o la configuración
except ArandaAPIError as e:
    print(e.status_code, e.body)  # la API respondió con error HTTP

Skills disponibles

Función	Descripción
get_item_types()	Tipos de caso disponibles
get_registry_types()	Catálogo de tipos de registro
get_urgency()	Catálogo de urgencia
get_impact()	Catálogo de impacto
get_projects(console_type=None)	Proyectos del usuario
get_services(project_id, item_type, ...)	Servicios de un proyecto
get_categories_by_service(item_type, service_id)	Categorías de un servicio
get_model(item_type, category_id, service_id)	Modelo de flujo de trabajo
get_states(model_id, item_type, state_id=None, item_id=None)	Estados / transiciones
get_companies(project_id, item_type)	Compañías de un proyecto
get_customers(project_id, item_type, company_id, service_id, ...)	Clientes finales
get_groups_by_state(service_id, state_id)	Grupos de especialistas
get_responsible(group_id, project_id)	Especialistas de un grupo
get_reasons_for_state(state_id)	Razones para un estado
get_additional_fields(category_id, item_type, model_id, state_id, ...)	Campos personalizados
search_cis(project_id, item_type, service_id, ...)	Elementos de Configuración (CIs)
create_item(...)	Crea un caso

Todas aceptan el argumento opcional client=ArandaClient(...).

Desarrollo

pip install -e ".[dev]"
pytest -q