Referência · Documentação da API

Todas as rotas da API, geradas da especificação OpenAPI 1.0.0-beta. Os exemplos usam o endereço deste servidor; guarde a chave na variável EDUPAY_KEY.

Baixar openapi.json

Conta

A escola dona da chave.

GET /api/v1/me

A escola dona da chave

Qualquer chave

Dados da escola dona da chave e da própria chave. Qualquer chave válida pode chamar; serve para testar a conexão.

Exemplo

curl https://edupay.estudiosite.com/api/v1/me \
  -H "Authorization: Bearer $EDUPAY_KEY"

Respostas

200 A escola e a chave. application/json

{
    "data": {
        "school": {
            "name": "Colégio Modelo",
            "country": "BR",
            "currency": "BRL",
            "timezone": "America/Sao_Paulo"
        },
        "token": {
            "name": "ERP Financeiro",
            "prefix": "edp_7d2e9f01...",
            "scopes": [
                "students:read",
                "billing:read"
            ],
            "expires_at": null
        }
    }
}

401 Chave ausente, inválida, vencida ou revogada. application/problem+json

{
    "type": "about:blank",
    "title": "Unauthorized",
    "status": 401,
    "detail": "Chave de acesso ausente, inválida, vencida ou revogada.",
    "code": "unauthenticated"
}

403 API desligada na escola (code api_disabled) ou chave sem a permissão necessária (code insufficient_scope, com a lista em scopes). application/problem+json

{
    "type": "about:blank",
    "title": "Forbidden",
    "status": 403,
    "detail": "A chave não tem a permissão necessária: students:read.",
    "code": "insufficient_scope",
    "scopes": [
        "students:read"
    ]
}

429 Limite de chamadas atingido. application/problem+json

{
    "type": "about:blank",
    "title": "Too Many Requests",
    "status": 429,
    "detail": "Limite de chamadas atingido. Tente de novo depois do tempo indicado em Retry-After.",
    "code": "rate_limited"
}

GET /api/v1/openapi.json

Especificação OpenAPI

Sem chave de acesso

Esta especificação, em JSON (OpenAPI 3.1), com o endereço deste servidor. Aberta, sem chave: serve para gerar cliente, importar no Postman ou Insomnia e ler em ferramentas de IA.

Exemplo

curl https://edupay.estudiosite.com/api/v1/openapi.json

Respostas

200 A especificação. application/json

Catálogo

O que a escola vende (catalog:read).

GET /api/v1/offerings

Listar cursos e ofertas

Chave com catalog:read

Parâmetros

Nome	Tipo	Descrição
`limit`na query · opcional	`integer`	Itens por página (1 a 200).
`cursor`na query · opcional	`string`	O meta.next_cursor da página anterior.
`updated_since`na query · opcional	`string`	Só registros alterados desde esta data e hora (ISO 8601).
`status`na query · opcional	`string (active, inactive)`
`type`na query · opcional	`string (postgrad, undergrad, school, free_course)`
`code`na query · opcional	`string`	Código da oferta, exato.

Exemplo

curl https://edupay.estudiosite.com/api/v1/offerings \
  -H "Authorization: Bearer $EDUPAY_KEY"

Respostas

200 Página de ofertas. application/json

400 Cursor inválido: recomece a lista sem cursor. application/problem+json

{
    "type": "about:blank",
    "title": "Bad Request",
    "status": 400,
    "detail": "Cursor inválido. Recomece a lista sem o parâmetro cursor.",
    "code": "invalid_cursor"
}

401 Chave ausente, inválida, vencida ou revogada. application/problem+json

{
    "type": "about:blank",
    "title": "Unauthorized",
    "status": 401,
    "detail": "Chave de acesso ausente, inválida, vencida ou revogada.",
    "code": "unauthenticated"
}

403 API desligada na escola (code api_disabled) ou chave sem a permissão necessária (code insufficient_scope, com a lista em scopes). application/problem+json

{
    "type": "about:blank",
    "title": "Forbidden",
    "status": 403,
    "detail": "A chave não tem a permissão necessária: students:read.",
    "code": "insufficient_scope",
    "scopes": [
        "students:read"
    ]
}

422 Parâmetro inválido (detalhe por campo em errors). application/problem+json

{
    "type": "about:blank",
    "title": "Unprocessable Content",
    "status": 422,
    "detail": "Alguns campos estão inválidos.",
    "code": "validation_failed",
    "errors": {
        "limit": [
            "O campo limit não pode ser superior a 200."
        ]
    }
}

429 Limite de chamadas atingido. application/problem+json

{
    "type": "about:blank",
    "title": "Too Many Requests",
    "status": 429,
    "detail": "Limite de chamadas atingido. Tente de novo depois do tempo indicado em Retry-After.",
    "code": "rate_limited"
}

GET /api/v1/offerings/{offering}

Uma oferta

Chave com catalog:read

Parâmetros

Nome	Tipo	Descrição
`offering`no caminho · obrigatório	`integer`

Exemplo

curl https://edupay.estudiosite.com/api/v1/offerings/123 \
  -H "Authorization: Bearer $EDUPAY_KEY"

Respostas

200 A oferta. application/json

401 Chave ausente, inválida, vencida ou revogada. application/problem+json

{
    "type": "about:blank",
    "title": "Unauthorized",
    "status": 401,
    "detail": "Chave de acesso ausente, inválida, vencida ou revogada.",
    "code": "unauthenticated"
}

403 API desligada na escola (code api_disabled) ou chave sem a permissão necessária (code insufficient_scope, com a lista em scopes). application/problem+json

{
    "type": "about:blank",
    "title": "Forbidden",
    "status": 403,
    "detail": "A chave não tem a permissão necessária: students:read.",
    "code": "insufficient_scope",
    "scopes": [
        "students:read"
    ]
}

404 Registro não existe nesta escola. application/problem+json

{
    "type": "about:blank",
    "title": "Not Found",
    "status": 404,
    "detail": "Registro não encontrado.",
    "code": "not_found"
}

429 Limite de chamadas atingido. application/problem+json

{
    "type": "about:blank",
    "title": "Too Many Requests",
    "status": 429,
    "detail": "Limite de chamadas atingido. Tente de novo depois do tempo indicado em Retry-After.",
    "code": "rate_limited"
}

GET /api/v1/trails

Listar trilhas

Chave com catalog:read

Trilhas com as ofertas que fazem parte de cada uma, na ordem em que o aluno cursa.

Parâmetros

Nome	Tipo	Descrição
`limit`na query · opcional	`integer`	Itens por página (1 a 200).
`cursor`na query · opcional	`string`	O meta.next_cursor da página anterior.
`updated_since`na query · opcional	`string`	Só registros alterados desde esta data e hora (ISO 8601).
`status`na query · opcional	`string (active, inactive)`

Exemplo

curl https://edupay.estudiosite.com/api/v1/trails \
  -H "Authorization: Bearer $EDUPAY_KEY"

Respostas

200 Página de trilhas. application/json

400 Cursor inválido: recomece a lista sem cursor. application/problem+json

{
    "type": "about:blank",
    "title": "Bad Request",
    "status": 400,
    "detail": "Cursor inválido. Recomece a lista sem o parâmetro cursor.",
    "code": "invalid_cursor"
}

401 Chave ausente, inválida, vencida ou revogada. application/problem+json

{
    "type": "about:blank",
    "title": "Unauthorized",
    "status": 401,
    "detail": "Chave de acesso ausente, inválida, vencida ou revogada.",
    "code": "unauthenticated"
}

403 API desligada na escola (code api_disabled) ou chave sem a permissão necessária (code insufficient_scope, com a lista em scopes). application/problem+json

{
    "type": "about:blank",
    "title": "Forbidden",
    "status": 403,
    "detail": "A chave não tem a permissão necessária: students:read.",
    "code": "insufficient_scope",
    "scopes": [
        "students:read"
    ]
}

422 Parâmetro inválido (detalhe por campo em errors). application/problem+json

{
    "type": "about:blank",
    "title": "Unprocessable Content",
    "status": 422,
    "detail": "Alguns campos estão inválidos.",
    "code": "validation_failed",
    "errors": {
        "limit": [
            "O campo limit não pode ser superior a 200."
        ]
    }
}

429 Limite de chamadas atingido. application/problem+json

{
    "type": "about:blank",
    "title": "Too Many Requests",
    "status": 429,
    "detail": "Limite de chamadas atingido. Tente de novo depois do tempo indicado em Retry-After.",
    "code": "rate_limited"
}

GET /api/v1/cohorts

Listar turmas

Chave com catalog:read

Parâmetros

Nome	Tipo	Descrição
`limit`na query · opcional	`integer`	Itens por página (1 a 200).
`cursor`na query · opcional	`string`	O meta.next_cursor da página anterior.
`updated_since`na query · opcional	`string`	Só registros alterados desde esta data e hora (ISO 8601).
`status`na query · opcional	`string (open, closed, archived)`

Exemplo

curl https://edupay.estudiosite.com/api/v1/cohorts \
  -H "Authorization: Bearer $EDUPAY_KEY"

Respostas

200 Página de turmas. application/json

400 Cursor inválido: recomece a lista sem cursor. application/problem+json

{
    "type": "about:blank",
    "title": "Bad Request",
    "status": 400,
    "detail": "Cursor inválido. Recomece a lista sem o parâmetro cursor.",
    "code": "invalid_cursor"
}

401 Chave ausente, inválida, vencida ou revogada. application/problem+json

{
    "type": "about:blank",
    "title": "Unauthorized",
    "status": 401,
    "detail": "Chave de acesso ausente, inválida, vencida ou revogada.",
    "code": "unauthenticated"
}

403 API desligada na escola (code api_disabled) ou chave sem a permissão necessária (code insufficient_scope, com a lista em scopes). application/problem+json

{
    "type": "about:blank",
    "title": "Forbidden",
    "status": 403,
    "detail": "A chave não tem a permissão necessária: students:read.",
    "code": "insufficient_scope",
    "scopes": [
        "students:read"
    ]
}

422 Parâmetro inválido (detalhe por campo em errors). application/problem+json

{
    "type": "about:blank",
    "title": "Unprocessable Content",
    "status": 422,
    "detail": "Alguns campos estão inválidos.",
    "code": "validation_failed",
    "errors": {
        "limit": [
            "O campo limit não pode ser superior a 200."
        ]
    }
}

429 Limite de chamadas atingido. application/problem+json

{
    "type": "about:blank",
    "title": "Too Many Requests",
    "status": 429,
    "detail": "Limite de chamadas atingido. Tente de novo depois do tempo indicado em Retry-After.",
    "code": "rate_limited"
}

GET /api/v1/financial-plans

Listar planos de pagamento

Chave com catalog:read

Formas de pagamento aceitas, número de parcelas, taxa de matrícula, juros e multa. Os campos de desconto do plano não são devolvidos: hoje eles não são aplicados na cobrança.

Parâmetros

Nome	Tipo	Descrição
`limit`na query · opcional	`integer`	Itens por página (1 a 200).
`cursor`na query · opcional	`string`	O meta.next_cursor da página anterior.
`updated_since`na query · opcional	`string`	Só registros alterados desde esta data e hora (ISO 8601).
`status`na query · opcional	`string (active, inactive)`

Exemplo

curl https://edupay.estudiosite.com/api/v1/financial-plans \
  -H "Authorization: Bearer $EDUPAY_KEY"

Respostas

200 Página de planos. application/json

400 Cursor inválido: recomece a lista sem cursor. application/problem+json

{
    "type": "about:blank",
    "title": "Bad Request",
    "status": 400,
    "detail": "Cursor inválido. Recomece a lista sem o parâmetro cursor.",
    "code": "invalid_cursor"
}

401 Chave ausente, inválida, vencida ou revogada. application/problem+json

{
    "type": "about:blank",
    "title": "Unauthorized",
    "status": 401,
    "detail": "Chave de acesso ausente, inválida, vencida ou revogada.",
    "code": "unauthenticated"
}

403 API desligada na escola (code api_disabled) ou chave sem a permissão necessária (code insufficient_scope, com a lista em scopes). application/problem+json

{
    "type": "about:blank",
    "title": "Forbidden",
    "status": 403,
    "detail": "A chave não tem a permissão necessária: students:read.",
    "code": "insufficient_scope",
    "scopes": [
        "students:read"
    ]
}

422 Parâmetro inválido (detalhe por campo em errors). application/problem+json

{
    "type": "about:blank",
    "title": "Unprocessable Content",
    "status": 422,
    "detail": "Alguns campos estão inválidos.",
    "code": "validation_failed",
    "errors": {
        "limit": [
            "O campo limit não pode ser superior a 200."
        ]
    }
}

429 Limite de chamadas atingido. application/problem+json

{
    "type": "about:blank",
    "title": "Too Many Requests",
    "status": 429,
    "detail": "Limite de chamadas atingido. Tente de novo depois do tempo indicado em Retry-After.",
    "code": "rate_limited"
}

GET /api/v1/sales-pages

Listar páginas de vendas publicadas

Chave com catalog:read

Só páginas publicadas, com o link público onde o interessado se matricula e o preço.

Parâmetros

Nome	Tipo	Descrição
`limit`na query · opcional	`integer`	Itens por página (1 a 200).
`cursor`na query · opcional	`string`	O meta.next_cursor da página anterior.
`updated_since`na query · opcional	`string`	Só registros alterados desde esta data e hora (ISO 8601).

Exemplo

curl https://edupay.estudiosite.com/api/v1/sales-pages \
  -H "Authorization: Bearer $EDUPAY_KEY"

Respostas

200 Página de páginas de vendas. application/json

400 Cursor inválido: recomece a lista sem cursor. application/problem+json

{
    "type": "about:blank",
    "title": "Bad Request",
    "status": 400,
    "detail": "Cursor inválido. Recomece a lista sem o parâmetro cursor.",
    "code": "invalid_cursor"
}

401 Chave ausente, inválida, vencida ou revogada. application/problem+json

{
    "type": "about:blank",
    "title": "Unauthorized",
    "status": 401,
    "detail": "Chave de acesso ausente, inválida, vencida ou revogada.",
    "code": "unauthenticated"
}

403 API desligada na escola (code api_disabled) ou chave sem a permissão necessária (code insufficient_scope, com a lista em scopes). application/problem+json

{
    "type": "about:blank",
    "title": "Forbidden",
    "status": 403,
    "detail": "A chave não tem a permissão necessária: students:read.",
    "code": "insufficient_scope",
    "scopes": [
        "students:read"
    ]
}

422 Parâmetro inválido (detalhe por campo em errors). application/problem+json

{
    "type": "about:blank",
    "title": "Unprocessable Content",
    "status": 422,
    "detail": "Alguns campos estão inválidos.",
    "code": "validation_failed",
    "errors": {
        "limit": [
            "O campo limit não pode ser superior a 200."
        ]
    }
}

429 Limite de chamadas atingido. application/problem+json

{
    "type": "about:blank",
    "title": "Too Many Requests",
    "status": 429,
    "detail": "Limite de chamadas atingido. Tente de novo depois do tempo indicado em Retry-After.",
    "code": "rate_limited"
}

Alunos

Cadastro dos alunos (students:read, students:write), resumo financeiro (billing:read) e link de entrada no portal (portal:link).

GET /api/v1/students

Listar alunos

Chave com students:read

Parâmetros

Nome	Tipo	Descrição
`limit`na query · opcional	`integer`	Itens por página (1 a 200).
`cursor`na query · opcional	`string`	O meta.next_cursor da página anterior.
`updated_since`na query · opcional	`string`	Só registros alterados desde esta data e hora (ISO 8601).
`email`na query · opcional	`string`	E-mail exato, sem diferença de maiúsculas.
`document_number`na query · opcional	`string`	CPF ou documento, com ou sem pontuação.
`external_id`na query · opcional	`string`	Código do aluno no sistema da escola.
`status`na query · opcional	`string (active, inactive)`

Exemplo

curl https://edupay.estudiosite.com/api/v1/students \
  -H "Authorization: Bearer $EDUPAY_KEY"

Respostas

200 Página de alunos. application/json

400 Cursor inválido: recomece a lista sem cursor. application/problem+json

{
    "type": "about:blank",
    "title": "Bad Request",
    "status": 400,
    "detail": "Cursor inválido. Recomece a lista sem o parâmetro cursor.",
    "code": "invalid_cursor"
}

401 Chave ausente, inválida, vencida ou revogada. application/problem+json

{
    "type": "about:blank",
    "title": "Unauthorized",
    "status": 401,
    "detail": "Chave de acesso ausente, inválida, vencida ou revogada.",
    "code": "unauthenticated"
}

403 API desligada na escola (code api_disabled) ou chave sem a permissão necessária (code insufficient_scope, com a lista em scopes). application/problem+json

{
    "type": "about:blank",
    "title": "Forbidden",
    "status": 403,
    "detail": "A chave não tem a permissão necessária: students:read.",
    "code": "insufficient_scope",
    "scopes": [
        "students:read"
    ]
}

422 Parâmetro inválido (detalhe por campo em errors). application/problem+json

{
    "type": "about:blank",
    "title": "Unprocessable Content",
    "status": 422,
    "detail": "Alguns campos estão inválidos.",
    "code": "validation_failed",
    "errors": {
        "limit": [
            "O campo limit não pode ser superior a 200."
        ]
    }
}

429 Limite de chamadas atingido. application/problem+json

{
    "type": "about:blank",
    "title": "Too Many Requests",
    "status": 429,
    "detail": "Limite de chamadas atingido. Tente de novo depois do tempo indicado em Retry-After.",
    "code": "rate_limited"
}

POST /api/v1/students

Cadastrar aluno

Chave com students:write

Cria o aluno e a conta de acesso ao portal, como o cadastro do painel. O login segue a configuração da escola (CPF ou e-mail).

Parâmetros

Nome	Tipo	Descrição
`Idempotency-Key`no cabeçalho · opcional	`string`	Código único deste pedido (até 255 caracteres visíveis; um UUID serve). Repetir com a mesma chave em 24 h devolve a primeira resposta.

Campos do corpo (JSON)

Nome	Tipo	Descrição
`external_id`opcional	`string \| null`	Código do aluno no sistema da escola. Único na escola.
`full_name`obrigatório	`string`
`email`opcional	`string \| null`
`phone`opcional	`string \| null`
`document_number`opcional	`string \| null`	CPF (conferido quando a escola liga a validação). Único na escola.
`birth_date`opcional	`string \| null`
`status`opcional	`string (active, inactive)`
`address`opcional	`object`
`send_welcome_email`opcional	`boolean`	Envia ao aluno o e-mail com login e senha temporária do portal. Com false, a conta é criada sem e-mail (use o link de entrada ou o "esqueci a senha").

Exemplo

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

Respostas

201 Aluno cadastrado. application/json

400 Idempotency-Key ausente onde é exigida (idempotency_key_required) ou fora do formato (idempotency_key_invalid). application/problem+json

{
    "type": "about:blank",
    "title": "Bad Request",
    "status": 400,
    "detail": "Este pedido exige o cabeçalho Idempotency-Key, com um código único por pedido (por exemplo, um UUID).",
    "code": "idempotency_key_required"
}

401 Chave ausente, inválida, vencida ou revogada. application/problem+json

{
    "type": "about:blank",
    "title": "Unauthorized",
    "status": 401,
    "detail": "Chave de acesso ausente, inválida, vencida ou revogada.",
    "code": "unauthenticated"
}

403 API desligada, chave sem a permissão (insufficient_scope) ou limite de alunos do plano atingido (student_limit_reached). application/problem+json

{
    "type": "about:blank",
    "title": "Forbidden",
    "status": 403,
    "detail": "O plano da escola permite até 500 alunos, e o limite foi atingido.",
    "code": "student_limit_reached"
}

409 Outro pedido com a mesma Idempotency-Key ainda está em andamento. application/problem+json

{
    "type": "about:blank",
    "title": "Conflict",
    "status": 409,
    "detail": "Um pedido com esta Idempotency-Key ainda está em andamento. Aguarde alguns segundos e repita.",
    "code": "idempotency_in_progress"
}

422 Campos inválidos (validation_failed, com o detalhe por campo em errors) ou Idempotency-Key já usada com outros dados (idempotency_key_reused). application/problem+json

{
    "type": "about:blank",
    "title": "Unprocessable Content",
    "status": 422,
    "detail": "Alguns campos estão inválidos.",
    "code": "validation_failed",
    "errors": {
        "address.line": [
            "O campo endereço é obrigatório."
        ]
    }
}

429 Limite de chamadas atingido. application/problem+json

{
    "type": "about:blank",
    "title": "Too Many Requests",
    "status": 429,
    "detail": "Limite de chamadas atingido. Tente de novo depois do tempo indicado em Retry-After.",
    "code": "rate_limited"
}

GET /api/v1/students/{student}

Um aluno

Chave com students:read

Parâmetros

Nome	Tipo	Descrição
`student`no caminho · obrigatório	`integer`

Exemplo

curl https://edupay.estudiosite.com/api/v1/students/123 \
  -H "Authorization: Bearer $EDUPAY_KEY"

Respostas

200 O aluno. application/json

401 Chave ausente, inválida, vencida ou revogada. application/problem+json

{
    "type": "about:blank",
    "title": "Unauthorized",
    "status": 401,
    "detail": "Chave de acesso ausente, inválida, vencida ou revogada.",
    "code": "unauthenticated"
}

403 API desligada na escola (code api_disabled) ou chave sem a permissão necessária (code insufficient_scope, com a lista em scopes). application/problem+json

{
    "type": "about:blank",
    "title": "Forbidden",
    "status": 403,
    "detail": "A chave não tem a permissão necessária: students:read.",
    "code": "insufficient_scope",
    "scopes": [
        "students:read"
    ]
}

404 Registro não existe nesta escola. application/problem+json

{
    "type": "about:blank",
    "title": "Not Found",
    "status": 404,
    "detail": "Registro não encontrado.",
    "code": "not_found"
}

429 Limite de chamadas atingido. application/problem+json

{
    "type": "about:blank",
    "title": "Too Many Requests",
    "status": 429,
    "detail": "Limite de chamadas atingido. Tente de novo depois do tempo indicado em Retry-After.",
    "code": "rate_limited"
}

PATCH /api/v1/students/{student}

Alterar aluno

Chave com students:write

Altera só os campos enviados. 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, como na edição pelo painel.

Parâmetros

Nome	Tipo	Descrição
`student`no caminho · obrigatório	`integer`
`Idempotency-Key`no cabeçalho · opcional	`string`	Código único deste pedido (até 255 caracteres visíveis; um UUID serve). Repetir com a mesma chave em 24 h devolve a primeira resposta.

Campos do corpo (JSON)

Nome	Tipo	Descrição
`external_id`opcional	`string \| null`	Código do aluno no sistema da escola. Único na escola.
`full_name`opcional	`string`
`email`opcional	`string \| null`
`phone`opcional	`string \| null`
`document_number`opcional	`string \| null`	CPF (conferido quando a escola liga a validação). Único na escola.
`birth_date`opcional	`string \| null`
`status`opcional	`string (active, inactive)`
`address`opcional	`object`

Exemplo

curl -X PATCH https://edupay.estudiosite.com/api/v1/students/123 \
  -H "Authorization: Bearer $EDUPAY_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phone":"11988887777","address":{"number":"1200"}}'

Respostas

200 Aluno alterado. application/json

400 Idempotency-Key ausente onde é exigida (idempotency_key_required) ou fora do formato (idempotency_key_invalid). application/problem+json

{
    "type": "about:blank",
    "title": "Bad Request",
    "status": 400,
    "detail": "Este pedido exige o cabeçalho Idempotency-Key, com um código único por pedido (por exemplo, um UUID).",
    "code": "idempotency_key_required"
}

401 Chave ausente, inválida, vencida ou revogada. application/problem+json

{
    "type": "about:blank",
    "title": "Unauthorized",
    "status": 401,
    "detail": "Chave de acesso ausente, inválida, vencida ou revogada.",
    "code": "unauthenticated"
}

403 API desligada na escola (code api_disabled) ou chave sem a permissão necessária (code insufficient_scope, com a lista em scopes). application/problem+json

{
    "type": "about:blank",
    "title": "Forbidden",
    "status": 403,
    "detail": "A chave não tem a permissão necessária: students:read.",
    "code": "insufficient_scope",
    "scopes": [
        "students:read"
    ]
}

404 Registro não existe nesta escola. application/problem+json

{
    "type": "about:blank",
    "title": "Not Found",
    "status": 404,
    "detail": "Registro não encontrado.",
    "code": "not_found"
}

409 Outro pedido com a mesma Idempotency-Key ainda está em andamento. application/problem+json

{
    "type": "about:blank",
    "title": "Conflict",
    "status": 409,
    "detail": "Um pedido com esta Idempotency-Key ainda está em andamento. Aguarde alguns segundos e repita.",
    "code": "idempotency_in_progress"
}

422 Campos inválidos (validation_failed, com o detalhe por campo em errors) ou Idempotency-Key já usada com outros dados (idempotency_key_reused). application/problem+json

{
    "type": "about:blank",
    "title": "Unprocessable Content",
    "status": 422,
    "detail": "Alguns campos estão inválidos.",
    "code": "validation_failed",
    "errors": {
        "address.line": [
            "O campo endereço é obrigatório."
        ]
    }
}

429 Limite de chamadas atingido. application/problem+json

{
    "type": "about:blank",
    "title": "Too Many Requests",
    "status": 429,
    "detail": "Limite de chamadas atingido. Tente de novo depois do tempo indicado em Retry-After.",
    "code": "rate_limited"
}

GET /api/v1/students/{student}/summary

Resumo financeiro do aluno

Chave com billing:read

Soma as parcelas que ainda podem ser pagas em qualquer matrícula do aluno, inclusive multa de matrícula cancelada. O contrato é o da matrícula viva mais recente.

Parâmetros

Nome	Tipo	Descrição
`student`no caminho · obrigatório	`integer`

Exemplo

curl https://edupay.estudiosite.com/api/v1/students/123/summary \
  -H "Authorization: Bearer $EDUPAY_KEY"

Respostas

200 O resumo. application/json

{
    "data": {
        "student_id": 532,
        "currency": "BRL",
        "open_installments": 3,
        "overdue_installments": 1,
        "amount_due": 135000,
        "amount_overdue": 45000,
        "next_installment": {
            "id": 9813,
            "due_date": "2026-11-10",
            "amount": 45000
        },
        "active_enrollments": 1,
        "contract_status": "signed"
    }
}

401 Chave ausente, inválida, vencida ou revogada. application/problem+json

{
    "type": "about:blank",
    "title": "Unauthorized",
    "status": 401,
    "detail": "Chave de acesso ausente, inválida, vencida ou revogada.",
    "code": "unauthenticated"
}

403 API desligada na escola (code api_disabled) ou chave sem a permissão necessária (code insufficient_scope, com a lista em scopes). application/problem+json

{
    "type": "about:blank",
    "title": "Forbidden",
    "status": 403,
    "detail": "A chave não tem a permissão necessária: students:read.",
    "code": "insufficient_scope",
    "scopes": [
        "students:read"
    ]
}

404 Registro não existe nesta escola. application/problem+json

{
    "type": "about:blank",
    "title": "Not Found",
    "status": 404,
    "detail": "Registro não encontrado.",
    "code": "not_found"
}

429 Limite de chamadas atingido. application/problem+json

{
    "type": "about:blank",
    "title": "Too Many Requests",
    "status": 429,
    "detail": "Limite de chamadas atingido. Tente de novo depois do tempo indicado em Retry-After.",
    "code": "rate_limited"
}

POST /api/v1/students/{student}/portal-link

Link de entrada no portal do aluno

Chave com portal:link

Gera um link que abre o portal do aluno já conectado, sem senha. Vale 5 minutos e uma vez só: gere na hora do clique. O aluno precisa estar ativo, ter e-mail e conta no portal.

Parâmetros

Nome	Tipo	Descrição
`student`no caminho · obrigatório	`integer`

Exemplo

curl -X POST https://edupay.estudiosite.com/api/v1/students/123/portal-link \
  -H "Authorization: Bearer $EDUPAY_KEY"

Respostas

201 Link gerado. application/json

401 Chave ausente, inválida, vencida ou revogada. application/problem+json

{
    "type": "about:blank",
    "title": "Unauthorized",
    "status": 401,
    "detail": "Chave de acesso ausente, inválida, vencida ou revogada.",
    "code": "unauthenticated"
}

403 API desligada na escola (code api_disabled) ou chave sem a permissão necessária (code insufficient_scope, com a lista em scopes). application/problem+json

{
    "type": "about:blank",
    "title": "Forbidden",
    "status": 403,
    "detail": "A chave não tem a permissão necessária: students:read.",
    "code": "insufficient_scope",
    "scopes": [
        "students:read"
    ]
}

404 Registro não existe nesta escola. application/problem+json

{
    "type": "about:blank",
    "title": "Not Found",
    "status": 404,
    "detail": "Registro não encontrado.",
    "code": "not_found"
}

409 Aluno inativo (student_inactive), sem e-mail ou conta no portal (student_without_portal_access), portal sem endereço (portal_not_configured) ou e-mail repetido em outro aluno (portal_link_ambiguous_email). application/problem+json

{
    "type": "about:blank",
    "title": "Conflict",
    "status": 409,
    "detail": "O aluno não tem e-mail ou conta de acesso ao portal.",
    "code": "student_without_portal_access"
}

429 Limite de chamadas atingido. application/problem+json

{
    "type": "about:blank",
    "title": "Too Many Requests",
    "status": 429,
    "detail": "Limite de chamadas atingido. Tente de novo depois do tempo indicado em Retry-After.",
    "code": "rate_limited"
}

Matrículas

Matrículas e contratos (enrollments:read, enrollments:write).

GET /api/v1/enrollments

Listar matrículas

Chave com enrollments:read

Parâmetros

Nome	Tipo	Descrição
`limit`na query · opcional	`integer`	Itens por página (1 a 200).
`cursor`na query · opcional	`string`	O meta.next_cursor da página anterior.
`updated_since`na query · opcional	`string`	Só registros alterados desde esta data e hora (ISO 8601).
`include`na query · opcional	`string`	Dados relacionados, separados por vírgula: student (exige students:read), installments (exige billing:read), contract.
`student_id`na query · opcional	`integer`
`external_id`na query · opcional	`string`	Código da matrícula no sistema da escola.
`offering_id`na query · opcional	`integer`
`trail_id`na query · opcional	`integer`
`cohort_id`na query · opcional	`integer`
`status`na query · opcional	`string (pending_contract, pending_payment, active, cancelled, completed)`

Exemplo

curl https://edupay.estudiosite.com/api/v1/enrollments \
  -H "Authorization: Bearer $EDUPAY_KEY"

Respostas

200 Página de matrículas. application/json

400 Cursor inválido: recomece a lista sem cursor. application/problem+json

{
    "type": "about:blank",
    "title": "Bad Request",
    "status": 400,
    "detail": "Cursor inválido. Recomece a lista sem o parâmetro cursor.",
    "code": "invalid_cursor"
}

401 Chave ausente, inválida, vencida ou revogada. application/problem+json

{
    "type": "about:blank",
    "title": "Unauthorized",
    "status": 401,
    "detail": "Chave de acesso ausente, inválida, vencida ou revogada.",
    "code": "unauthenticated"
}

403 API desligada na escola (code api_disabled) ou chave sem a permissão necessária (code insufficient_scope, com a lista em scopes). application/problem+json

{
    "type": "about:blank",
    "title": "Forbidden",
    "status": 403,
    "detail": "A chave não tem a permissão necessária: students:read.",
    "code": "insufficient_scope",
    "scopes": [
        "students:read"
    ]
}

422 Parâmetro inválido (detalhe por campo em errors). application/problem+json

{
    "type": "about:blank",
    "title": "Unprocessable Content",
    "status": 422,
    "detail": "Alguns campos estão inválidos.",
    "code": "validation_failed",
    "errors": {
        "limit": [
            "O campo limit não pode ser superior a 200."
        ]
    }
}

429 Limite de chamadas atingido. application/problem+json

{
    "type": "about:blank",
    "title": "Too Many Requests",
    "status": 429,
    "detail": "Limite de chamadas atingido. Tente de novo depois do tempo indicado em Retry-After.",
    "code": "rate_limited"
}

POST /api/v1/enrollments

Criar matrícula

Chave com enrollments:write

Cria a matrícula como o painel: gera as parcelas e o contrato, coloca o aluno no Moodle na hora (quando a turma está ligada ao Moodle) e emite as cobranças que já estão na janela de emissão — cartão na hora; boleto e PIX quando faltam poucos dias para o vencimento. Exige Idempotency-Key. Aceita ?include= como a consulta da matrícula.

Parâmetros

Nome	Tipo	Descrição
`Idempotency-Key`no cabeçalho · obrigatório	`string`	Código único deste pedido (até 255 caracteres visíveis; um UUID serve). Repetir com a mesma chave em 24 h devolve a primeira resposta.
`include`na query · opcional	`string`	Dados relacionados, separados por vírgula: student (exige students:read), installments (exige billing:read), contract.

Campos do corpo (JSON)

Nome	Tipo	Descrição
`external_id`opcional	`string \| null`	Código da matrícula no sistema da escola. Único na escola.
`student_id`opcional	`integer`
`student`opcional	`object`	Aluno novo. Os campos obrigatórios seguem a configuração da escola (CPF, telefone e endereço podem ser exigidos; e-mail é exigido quando o login do aluno é o e-mail).
`offering_id`opcional	`integer`
`trail_id`opcional	`integer`
`cohort_id`opcional	`integer \| null`	Turma. Ligada a uma turma do Moodle, o aluno entra no Moodle na hora, como na matrícula pelo painel.
`financial_plan_id`obrigatório	`integer`
`payment_method`obrigatório	`string (boleto, pix, credit_card)`	Precisa ser aceita pelo plano e pela conta Stripe da escola.
`contract_template_id`opcional	`integer \| null`	Modelo de contrato. Com assinatura exigida, a matrícula nasce aguardando contrato.
`base_value`opcional	`integer \| null`	Valor do curso em centavos. Sem ele, vale o preço do curso (ou a soma dos cursos da trilha).
`enrollment_fee`opcional	`integer \| null`	Taxa de matrícula em centavos. Sem ela, vale a do plano.
`billing_start_date`opcional	`string \| null`	Início da cobrança (AAAA-MM-DD).
`billing_due_day`opcional	`integer \| null`	Dia de vencimento das parcelas.

Exemplo

curl -X POST https://edupay.estudiosite.com/api/v1/enrollments \
  -H "Authorization: Bearer $EDUPAY_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"external_id":"PED-2026-1187","student":{"external_id":"ALU-0091","full_name":"Maria Souza","email":"maria@exemplo.com","document_number":"12345678909","phone":"11999990000"},"offering_id":14,"cohort_id":3,"financial_plan_id":2,"payment_method":"pix"}'

Respostas

201 Matrícula criada. application/json

400 Idempotency-Key ausente onde é exigida (idempotency_key_required) ou fora do formato (idempotency_key_invalid). application/problem+json

{
    "type": "about:blank",
    "title": "Bad Request",
    "status": 400,
    "detail": "Este pedido exige o cabeçalho Idempotency-Key, com um código único por pedido (por exemplo, um UUID).",
    "code": "idempotency_key_required"
}

401 Chave ausente, inválida, vencida ou revogada. application/problem+json

{
    "type": "about:blank",
    "title": "Unauthorized",
    "status": 401,
    "detail": "Chave de acesso ausente, inválida, vencida ou revogada.",
    "code": "unauthenticated"
}

403 API desligada, chave sem a permissão (insufficient_scope) ou, com aluno novo, limite de alunos do plano atingido (student_limit_reached). application/problem+json

{
    "type": "about:blank",
    "title": "Forbidden",
    "status": 403,
    "detail": "A chave não tem a permissão necessária: enrollments:write.",
    "code": "insufficient_scope",
    "scopes": [
        "enrollments:write"
    ]
}

409 O aluno já tem matrícula viva no mesmo curso ou trilha (enrollment_conflict, com existing_enrollment_id) ou o pedido com esta Idempotency-Key ainda está em andamento (idempotency_in_progress). application/problem+json

{
    "type": "about:blank",
    "title": "Conflict",
    "status": 409,
    "detail": "O aluno já tem matrícula viva neste curso ou trilha (veja existing_enrollment_id).",
    "code": "enrollment_conflict",
    "existing_enrollment_id": 812
}

422 Campos inválidos (validation_failed, com o detalhe por campo em errors) ou Idempotency-Key já usada com outros dados (idempotency_key_reused). application/problem+json

{
    "type": "about:blank",
    "title": "Unprocessable Content",
    "status": 422,
    "detail": "Alguns campos estão inválidos.",
    "code": "validation_failed",
    "errors": {
        "address.line": [
            "O campo endereço é obrigatório."
        ]
    }
}

429 Limite de chamadas atingido. application/problem+json

{
    "type": "about:blank",
    "title": "Too Many Requests",
    "status": 429,
    "detail": "Limite de chamadas atingido. Tente de novo depois do tempo indicado em Retry-After.",
    "code": "rate_limited"
}

GET /api/v1/enrollments/{enrollment}

Uma matrícula

Chave com enrollments:read

Parâmetros

Nome	Tipo	Descrição
`enrollment`no caminho · obrigatório	`integer`
`include`na query · opcional	`string`	Dados relacionados, separados por vírgula: student (exige students:read), installments (exige billing:read), contract.

Exemplo

curl https://edupay.estudiosite.com/api/v1/enrollments/123 \
  -H "Authorization: Bearer $EDUPAY_KEY"

Respostas

200 A matrícula. application/json

401 Chave ausente, inválida, vencida ou revogada. application/problem+json

{
    "type": "about:blank",
    "title": "Unauthorized",
    "status": 401,
    "detail": "Chave de acesso ausente, inválida, vencida ou revogada.",
    "code": "unauthenticated"
}

403 API desligada na escola (code api_disabled) ou chave sem a permissão necessária (code insufficient_scope, com a lista em scopes). application/problem+json

{
    "type": "about:blank",
    "title": "Forbidden",
    "status": 403,
    "detail": "A chave não tem a permissão necessária: students:read.",
    "code": "insufficient_scope",
    "scopes": [
        "students:read"
    ]
}

404 Registro não existe nesta escola. application/problem+json

{
    "type": "about:blank",
    "title": "Not Found",
    "status": 404,
    "detail": "Registro não encontrado.",
    "code": "not_found"
}

422 Parâmetro inválido (detalhe por campo em errors). application/problem+json

{
    "type": "about:blank",
    "title": "Unprocessable Content",
    "status": 422,
    "detail": "Alguns campos estão inválidos.",
    "code": "validation_failed",
    "errors": {
        "limit": [
            "O campo limit não pode ser superior a 200."
        ]
    }
}

429 Limite de chamadas atingido. application/problem+json

{
    "type": "about:blank",
    "title": "Too Many Requests",
    "status": 429,
    "detail": "Limite de chamadas atingido. Tente de novo depois do tempo indicado em Retry-After.",
    "code": "rate_limited"
}

GET /api/v1/enrollments/{enrollment}/contract

Contrato da matrícula

Chave com enrollments:read

Parâmetros

Nome	Tipo	Descrição
`enrollment`no caminho · obrigatório	`integer`

Exemplo

curl https://edupay.estudiosite.com/api/v1/enrollments/123/contract \
  -H "Authorization: Bearer $EDUPAY_KEY"

Respostas

200 O contrato. application/json

401 Chave ausente, inválida, vencida ou revogada. application/problem+json

{
    "type": "about:blank",
    "title": "Unauthorized",
    "status": 401,
    "detail": "Chave de acesso ausente, inválida, vencida ou revogada.",
    "code": "unauthenticated"
}

403 API desligada na escola (code api_disabled) ou chave sem a permissão necessária (code insufficient_scope, com a lista em scopes). application/problem+json

{
    "type": "about:blank",
    "title": "Forbidden",
    "status": 403,
    "detail": "A chave não tem a permissão necessária: students:read.",
    "code": "insufficient_scope",
    "scopes": [
        "students:read"
    ]
}

404 Registro não existe nesta escola. application/problem+json

{
    "type": "about:blank",
    "title": "Not Found",
    "status": 404,
    "detail": "Registro não encontrado.",
    "code": "not_found"
}

429 Limite de chamadas atingido. application/problem+json

{
    "type": "about:blank",
    "title": "Too Many Requests",
    "status": 429,
    "detail": "Limite de chamadas atingido. Tente de novo depois do tempo indicado em Retry-After.",
    "code": "rate_limited"
}

GET /api/v1/enrollments/{enrollment}/contract/pdf

PDF do contrato

Chave com enrollments:read

O mesmo PDF que o painel da escola baixa.

Parâmetros

Nome	Tipo	Descrição
`enrollment`no caminho · obrigatório	`integer`

Exemplo

curl https://edupay.estudiosite.com/api/v1/enrollments/123/contract/pdf \
  -H "Authorization: Bearer $EDUPAY_KEY"

Respostas

200 O arquivo. application/pdf

401 Chave ausente, inválida, vencida ou revogada. application/problem+json

{
    "type": "about:blank",
    "title": "Unauthorized",
    "status": 401,
    "detail": "Chave de acesso ausente, inválida, vencida ou revogada.",
    "code": "unauthenticated"
}

403 API desligada na escola (code api_disabled) ou chave sem a permissão necessária (code insufficient_scope, com a lista em scopes). application/problem+json

{
    "type": "about:blank",
    "title": "Forbidden",
    "status": 403,
    "detail": "A chave não tem a permissão necessária: students:read.",
    "code": "insufficient_scope",
    "scopes": [
        "students:read"
    ]
}

404 Registro não existe nesta escola. application/problem+json

{
    "type": "about:blank",
    "title": "Not Found",
    "status": 404,
    "detail": "Registro não encontrado.",
    "code": "not_found"
}

429 Limite de chamadas atingido. application/problem+json

{
    "type": "about:blank",
    "title": "Too Many Requests",
    "status": 429,
    "detail": "Limite de chamadas atingido. Tente de novo depois do tempo indicado em Retry-After.",
    "code": "rate_limited"
}

POST /api/v1/enrollments/{enrollment}/cancel

Cancelar matrícula

Chave com enrollments:write

Cancela como o painel, sem multa de rescisão (essa só pelo painel): as parcelas em aberto são canceladas junto com as cobranças no Stripe, o aluno é avisado e sai do Moodle. Boleto ainda dentro da validade não pode ser cancelado no Stripe e continua pagável até vencer: meta.charges_still_payable diz quantos.

Parâmetros

Nome	Tipo	Descrição
`enrollment`no caminho · obrigatório	`integer`
`Idempotency-Key`no cabeçalho · opcional	`string`	Código único deste pedido (até 255 caracteres visíveis; um UUID serve). Repetir com a mesma chave em 24 h devolve a primeira resposta.
`include`na query · opcional	`string`	Dados relacionados, separados por vírgula: student (exige students:read), installments (exige billing:read), contract.

Campos do corpo (JSON)

Nome	Tipo	Descrição
`reason`opcional	`string \| null (student_withdrawal, transfer, default, administrative, null)`	Desistência do aluno, transferência, inadimplência ou decisão administrativa.

Exemplo

curl -X POST https://edupay.estudiosite.com/api/v1/enrollments/123/cancel \
  -H "Authorization: Bearer $EDUPAY_KEY" \
  -H "Content-Type: application/json" \
  -d '{"reason":"student_withdrawal"}'

Respostas

200 Matrícula cancelada. application/json

400 Idempotency-Key ausente onde é exigida (idempotency_key_required) ou fora do formato (idempotency_key_invalid). application/problem+json

{
    "type": "about:blank",
    "title": "Bad Request",
    "status": 400,
    "detail": "Este pedido exige o cabeçalho Idempotency-Key, com um código único por pedido (por exemplo, um UUID).",
    "code": "idempotency_key_required"
}

401 Chave ausente, inválida, vencida ou revogada. application/problem+json

{
    "type": "about:blank",
    "title": "Unauthorized",
    "status": 401,
    "detail": "Chave de acesso ausente, inválida, vencida ou revogada.",
    "code": "unauthenticated"
}

403 API desligada na escola (code api_disabled) ou chave sem a permissão necessária (code insufficient_scope, com a lista em scopes). application/problem+json

{
    "type": "about:blank",
    "title": "Forbidden",
    "status": 403,
    "detail": "A chave não tem a permissão necessária: students:read.",
    "code": "insufficient_scope",
    "scopes": [
        "students:read"
    ]
}

404 Registro não existe nesta escola. application/problem+json

{
    "type": "about:blank",
    "title": "Not Found",
    "status": 404,
    "detail": "Registro não encontrado.",
    "code": "not_found"
}

409 A matrícula já está cancelada ou concluída (enrollment_not_cancellable). application/problem+json

{
    "type": "about:blank",
    "title": "Conflict",
    "status": 409,
    "detail": "Só matrícula aguardando contrato, aguardando pagamento ou ativa pode ser cancelada.",
    "code": "enrollment_not_cancellable"
}

422 Campos inválidos (validation_failed, com o detalhe por campo em errors) ou Idempotency-Key já usada com outros dados (idempotency_key_reused). application/problem+json

{
    "type": "about:blank",
    "title": "Unprocessable Content",
    "status": 422,
    "detail": "Alguns campos estão inválidos.",
    "code": "validation_failed",
    "errors": {
        "address.line": [
            "O campo endereço é obrigatório."
        ]
    }
}

429 Limite de chamadas atingido. application/problem+json

{
    "type": "about:blank",
    "title": "Too Many Requests",
    "status": 429,
    "detail": "Limite de chamadas atingido. Tente de novo depois do tempo indicado em Retry-After.",
    "code": "rate_limited"
}

Cobranças

Parcelas, dados para pagar (billing:read) e 2ª via (billing:write).

GET /api/v1/installments

Listar parcelas

Chave com billing:read

Parâmetros

Nome	Tipo	Descrição
`limit`na query · opcional	`integer`	Itens por página (1 a 200).
`cursor`na query · opcional	`string`	O meta.next_cursor da página anterior.
`updated_since`na query · opcional	`string`	Só registros alterados desde esta data e hora (ISO 8601).
`enrollment_id`na query · opcional	`integer`
`student_id`na query · opcional	`integer`
`status`na query · opcional	`string (open, paid, overdue, cancelled, waived, outstanding)`
`due_from`na query · opcional	`string`
`due_to`na query · opcional	`string`
`paid_from`na query · opcional	`string`
`paid_to`na query · opcional	`string`

Exemplo

curl https://edupay.estudiosite.com/api/v1/installments \
  -H "Authorization: Bearer $EDUPAY_KEY"

Respostas

200 Página de parcelas. application/json

400 Cursor inválido: recomece a lista sem cursor. application/problem+json

{
    "type": "about:blank",
    "title": "Bad Request",
    "status": 400,
    "detail": "Cursor inválido. Recomece a lista sem o parâmetro cursor.",
    "code": "invalid_cursor"
}

401 Chave ausente, inválida, vencida ou revogada. application/problem+json

{
    "type": "about:blank",
    "title": "Unauthorized",
    "status": 401,
    "detail": "Chave de acesso ausente, inválida, vencida ou revogada.",
    "code": "unauthenticated"
}

403 API desligada na escola (code api_disabled) ou chave sem a permissão necessária (code insufficient_scope, com a lista em scopes). application/problem+json

{
    "type": "about:blank",
    "title": "Forbidden",
    "status": 403,
    "detail": "A chave não tem a permissão necessária: students:read.",
    "code": "insufficient_scope",
    "scopes": [
        "students:read"
    ]
}

422 Parâmetro inválido (detalhe por campo em errors). application/problem+json

{
    "type": "about:blank",
    "title": "Unprocessable Content",
    "status": 422,
    "detail": "Alguns campos estão inválidos.",
    "code": "validation_failed",
    "errors": {
        "limit": [
            "O campo limit não pode ser superior a 200."
        ]
    }
}

429 Limite de chamadas atingido. application/problem+json

{
    "type": "about:blank",
    "title": "Too Many Requests",
    "status": 429,
    "detail": "Limite de chamadas atingido. Tente de novo depois do tempo indicado em Retry-After.",
    "code": "rate_limited"
}

GET /api/v1/installments/{installment}

Uma parcela

Chave com billing:read

Inclui a imagem do QR Code PIX (payment.pix_qr_code_base64), que a lista não traz.

Parâmetros

Nome	Tipo	Descrição
`installment`no caminho · obrigatório	`integer`

Exemplo

curl https://edupay.estudiosite.com/api/v1/installments/123 \
  -H "Authorization: Bearer $EDUPAY_KEY"

Respostas

200 A parcela. application/json

401 Chave ausente, inválida, vencida ou revogada. application/problem+json

{
    "type": "about:blank",
    "title": "Unauthorized",
    "status": 401,
    "detail": "Chave de acesso ausente, inválida, vencida ou revogada.",
    "code": "unauthenticated"
}

403 API desligada na escola (code api_disabled) ou chave sem a permissão necessária (code insufficient_scope, com a lista em scopes). application/problem+json

{
    "type": "about:blank",
    "title": "Forbidden",
    "status": 403,
    "detail": "A chave não tem a permissão necessária: students:read.",
    "code": "insufficient_scope",
    "scopes": [
        "students:read"
    ]
}

404 Registro não existe nesta escola. application/problem+json

{
    "type": "about:blank",
    "title": "Not Found",
    "status": 404,
    "detail": "Registro não encontrado.",
    "code": "not_found"
}

429 Limite de chamadas atingido. application/problem+json

{
    "type": "about:blank",
    "title": "Too Many Requests",
    "status": 429,
    "detail": "Limite de chamadas atingido. Tente de novo depois do tempo indicado em Retry-After.",
    "code": "rate_limited"
}

POST /api/v1/installments/{installment}/second-copy

Gerar 2ª via

Chave com billing:write

Gera a 2ª via com novo vencimento, como o painel: a parcela atual é cancelada junto com a cobrança no Stripe e nasce outra (replaces_installment_id aponta a anterior), com boleto ou PIX novo e e-mail ao aluno. O valor não muda pela API.

Parâmetros

Nome	Tipo	Descrição
`installment`no caminho · obrigatório	`integer`
`Idempotency-Key`no cabeçalho · opcional	`string`	Código único deste pedido (até 255 caracteres visíveis; um UUID serve). Repetir com a mesma chave em 24 h devolve a primeira resposta.

Campos do corpo (JSON)

Nome	Tipo	Descrição
`due_date`opcional	`string \| null`	Novo vencimento (AAAA-MM-DD, de hoje em diante no fuso da escola). Sem ele, vence em 3 dias.

Exemplo

curl -X POST https://edupay.estudiosite.com/api/v1/installments/123/second-copy \
  -H "Authorization: Bearer $EDUPAY_KEY" \
  -H "Content-Type: application/json" \
  -d '{"due_date":"2026-11-20"}'

Respostas

201 A parcela nova, com os dados para pagar. application/json

400 Idempotency-Key ausente onde é exigida (idempotency_key_required) ou fora do formato (idempotency_key_invalid). application/problem+json

{
    "type": "about:blank",
    "title": "Bad Request",
    "status": 400,
    "detail": "Este pedido exige o cabeçalho Idempotency-Key, com um código único por pedido (por exemplo, um UUID).",
    "code": "idempotency_key_required"
}

401 Chave ausente, inválida, vencida ou revogada. application/problem+json

{
    "type": "about:blank",
    "title": "Unauthorized",
    "status": 401,
    "detail": "Chave de acesso ausente, inválida, vencida ou revogada.",
    "code": "unauthenticated"
}

403 API desligada na escola (code api_disabled) ou chave sem a permissão necessária (code insufficient_scope, com a lista em scopes). application/problem+json

{
    "type": "about:blank",
    "title": "Forbidden",
    "status": 403,
    "detail": "A chave não tem a permissão necessária: students:read.",
    "code": "insufficient_scope",
    "scopes": [
        "students:read"
    ]
}

404 Registro não existe nesta escola. application/problem+json

{
    "type": "about:blank",
    "title": "Not Found",
    "status": 404,
    "detail": "Registro não encontrado.",
    "code": "not_found"
}

409 Parcela paga, cancelada ou dispensada (installment_not_payable), boleto atual ainda válido (boleto_still_valid) ou escola sem conta Stripe conectada (gateway_not_connected). application/problem+json

{
    "type": "about:blank",
    "title": "Conflict",
    "status": 409,
    "detail": "O boleto atual ainda está dentro da validade e não pode ser cancelado.",
    "code": "boleto_still_valid"
}

422 Campos inválidos (validation_failed, com o detalhe por campo em errors) ou Idempotency-Key já usada com outros dados (idempotency_key_reused). application/problem+json

{
    "type": "about:blank",
    "title": "Unprocessable Content",
    "status": 422,
    "detail": "Alguns campos estão inválidos.",
    "code": "validation_failed",
    "errors": {
        "address.line": [
            "O campo endereço é obrigatório."
        ]
    }
}

429 Limite de chamadas atingido. application/problem+json

{
    "type": "about:blank",
    "title": "Too Many Requests",
    "status": 429,
    "detail": "Limite de chamadas atingido. Tente de novo depois do tempo indicado em Retry-After.",
    "code": "rate_limited"
}

502 O Stripe recusou ou não respondeu (gateway_error). Com installment_id, a 2ª via foi criada e a cobrança dela sai de novo automaticamente. application/problem+json

{
    "type": "about:blank",
    "title": "Bad Gateway",
    "status": 502,
    "detail": "O Stripe recusou ou não respondeu. Se veio installment_id, a 2ª via foi criada e a cobrança dela sai de novo automaticamente.",
    "code": "gateway_error",
    "installment_id": 4521
}

Avisos automáticos

Endereços que recebem os avisos da escola (webhooks:manage). O formato do aviso está em webhooks → evento.

GET /api/v1/webhooks

Listar endereços de aviso

Chave com webhooks:manage

Exemplo

curl https://edupay.estudiosite.com/api/v1/webhooks \
  -H "Authorization: Bearer $EDUPAY_KEY"

Respostas

200 Endereços da escola (sem o segredo). application/json

401 Chave ausente, inválida, vencida ou revogada. application/problem+json

{
    "type": "about:blank",
    "title": "Unauthorized",
    "status": 401,
    "detail": "Chave de acesso ausente, inválida, vencida ou revogada.",
    "code": "unauthenticated"
}

403 API desligada na escola (code api_disabled) ou chave sem a permissão necessária (code insufficient_scope, com a lista em scopes). application/problem+json

{
    "type": "about:blank",
    "title": "Forbidden",
    "status": 403,
    "detail": "A chave não tem a permissão necessária: students:read.",
    "code": "insufficient_scope",
    "scopes": [
        "students:read"
    ]
}

429 Limite de chamadas atingido. application/problem+json

{
    "type": "about:blank",
    "title": "Too Many Requests",
    "status": 429,
    "detail": "Limite de chamadas atingido. Tente de novo depois do tempo indicado em Retry-After.",
    "code": "rate_limited"
}

POST /api/v1/webhooks

Cadastrar endereço de aviso

Chave com webhooks:manage

A resposta traz o segredo (secret) uma única vez: guarde-o para conferir a assinatura dos avisos. Até 10 endereços por escola.

Campos do corpo (JSON)

Nome	Tipo	Descrição
`url`opcional	`string`	Precisa ser https e apontar para endereço público.
`description`opcional	`string \| null`
`events`opcional	`array`	Eventos assinados (WebhookEventType) ou ["*"] para todos.

Exemplo

curl -X POST https://edupay.estudiosite.com/api/v1/webhooks \
  -H "Authorization: Bearer $EDUPAY_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://erp.escola.com.br/edupay/avisos","description":"ERP financeiro","events":["installment.paid","installment.overdue"]}'

Respostas

201 Endereço cadastrado, com o segredo. application/json

401 Chave ausente, inválida, vencida ou revogada. application/problem+json

{
    "type": "about:blank",
    "title": "Unauthorized",
    "status": 401,
    "detail": "Chave de acesso ausente, inválida, vencida ou revogada.",
    "code": "unauthenticated"
}

403 API desligada na escola (code api_disabled) ou chave sem a permissão necessária (code insufficient_scope, com a lista em scopes). application/problem+json

{
    "type": "about:blank",
    "title": "Forbidden",
    "status": 403,
    "detail": "A chave não tem a permissão necessária: students:read.",
    "code": "insufficient_scope",
    "scopes": [
        "students:read"
    ]
}

409 Limite de endereços atingido. application/problem+json

422 Parâmetro inválido (detalhe por campo em errors). application/problem+json

{
    "type": "about:blank",
    "title": "Unprocessable Content",
    "status": 422,
    "detail": "Alguns campos estão inválidos.",
    "code": "validation_failed",
    "errors": {
        "limit": [
            "O campo limit não pode ser superior a 200."
        ]
    }
}

429 Limite de chamadas atingido. application/problem+json

{
    "type": "about:blank",
    "title": "Too Many Requests",
    "status": 429,
    "detail": "Limite de chamadas atingido. Tente de novo depois do tempo indicado em Retry-After.",
    "code": "rate_limited"
}

GET /api/v1/webhooks/{webhook}

Um endereço de aviso

Chave com webhooks:manage

Parâmetros

Nome	Tipo	Descrição
`webhook`no caminho · obrigatório	`integer`

Exemplo

curl https://edupay.estudiosite.com/api/v1/webhooks/123 \
  -H "Authorization: Bearer $EDUPAY_KEY"

Respostas

200 O endereço. application/json

401 Chave ausente, inválida, vencida ou revogada. application/problem+json

{
    "type": "about:blank",
    "title": "Unauthorized",
    "status": 401,
    "detail": "Chave de acesso ausente, inválida, vencida ou revogada.",
    "code": "unauthenticated"
}

403 API desligada na escola (code api_disabled) ou chave sem a permissão necessária (code insufficient_scope, com a lista em scopes). application/problem+json

{
    "type": "about:blank",
    "title": "Forbidden",
    "status": 403,
    "detail": "A chave não tem a permissão necessária: students:read.",
    "code": "insufficient_scope",
    "scopes": [
        "students:read"
    ]
}

404 Registro não existe nesta escola. application/problem+json

{
    "type": "about:blank",
    "title": "Not Found",
    "status": 404,
    "detail": "Registro não encontrado.",
    "code": "not_found"
}

429 Limite de chamadas atingido. application/problem+json

{
    "type": "about:blank",
    "title": "Too Many Requests",
    "status": 429,
    "detail": "Limite de chamadas atingido. Tente de novo depois do tempo indicado em Retry-After.",
    "code": "rate_limited"
}

PATCH /api/v1/webhooks/{webhook}

Alterar endereço de aviso

Chave com webhooks:manage

Envie só o que muda. enabled: false pausa; enabled: true religa e zera a contagem de falhas.

Parâmetros

Nome	Tipo	Descrição
`webhook`no caminho · obrigatório	`integer`

Exemplo

curl -X PATCH https://edupay.estudiosite.com/api/v1/webhooks/123 \
  -H "Authorization: Bearer $EDUPAY_KEY" \
  -H "Content-Type: application/json"

Respostas

200 O endereço alterado. application/json

401 Chave ausente, inválida, vencida ou revogada. application/problem+json

{
    "type": "about:blank",
    "title": "Unauthorized",
    "status": 401,
    "detail": "Chave de acesso ausente, inválida, vencida ou revogada.",
    "code": "unauthenticated"
}

403 API desligada na escola (code api_disabled) ou chave sem a permissão necessária (code insufficient_scope, com a lista em scopes). application/problem+json

{
    "type": "about:blank",
    "title": "Forbidden",
    "status": 403,
    "detail": "A chave não tem a permissão necessária: students:read.",
    "code": "insufficient_scope",
    "scopes": [
        "students:read"
    ]
}

404 Registro não existe nesta escola. application/problem+json

{
    "type": "about:blank",
    "title": "Not Found",
    "status": 404,
    "detail": "Registro não encontrado.",
    "code": "not_found"
}

422 Parâmetro inválido (detalhe por campo em errors). application/problem+json

{
    "type": "about:blank",
    "title": "Unprocessable Content",
    "status": 422,
    "detail": "Alguns campos estão inválidos.",
    "code": "validation_failed",
    "errors": {
        "limit": [
            "O campo limit não pode ser superior a 200."
        ]
    }
}

429 Limite de chamadas atingido. application/problem+json

{
    "type": "about:blank",
    "title": "Too Many Requests",
    "status": 429,
    "detail": "Limite de chamadas atingido. Tente de novo depois do tempo indicado em Retry-After.",
    "code": "rate_limited"
}

DELETE /api/v1/webhooks/{webhook}

Excluir endereço de aviso

Chave com webhooks:manage

Apaga também o histórico de entregas.

Parâmetros

Nome	Tipo	Descrição
`webhook`no caminho · obrigatório	`integer`

Exemplo

curl -X DELETE https://edupay.estudiosite.com/api/v1/webhooks/123 \
  -H "Authorization: Bearer $EDUPAY_KEY"

Respostas

204 Excluído.

401 Chave ausente, inválida, vencida ou revogada. application/problem+json

{
    "type": "about:blank",
    "title": "Unauthorized",
    "status": 401,
    "detail": "Chave de acesso ausente, inválida, vencida ou revogada.",
    "code": "unauthenticated"
}

403 API desligada na escola (code api_disabled) ou chave sem a permissão necessária (code insufficient_scope, com a lista em scopes). application/problem+json

{
    "type": "about:blank",
    "title": "Forbidden",
    "status": 403,
    "detail": "A chave não tem a permissão necessária: students:read.",
    "code": "insufficient_scope",
    "scopes": [
        "students:read"
    ]
}

404 Registro não existe nesta escola. application/problem+json

{
    "type": "about:blank",
    "title": "Not Found",
    "status": 404,
    "detail": "Registro não encontrado.",
    "code": "not_found"
}

429 Limite de chamadas atingido. application/problem+json

{
    "type": "about:blank",
    "title": "Too Many Requests",
    "status": 429,
    "detail": "Limite de chamadas atingido. Tente de novo depois do tempo indicado em Retry-After.",
    "code": "rate_limited"
}

GET /api/v1/webhooks/{webhook}/deliveries

Histórico de entregas do endereço

Chave com webhooks:manage

Últimos 30 dias, do mais antigo para o mais novo.

Parâmetros

Nome	Tipo	Descrição
`webhook`no caminho · obrigatório	`integer`
`limit`na query · opcional	`integer`	Itens por página (1 a 200).
`cursor`na query · opcional	`string`	O meta.next_cursor da página anterior.
`updated_since`na query · opcional	`string`	Só registros alterados desde esta data e hora (ISO 8601).

Exemplo

curl https://edupay.estudiosite.com/api/v1/webhooks/123/deliveries \
  -H "Authorization: Bearer $EDUPAY_KEY"

Respostas

200 Página de entregas. application/json

400 Cursor inválido: recomece a lista sem cursor. application/problem+json

{
    "type": "about:blank",
    "title": "Bad Request",
    "status": 400,
    "detail": "Cursor inválido. Recomece a lista sem o parâmetro cursor.",
    "code": "invalid_cursor"
}

401 Chave ausente, inválida, vencida ou revogada. application/problem+json

{
    "type": "about:blank",
    "title": "Unauthorized",
    "status": 401,
    "detail": "Chave de acesso ausente, inválida, vencida ou revogada.",
    "code": "unauthenticated"
}

403 API desligada na escola (code api_disabled) ou chave sem a permissão necessária (code insufficient_scope, com a lista em scopes). application/problem+json

{
    "type": "about:blank",
    "title": "Forbidden",
    "status": 403,
    "detail": "A chave não tem a permissão necessária: students:read.",
    "code": "insufficient_scope",
    "scopes": [
        "students:read"
    ]
}

404 Registro não existe nesta escola. application/problem+json

{
    "type": "about:blank",
    "title": "Not Found",
    "status": 404,
    "detail": "Registro não encontrado.",
    "code": "not_found"
}

429 Limite de chamadas atingido. application/problem+json

{
    "type": "about:blank",
    "title": "Too Many Requests",
    "status": 429,
    "detail": "Limite de chamadas atingido. Tente de novo depois do tempo indicado em Retry-After.",
    "code": "rate_limited"
}

POST /api/v1/webhooks/{webhook}/test

Enviar aviso de teste

Chave com webhooks:manage

Manda um aviso webhook.test ao endereço, numa tentativa só. Funciona mesmo com a API da escola desligada.

Parâmetros

Nome	Tipo	Descrição
`webhook`no caminho · obrigatório	`integer`

Exemplo

curl -X POST https://edupay.estudiosite.com/api/v1/webhooks/123/test \
  -H "Authorization: Bearer $EDUPAY_KEY"

Respostas

202 Aviso de teste na fila. application/json

401 Chave ausente, inválida, vencida ou revogada. application/problem+json

{
    "type": "about:blank",
    "title": "Unauthorized",
    "status": 401,
    "detail": "Chave de acesso ausente, inválida, vencida ou revogada.",
    "code": "unauthenticated"
}

403 API desligada na escola (code api_disabled) ou chave sem a permissão necessária (code insufficient_scope, com a lista em scopes). application/problem+json

{
    "type": "about:blank",
    "title": "Forbidden",
    "status": 403,
    "detail": "A chave não tem a permissão necessária: students:read.",
    "code": "insufficient_scope",
    "scopes": [
        "students:read"
    ]
}

404 Registro não existe nesta escola. application/problem+json

{
    "type": "about:blank",
    "title": "Not Found",
    "status": 404,
    "detail": "Registro não encontrado.",
    "code": "not_found"
}

429 Limite de chamadas atingido. application/problem+json

{
    "type": "about:blank",
    "title": "Too Many Requests",
    "status": 429,
    "detail": "Limite de chamadas atingido. Tente de novo depois do tempo indicado em Retry-After.",
    "code": "rate_limited"
}