Documentação API

Esta documentação descreve a API para integração de correções em nossa plataforma.

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

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

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: O texto da redação/resposta do aluno.
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.
```
{
	"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."
	}
}
```

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": "novo",
	"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. 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}
- Substitua {id_da_correcao} pelo ID da correção desejada.
Headers:
- Authorization: Bearer SEU_TOKEN_AQUI

Resposta em Caso de Sucesso (200 OK):

Retorna o objeto da correção encontrada.

{
	"data": {
		"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": {
			"nota_final": 960,
			"feedback": "Sua redação apresenta bom domínio do tema, mas deve evitar termos inadequados como 'prevaricação'. O uso de repertório legislativo está adequado. Invista em detalhamento das propostas na competência 5.",
			"lista_de_marcacoes": [
				{
					"trecho": "prevaricação real",
					"competencia": "C1",
					"tipo": "DESVIO",
					"comentario": "Uso inadequado do termo 'prevaricação'"
				},
				{
					"trecho": "servicos adequados de saneamento básico",
					"competencia": "C2",
					"tipo": "PALAVRA-CHAVE",
					"comentario": "Palavra-chave central do tema"
				},
				{
					"trecho": "artigo, 225, da Constituição Federal de 1988, fala-se que é dever do estado garantir que a sociedade tenha acesso ao tratamento do esgoto e ao acesso por parte da sociedade ao consumo de água potável",
					"competencia": "C2",
					"tipo": "REPERTÓRIO",
					"comentario": "Repertório sociocultural: citação legislativa"
				},
				{
					"trecho": "com isso",
					"competencia": "C4",
					"tipo": "OPERADOR",
					"comentario": "Operador que estabelece relação de consequência"
				},
				{
					"trecho": "o Governo Federal",
					"competencia": "C5",
					"tipo": "AGENTE",
					"comentario": "Agente da proposta de intervenção"
				},
				{
					"trecho": "intensifique políticas públicas que levem tratamento de água, abastecimento de água potável, manejo de resíduos",
					"competencia": "C5",
					"tipo": "AÇÃO",
					"comentario": "Ação da proposta de intervenção"
				}
			],
			"resposta_aluno_marcada": "Texto integral da redação do aluno aqui, com as devidas <span class=\"marcacao\" data-competencia=\"C1\" data-tipo=\"DESVIO\" data-comentario=\"Uso inadequado do termo 'prevaricação'\">marcações</span> nos trechos correspondentes."
		},
		"status": "corrigido",
		"user_created": "u1v2w3x4-y5z6-7890-1234-567890abcdef",
		"date_updated": "2024-07-30T12:00:00.000Z",
		"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"
	}
}

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

3. Buscar Correção por `custom_id`

Este endpoint permite buscar correções utilizando o custom_id fornecido pelo cliente.

Método: GET
URL: https://os.corrigir.ai/items/mc_correcoes?filter[custom_id]={seu_custom_id}
- Substitua {seu_custom_id} pelo custom_id desejado.
Headers:
- Authorization: Bearer SEU_TOKEN_AQUI

Resposta em Caso de Sucesso (200 OK):

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

{
	"data": [
		{
			"id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
			"cliente": "c1d2e3f4-g5h6-7890-1234-567890abcdef",
			"payload": {
				"textos_apoio": "Texto de apoio para custom_id X.",
				"resposta_aluno": "Resposta do aluno para custom_id X."
			},
			"resultado": null,
			"status": "em-correcao",
			"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"
		}
		// Outras correções com o mesmo custom_id podem aparecer aqui
	]
}

4. Buscar Correções por `aluno_id`

Este endpoint permite buscar todas as correções associadas a um aluno_id específico.

Método: GET
URL: https://os.corrigir.ai/items/mc_correcoes?filter[aluno_id]={id_do_aluno}
- Substitua {id_do_aluno} pelo ID do aluno desejado.
Headers:
- Authorization: Bearer SEU_TOKEN_AQUI

Resposta em Caso de Sucesso (200 OK):

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

{
	"data": [
		{
			"id": "b2c3d4e5-f6g7-8901-2345-678901abcdef",
			"cliente": "d2e3f4g5-h6i7-8901-2345-678901abcdef",
			"payload": {
				"textos_apoio": "Texto de apoio para o aluno Y.",
				"resposta_aluno": "Resposta 1 do aluno Y."
			},
			"resultado": {
				"nota_final": 880,
				"feedback": "Bom desenvolvimento, atente-se à coesão entre os parágrafos. Verifique a marcação sobre o uso de conectivos.",
				"lista_de_marcacoes": [
					{
						"trecho": "Ademais",
						"competencia": "C4",
						"tipo": "OPERADOR",
						"comentario": "Bom uso de operador argumentativo."
					},
					{
						"trecho": "proposta de intervenção detalhada",
						"competencia": "C5",
						"tipo": "DETALHAMENTO",
						"comentario": "Excelente detalhamento na proposta."
					}
				],
				"resposta_aluno_marcada": "Aluno Y: Texto da redação com <span class=\"marcacao\" data-competencia=\"C4\" data-tipo=\"OPERADOR\">Ademais</span> e outras marcações."
			},
			"status": "corrigido",
			"user_created": "v2w3x4y5-z6a7-8901-2345-678901abcdef",
			"date_updated": "2024-07-29T14:00:00.000Z",
			"metodo": "n2o3p4q5-r6s7-8901-2345-678901abcdef",
			"custom_id": "clienteExemploID-002",
			"aluno_id": "alunoExemplo-789",
			"atividade_id": "atividadeExemplo-101",
			"date_created": "2024-07-29T11:00:00.000Z"
		},
		{
			"id": "c3d4e5f6-g7h8-9012-3456-789012abcdef",
			"cliente": "e3f4g5h6-i7j8-9012-3456-789012abcdef",
			"payload": {
				"textos_apoio": "Outro texto de apoio para o aluno Y.",
				"resposta_aluno": "Resposta 2 do aluno Y, que resultou em erro."
			},
			"resultado": {
				"erros": ["Falha ao processar competência C2: Não foi possível identificar o repertório utilizado.", "Erro interno do servidor durante a análise da C5."]
			},
			"status": "erro",
			"user_created": "w3x4y5z6-a7b8-9012-3456-789012abcdef",
			"date_updated": "2024-07-30T09:20:00.000Z",
			"metodo": "o3p4q5r6-s7t8-9012-3456-789012abcdef",
			"custom_id": "clienteExemploID-003",
			"aluno_id": "alunoExemplo-789",
			"atividade_id": "atividadeExemplo-102",
			"date_created": "2024-07-30T09:15:00.000Z"
		}
	]
}

5. Buscar Correções por `atividade_id`

Este endpoint permite buscar todas as correções associadas a uma atividade_id específica.

Método: GET
URL: https://os.corrigir.ai/items/mc_correcoes?filter[atividade_id]={id_da_atividade}
- Substitua {id_da_atividade} pelo ID da atividade desejada.
Headers:
- Authorization: Bearer SEU_TOKEN_AQUI

Resposta em Caso de Sucesso (200 OK):

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

{
	"data": [
		{
			"id": "d4e5f6g7-h8i9-0123-4567-890123abcdef",
			"cliente": "f4g5h6i7-j8k9-0123-4567-890123abcdef",
			"payload": {
				"textos_apoio": "Texto de apoio para a atividade Z.",
				"resposta_aluno": "Resposta do aluno A para a atividade Z."
			},
			"resultado": {
				"nota_final": 700,
				"feedback": "Argumentação precisa de mais desenvolvimento e exemplos concretos. A proposta de intervenção pode ser mais específica.",
				"lista_de_marcacoes": [
					{
						"trecho": "Segundo Foucault",
						"competencia": "C2",
						"tipo": "REPERTÓRIO",
						"comentario": "Repertório pertinente."
					},
					{
						"trecho": "falta de detalhamento",
						"competencia": "C3",
						"tipo": "ARGUMENTO",
						"comentario": "Argumento pouco desenvolvido."
					}
				],
				"resposta_aluno_marcada": "Redação do Aluno A para atividade Z, <span class=\"marcacao\" data-competencia=\"C3\">com trechos marcados</span> para revisão."
			},
			"status": "corrigido",
			"user_created": "x4y5z6a7-b8c9-0123-4567-890123abcdef",
			"date_updated": "2024-07-28T18:00:00.000Z",
			"metodo": "p4q5r6s7-t8u9-0123-4567-890123abcdef",
			"custom_id": "clienteExemploID-004",
			"aluno_id": "alunoExemplo-XYZ",
			"atividade_id": "atividadeExemplo-789",
			"date_created": "2024-07-28T15:30:00.000Z"
		},
		{
			"id": "e5f6g7h8-i9j0-1234-5678-901234abcdef",
			"cliente": "g5h6i7j8-k9l0-1234-5678-901234abcdef",
			"payload": {
				"textos_apoio": "Texto de apoio para a atividade Z.",
				"resposta_aluno": "Resposta do aluno B para a atividade Z."
			},
			"resultado": null,
			"status": "em-correcao",
			"user_created": "y5z6a7b8-c9d0-1234-5678-901234abcdef",
			"date_updated": null,
			"metodo": "q5r6s7t8-u9v0-1234-5678-901234abcdef",
			"custom_id": "clienteExemploID-005",
			"aluno_id": "alunoExemplo-LMN",
			"atividade_id": "atividadeExemplo-789",
			"date_created": "2024-07-29T10:45:00.000Z"
		}
	]
}

Fluxo de Processamento da Correção

Criação e Enfileiramento: Ao realizar uma chamada bem-sucedida ao endpoint POST /api/correcao-enem, uma nova correção é criada e imediatamente colocada em uma fila de processamento. Neste momento, a correção recebe o status novo.
Início do Processamento: Quando a correção chega à sua vez na fila, o sistema inicia o seu processamento. O status da correção é então atualizado de novo para em-correcao.
Conclusão do Processamento: Após a tentativa de correção, o status final será:
- corrigido: Se o processamento for bem-sucedido. Os detalhes da correção estarão disponíveis no campo resultado.
- erro: Se ocorrer alguma falha durante o processamento. Detalhes sobre o erro estarão disponíveis no campo resultado.erros.

Tempo Estimado e Consulta de Status:

O tempo estimado para o processamento completo de uma correção é de aproximadamente 5 minutos a partir do momento em que entra no status em-correcao. No entanto, esse tempo pode variar dependendo da carga do sistema.

Para verificar o status atual de uma correção e obter o resultado final, o cliente deve utilizar os endpoints de consulta GET (Buscar Correção por ID, Buscar Correção por custom_id, etc.). Recomenda-se implementar um mecanismo de polling para consultar periodicamente o status da correção até que ela atinja o estado corrigido ou erro.

Tipos de Status da Correção

novo: Novo - A correção foi recebida e está na fila para processamento. O campo resultado será null.
em-correcao: Em Correção - A correção está atualmente sendo processada. O campo resultado será null.
corrigido: Corrigido - A correção foi concluída e o resultado está disponível no campo resultado (ver exemplos dos endpoints GET).
erro: Erro - Ocorreu um erro durante o processamento da correção. O campo resultado conterá um objeto com uma chave erros, que é um array de strings descrevendo as falhas. Ex: {"erros": ["Falha X", "Falha Y"]}.

Respostas de Erro Comuns

Abaixo estão exemplos de respostas de erro que a API pode retornar.

400 Bad Request (Erro de Validação)

Este erro ocorre quando os dados enviados na requisição não passam nas validações do servidor. Um exemplo comum é tentar criar uma correção com um custom_id que já existe.

Exemplo de Resposta:

{
	"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"
			}
		}
	]
}

Neste caso, a mensagem indica que o custom_id fornecido já está em uso e precisa ser único.

403 Forbidden (Erro de Permissão)

Este erro é retornado quando o token de autenticação fornecido não tem as permissões necessárias para acessar o recurso solicitado, ou se o token for inválido/expirado.

Exemplo de Resposta:

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

Verifique se o token de autenticação está correto e possui as permissões adequadas para a operação desejada.

Baixar coleção Postman

Postman Collection para Integração

Api Integracao

Autenticação

Endpoints da API

1. Criar Correção

2. Buscar Correção por ID

3. Buscar Correção por `custom_id`

4. Buscar Correções por `aluno_id`

5. Buscar Correções por `atividade_id`

Fluxo de Processamento da Correção

Tipos de Status da Correção

Respostas de Erro Comuns

400 Bad Request (Erro de Validação)

403 Forbidden (Erro de Permissão)

Baixar coleção Postman

Postman Collection para Integração

Api Integracao

Autenticação

Endpoints da API

1. Criar Correção

2. Buscar Correção por ID

3. Buscar Correção por custom_id

4. Buscar Correções por aluno_id

5. Buscar Correções por atividade_id

Fluxo de Processamento da Correção

Tipos de Status da Correção

Respostas de Erro Comuns

400 Bad Request (Erro de Validação)

403 Forbidden (Erro de Permissão)

3. Buscar Correção por `custom_id`

4. Buscar Correções por `aluno_id`

5. Buscar Correções por `atividade_id`