Third-AI-Uniandes — Flujos HTTP para APIM

Documentación de cómo el CLI de AI Uniandes consume las APIs para integración con APIM.

Servicios del CLI

1. Autenticación OAuth2 client_credentials

sequenceDiagram
    participant Client
    participant EntraID as Microsoft Entra ID
    participant APIM
    Client->>EntraID: POST /oauth2/v2.0/token (client_credentials + scope)
    EntraID-->>Client: access_token (JWT)
    Client->>APIM: API call con Authorization: Bearer {token}
    APIM-->>Client: Response

Scopes por servicio

Ejemplo de obtención de token

POST https://login.microsoftonline.com/{tenant_id}/oauth2/v2.0/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
&client_id={client_id}
&client_secret={client_secret}
&scope=api://FA-QA-AIUniandes-UploadDocument/.default

Headers comunes

Accept: application/json
Authorization: Bearer {access_token}
Content-Type: application/json

2. Flujo de ingesta para asistentes RAG

sequenceDiagram
    participant Client
    participant APIM
    participant Upload as UploadDocument API
    Client->>APIM: POST /documents/upload/assistant (multipart)
    APIM->>Upload: forward
    Upload-->>APIM: file_id, status: UPLOADED
    APIM-->>Client: 200 OK + file_id
    Client->>APIM: POST /documents/process {file_id, type: context_assistant}
    APIM->>Upload: forward
    Upload-->>APIM: 202 Accepted
    APIM-->>Client: 202 Accepted
    loop Polling cada 5s (max 300s)
        Client->>APIM: GET /document/{id}/status
        APIM-->>Client: status: PROCESSING
    end
    Client->>APIM: GET /document/{id}/status
    APIM-->>Client: status: READY

Upload del archivo

{
  "file_id": "2da40ce5-4c9f-4cce-a76d-7ff7304c4fd1",
  "file_name": "documento.pdf",
  "status": "UPLOADED"
}

Procesamiento

{
  "file_id": "{file_id}",
  "id_application": "{assistant_id}",
  "type": "context_assistant"
}

Polling de estado

{
  "id": "{document_id}",
  "filename": "documento.pdf",
  "status": "READY",
  "source": "CONTEXT_ASSISTANT",
  "blob_name": "container/documento.pdf",
  "id_assistant": "{assistant_id}",
  "error": false
}

Estados terminales

3. Flujo de chat con asistentes

sequenceDiagram
    participant Client
    participant APIM
    participant Assistant as ClientAssistant API
    Client->>APIM: POST /ai-assistant/chat/{assistant_id}
    Note right of Client: question, model, idConversation
    APIM->>Assistant: forward + Bearer token
    Assistant-->>APIM: answer, links, keyWords
    APIM-->>Client: 200 OK

Modelos disponibles

Payload completo

{
  "id": "{message_uuid}",
  "userName": "script-rag-chat",
  "roles": "ADMINISTRATIVE,STUDENT,TEACHER,ADMINISTRATOR-ASSISTANT,OWNER-ASSISTANT,USER-TD",
  "state": "INITIALIZED",
  "category": "",
  "question": "Cual es la politica de homologaciones?",
  "answer": "   ",
  "answerTyping": "   ",
  "answerRating": 0,
  "reasonRating": "",
  "refinedAnswer": "",
  "academicCategory": null,
  "keyWords": [],
  "links": [],
  "restrictionService": null,
  "idConversation": "{conversation_uuid}",
  "files": [],
  "model": "GPT_5_CHAT_UNIANDES",
  "model_label": "Open AI gpt-5-chat",
  "is_open": "NO"
}

Campos de respuesta

4. Descarga de metadata desde OnBase

flowchart TD
    A[Inicio] --> B{Modo?}
    B -->|Navegacion| C[GET /onbase/files?path=X]
    B -->|Busqueda| D[GET /onbase/files?search=X]
    C --> E{Tiene subcarpetas?}
    E -->|Si| F[Encolar subcarpetas]
    F --> C
    E -->|No| G[Recoger archivos]
    D --> H{next_cursor?}
    H -->|Si| I[Repetir con cursor]
    I --> D
    H -->|No| G
    G --> J[Exportar Excel]

Listado por navegación

GET /api/v1/onbase/files?path=Secretaria/Actas/&page_size=50
Authorization: Bearer {onbase_token}
Accept: application/json

Búsqueda paginada

Mapeo OnBase → Excel

5. Ingesta institucional simple

sequenceDiagram
    participant Client
    participant APIM
    participant Upload as UploadDocument
    participant Classifier as DocumentClassifier
    alt source = PORTAL_WEB
        Client->>APIM: POST /document/upload/institutional (multipart)
    else source = ONBASE
        Client->>APIM: POST /documents/upload/onbase {file_id, source}
    end
    APIM-->>Client: file_id
    opt visibility = RESTRICTED
        Client->>APIM: POST /document-groups {file_id, allowed_groups, allowed_users}
        APIM-->>Client: 201 Created
    end
    Client->>APIM: POST /document-groups/classify/batch {file_ids}
    APIM-->>Client: job_id
    loop Polling
        Client->>APIM: GET /document-groups/classify/status/{job_id}
        APIM-->>Client: status
    end

Upload local

POST /api/v1/document/upload/institutional
Authorization: Bearer {upload_token}
Content-Type: multipart/form-data

file: documento.pdf (binary)
application_id: {application_id}

Upload desde OnBase

{
  "file_id": "{document_onbase_id}",
  "source": "CONTEXT_INSTITUTIONAL"
}

Crear DocumentGroup (RESTRICTED)

{
  "file_id": "{file_id}",
  "application_id": "{application_id}",
  "allowed_groups": [{ "name_group": "Secretaria-General" }],
  "allowed_users": [{ "username": "[email protected]" }]
}

Actualizar DocumentGroup

{
  "allowed_groups": [{ "name_group": "Secretaria-General" }],
  "allowed_users": [{ "username": "[email protected]" }]
}

Clasificación batch

{
  "file_ids": ["{file_id}"],
  "application_id": "{application_id}"
}

{
  "data": {
    "job_id": "{job_id}",
    "status_url": "/api/v1/document-groups/classify/status/{job_id}"
  }
}

Polling clasificación

6. Eliminación de archivo institucional

sequenceDiagram
    participant Client
    participant APIM
    Client->>APIM: GET /document/{id}/detail
    APIM-->>Client: document metadata
    Client->>APIM: GET /document-groups/by-file/{id}
    alt Existe DocumentGroup
        APIM-->>Client: {id: ...}
        Client->>APIM: DELETE /document-groups/{file_id}
        APIM-->>Client: 204 No Content
    else No existe
        APIM-->>Client: 404
    end
    Client->>APIM: DELETE /document/delete/{id}
    APIM-->>Client: 204 No Content

7. Recomendaciones APIM

8. Diferencias importantes