Alunos e matrículas

Este guia mostra como manter alunos e matrículas iguais nos dois sistemas, sem duplicar ninguém. Os campos completos de cada rota estão na Referência.

O catálogo: os números que a matrícula usa#

Matricular pede o número do curso (ou trilha), da turma e do plano de pagamento. Eles vêm do catálogo (catalog:read):

Guarde esses números na configuração da integração. Eles mudam pouco.

Código externo: o seu número dentro do EduPay#

Aluno e matrícula têm o campo external_id, com o código do registro no seu sistema (até 100 caracteres, único na escola). Grave-o ao criar e use-o para achar o registro depois:

curl "https://edupay.estudiosite.com/api/v1/students?external_id=ALU-0091" \
  -H "Authorization: Bearer $EDUPAY_KEY"

A escola também consegue preencher o código no painel, na tela do aluno e da matrícula.

Sincronizar com updated_since#

Para trazer só o que mudou desde a última vez, guarde o horário de início de cada sincronização e passe-o na próxima:

curl "https://edupay.estudiosite.com/api/v1/students?updated_since=2026-10-29T12:00:00Z&limit=200" \
  -H "Authorization: Bearer $EDUPAY_KEY"

Percorra as páginas com cursor até meta.has_more ser false. Funciona em alunos, matrículas, parcelas e no catálogo. Para saber na hora, sem consultar de tempos em tempos, use os Avisos automáticos.

Alunos#

Consultar (students:read): GET /students aceita email (sem diferença de maiúsculas), document_number (com ou sem pontuação), external_id e status. GET /students/{id} traz o cadastro completo, com o endereço em address.

Cadastrar (students:write): POST /students. O aluno nasce com a conta de acesso ao portal e recebe o e-mail de boas-vindas com a senha temporária. Mande "send_welcome_email": false para não enviar.

curl -X POST https://edupay.estudiosite.com/api/v1/students \
  -H "Authorization: Bearer $EDUPAY_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 4b0c8f2e-6a7d-4f1e-9c3b-1d2e3f4a5b6c" \
  -d '{
    "external_id": "ALU-0091",
    "full_name": "Maria Souza",
    "email": "maria@exemplo.com",
    "document_number": "52998224725",
    "phone": "11999990000",
    "address": { "zip_code": "01310-100", "line": "Av. Paulista", "number": "1000",
                 "neighborhood": "Bela Vista", "city": "São Paulo", "state": "SP", "country": "BR" }
  }'

Valem as mesmas regras do cadastro no painel, e elas mudam de escola para escola:

• CPF, telefone e endereço podem ser obrigatórios; o e-mail é obrigatório quando o aluno entra no portal pelo e-mail;
• a escola pode ligar a conferência do CPF;
• CPF e external_id não se repetem na escola. CPF de aluno apagado também é recusado: a escola restaura o cadastro antigo no painel;
• o plano da escola pode ter limite de alunos (403 com code student_limit_reached).

Erros de campo voltam em errors, com os nomes da API (address.line, e não o nome da coluna).

Alterar: PATCH /students/{id} muda só o que foi enviado. Se o aluno ainda não tinha conta no portal e o dado de login passa a existir, a conta é criada e o e-mail de boas-vindas sai — igual à edição no painel.

Abrir o portal já conectado (portal:link): POST /students/{id}/portal-link devolve um url que entra no portal do aluno sem senha. Vale 5 minutos e uma vez só: gere na hora do clique, nunca deixe salvo numa página. O aluno precisa estar ativo, ter e-mail e conta no portal. No primeiro acesso, o portal pede para ele definir uma senha nova.

Matrículas#

Consultar (enrollments:read): GET /enrollments aceita student_id, external_id, offering_id, trail_id, cohort_id e status. Com include=student,installments,contract vêm os dados relacionados (cada um com a permissão da sua área). GET /enrollments/{id}/contract traz a situação do contrato e GET /enrollments/{id}/contract/pdf baixa o PDF.

Criar (enrollments:write): POST /enrollments, sempre com Idempotency-Key. O aluno vem por student_id ou é cadastrado no mesmo pedido em student (mesmos campos do cadastro). O produto vem por offering_id ou trail_id.

curl -X POST "https://edupay.estudiosite.com/api/v1/enrollments?include=installments" \
  -H "Authorization: Bearer $EDUPAY_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: PED-2026-1187" \
  -d '{
    "external_id": "PED-2026-1187",
    "student_id": 532,
    "offering_id": 14,
    "cohort_id": 3,
    "financial_plan_id": 2,
    "payment_method": "pix"
  }'

A matrícula segue exatamente o caminho da matrícula feita no painel:

1. gera as parcelas pelo plano de pagamento e, se houver modelo, o contrato para assinatura;
2. se a turma estiver ligada a uma turma do Moodle, coloca o aluno no Moodle na hora;
3. emite as cobranças: o link de cartão sai na hora; boleto e PIX saem quando o vencimento entra na janela de emissão da escola (poucos dias antes), como no painel;
4. avisa o aluno por e-mail.

Detalhes:

• Valores em centavos. Sem base_value, vale o preço do curso (ou a soma dos cursos da trilha). Sem enrollment_fee, vale a taxa do plano.
• A forma de pagamento precisa ser aceita pelo plano e pela conta de recebimento da escola. Se não for, 422 em payment_method.
• Curso, trilha e plano precisam estar ativos, e a turma, aberta.
• Matrícula repetida: se o aluno já tem matrícula viva (aguardando contrato, aguardando pagamento ou ativa) no mesmo curso ou trilha, a resposta é 409 com code enrollment_conflict e o número da existente em existing_enrollment_id.
• A matrícula fica no nome de quem criou a chave no painel.

Cancelar: POST /enrollments/{id}/cancel, com reason opcional (student_withdrawal, transfer, default ou administrative). As parcelas em aberto são canceladas junto com as cobranças, o aluno é avisado e sai do Moodle. A multa de rescisão continua só pelo painel. Boleto ainda dentro da validade não pode ser cancelado no banco e segue pagável até vencer: meta.charges_still_payable diz quantos.

Situações da matrícula#

Repetir sem duplicar#

Rede cai, tempo esgota, o sistema reinicia no meio. Para isso existe o cabeçalho Idempotency-Key: mande um código único por pedido (um UUID ou o número do pedido no seu sistema). Repetir o mesmo pedido com a mesma chave em até 24 horas devolve a primeira resposta, com o cabeçalho Idempotent-Replayed: true, e nada é gravado de novo. Detalhes em Erros e limites.