Portal de prova: liberar e enviar a nota

Quando o vestibular é aplicado num portal de prova, seu ou de um parceiro (a aplicadora), o candidato chega ao portal pelo botão da prova na área dele. O portal fala com a API duas vezes: para saber se libera a prova e para devolver a nota. A nota que alcança o corte aprova na hora.

Antes de começar, o vestibular precisa estar no edital com Prova exigida neste edital, o Endereço da prova (o do seu portal), a nota de corte, a janela e o limite de tentativas (como configurar).

Uma chave só para o portal de prova — Toda chave com o módulo de Processo seletivo lê a inscrição e envia nota; não há permissão separada. Gere uma chave exclusiva para o portal: dá para revogá-la sem derrubar a sua página de inscrição.

1 · O candidato chega com o número da inscrição

O botão abre o Endereço da prova do edital com o número da inscrição em applicationId:

https://prova.example.com/vestibular?turma=A&applicationId=cmu4ucd25000akgmbcxc4gg1d

A Workfuse acrescenta o parâmetro, e o que o endereço já tinha fica como está.
O link é o mesmo na API, em journey[].exam.url. Se você montou a sua própria área do candidato (Consultar a situação), mostre esse link e o número chega igual.
Ele só aparece dentro da janela da prova e com tentativa sobrando.
Só o número vai na URL. CPF e e-mail nunca: endereço de página acaba em log.

O número identifica, não autentica — Quem tiver o link chega ao seu portal com aquele número. Antes de liberar, confira quem está ali com o seu próprio acesso: o login do portal, ou o CPF e a data de nascimento comparados com os da inscrição.

2 · Confira se a inscrição pode fazer a prova

Do seu servidor, leia a inscrição pelo número que chegou:

curl "API_BASE/public/v1/admissions/applications/cmu4ucd25000akgmbcxc4gg1d" \
  -H "Authorization: Bearer wf_sua_chave_aqui"

{
  "id": "cmu4ucd25000akgmbcxc4gg1d",
  "status": "UNDER_REVIEW",
  "journey": [
    {
      "kind": "EVALUATION",
      "state": "CURRENT",
      "exam": {
        "url": "https://prova.example.com/vestibular?turma=A&applicationId=cmu4ucd25000akgmbcxc4gg1d",
        "opensAt": "2026-10-01T12:00:00.000Z",
        "closesAt": "2026-10-01T16:00:00.000Z"
      },
      "evaluation": { "result": "PENDING", "attemptsUsed": 0, "attemptLimit": 3, "attemptsRemaining": 3, "…": "…" }
    }
  ],
  "…": "…"
}

Libere a prova quando a etapa EVALUATION trouxer exam.url preenchida. É a mesma regra que mostra o botão ao candidato: a inscrição está em avaliação, a janela está aberta e sobra tentativa. Sem exam.url, não libere; status e evaluation dizem o porquê:

O que a API responde	O que aconteceu
`404`	o número não existe na instituição da chave
`status: "FEE_PENDING"`	o edital libera a prova só depois do pagamento, e a taxa não foi paga
`state: "CURRENT"` e `exam.opensAt` no futuro	a janela ainda não abriu
`evaluation.examPeriodEnded: true`	a janela fechou
`evaluation.result: "APPROVED"`	já foi aprovado: não há prova a fazer
`status` final (`REJECTED`, `CANCELLED`, `EXPIRED`, `ABSENT`)	a inscrição terminou

Leia de novo a cada acesso, sem guardar a decisão: a janela abre e fecha com o relógio, e isso não mexe no updatedAt.

3 · Envie a nota de cada tentativa

Com o mesmo número:

curl -X POST "API_BASE/public/v1/admissions/applications/cmu4ucd25000akgmbcxc4gg1d/exam-attempts" \
  -H "Authorization: Bearer wf_sua_chave_aqui" \
  -H "Content-Type: application/json" \
  -d '{ "attemptNumber": 1, "score": 7.4 }'

Campo	Regra
`attemptNumber`	inteiro de `1` a `2147483647`: o número da tentativa no seu sistema. É identidade, não posição
`score`	de `0` a `10`, com até duas casas. Fora disso é recusado, nunca convertido: `85` não vira `8.5`

{ "applicationId": "cmu4ucd25000akgmbcxc4gg1d", "outcome": "APPLIED", "status": "APPROVED", "attemptsUsed": 1, "attemptLimit": 3 }

status é a situação depois da nota: com corte 5, o 7,4 aprovou na hora. A tentativa que esgota o limite abaixo do corte reprova (REJECTED). attemptLimit é o limite que a inscrição guardou no envio; mudar o edital depois não o altera.

A ordem das respostas é contrato: a primeira condição que casa responde.

Ordem	Resposta	Quando
1	`400`	falta `attemptNumber` ou `score`, ou o tipo não confere
2	`404` `CANDIDACY_NOT_FOUND`	a inscrição não existe na instituição da chave
3	`422` `SCORE_OUT_OF_SCALE` · `SCORE_PRECISION_EXCEEDED`	nota fora de 0 a 10 (`details` traz `min` e `max`) · mais de duas casas
4	`200` `DISCARDED`	a inscrição foi cancelada: a nota é descartada, sem gravar
5	`409` `CANDIDACY_NOT_UNDER_REVIEW` · `EXAM_NOT_REQUIRED`	a inscrição não está em avaliação (`details` traz a situação) · a forma não aplica prova neste edital
6	`200` `DUPLICATE`	esse número de tentativa já chegou. Nada muda
7	`200` `APPLIED`	a tentativa conta, e a nota é comparada ao corte

As regras que decidem a nota que vale:

O primeiro envio de um número vence, enquanto a inscrição está em avaliação. Reenviar é seguro: DUPLICATE não soma tentativa nem troca a nota. Corrigir uma nota é com a secretaria, no painel. Depois do resultado, o reenvio responde 409.
Conta o número, não a ordem. As tentativas 1 e 4 são duas tentativas.
Vale a maior nota entre a última lançada pela secretaria e a melhor tentativa recebida depois dela. Sem lançamento manual, vale a melhor tentativa.
A janela fecha a inscrição em até 15 minutos. Quando a prova fecha, a plataforma encerra as inscrições que ainda estão em avaliação, e a nota que chega depois disso responde 409. Até o encerramento, uma nota atrasada ainda conta, mas não conte com essa folga: envie assim que a prova for corrigida.

A resposta já traz a situação. O detalhe (a nota que vale, o corte, quanto faltou e as tentativas) está em journey[].evaluation, na inscrição pelo número.

A lista de quem pode fazer a prova

Para o portal que precisa dos candidatos antes da prova, para criar os acessos, por exemplo:

curl "API_BASE/public/v1/admissions/exam-candidates?admissionNoticeId=cmu4sh97w00chp0mb551lq2jq" \
  -H "Authorization: Bearer wf_sua_chave_aqui"

{
  "data": [
    {
      "applicationId": "cmu4ucd25000akgmbcxc4gg1d",
      "candidateName": "Bianca Teixeira",
      "candidateCpf": "39053344705",
      "candidateEmail": "bianca.teixeira@exemplo.test",
      "admissionNotice": { "id": "cmu4sh97w00chp0mb551lq2jq", "name": "Processo Seletivo 2027.1" },
      "entryFormName": "Vestibular",
      "courseName": "Administração",
      "attemptsUsed": 0,
      "attemptLimit": 3
    }
  ]
}

Entra na lista a inscrição em avaliação (UNDER_REVIEW), no vestibular com prova exigida e com tentativa restante, de editais abertos ou encerrados. admissionNoticeId é opcional e estreita para um edital. A lista traz CPF e e-mail em claro.


a nota	não vem na lista. Ela está na inscrição, pelo número
`courseName`	o curso da 1ª opção. A 2ª opção faz a mesma prova
a janela da prova	não filtra: quem espera a prova abrir já aparece. Na hora de liberar, vale o passo 2
quem sai da lista	quem foi aprovado, esgotou as tentativas, cancelou ou foi encerrado pela janela ou pelo prazo. Com a prova liberada só depois do pagamento, a inscrição entra quando a taxa é paga
paginação	não há: a lista vem inteira, na ordem do envio
edital de outra instituição	`{ "data": [] }`

Outras formas de ingresso

Forma (`evaluationType`)	Como a nota chega
Vestibular com prova (`EXAM_SCORE`)	por esta página, tentativa a tentativa
Nota do ENEM (`ENEM_SCORE`)	no próprio envio da inscrição, em `formAnswers.ENEM_SCORE`: de 0 a 1000, com até duas casas. A inscrição é decidida na hora
as formas sem nota (`DOCUMENT_REVIEW`, `EXTERNAL_CALL`, `AUTOMATIC`)	não há nota pela API: a secretaria decide no painel

1 · O candidato chega com o número da inscrição​

2 · Confira se a inscrição pode fazer a prova​

3 · Envie a nota de cada tentativa​

A lista de quem pode fazer a prova​

Outras formas de ingresso​

1 · O candidato chega com o número da inscrição

2 · Confira se a inscrição pode fazer a prova

3 · Envie a nota de cada tentativa

A lista de quem pode fazer a prova

Outras formas de ingresso