Autenticação

Todas as chamadas à API devem incluir um token de autenticação no cabeçalho Authorization.

Authorization: Bearer SEU_TOKEN_AQUI

Substitua SEU_TOKEN_AQUI pelo token fornecido.

Endpoints da API

1. Criar Correção de Redação (ENEM)

Este endpoint permite o envio de uma nova redação para correção no modelo ENEM.

• Método: POST
• URL: https://os.corrigir.ai/api/correcao-enem
• Headers:
  • Authorization: Bearer SEU_TOKEN_AQUI
  • Content-Type: application/json

Corpo da Requisição (Request Body):

Campos obrigatórios:

• aluno_id: Identificador do aluno.
• atividade_id: Identificador da atividade.
• payload.textos_apoio: Textos de apoio para a correção (string, pode ser vazia se não houver textos de apoio, mas o campo deve existir).
• payload.resposta_aluno: A resposta do aluno. Pode ser enviada em três formatos diferentes:
  • Formato Texto: Uma string simples com o texto da redação.
  • Formato Objeto com URL da imagem: Um objeto com campos tipo e url para imagens.
  • Formato Objeto com Base64: Um objeto com campos tipo e base64 para imagens codificadas.

Campo opcional:

• custom_id: Um identificador único opcional para controle interno do cliente. Se fornecido, este valor deve ser único em todas as correções.

Exemplo 1: Resposta em formato texto

{
    "custom_id": "ExemploID-001",
    "aluno_id": "alunoExemplo-123",
    "atividade_id": "atividadeExemplo-456",
    "payload": {
        "textos_apoio": "Texto de apoio e proposta de redação aqui...",
        "resposta_aluno": "A redação do aluno vai aqui.\\nCom múltiplas linhas se necessário."
    }
}

Exemplo 2: Resposta em formato de URL de imagem

{
    "custom_id": "ExemploID-002",
    "aluno_id": "alunoExemplo-123",
    "atividade_id": "atividadeExemplo-456",
    "payload": {
        "textos_apoio": "Texto de apoio e proposta de redação aqui...",
        "resposta_aluno": {
            "tipo": "imagem",
            "url": "https://exemplo.com/imagens/redacao-aluno-123.jpg"
        }
    }
}

Exemplo 3: Resposta em formato Base64

{
    "custom_id": "ExemploID-003",
    "aluno_id": "alunoExemplo-123",
    "atividade_id": "atividadeExemplo-456",
    "payload": {
        "textos_apoio": "Texto de apoio e proposta de redação aqui...",
        "resposta_aluno": {
            "tipo": "imagem",
            "base64": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQEAYABgAAD/2wBDAAIBAQIBAQ..."
        }
    }
}

Resposta em Caso de Sucesso (200 OK):

Retorna o objeto da correção criada.

{
    "id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
    "cliente": "c1d2e3f4-g5h6-7890-1234-567890abcdef",
    "payload": {
        "textos_apoio": "Texto de apoio e proposta de redação aqui...",
        "resposta_aluno": "A redação do aluno vai aqui.\\nCom múltiplas linhas se necessário."
    },
    "resultado": null,
    "status": "new",
    "user_created": "u1v2w3x4-y5z6-7890-1234-567890abcdef",
    "date_updated": null,
    "metodo": "m1n2o3p4-q5r6-7890-1234-567890abcdef",
    "custom_id": "ExemploID-001",
    "aluno_id": "alunoExemplo-123",
    "atividade_id": "atividadeExemplo-456",
    "date_created": "2024-07-30T10:00:00.000Z"
}

2. Criar Correção de Questão Discursiva

Este endpoint permite o envio de uma nova questão discursiva para correção.

• Método: POST
• URL: https://os.corrigir.ai/api/questao-discursiva
• Headers:
  • Authorization: Bearer SEU_TOKEN_AQUI
  • Content-Type: application/json

Corpo da Requisição (Request Body):

Campos obrigatórios:

• aluno_id: Identificador do aluno.
• atividade_id: Identificador da atividade.
• questao_id: Identificador da questão.
• payload.enunciado_questao: O enunciado da questão.
• payload.gabarito: O gabarito ou critério de correção para a questão.
• payload.resposta_aluno: A resposta do aluno (suporta os mesmos formatos de texto, URL de imagem e Base64 da correção de redação).

Campo opcional:

• custom_id: Um identificador único opcional.

Exemplo: Resposta em formato texto

{
    "custom_id": "ExemploDiscursiva-001",
    "aluno_id": "alunoExemplo-123",
    "atividade_id": "atividadeExemplo-789",
    "questao_id": "questaoExemplo-101",
    "payload": {
        "enunciado_questao": "Qual o impacto da Revolução Industrial na sociedade moderna?",
        "gabarito": "A resposta deve abordar os seguintes pontos: urbanização, novas classes sociais, e mudanças nas condições de trabalho.",
        "resposta_aluno": "A Revolução Industrial foi um divisor de águas, transformando fundamentalmente a estrutura social e econômica."
    }
}

Resposta em Caso de Sucesso (200 OK):

Retorna o objeto da correção criada, similar à correção de redação, com o status inicial new.

3. Buscar Correção por ID

Este endpoint permite buscar uma correção específica pelo seu ID único (gerado pelo sistema).

• Método: GET
• URL: https://os.corrigir.ai/items/mc_correcoes/{id_da_correcao}

Resposta em Caso de Sucesso (200 OK):

Retorna o objeto da correção encontrada. O conteúdo do campo resultado varia conforme o tipo de correção.

Exemplo de Resposta (Redação ENEM):

{
    "data": {
        "id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
        "status": "success",
        "custom_id": "ExemploID-001",
        "aluno_id": "alunoExemplo-123",
        "atividade_id": "atividadeExemplo-456",
        "resultado": {
            "nota_final": 960,
            "feedback": "Sua redação apresenta bom domínio do tema...",
            "lista_de_marcacoes": [
                {
                    "trecho": "prevaricação real",
                    "competencia": "C1",
                    "tipo": "DESVIO",
                    "comentario": "Uso inadequado do termo 'prevaricação'"
                }
            ],
            "resposta_aluno_marcada": "Texto... com as devidas <span class='marcacao'>marcações</span>..."
        }
        // ... outros campos ...
    }
}

Exemplo de Resposta (Questão Discursiva):

{
    "data": {
        "id": "f1g2h3i4-j5k6-7890-1234-567890lmnpq",
        "status": "success",
        "custom_id": "ExemploDiscursiva-001",
        "aluno_id": "alunoExemplo-123",
        "atividade_id": "atividadeExemplo-789",
        "resultado": {
            "feedback": "Olá! ❗\\n\\n⚠️ AVALIAÇÃO\\nSua resposta à questão sobre \"\" não atingiu pontuação...",
            "nota_final": "0"
        }
        // ... outros campos ...
    }
}

Se nenhuma correção for encontrada com o ID fornecido, o campo data será null.

4. Buscar Correção por custom_id

• Método: GET
• URL: https://os.corrigir.ai/items/mc_correcoes?filter[custom_id]={seu_custom_id}

Retorna um array de objetos de correção que correspondem ao custom_id.

5. Buscar Correções por aluno_id

• Método: GET
• URL: https://os.corrigir.ai/items/mc_correcoes?filter[aluno_id]={id_do_aluno}

Retorna um array de objetos de correção para o aluno especificado.

6. Buscar Correções por atividade_id

• Método: GET
• URL: https://os.corrigir.ai/items/mc_correcoes?filter[atividade_id]={id_da_atividade}

Retorna um array de objetos de correção para a atividade especificada.

Fluxo de Processamento da Correção

Visão Geral do Fluxo

Etapas do Processamento

1. Criação e Enfileiramento: Ao criar uma correção, ela recebe o status new.
2. Espera em Fila: A correção pode aguardar com o status waiting.
3. Início do Processamento: O status é atualizado para running.
4. Conclusão do Processamento: O status final será success ou error.

O tempo estimado para processamento é de aproximadamente 5 minutos. Recomenda-se implementar um mecanismo de polling para consultar periodicamente o status.

Tipos de Status da Correção

Respostas de Erro Comuns

400 Bad Request (Erro de Validação)

Ocorre quando os dados enviados são inválidos, por exemplo, um custom_id duplicado.

{
    "errors": [
        {
            "message": "Value for field \\"custom_id\\" in collection \\"mc_correcoes\\" has to be unique.",
            "extensions": {
                "collection": "mc_correcoes",
                "field": "custom_id",
                "code": "RECORD_NOT_UNIQUE"
            }
        }
    ]
}

403 Forbidden (Erro de Permissão)

Ocorre quando o token é inválido, expirado ou não tem permissão.

{
    "errors": [
        {
            "message": "You don't have permission to access this.",
            "extensions": {
                "code": "FORBIDDEN"
            }
        }
    ]
}