activesoft-cli 0.6.0

Python SDK and CLI tool for Activesoft Siga automation

Activesoft Siga CLI

A Python SDK and CLI tool for automating interactions with the Activesoft Siga API. This tool simplifies retrieval of student data (including enrollment and presence permissions), responsible party data, class lists, and sending messages.

Installation

Install via pip:

pip install activesoft-cli

Or from source:

git clone https://github.com/tsuriu/activesoft-cli.git
cd activesoft-cli
pip install .

CLI Usage

The package includes a command-line interface activesoft-cli.

Configuration

You can use either HTML Scraping mode (Unofficial) or API Token mode (Official REST API).

HTML Scraping Mode (Unofficial)

Credentials can be provided via CLI flags or environment variables:

• --username / SIGA_USERNAME
• --password / SIGA_PASSWORD
• --instituicao / SIGA_INSTITUICAO

The CLI automatically saves your session (cookies) to a local JSON file: ~/.activesoft_siga_<instituicao>_<username>.json

Subsequent commands will reuse this session, avoiding full re-authentication. If the session expires, the CLI will automatically attempt to re-login.

[!TIP] Multi-User Support: The session is isolated by username and instituicao. This allows running multiple instances for different users on the same machine without session interference.

You can also specify a custom session path when using the SDK:

client = SigaClient(..., session_path="/path/to/session.json")

API Token Mode (Official REST API)

You can use the official API by providing the Bearer Token and optional API version:

• --api-token / SIGA_API_TOKEN / ACTIVESOFT_API_TOKEN
• --api-version / api_version (defaults to "0")

Commands

Student Management (students)

Lists students or retrieves complete profile details for a specific student, including associated classes (turmas) and presence management/exit permissions.

# List students (defaults to 10)
activesoft-cli students --limit 20

# Fetch complete profile for a specific student ID
# Returns a merged JSON with student data, enrollment (turmas), and presence permissions
activesoft-cli students --id 4907

Class Management (turmas)

Lists available classes/groups.

# List classes (defaults to 10)
activesoft-cli turmas --limit 5 --periodo 14

Responsible Parties (responsaveis)

Lists responsible parties or retrieves specific details.

# List responsible parties (defaults to 21)
activesoft-cli responsaveis --limit 10

# Fetch details for a specific responsible party ID
activesoft-cli responsaveis --id 10188

Messaging (send-message)

Sends a message through the Siga system.

activesoft-cli send-message \
  --student-id 4907 \
  --destinatario-id 13578 \
  --message "Your message here" \
  --title "Aviso"

Avatar/Photo Management (upload-avatar)

Uploads a new photo/avatar for a specific student.

activesoft-cli upload-avatar \
  --student-id 4907 \
  --image-path "./photos/4907.jpg"

Bulk Photo Retrieval (bulk-fotos)

Retrieves photo URLs (S3 links) for multiple students or responsible parties at once.

# Using a comma-separated list for students (default)
activesoft-cli bulk-fotos --ids "104,106,107,111"

# Or using multiple ID flags for responsible parties
activesoft-cli bulk-fotos --id 13578 --id 12354 --tipo responsavel

SDK Usage

You can use the SigaClient directly in your Python applications.

1. Official API Token Mode (Recommended)

import asyncio
from activesoft_cli import SigaClient

async def main():
    # Initialize SigaClient with your official Bearer Token
    client = SigaClient(api_token="your-api-token")

    async with client:
        # Exposes all 40 official endpoints dynamically
        alunos = await client.lista_alunos(limit=5)
        print("Alunos:", alunos)

        escola_params = await client.parametro()
        print("Configurações da Escola:", escola_params)

if __name__ == "__main__":
    asyncio.run(main())

2. HTML Scraping Mode (Unofficial)

import asyncio
import json
from activesoft_cli import SigaClient

async def main():
    client = SigaClient(
        username="your-username", 
        password="your-password", 
        instituicao="YOUR_INSTITUTION"
    )

    async with client: # Closes session automatically
        if await client.login():
            # Get complete student profile
            aluno_detail = await client.get_aluno_detail(4907)
            aluno_info = aluno_detail.get('aluno', {})
            
            # Fetch and merge enrollment/turmas
            aluno_info['turmas'] = await client.get_aluno_turmas(4907)
            
            # Fetch and merge presence permissions
            aluno_info['gestao_presenca'] = aluno_detail.get('gestao_presenca', {})
            
            print(json.dumps(aluno_info, indent=2))

if __name__ == "__main__":
    asyncio.run(main())

Requirements

• Python 3.8+
• httpx
• loguru
• click

License

This project is licensed under the MIT License.