Referencia · Documentación de la API

Todas las rutas de la API, generadas de la especificación OpenAPI 1.0.0-beta. Los ejemplos usan la dirección de este servidor; guarde la clave en la variable EDUPAY_KEY.

Descargar openapi.json

Cuenta

La escuela dueña de la clave.

GET /api/v1/me

La escuela dueña de la clave

Cualquier clave

Datos de la escuela dueña de la clave y de la propia clave. Cualquier clave válida puede llamarla; sirve para probar la conexión.

Ejemplo

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

Respuestas

200 La escuela y la clave. 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 Clave ausente, inválida, vencida o revocada. application/problem+json

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

403 API desactivada en la escuela (code api_disabled) o clave sin el permiso necesario (code insufficient_scope, con la lista en 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 Límite de llamadas alcanzado. 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

Especificación OpenAPI

Sin clave de acceso

Esta especificación, en JSON (OpenAPI 3.1), con la dirección de este servidor. Abierta, sin clave: sirve para generar un cliente, importar en Postman o Insomnia y leer en herramientas de IA.

Ejemplo

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

Respuestas

200 La especificación. application/json

Catálogo

Lo que vende la escuela (catalog:read).

GET /api/v1/offerings

Listar cursos y ofertas

Clave con catalog:read

Parámetros

Nombre	Tipo	Descripción
`limit`en la query · opcional	`integer`	Elementos por página (1 a 200).
`cursor`en la query · opcional	`string`	El meta.next_cursor de la página anterior.
`updated_since`en la query · opcional	`string`	Solo registros modificados desde esta fecha y hora (ISO 8601).
`status`en la query · opcional	`string (active, inactive)`
`type`en la query · opcional	`string (postgrad, undergrad, school, free_course)`
`code`en la query · opcional	`string`	Código de la oferta, exacto.

Ejemplo

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

Respuestas

200 Página de ofertas. application/json

400 Cursor inválido: reinicie la lista sin 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 Clave ausente, inválida, vencida o revocada. application/problem+json

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

403 API desactivada en la escuela (code api_disabled) o clave sin el permiso necesario (code insufficient_scope, con la lista en 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 (detalle por campo en 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 Límite de llamadas alcanzado. 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}

Una oferta

Clave con catalog:read

Parámetros

Nombre	Tipo	Descripción
`offering`en la ruta · obligatorio	`integer`

Ejemplo

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

Respuestas

200 La oferta. application/json

401 Clave ausente, inválida, vencida o revocada. application/problem+json

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

403 API desactivada en la escuela (code api_disabled) o clave sin el permiso necesario (code insufficient_scope, con la lista en 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 El registro no existe en esta escuela. application/problem+json

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

429 Límite de llamadas alcanzado. 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 trayectos

Clave con catalog:read

Trayectos con las ofertas que forman parte de cada uno, en el orden en que el alumno las cursa.

Parámetros

Nombre	Tipo	Descripción
`limit`en la query · opcional	`integer`	Elementos por página (1 a 200).
`cursor`en la query · opcional	`string`	El meta.next_cursor de la página anterior.
`updated_since`en la query · opcional	`string`	Solo registros modificados desde esta fecha y hora (ISO 8601).
`status`en la query · opcional	`string (active, inactive)`

Ejemplo

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

Respuestas

200 Página de trayectos. application/json

400 Cursor inválido: reinicie la lista sin 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 Clave ausente, inválida, vencida o revocada. application/problem+json

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

403 API desactivada en la escuela (code api_disabled) o clave sin el permiso necesario (code insufficient_scope, con la lista en 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 (detalle por campo en 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 Límite de llamadas alcanzado. 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 grupos

Clave con catalog:read

Parámetros

Nombre	Tipo	Descripción
`limit`en la query · opcional	`integer`	Elementos por página (1 a 200).
`cursor`en la query · opcional	`string`	El meta.next_cursor de la página anterior.
`updated_since`en la query · opcional	`string`	Solo registros modificados desde esta fecha y hora (ISO 8601).
`status`en la query · opcional	`string (open, closed, archived)`

Ejemplo

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

Respuestas

200 Página de grupos. application/json

400 Cursor inválido: reinicie la lista sin 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 Clave ausente, inválida, vencida o revocada. application/problem+json

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

403 API desactivada en la escuela (code api_disabled) o clave sin el permiso necesario (code insufficient_scope, con la lista en 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 (detalle por campo en 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 Límite de llamadas alcanzado. 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 planes de pago

Clave con catalog:read

Formas de pago aceptadas, número de cuotas, tasa de matrícula, intereses y multa. Los campos de descuento del plan no se devuelven: hoy no se aplican en el cobro.

Parámetros

Nombre	Tipo	Descripción
`limit`en la query · opcional	`integer`	Elementos por página (1 a 200).
`cursor`en la query · opcional	`string`	El meta.next_cursor de la página anterior.
`updated_since`en la query · opcional	`string`	Solo registros modificados desde esta fecha y hora (ISO 8601).
`status`en la query · opcional	`string (active, inactive)`

Ejemplo

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

Respuestas

200 Página de planes. application/json

400 Cursor inválido: reinicie la lista sin 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 Clave ausente, inválida, vencida o revocada. application/problem+json

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

403 API desactivada en la escuela (code api_disabled) o clave sin el permiso necesario (code insufficient_scope, con la lista en 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 (detalle por campo en 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 Límite de llamadas alcanzado. 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 ventas publicadas

Clave con catalog:read

Solo páginas publicadas, con el enlace público donde el interesado se matricula y el precio.

Parámetros

Nombre	Tipo	Descripción
`limit`en la query · opcional	`integer`	Elementos por página (1 a 200).
`cursor`en la query · opcional	`string`	El meta.next_cursor de la página anterior.
`updated_since`en la query · opcional	`string`	Solo registros modificados desde esta fecha y hora (ISO 8601).

Ejemplo

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

Respuestas

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

400 Cursor inválido: reinicie la lista sin 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 Clave ausente, inválida, vencida o revocada. application/problem+json

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

403 API desactivada en la escuela (code api_disabled) o clave sin el permiso necesario (code insufficient_scope, con la lista en 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 (detalle por campo en 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 Límite de llamadas alcanzado. 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"
}

Alumnos

Registro de los alumnos (students:read, students:write), resumen financiero (billing:read) y enlace de acceso al portal (portal:link).

GET /api/v1/students

Listar alumnos

Clave con students:read

Parámetros

Nombre	Tipo	Descripción
`limit`en la query · opcional	`integer`	Elementos por página (1 a 200).
`cursor`en la query · opcional	`string`	El meta.next_cursor de la página anterior.
`updated_since`en la query · opcional	`string`	Solo registros modificados desde esta fecha y hora (ISO 8601).
`email`en la query · opcional	`string`	E-mail exacto, sin distinguir mayúsculas.
`document_number`en la query · opcional	`string`	CPF (documento fiscal de persona física en Brasil) u otro documento, con o sin puntuación.
`external_id`en la query · opcional	`string`	Código del alumno en el sistema de la escuela.
`status`en la query · opcional	`string (active, inactive)`

Ejemplo

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

Respuestas

200 Página de alumnos. application/json

400 Cursor inválido: reinicie la lista sin 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 Clave ausente, inválida, vencida o revocada. application/problem+json

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

403 API desactivada en la escuela (code api_disabled) o clave sin el permiso necesario (code insufficient_scope, con la lista en 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 (detalle por campo en 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 Límite de llamadas alcanzado. 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

Registrar alumno

Clave con students:write

Crea el alumno y la cuenta de acceso al portal, como el registro del panel. El inicio de sesión sigue la configuración de la escuela (CPF o e-mail).

Parámetros

Nombre	Tipo	Descripción
`Idempotency-Key`en el encabezado · opcional	`string`	Código único de esta solicitud (hasta 255 caracteres visibles; sirve un UUID). Repetir con la misma clave en 24 h devuelve la primera respuesta.

Campos del cuerpo (JSON)

Nombre	Tipo	Descripción
`external_id`opcional	`string \| null`	Código del alumno en el sistema de la escuela. Único en la escuela.
`full_name`obligatorio	`string`
`email`opcional	`string \| null`
`phone`opcional	`string \| null`
`document_number`opcional	`string \| null`	CPF (verificado cuando la escuela activa la validación). Único en la escuela.
`birth_date`opcional	`string \| null`
`status`opcional	`string (active, inactive)`
`address`opcional	`object`
`send_welcome_email`opcional	`boolean`	Envía al alumno el e-mail con el usuario y la contraseña temporal del portal. Con false, la cuenta se crea sin e-mail (use el enlace de acceso o "Olvidé mi contraseña").

Ejemplo

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"}}'

Respuestas

201 Alumno registrado. application/json

400 Idempotency-Key ausente donde se exige (idempotency_key_required) o fuera del 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 Clave ausente, inválida, vencida o revocada. application/problem+json

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

403 API desactivada, clave sin el permiso (insufficient_scope) o límite de alumnos del plan alcanzado (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 Otra solicitud con la misma Idempotency-Key todavía está en curso. 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, con el detalle por campo en errors) o Idempotency-Key ya usada con otros datos (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 Límite de llamadas alcanzado. 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}

Un alumno

Clave con students:read

Parámetros

Nombre	Tipo	Descripción
`student`en la ruta · obligatorio	`integer`

Ejemplo

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

Respuestas

200 El alumno. application/json

401 Clave ausente, inválida, vencida o revocada. application/problem+json

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

403 API desactivada en la escuela (code api_disabled) o clave sin el permiso necesario (code insufficient_scope, con la lista en 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 El registro no existe en esta escuela. application/problem+json

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

429 Límite de llamadas alcanzado. 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}

Modificar alumno

Clave con students:write

Modifica solo los campos enviados. Si el alumno todavía no tenía cuenta en el portal y el dato de inicio de sesión pasa a existir, se crea la cuenta y sale el e-mail de bienvenida, como en la edición por el panel.

Parámetros

Nombre	Tipo	Descripción
`student`en la ruta · obligatorio	`integer`
`Idempotency-Key`en el encabezado · opcional	`string`	Código único de esta solicitud (hasta 255 caracteres visibles; sirve un UUID). Repetir con la misma clave en 24 h devuelve la primera respuesta.

Campos del cuerpo (JSON)

Nombre	Tipo	Descripción
`external_id`opcional	`string \| null`	Código del alumno en el sistema de la escuela. Único en la escuela.
`full_name`opcional	`string`
`email`opcional	`string \| null`
`phone`opcional	`string \| null`
`document_number`opcional	`string \| null`	CPF (verificado cuando la escuela activa la validación). Único en la escuela.
`birth_date`opcional	`string \| null`
`status`opcional	`string (active, inactive)`
`address`opcional	`object`

Ejemplo

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"}}'

Respuestas

200 Alumno modificado. application/json

400 Idempotency-Key ausente donde se exige (idempotency_key_required) o fuera del 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 Clave ausente, inválida, vencida o revocada. application/problem+json

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

403 API desactivada en la escuela (code api_disabled) o clave sin el permiso necesario (code insufficient_scope, con la lista en 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 El registro no existe en esta escuela. application/problem+json

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

409 Otra solicitud con la misma Idempotency-Key todavía está en curso. 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, con el detalle por campo en errors) o Idempotency-Key ya usada con otros datos (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 Límite de llamadas alcanzado. 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

Resumen financiero del alumno

Clave con billing:read

Suma las cuotas que todavía se pueden pagar en cualquier matrícula del alumno, incluida la multa de una matrícula cancelada. El contrato es el de la matrícula vigente más reciente.

Parámetros

Nombre	Tipo	Descripción
`student`en la ruta · obligatorio	`integer`

Ejemplo

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

Respuestas

200 El resumen. 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 Clave ausente, inválida, vencida o revocada. application/problem+json

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

403 API desactivada en la escuela (code api_disabled) o clave sin el permiso necesario (code insufficient_scope, con la lista en 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 El registro no existe en esta escuela. application/problem+json

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

429 Límite de llamadas alcanzado. 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

Enlace de acceso al portal del alumno

Clave con portal:link

Genera un enlace que abre el portal del alumno con la sesión ya iniciada, sin contraseña. Vale 5 minutos y una sola vez: genérelo en el momento del clic. El alumno tiene que estar activo y tener e-mail y cuenta en el portal.

Parámetros

Nombre	Tipo	Descripción
`student`en la ruta · obligatorio	`integer`

Ejemplo

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

Respuestas

201 Enlace generado. application/json

401 Clave ausente, inválida, vencida o revocada. application/problem+json

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

403 API desactivada en la escuela (code api_disabled) o clave sin el permiso necesario (code insufficient_scope, con la lista en 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 El registro no existe en esta escuela. application/problem+json

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

409 Alumno inactivo (student_inactive), sin e-mail o cuenta en el portal (student_without_portal_access), portal sin dirección (portal_not_configured) o e-mail repetido en otro alumno (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 Límite de llamadas alcanzado. 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 y contratos (enrollments:read, enrollments:write).

GET /api/v1/enrollments

Listar matrículas

Clave con enrollments:read

Parámetros

Nombre	Tipo	Descripción
`limit`en la query · opcional	`integer`	Elementos por página (1 a 200).
`cursor`en la query · opcional	`string`	El meta.next_cursor de la página anterior.
`updated_since`en la query · opcional	`string`	Solo registros modificados desde esta fecha y hora (ISO 8601).
`include`en la query · opcional	`string`	Datos relacionados, separados por coma: student (exige students:read), installments (exige billing:read), contract.
`student_id`en la query · opcional	`integer`
`external_id`en la query · opcional	`string`	Código de la matrícula en el sistema de la escuela.
`offering_id`en la query · opcional	`integer`
`trail_id`en la query · opcional	`integer`
`cohort_id`en la query · opcional	`integer`
`status`en la query · opcional	`string (pending_contract, pending_payment, active, cancelled, completed)`

Ejemplo

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

Respuestas

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

400 Cursor inválido: reinicie la lista sin 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 Clave ausente, inválida, vencida o revocada. application/problem+json

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

403 API desactivada en la escuela (code api_disabled) o clave sin el permiso necesario (code insufficient_scope, con la lista en 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 (detalle por campo en 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 Límite de llamadas alcanzado. 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

Crear matrícula

Clave con enrollments:write

Crea la matrícula como el panel: genera las cuotas y el contrato, inscribe al alumno en Moodle en el momento (cuando el grupo está vinculado a Moodle) y emite los cobros que ya están en la ventana de emisión — tarjeta en el momento; boleto y PIX cuando faltan pocos días para el vencimiento. Exige Idempotency-Key. Acepta ?include= como la consulta de la matrícula.

Parámetros

Nombre	Tipo	Descripción
`Idempotency-Key`en el encabezado · obligatorio	`string`	Código único de esta solicitud (hasta 255 caracteres visibles; sirve un UUID). Repetir con la misma clave en 24 h devuelve la primera respuesta.
`include`en la query · opcional	`string`	Datos relacionados, separados por coma: student (exige students:read), installments (exige billing:read), contract.

Campos del cuerpo (JSON)

Nombre	Tipo	Descripción
`external_id`opcional	`string \| null`	Código de la matrícula en el sistema de la escuela. Único en la escuela.
`student_id`opcional	`integer`
`student`opcional	`object`	Alumno nuevo. Los campos obligatorios siguen la configuración de la escuela (se pueden exigir CPF, teléfono y dirección; el e-mail se exige cuando el inicio de sesión del alumno es el e-mail).
`offering_id`opcional	`integer`
`trail_id`opcional	`integer`
`cohort_id`opcional	`integer \| null`	Grupo. Si está vinculado a una cohorte de Moodle, el alumno entra a Moodle en el momento, como en la matrícula por el panel.
`financial_plan_id`obligatorio	`integer`
`payment_method`obligatorio	`string (boleto, pix, credit_card)`	Tiene que ser aceptada por el plan y por la cuenta de Stripe de la escuela.
`contract_template_id`opcional	`integer \| null`	Modelo de contrato. Si exige firma, la matrícula se crea esperando contrato.
`base_value`opcional	`integer \| null`	Valor del curso en centavos. Sin él, vale el precio del curso (o la suma de los cursos del trayecto).
`enrollment_fee`opcional	`integer \| null`	Tasa de matrícula en centavos. Sin ella, vale la del plan.
`billing_start_date`opcional	`string \| null`	Inicio del cobro (AAAA-MM-DD).
`billing_due_day`opcional	`integer \| null`	Día de vencimiento de las cuotas.

Ejemplo

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"}'

Respuestas

201 Matrícula creada. application/json

400 Idempotency-Key ausente donde se exige (idempotency_key_required) o fuera del 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 Clave ausente, inválida, vencida o revocada. application/problem+json

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

403 API desactivada, clave sin el permiso (insufficient_scope) o, con un alumno nuevo, límite de alumnos del plan alcanzado (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 El alumno ya tiene una matrícula vigente en el mismo curso o trayecto (enrollment_conflict, con existing_enrollment_id) o la solicitud con esta Idempotency-Key todavía está en curso (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, con el detalle por campo en errors) o Idempotency-Key ya usada con otros datos (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 Límite de llamadas alcanzado. 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}

Una matrícula

Clave con enrollments:read

Parámetros

Nombre	Tipo	Descripción
`enrollment`en la ruta · obligatorio	`integer`
`include`en la query · opcional	`string`	Datos relacionados, separados por coma: student (exige students:read), installments (exige billing:read), contract.

Ejemplo

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

Respuestas

200 La matrícula. application/json

401 Clave ausente, inválida, vencida o revocada. application/problem+json

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

403 API desactivada en la escuela (code api_disabled) o clave sin el permiso necesario (code insufficient_scope, con la lista en 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 El registro no existe en esta escuela. application/problem+json

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

422 Parámetro inválido (detalle por campo en 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 Límite de llamadas alcanzado. 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 de la matrícula

Clave con enrollments:read

Parámetros

Nombre	Tipo	Descripción
`enrollment`en la ruta · obligatorio	`integer`

Ejemplo

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

Respuestas

200 El contrato. application/json

401 Clave ausente, inválida, vencida o revocada. application/problem+json

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

403 API desactivada en la escuela (code api_disabled) o clave sin el permiso necesario (code insufficient_scope, con la lista en 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 El registro no existe en esta escuela. application/problem+json

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

429 Límite de llamadas alcanzado. 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 del contrato

Clave con enrollments:read

El mismo PDF que descarga el panel de la escuela.

Parámetros

Nombre	Tipo	Descripción
`enrollment`en la ruta · obligatorio	`integer`

Ejemplo

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

Respuestas

200 El archivo. application/pdf

401 Clave ausente, inválida, vencida o revocada. application/problem+json

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

403 API desactivada en la escuela (code api_disabled) o clave sin el permiso necesario (code insufficient_scope, con la lista en 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 El registro no existe en esta escuela. application/problem+json

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

429 Límite de llamadas alcanzado. 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

Clave con enrollments:write

Cancela como el panel, sin multa por rescisión (esa solo por el panel): las cuotas pendientes se cancelan junto con los cobros en Stripe, el alumno recibe un aviso y sale de Moodle. Un boleto todavía dentro de su validez no se puede cancelar en Stripe y se puede pagar hasta que venza: meta.charges_still_payable dice cuántos.

Parámetros

Nombre	Tipo	Descripción
`enrollment`en la ruta · obligatorio	`integer`
`Idempotency-Key`en el encabezado · opcional	`string`	Código único de esta solicitud (hasta 255 caracteres visibles; sirve un UUID). Repetir con la misma clave en 24 h devuelve la primera respuesta.
`include`en la query · opcional	`string`	Datos relacionados, separados por coma: student (exige students:read), installments (exige billing:read), contract.

Campos del cuerpo (JSON)

Nombre	Tipo	Descripción
`reason`opcional	`string \| null (student_withdrawal, transfer, default, administrative, null)`	Desistimiento del alumno, traslado, morosidad o decisión administrativa.

Ejemplo

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"}'

Respuestas

200 Matrícula cancelada. application/json

400 Idempotency-Key ausente donde se exige (idempotency_key_required) o fuera del 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 Clave ausente, inválida, vencida o revocada. application/problem+json

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

403 API desactivada en la escuela (code api_disabled) o clave sin el permiso necesario (code insufficient_scope, con la lista en 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 El registro no existe en esta escuela. application/problem+json

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

409 La matrícula ya está cancelada o concluida (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, con el detalle por campo en errors) o Idempotency-Key ya usada con otros datos (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 Límite de llamadas alcanzado. 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"
}

Cobros

Cuotas, datos para pagar (billing:read) y segunda copia (billing:write).

GET /api/v1/installments

Listar cuotas

Clave con billing:read

Parámetros

Nombre	Tipo	Descripción
`limit`en la query · opcional	`integer`	Elementos por página (1 a 200).
`cursor`en la query · opcional	`string`	El meta.next_cursor de la página anterior.
`updated_since`en la query · opcional	`string`	Solo registros modificados desde esta fecha y hora (ISO 8601).
`enrollment_id`en la query · opcional	`integer`
`student_id`en la query · opcional	`integer`
`status`en la query · opcional	`string (open, paid, overdue, cancelled, waived, outstanding)`
`due_from`en la query · opcional	`string`
`due_to`en la query · opcional	`string`
`paid_from`en la query · opcional	`string`
`paid_to`en la query · opcional	`string`

Ejemplo

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

Respuestas

200 Página de cuotas. application/json

400 Cursor inválido: reinicie la lista sin 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 Clave ausente, inválida, vencida o revocada. application/problem+json

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

403 API desactivada en la escuela (code api_disabled) o clave sin el permiso necesario (code insufficient_scope, con la lista en 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 (detalle por campo en 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 Límite de llamadas alcanzado. 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}

Una cuota

Clave con billing:read

Incluye la imagen del código QR PIX (payment.pix_qr_code_base64), que la lista no trae.

Parámetros

Nombre	Tipo	Descripción
`installment`en la ruta · obligatorio	`integer`

Ejemplo

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

Respuestas

200 La cuota. application/json

401 Clave ausente, inválida, vencida o revocada. application/problem+json

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

403 API desactivada en la escuela (code api_disabled) o clave sin el permiso necesario (code insufficient_scope, con la lista en 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 El registro no existe en esta escuela. application/problem+json

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

429 Límite de llamadas alcanzado. 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

Generar segunda copia

Clave con billing:write

Genera la segunda copia con un nuevo vencimiento, como el panel: la cuota actual se cancela junto con el cobro en Stripe y se crea otra (replaces_installment_id apunta a la anterior), con un boleto o PIX nuevo y un e-mail al alumno. El valor no cambia por la API.

Parámetros

Nombre	Tipo	Descripción
`installment`en la ruta · obligatorio	`integer`
`Idempotency-Key`en el encabezado · opcional	`string`	Código único de esta solicitud (hasta 255 caracteres visibles; sirve un UUID). Repetir con la misma clave en 24 h devuelve la primera respuesta.

Campos del cuerpo (JSON)

Nombre	Tipo	Descripción
`due_date`opcional	`string \| null`	Nuevo vencimiento (AAAA-MM-DD, de hoy en adelante en la zona horaria de la escuela). Sin él, vence en 3 días.

Ejemplo

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"}'

Respuestas

201 La cuota nueva, con los datos para pagar. application/json

400 Idempotency-Key ausente donde se exige (idempotency_key_required) o fuera del 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 Clave ausente, inválida, vencida o revocada. application/problem+json

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

403 API desactivada en la escuela (code api_disabled) o clave sin el permiso necesario (code insufficient_scope, con la lista en 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 El registro no existe en esta escuela. application/problem+json

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

409 Cuota pagada, cancelada o dispensada (installment_not_payable), boleto actual todavía válido (boleto_still_valid) o escuela sin cuenta de 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, con el detalle por campo en errors) o Idempotency-Key ya usada con otros datos (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 Límite de llamadas alcanzado. 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 Stripe rechazó o no respondió (gateway_error). Con installment_id, la segunda copia se creó y su cobro sale de nuevo automáticamente. 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

Direcciones que reciben los avisos de la escuela (webhooks:manage). El formato del aviso está en webhooks → evento.

GET /api/v1/webhooks

Listar direcciones de aviso

Clave con webhooks:manage

Ejemplo

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

Respuestas

200 Direcciones de la escuela (sin el secreto). application/json

401 Clave ausente, inválida, vencida o revocada. application/problem+json

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

403 API desactivada en la escuela (code api_disabled) o clave sin el permiso necesario (code insufficient_scope, con la lista en 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 Límite de llamadas alcanzado. 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

Registrar dirección de aviso

Clave con webhooks:manage

La respuesta trae el secreto (secret) una sola vez: guárdelo para verificar la firma de los avisos. Hasta 10 direcciones por escuela.

Campos del cuerpo (JSON)

Nombre	Tipo	Descripción
`url`opcional	`string`	Tiene que ser https y apuntar a una dirección pública.
`description`opcional	`string \| null`
`events`opcional	`array`	Eventos suscritos (WebhookEventType) o ["*"] para todos.

Ejemplo

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

Respuestas

201 Dirección registrada, con el secreto. application/json

401 Clave ausente, inválida, vencida o revocada. application/problem+json

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

403 API desactivada en la escuela (code api_disabled) o clave sin el permiso necesario (code insufficient_scope, con la lista en 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 Límite de direcciones alcanzado. application/problem+json

422 Parámetro inválido (detalle por campo en 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 Límite de llamadas alcanzado. 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}

Una dirección de aviso

Clave con webhooks:manage

Parámetros

Nombre	Tipo	Descripción
`webhook`en la ruta · obligatorio	`integer`

Ejemplo

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

Respuestas

200 La dirección. application/json

401 Clave ausente, inválida, vencida o revocada. application/problem+json

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

403 API desactivada en la escuela (code api_disabled) o clave sin el permiso necesario (code insufficient_scope, con la lista en 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 El registro no existe en esta escuela. application/problem+json

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

429 Límite de llamadas alcanzado. 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}

Modificar dirección de aviso

Clave con webhooks:manage

Envíe solo lo que cambia. enabled: false pausa; enabled: true reactiva y pone en cero el conteo de fallas.

Parámetros

Nombre	Tipo	Descripción
`webhook`en la ruta · obligatorio	`integer`

Ejemplo

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

Respuestas

200 La dirección modificada. application/json

401 Clave ausente, inválida, vencida o revocada. application/problem+json

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

403 API desactivada en la escuela (code api_disabled) o clave sin el permiso necesario (code insufficient_scope, con la lista en 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 El registro no existe en esta escuela. application/problem+json

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

422 Parámetro inválido (detalle por campo en 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 Límite de llamadas alcanzado. 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}

Eliminar dirección de aviso

Clave con webhooks:manage

También borra el historial de entregas.

Parámetros

Nombre	Tipo	Descripción
`webhook`en la ruta · obligatorio	`integer`

Ejemplo

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

Respuestas

204 Eliminada.

401 Clave ausente, inválida, vencida o revocada. application/problem+json

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

403 API desactivada en la escuela (code api_disabled) o clave sin el permiso necesario (code insufficient_scope, con la lista en 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 El registro no existe en esta escuela. application/problem+json

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

429 Límite de llamadas alcanzado. 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

Historial de entregas de la dirección

Clave con webhooks:manage

Últimos 30 días, del más antiguo al más reciente.

Parámetros

Nombre	Tipo	Descripción
`webhook`en la ruta · obligatorio	`integer`
`limit`en la query · opcional	`integer`	Elementos por página (1 a 200).
`cursor`en la query · opcional	`string`	El meta.next_cursor de la página anterior.
`updated_since`en la query · opcional	`string`	Solo registros modificados desde esta fecha y hora (ISO 8601).

Ejemplo

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

Respuestas

200 Página de entregas. application/json

400 Cursor inválido: reinicie la lista sin 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 Clave ausente, inválida, vencida o revocada. application/problem+json

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

403 API desactivada en la escuela (code api_disabled) o clave sin el permiso necesario (code insufficient_scope, con la lista en 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 El registro no existe en esta escuela. application/problem+json

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

429 Límite de llamadas alcanzado. 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 prueba

Clave con webhooks:manage

Envía un aviso webhook.test a la dirección, en un solo intento. Funciona aunque la API de la escuela esté desactivada.

Parámetros

Nombre	Tipo	Descripción
`webhook`en la ruta · obligatorio	`integer`

Ejemplo

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

Respuestas

202 Aviso de prueba en cola. application/json

401 Clave ausente, inválida, vencida o revocada. application/problem+json

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

403 API desactivada en la escuela (code api_disabled) o clave sin el permiso necesario (code insufficient_scope, con la lista en 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 El registro no existe en esta escuela. application/problem+json

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

429 Límite de llamadas alcanzado. 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"
}