🔧 Guia de Integração¶

Guia completo para integração com a API SADIONLINE

Este guia fornece instruções abrangentes para desenvolvedores e integradores implementarem com sucesso a integração com a API SADIONLINE.

📋 Índice¶

Autenticação e Configuração
API de Estudantes
API de Atividades
API de Sessões
Análise de Engajamento
Melhores Práticas
Tratamento de Erros
Testes

🔐 Autenticação e Configuração¶

Autenticação por Chave API¶

Todas as requisições da API requerem autenticação usando uma chave API no cabeçalho Authorization:

Authorization: APIKey sk_sua_chave_api_aqui

Configuração do Ambiente¶

Ambiente de Produção¶

BASE_URL=https://api.sadionline.com.br
API_KEY=sk_sua_chave_de_producao

Como Usar sua Chave API¶

Sua chave API é fornecida pela equipe do SADIONLINE e deve ser mantida segura. Nunca compartilhe ou exponha sua chave API publicamente.

Formato da Chave API: - Prefixo: sk_ - Exemplo: sk_abc123def456ghi789jkl012mno345pqr678

Configuração de Idioma¶

Configure seu idioma preferido para respostas localizadas:

Accept-Language: pt-br    # Português (BR) - Padrão
Accept-Language: en-us    # Inglês (US)
Accept-Language: es-es    # Espanhol (ES)

👥 API de Estudantes¶

A API de Estudantes permite gerenciar registros e perfis de estudantes.

Endpoint Base¶

/tenant/{organization_id}/v1/students/

⚠️ Importante: Substitua {organization_id} pelo UUID da sua organização.

Criar Estudante¶

Crie um novo registro de estudante.

Endpoint: POST /tenant/{organization_id}/v1/students/

Corpo da Requisição:

{
  "registration_code": "EST001",
  "email": "estudante@exemplo.com",
  "status": "ACTIVE",
  "entry_date": "2024-01-15"
}

Parâmetros: - registration_code (string, obrigatório): Identificador único do estudante - email (string, obrigatório): Endereço de email do estudante - status (string, obrigatório): Status do estudante (ACTIVE, INACTIVE, FINISHED, TRANSFERRED, SUSPENDED) - entry_date (date, obrigatório): Data de matrícula do estudante

Resposta:



name=__codelineno-5-1 href=#__codelineno-5-1>{ "success": true, "message": "Estudante criado com sucesso", "data": { "id": "550e8400-e29b-41d4-a716-446655440000", "user_detail": { "id": "550e8400-e29b-41d4-a716-446655440000", "email": "estudante@exemplo.com", "name": "EST001", "avatar": null }, "registration_code": "EST001", "email": "estudante@exemplo.com", "status": "ACTIVE", "entry_date": "2024-01-15", "entry_year": "2024", "entry_semester": "1", "class_batch": "2024.1", "created_at": "2024-01-15T10:30:00Z", "updated_at": "2024-01-15T10:30:00Z" } class=p>}
 Listar Estudantes¶
 Recupere uma lista de todos os estudantes com filtragem opcional.
 Endpoint: GET /tenant/{organization_id}/v1/students/
 Parâmetros de Query: - status (string): Filtrar por status do estudante - registration_code (string): Filtrar por código de matrícula (exato) - email (string): Filtrar por email (contém) - entry_year (integer): Filtrar por ano de entrada - entry_semester (integer): Filtrar por semestre de entrada (1 ou 2) - entry_after (date): Filtrar por data de entrada após - entry_before (date): Filtrar por data de entrada antes - created_after (datetime): Filtrar por criado após - created_before (datetime): Filtrar por criado antes - updated_after (datetime): Filtrar por atualizado após - updated_before (datetime): Filtrar por atualizado antes - search (string): Buscar em código de matrícula e email - ordering (string): Ordenar resultados (created_at, -created_at, registration_code, email, status, entry_date)
 Exemplo de Requisição: 
GET /tenant/550e8400-e29b-41d4-a716-446655440002/v1/students/?status=ACTIVE&ordering=-created_at
Authorization: APIKey sk_sua_chave_api_aqui
 Resposta: 
{
  "success": true,
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "user_detail": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "email": "estudante@exemplo.com",
        "name": "EST001",
        "avatar": null
      },
      "registration_code": "EST001",
      "email": "estudante@exemplo.com",
      "status": "ACTIVE",
      "entry_date": "2024-01-15",
      "entry_year": "2024",
      "entry_semester": "1",
      "class_batch": "2024.1",
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-15T10:30:00Z"
    }
  ],
  "count": 1,
  "next": null,
  "previous": null
}
 Obter Detalhes do Estudante¶
 Recupere informações detalhadas sobre um estudante específico.
 Endpoint: GET /tenant/{organization_id}/v1/students/{id}/
 Resposta: Mesmo formato da resposta de Criar Estudante.
 Atualizar Estudante¶
 Atualize informações do estudante.
 Endpoint: PUT /tenant/{organization_id}/v1/students/{id}/ ou PATCH /tenant/{organization_id}/v1/students/{id}/
 Corpo da Requisição: 
{
  "registration_code": "EST001",
  "email": "atualizado@exemplo.com",
  "status": "ACTIVE",
  "entry_date": "2024-01-15"
}
 Excluir Estudante¶
 Exclua um registro de estudante (exclusão suave).
 Endpoint: DELETE /tenant/{organization_id}/v1/students/{id}/
 Resposta: 
{
  "success": true,
  "message": "Estudante excluído com sucesso"
}
 Atualizar Status do Estudante¶
 Atualize apenas o status de um estudante específico.
 Endpoint: PATCH /tenant/{organization_id}/v1/students/{id}/status/
 Corpo da Requisição: 
{
  "status": "FINISHED"
}
 
 📚 API de Atividades¶
 A API de Atividades gerencia atividades de aprendizagem e sessões.
 Endpoint Base¶
 /tenant/{organization_id}/v1/activities/
  ⚠️ Importante: Substitua {organization_id} pelo UUID da sua organização.
 
 Criar Atividade¶
 Crie uma nova atividade de aprendizagem.
 Endpoint: POST /tenant/{organization_id}/v1/activities/
 Corpo da Requisição: 
{
  "name": "Aula de Matemática",
  "description": "Cálculo avançado e equações diferenciais",
  "type": "CLASS",
  "custom_type": null
}
 Parâmetros: - name (string, obrigatório): Nome da atividade - description (string, opcional): Descrição da atividade - type (string, obrigatório): Tipo da atividade (veja Tipos de Atividade abaixo) - custom_type (string, opcional): Tipo personalizado quando type é "OTHER"
 Tipos de Atividade: - CLASS: Aula tradicional - EXERCISE: Exercício prático - EXAM: Prova ou avaliação - ASSIGNMENT: Tarefa ou trabalho - MEETING: Reunião ou encontro - QUIZ: Questionário rápido - PRESENTATION: Apresentação de estudante - WORKSHOP: Oficina prática - SEMINAR: Seminário interativo - LABORATORY: Sessão de laboratório - TUTORIAL: Sessão de tutoria - REVIEW: Sessão de revisão - OTHER: Tipo personalizado
 Resposta: 
{
  "success": true,
  "message": "Atividade criada com sucesso",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440001",
    "name": "Aula de Matemática",
    "description": "Cálculo avançado e equações diferenciais",
    "type": "CLASS",
    "custom_type": null,
    "display_type": "Aula",
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z"
  }
}
 Listar Atividades¶
 Recupere todas as atividades com opções de filtragem.
 Endpoint: GET /tenant/{organization_id}/v1/activities/
 Parâmetros de Query: - name (string): Filtrar por nome da atividade (contém) - type (string): Filtrar por tipo de atividade - custom_type (string): Filtrar por tipo personalizado (contém) - description (string): Filtrar por descrição (contém) - created_after (datetime): Filtrar por criado após - created_before (datetime): Filtrar por criado antes - search (string): Buscar em nome, descrição e custom_type - ordering (string): Ordenar resultados
 Exemplo de Requisição: 
GET /tenant/550e8400-e29b-41d4-a716-446655440002/v1/activities/?type=CLASS&ordering=-created_at
Authorization: APIKey sk_sua_chave_api_aqui
 Obter Detalhes da Atividade¶
 Recupere informações detalhadas da atividade.
 Endpoint: GET /tenant/{organization_id}/v1/activities/{id}/
 Atualizar Atividade¶
 Atualize informações da atividade.
 Endpoint: PUT /tenant/{organization_id}/v1/activities/{id}/ ou PATCH /tenant/{organization_id}/v1/activities/{id}/
 Excluir Atividade¶
 Exclua uma atividade (exclusão suave).
 Endpoint: DELETE /tenant/{organization_id}/v1/activities/{id}/
 Obter Tipos de Atividade¶
 Recupere todos os tipos de atividade disponíveis.
 Endpoint: GET /tenant/{organization_id}/v1/activities/types/
 Resposta: 
{
  "success": true,
  "message": "Tipos de atividade recuperados com sucesso",
  "data": {
    "types": [
      {"value": "CLASS", "label": "Aula"},
      {"value": "EXERCISE", "label": "Exercício"},
      {"value": "EXAM", "label": "Prova"},
      {"value": "ASSIGNMENT", "label": "Tarefa"},
      {"value": "MEETING", "label": "Reunião"},
      {"value": "QUIZ", "label": "Quiz"},
      {"value": "PRESENTATION", "label": "Apresentação"},
      {"value": "WORKSHOP", "label": "Workshop"},
      {"value": "SEMINAR", "label": "Seminário"},
      {"value": "LABORATORY", "label": "Laboratório"},
      {"value": "TUTORIAL", "label": "Tutorial"},
      {"value": "REVIEW", "label": "Revisão"},
      {"value": "OTHER", "label": "Outro"}
    ]
  }
}
 Obter Estatísticas de Atividades¶
 Recupere estatísticas sobre atividades.
 Endpoint: GET /tenant/{organization_id}/v1/activities/statistics/
 Resposta: 
{
  "success": true,
  "message": "Estatísticas de atividades recuperadas com sucesso",
  "data": {
    "statistics": [
      {
        "type": "CLASS",
        "count": 15,
        "percentage": 65.2
      },
      {
        "type": "EXAM",
        "count": 5,
        "percentage": 21.7
      },
      {
        "type": "WORKSHOP",
        "count": 3,
        "percentage": 13.1
      }
    ]
  }
}
 
 🎬 API de Sessões¶
 A API de Sessões gerencia sessões de rastreamento de engajamento.
 Endpoint Base¶
 /tenant/{organization_id}/v1/sessions/
  ⚠️ Importante: Substitua {organization_id} pelo UUID da sua organização.
 
 Listar Sessões¶
 Recupere todas as sessões de rastreamento com opções de filtragem.
 Endpoint: GET /tenant/{organization_id}/v1/sessions/
 Parâmetros de Query: - student (UUID): Filtrar por ID do estudante - student_registration_code (string): Filtrar por código de matrícula do estudante (contém) - student_email (string): Filtrar por email do estudante (contém) - activity (UUID): Filtrar por ID da atividade - activity_name (string): Filtrar por nome da atividade (contém) - activity_type (string): Filtrar por tipo da atividade - started_after (datetime): Filtrar por iniciado após - started_before (datetime): Filtrar por iniciado antes - ended_after (datetime): Filtrar por finalizado após - ended_before (datetime): Filtrar por finalizado antes - is_active (boolean): Filtrar por status ativo - is_completed (boolean): Filtrar por status completo - min_duration_minutes (number): Filtrar por duração mínima em minutos - max_duration_minutes (number): Filtrar por duração máxima em minutos - search (string): Buscar em código de matrícula do estudante, email ou nome da atividade - ordering (string): Ordenar resultados
 Exemplo de Requisição: 
GET /tenant/550e8400-e29b-41d4-a716-446655440002/v1/sessions/?student=550e8400-e29b-41d4-a716-446655440000&is_active=true
Authorization: APIKey sk_sua_chave_api_aqui
 Resposta: 
{
  "success": true,
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440002",
      "student_id": "550e8400-e29b-41d4-a716-446655440000",
      "student_name": "EST001",
      "activity_id": "550e8400-e29b-41d4-a716-446655440001",
      "activity_name": "Aula de Matemática",
      "activity_type": "CLASS",
      "started_at": "2024-01-15T10:30:00Z",
      "ended_at": null,
      "is_active": true,
      "duration_minutes": 45.5,
      "display_duration": "45m 30s",
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-15T10:30:00Z"
    }
  ],
  "count": 1,
  "next": null,
  "previous": null
}
 Obter Detalhes da Sessão¶
 Recupere informações detalhadas da sessão.
 Endpoint: GET /tenant/{organization_id}/v1/sessions/{id}/
 Resposta: 
{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440002",
    "student_id": "550e8400-e29b-41d4-a716-446655440000",
    "activity_id": "550e8400-e29b-41d4-a716-446655440001",
    "student_detail": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "registration_code": "EST001",
      "email": "estudante@exemplo.com",
      "status": "ACTIVE"
    },
    "activity_detail": {
      "id": "550e8400-e29b-41d4-a716-446655440001",
      "name": "Aula de Matemática",
      "type": "CLASS",
      "description": "Cálculo avançado e equações diferenciais"
    },
    "started_at": "2024-01-15T10:30:00Z",
    "ended_at": "2024-01-15T11:15:00Z",
    "is_active": false,
    "duration_seconds": 2700,
    "duration_minutes": 45.0,
    "display_duration": "45m 0s",
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T11:15:00Z"
  }
}
 
 📊 Análise de Engajamento¶
 A API de Engajamento fornece análises detalhadas e insights sobre o engajamento do estudante durante as sessões.
 Endpoint Base¶
 /tenant/{organization_id}/v1/sessions/{session_id}/engagement/
  ⚠️ Importante: Substitua {organization_id} pelo UUID da sua organização.
 
 Obter Resumo de Engajamento¶
 Recupere estatísticas agregadas de engajamento para uma sessão.
 Endpoint: GET /tenant/{organization_id}/v1/sessions/{session_id}/engagement/summary/
 Resposta: 
{
  "session": {
    "id": "550e8400-e29b-41d4-a716-446655440002",
    "duration_minutes": 45.0,
    "total_frames_analyzed": 2700,
    "granularity_minutes": 1.0
  },
  "engagement_summary": {
    "mean_score": 0.725,
    "mean_percentage": 72.5,
    "min": {
      "score": 0.452,
      "percentage": 45.2
    },
    "max": {
      "score": 0.891,
      "percentage": 89.1
    },
    "total_periods": 45,
    "high_engagement_periods": 12,
    "low_engagement_periods": 3,
    "high_engagement_ratio": 0.267,
    "low_engagement_ratio": 0.067
  },
  "events_summary": {
    "events": [
      {
        "name": "phone_use",
        "total_occurrences": 2,
        "occurrences_per_minute": 0.044
      },
      {
        "name": "yawning",
        "total_occurrences": 1,
        "occurrences_per_minute": 0.022
      },
      {
        "name": "drowsiness",
        "total_occurrences": 0,
        "occurrences_per_minute": 0.0
      },
      {
        "name": "unfocused",
        "total_occurrences": 0,
        "occurrences_per_minute": 0.0
      }
    ]
  }
}
 Campos de Resposta: - session.id: Identificador único da sessão - session.duration_minutes: Duração total da sessão em minutos - session.total_frames_analyzed: Número total de frames processados - session.granularity_minutes: Intervalo de agregação (sempre 1.0 minuto) - engagement_summary.mean_score: Pontuação média de engajamento (0.0 a 1.0) - engagement_summary.mean_percentage: Porcentagem média de engajamento (0.0 a 100.0) - engagement_summary.min: Objeto com menor pontuação e porcentagem de engajamento - engagement_summary.max: Objeto com maior pontuação e porcentagem de engajamento - engagement_summary.total_periods: Total de períodos analisados - engagement_summary.high_engagement_periods: Número de períodos com engajamento ≥ 70% - engagement_summary.low_engagement_periods: Número de períodos com engajamento < 30% - engagement_summary.high_engagement_ratio: Razão de períodos de alto engajamento (0.0 a 1.0) - engagement_summary.low_engagement_ratio: Razão de períodos de baixo engajamento (0.0 a 1.0) - events_summary.events: Array de eventos detectados (phone_use, yawning, drowsiness, unfocused) - events_summary.events[].name: Nome do evento - events_summary.events[].total_occurrences: Total de ocorrências do evento - events_summary.events[].occurrences_per_minute: Ocorrências por minuto
 Obter Distribuição de Engajamento¶
 Recupere dados de engajamento agregados por intervalos de minuto.
 Endpoint: GET /tenant/{organization_id}/v1/sessions/{session_id}/engagement/distribution/
 Resposta: 
{
  "session": {
    "id": "550e8400-e29b-41d4-a716-446655440002",
    "granularity_minutes": 1.0
  },
  "timeline": [
    {
      "timestamp": "2024-01-15T10:30:00Z",
      "frames_analyzed": 60,
      "engagement": {
        "score": 0.85,
        "percentage": 85.0
      },
      "events": [
        {
          "name": "phone_use",
          "active": false
        },
        {
          "name": "yawning",
          "active": false
        },
        {
          "name": "drowsiness",
          "active": false
        },
        {
          "name": "unfocused",
          "active": false
        }
      ]
    },
    {
      "timestamp": "2024-01-15T10:31:00Z",
      "frames_analyzed": 60,
      "engagement": {
        "score": 0.72,
        "percentage": 72.0
      },
      "events": [
        {
          "name": "phone_use",
          "active": true
        },
        {
          "name": "yawning",
          "active": false
        },
        {
          "name": "drowsiness",
          "active": false
        },
        {
          "name": "unfocused",
          "active": false
        }
      ]
    }
  ]
}
 Campos de Resposta: - session.id: Identificador único da sessão - session.granularity_minutes: Intervalo de agregação (sempre 1.0 minuto) - timeline: Array de pontos de dados de engajamento por minuto
 Campos de Timeline: - timestamp: Hora de início do intervalo de minuto - frames_analyzed: Número de frames analisados neste minuto - engagement.score: Pontuação de engajamento (0.0 a 1.0) para este minuto - engagement.percentage: Porcentagem de engajamento (0.0 a 100.0) para este minuto - events: Array de eventos detectados neste minuto - events[].name: Nome do evento (phone_use, yawning, drowsiness, unfocused) - events[].active: Se o evento ocorreu neste minuto (true/false)
 
 😊 Análise de Emoção¶
 A API de Emoção fornece análises detalhadas sobre as emoções detectadas durante as sessões.
 Endpoint Base¶
 /tenant/{organization_id}/v1/sessions/{session_id}/emotion/
  ⚠️ Importante: Substitua {organization_id} pelo UUID da sua organização.
 
 Obter Resumo de Emoção¶
 Recupere estatísticas agregadas de emoção para uma sessão.
 Endpoint: GET /tenant/{organization_id}/v1/sessions/{session_id}/emotion/summary/
 Resposta: 
{
  "session": {
    "id": "550e8400-e29b-41d4-a716-446655440002",
    "duration_minutes": 45.0,
    "total_frames_analyzed": 2700,
    "granularity_minutes": 1.0
  },
  "emotion_summary": {
    "dominant_emotion": {
      "name": "HAPPY",
      "score": 0.65,
      "percentage": 65.0
    },
    "distribution": [
      {
        "name": "HAPPY",
        "score": 0.65,
        "percentage": 65.0
      },
      {
        "name": "NEUTRAL",
        "score": 0.25,
        "percentage": 25.0
      },
      {
        "name": "SAD",
        "score": 0.08,
        "percentage": 8.0
      },
      {
        "name": "ANGRY",
        "score": 0.02,
        "percentage": 2.0
      }
    ]
  }
}
 Campos de Resposta: - session.id: Identificador único da sessão - session.duration_minutes: Duração total da sessão em minutos - session.total_frames_analyzed: Número total de frames processados - session.granularity_minutes: Intervalo de agregação (sempre 1.0 minuto) - emotion_summary.dominant_emotion: Emoção mais frequente detectada durante a sessão - emotion_summary.distribution: Distribuição de todas as emoções detectadas
 Emoções Disponíveis: - HAPPY: Felicidade - NEUTRAL: Neutro - SAD: Tristeza - ANGRY: Raiva - SURPRISED: Surpresa - FEAR: Medo - DISGUST: Nojo - NOT_DETECTED: Não detectado
 Obter Distribuição de Emoção¶
 Recupere dados de emoção agregados por intervalos de minuto.
 Endpoint: GET /tenant/{organization_id}/v1/sessions/{session_id}/emotion/distribution/
 Resposta: 
{
  "session": {
    "id": "550e8400-e29b-41d4-a716-446655440002",
    "duration_minutes": 45.0,
    "total_frames_analyzed": 2700,
    "granularity_minutes": 1.0
  },
  "timeline": [
    {
      "timestamp": "2024-01-15T10:30:00Z",
      "frames_analyzed": 60,
      "emotion": {
        "dominant_emotion": {
          "name": "HAPPY",
          "score": 0.75,
          "percentage": 75.0
        },
        "distribution": [
          {
            "name": "HAPPY",
            "score": 0.75,
            "percentage": 75.0
          },
          {
            "name": "NEUTRAL",
            "score": 0.20,
            "percentage": 20.0
          }
        ]
      }
    }
  ]
}
 Campos de Timeline: - timestamp: Hora de início do intervalo de minuto - frames_analyzed: Número de frames analisados neste minuto - emotion.dominant_emotion: Emoção dominante neste minuto - emotion.distribution: Distribuição de todas as emoções neste minuto
 
 🧠 Análise Cognitiva¶
 A API de Análise Cognitiva fornece insights sobre a presença cognitiva do estudante durante as sessões, baseada no modelo de Community of Inquiry.
 Endpoint Base¶
 /tenant/{organization_id}/v1/sessions/{session_id}/cognitive/
  ⚠️ Importante: Substitua {organization_id} pelo UUID da sua organização.
 
 Obter Resumo Cognitivo¶
 Recupere estatísticas agregadas de presença cognitiva para uma sessão.
 Endpoint: GET /tenant/{organization_id}/v1/sessions/{session_id}/cognitive/summary/
 Resposta: 
{
  "session": {
    "id": "550e8400-e29b-41d4-a716-446655440002",
    "duration_minutes": 45.0,
    "total_frames_analyzed": 2700
  },
  "cognitive_presence_summary": {
    "dominant_state": {
      "name": "full_presence",
      "score": 0.55,
      "percentage": 55.0
    },
    "distribution": [
      {
        "name": "full_presence",
        "score": 0.55,
        "percentage": 55.0
      },
      {
        "name": "semi_presence",
        "score": 0.30,
        "percentage": 30.0
      },
      {
        "name": "absent",
        "score": 0.15,
        "percentage": 15.0
      }
    ]
  }
}
 Campos de Resposta: - session.id: Identificador único da sessão - session.duration_minutes: Duração total da sessão em minutos - session.total_frames_analyzed: Número total de frames processados - cognitive_presence_summary.dominant_state: Estado cognitivo mais frequente durante a sessão - cognitive_presence_summary.distribution: Distribuição de todos os estados cognitivos
 Estados Cognitivos: - absent: Ausência de presença cognitiva (engajamento < 40%) - semi_presence: Presença cognitiva parcial (engajamento entre 40% e 85%) - full_presence: Presença cognitiva completa (engajamento ≥ 85% ou engajamento ≥ 70% com emoções positivas)
 Obter Distribuição Cognitiva¶
 Recupere dados de presença cognitiva agregados por intervalos de minuto.
 Endpoint: GET /tenant/{organization_id}/v1/sessions/{session_id}/cognitive/distribution/
 Resposta: 
{
  "session": {
    "id": "550e8400-e29b-41d4-a716-446655440002",
    "granularity_minutes": 1.0
  },
  "timeline": [
    {
      "timestamp": "2024-01-15T10:30:00Z",
      "frames_analyzed": 60,
      "cognitive_presence": {
        "dominant_state": {
          "name": "full_presence",
          "score": 0.65,
          "percentage": 65.0
        },
        "distribution": [
          {
            "name": "full_presence",
            "score": 0.65,
            "percentage": 65.0
          },
          {
            "name": "semi_presence",
            "score": 0.25,
            "percentage": 25.0
          },
          {
            "name": "absent",
            "score": 0.10,
            "percentage": 10.0
          }
        ]
      }
    }
  ]
}
 Campos de Timeline: - timestamp: Hora de início do intervalo de minuto - frames_analyzed: Número de frames analisados neste minuto - cognitive_presence.dominant_state: Estado cognitivo dominante neste minuto (absent, semi_presence, full_presence) - cognitive_presence.distribution: Distribuição de todos os estados cognitivos neste minuto
 
 🏆 Melhores Práticas¶
 1. Autenticação¶
  Armazene chaves API de forma segura e nunca as exponha em código do lado do cliente
 Use variáveis de ambiente para chaves API em produção
 Rotacione chaves API regularmente por segurança
 
 2. Tratamento de Erros¶
  Sempre verifique o campo success nas respostas
 Trate erros de limite de taxa graciosamente com backoff exponencial
 Registre erros para depuração e monitoramento
 
 3. Performance¶
  Use paginação para conjuntos de dados grandes
 Implemente cache para dados acessados frequentemente
 Use parâmetros de query apropriados para filtrar resultados
 
 4. Gerenciamento de Dados¶
  Valide dados antes de enviar requisições
 Use métodos HTTP apropriados (GET para recuperação, POST para criação, etc.)
 Trate exclusões suaves apropriadamente
 
 5. Monitoramento¶
  Monitore uso da API e limites de taxa
 Acompanhe tendências de métricas de engajamento ao longo do tempo
 Configure alertas para padrões incomuns
 
 
 ❌ Tratamento de Erros¶
 Códigos de Erro Comuns¶
    Código  Descrição  Solução  
 
   400  Requisição Inválida  Verifique formato da requisição e campos obrigatórios  
  401  Não Autorizado  Verifique se a chave API está correta e não expirou  
  403  Proibido  Verifique permissões da chave API  
  404  Não Encontrado  Verifique se o ID do recurso existe  
  429  Muitas Requisições  Implemente limitação de taxa e lógica de retry  
  500  Erro Interno do Servidor  Contate o suporte se persistir  
 
 
 Formato de Resposta de Erro¶
 {
  "success": false,
  "message": "Erro de validação ocorreu",
  "errors": {
    "email": ["Insira um endereço de email válido."],
    "registration_code": ["Este campo é obrigatório."]
  },
  "timestamp": "2024-01-15T10:30:00Z"
}
 Limitação de Taxa¶
 Quando limites de taxa são excedidos:
 HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1642248000
Retry-After: 3600
 
 🧪 Testes¶
 Fluxo de Teste de Exemplo¶
  Criar um estudante
 Criar uma atividade
 Listar sessões (deve estar vazio inicialmente)
 Obter análise de engajamento (após a sessão ter dados)
 
 Ferramentas de Teste¶
  Postman: Importe nossa coleção da API
 curl: Use testes de linha de comando
 Seu cliente HTTP preferido: Qualquer cliente REST funciona
 
 Script de Teste de Exemplo (Python)¶
 import requests
import json

BASE_URL = "https://api.sadionline.com"
API_KEY = "sk_sua_chave_api"

headers = {
    "Authorization": f"APIKey {API_KEY}",
    "Content-Type": "application/json",
    "Accept-Language": "pt-br"
}

# Criar estudante
student_data = {
    "registration_code": "TESTE001",
    "email": "teste@exemplo.com",
    "status": "ACTIVE",
    "entry_date": "2024-01-15"
}

# Substitua pelo UUID da sua organização
ORGANIZATION_ID = "550e8400-e29b-41d4-a716-446655440002"

response = requests.post(
    f"{BASE_URL}/tenant/{ORGANIZATION_ID}/v1/students/",
    headers=headers,
    json=student_data
)

print(f"Estudante criado: {response.status_code}")
print(json.dumps(response.json(), indent=2))

# Criar atividade
activity_data = {
    "name": "Aula de Teste",
    "description": "Atividade de teste para integração",
    "type": "CLASS"
}

response = requests.post(
    f"{BASE_URL}/tenant/{ORGANIZATION_ID}/v1/activities/",
    headers=headers,
    json=activity_data
)

print(f"Atividade criada: {response.status_code}")
print(json.dumps(response.json(), indent=2))

# Listar sessões
response = requests.get(
    f"{BASE_URL}/tenant/{ORGANIZATION_ID}/v1/sessions/",
    headers=headers
)

print(f"Sessões listadas: {response.status_code}")
print(json.dumps(response.json(), indent=2))
 
 📞 Suporte¶
 Obtendo Ajuda¶
  Documentação: Este guia e referência da API
 Email de Suporte: suporte@sadionline.com
 Status da Plataforma: https://status.sadionline.com
 
 Relatando Problemas¶
 Ao relatar problemas, inclua: - Endpoint e método da API - Cabeçalhos e corpo da requisição - Código de status e corpo da resposta - Comportamento esperado vs real - Passos para reproduzir
 
  Boa Integração! 🚀 
 Construído com ❤️ pelo Instituto Anexo

Código	Descrição	Solução
`400`	Requisição Inválida	Verifique formato da requisição e campos obrigatórios
`401`	Não Autorizado	Verifique se a chave API está correta e não expirou
`403`	Proibido	Verifique permissões da chave API
`404`	Não Encontrado	Verifique se o ID do recurso existe
`429`	Muitas Requisições	Implemente limitação de taxa e lógica de retry
`500`	Erro Interno do Servidor	Contate o suporte se persistir