Sincronizar actividades

Objetivo: llevar el calendario de un grupo (clases, guardias, prácticas) de su sistema a Presente. Hay dos formas: importación CSV (varias actividades a la vez, idempotente) y alta unitaria (una actividad, con todos los campos).

Necesita: CADASTRAR en el grupo (vea Permisos) y el id del grupo.

Importar por CSV (recomendado para calendarios)

data,inicio,fim,descricao,local
10/03/2026,08:00,12:00,Guardia en urgencias,Hospital Ejemplo
11/03/2026,14:00,16:00,Clase de técnicas básicas,Laboratorio 2

Columna	Obligatoria	Formato
data	sí	AAAA-MM-DD o DD/MM/AAAA (alias: date, fecha).
inicio y fim	no, pero juntas	HH:MM o HH:MM:SS; fim después de inicio. Solo una de las dos completada es error.
descricao	no	Hasta 2000 caracteres.
local	no	Hasta 500 caracteres.

Límites y separadores: los mismos de Sincronizar alumnos (500 líneas, 90 000 caracteres, coma, punto y coma o tabulación).

El uso es igual al de la importación de alumnos: POST /turmas/{turmaId}/importacoes/atividades con { "csv": "...", "modo": "simular" }, revisar el informe y repetir con "modo": "aplicar" (todo o nada; parcial con hashConteudo como se describe allí).

curl -X POST "$API/turmas/$TURMA/importacoes/atividades" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d "$(jq -n --rawfile csv atividades.csv '{csv: $csv, modo: "aplicar"}')"

Idempotencia: una actividad se reconoce por la combinación fecha + hora de inicio + descripción (sin distinguir mayúsculas). Reaplicar el mismo archivo da JA_EXISTE en las que ya existen y CRIADA en las nuevas. Pero:

• La importación solo crea: no modifica ni borra actividades. Si usted cambia la hora o la descripción en su sistema, la importación lo trata como una actividad nueva.
• Dos líneas iguales en el archivo: la segunda es ERRO (duplicate).
• El texto de descricao se vuelve (o reutiliza, por nombre) un elemento del catálogo de actividades de la asignatura; use siempre la misma grafía para la misma actividad. Los campos que el CSV no tiene (obligatoria, cerca de ubicación, etc.) quedan con los valores predeterminados; ajústelos con el alta unitaria.

Alta unitaria

Para controlar todos los campos, o para modificar y cancelar:

curl -X POST "$API/turmas/$TURMA/atividades" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"data":"2026-03-10","horaInicio":"08:00","horaFim":"12:00","descricao":"Guardia en urgencias","local":"Hospital Ejemplo","obrigatoria":true}'

Solo data es obligatoria. Otros campos: atividadeProfissionalId (elemento del catálogo de la asignatura), observacoes, obrigatoria, cancelada, cercaAtiva, cercaRaioM (10 a 5000 m), lat y lng. Vea el modelo completo en AtividadeCriar.

Cuidado: POST /turmas/{turmaId}/atividades no es idempotente. Si la llamada falla por red después de que el servidor la procesó, repetir crea una actividad duplicada. Antes de repetir tras una falla incierta, liste las actividades del día (GET /turmas/{turmaId}/atividades?de=2026-03-10&ate=2026-03-10) y compruebe.

Leer, modificar y eliminar

Operación	Ruta
Listar (con filtro de fechas de y ate)	GET /turmas/{turmaId}/atividades
Leer una	GET /turmas/{turmaId}/atividades/{atividadeId}
Modificar	PATCH /turmas/{turmaId}/atividades/{atividadeId}
Cancelar (se mantiene en el calendario)	PATCH con {"cancelada": true}
Eliminar	DELETE /turmas/{turmaId}/atividades/{atividadeId}

Eliminar solo es posible mientras no haya asistencia registrada en la actividad; después, la respuesta es 409 CONFLICT. En ese caso, cancele en vez de eliminar.

Un flujo de sincronización del calendario

1. Lea las actividades actuales del grupo (todas las páginas) y arme un mapa fecha|inicio|descripción → id.
2. Para cada actividad de su sistema: si está en el mapa, compare los campos y use PATCH si cambiaron; si no está, créela (CSV o unitario).
3. Para actividades que su sistema quitó y que existen en Presente: cancele (PATCH con cancelada: true) o elimine (DELETE, si no tiene asistencia).

Este flujo evita la limitación del CSV (que solo crea) y no duplica nada.

Ejemplo (Python): crear las que faltan

def clave(a):
    return (a["data"], (a["horaInicio"] or "")[:5], (a["descricao"] or "").lower())

existentes = {clave(a) for a in todos(f"/turmas/{TURMA}/atividades", token)}  # vea "Paginación y límites"

for a in calendario_de_mi_sistema:
    if clave(a) in existentes:
        continue
    r = requests.post(f"{API}/turmas/{TURMA}/atividades",
                      headers={"Authorization": f"Bearer {token}"}, json=a)
    r.raise_for_status()