🎓Certificados

📜 Listar certificados

Endpoint

GET https://sua-plataforma.ensinio.cloud/public/api/v1/certificates

Headers obrigatórios

Authorization: Bearer {token}
X-Requested-With: XMLHttpRequest

(Os mesmos do “Getting Started”.)

Descrição

Retorna a lista de certificados com paginação e filtros opcionais por usuário e grupo.

Este endpoint depende da feature Public API – List Certificates estar habilitada no seu plano.

Parâmetros de query

Parâmetro	Tipo	Obrigatório	Padrão	Descrição
`user_id`	integer	❌	—	Filtra certificados pelo ID do usuário.
`group_id`	integer	❌	—	Filtra certificados pelo ID do grupo.
`page`	integer	❌	`1`	Número da página.
`per_page`	integer	❌	`15`	Itens por página (≥ 1).

Exemplos de requisição

Listar certificados (padrão)

GET /public/api/v1/certificates?page=1&per_page=15

Filtrar por usuário

GET /public/api/v1/certificates?user_id=9001

Filtrar por grupo com paginação customizada

GET /public/api/v1/certificates?group_id=12&page=2&per_page=50

Exemplo de resposta (paginação padrão do Laravel)

{
  "data": [
    {
      "id": 101,
      "user_id": 9001,
      "group_id": 12,
      "group_name": "Curso Completo de Marketing",
      "alternative_name": null,
      "member_name": "Ana Silva",
      "platform_name": "Minha Escola",
      "average_grade": 9.2,
      "member_photo": "https://cdn.example.com/users/9001.jpg",
      "link": "https://sua-plataforma.ensinio.cloud/certificados/101",
      "hash": "abcd1234efgh5678",
      "ch": "40h",
      "conclusion_date": "2025-05-20",
      "subscription_date": "2025-03-01",
      "expiration_date": "2026-03-01"
    },
    {
      "id": 102,
      "user_id": 9002,
      "group_id": 14,
      "group_name": "E-book Vendas",
      "alternative_name": "Cert. Vendas 2025",
      "member_name": "Bruno Oliveira",
      "platform_name": "Minha Escola",
      "average_grade": null,
      "member_photo": null,
      "link": "https://sua-plataforma.ensinio.cloud/certificados/102",
      "hash": "zz9911yy2233xx44",
      "ch": 8,
      "conclusion_date": "2025-05-10",
      "subscription_date": "2025-04-02",
      "expiration_date": null
    }
  ],
  "links": {
    "first": "https://sua-plataforma.ensinio.cloud/public/api/v1/certificates?page=1",
    "last": "https://sua-plataforma.ensinio.cloud/public/api/v1/certificates?page=5",
    "prev": null,
    "next": "https://sua-plataforma.ensinio.cloud/public/api/v1/certificates?page=2"
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 5,
    "path": "https://sua-plataforma.ensinio.cloud/public/api/v1/certificates",
    "per_page": 15,
    "to": 15,
    "total": 75
  }
}

🧩 Estrutura de cada item

Campo	Tipo	Descrição
`id`	int	ID do certificado.
`user_id`	int	ID do usuário.
`group_id`	int	ID do grupo.
`group_name`	string	null	Nome do grupo/curso.
`alternative_name`	string	null	Nome alternativo do certificado.
`member_name`	string	null	Nome do membro/aluno.
`platform_name`	string	null	Nome da plataforma
`average_grade`	number(float)	null	Média do aluno no grupo (quando aplicável).
`member_photo`	uri	null	URL da foto do usuário.
`link`	uri	null	URL pública do certificado.
`hash`	string	null	Hash do certificado.
`ch`	int	number	Carga horária.
`conclusion_date`	date	null	Data de conclusão.
`subscription_date`	date	null	Data de início da inscrição do aluno no grupo.
`expiration_date`	date	null	Data de expiração do certificado (se existir).

Possíveis respostas

200 OK — Lista paginada conforme exemplo.
400 Bad Request — Validação falhou (ex.: per_page inválido).
401 Unauthorized — Token inválido ou ausente.
403 Forbidden — Recurso não habilitado no plano (feature desativada).
429 Too Many Requests — Limite de requisições excedido.
500 Internal Server Error — Erro inesperado ao listar certificados.

✍️ Emitir certificado

Endpoint

POST https://sua-plataforma.ensinio.cloud/public/api/v1/certificates

Depende da feature Public API – Issue Certificate estar habilitada no seu plano.

Body (JSON)

Campo	Tipo	Obrigatório	Descrição
`group_id`	integer	✅	ID do grupo.
`user_id`	integer	✅	ID do usuário.
`conclusion_date`	date	✅	Data de conclusão (YYYY-MM-DD)

Exemplo

{
  "group_id": 12,
  "user_id": 9001,
  "conclusion_date": "2025-05-20"
}

Resposta (201 Created) — retorna um GroupCertificateDetailsResource:

{
  "id": 201,
  "user_id": 9001,
  "group_id": 12,
  "group_name": "Curso Completo de Marketing",
  "alternative_name": null,
  "member_name": "Ana Silva",
  "platform_name": "Minha Escola",
  "average_grade": 9.2,
  "member_photo": "https://cdn.example.com/users/9001.jpg",
  "link": "https://sua-plataforma.ensinio.cloud/certificados/201",
  "hash": "new201hash",
  "ch": "40h",
  "conclusion_date": "2025-05-20",
  "subscription_date": "2025-03-01",
  "expiration_date": "2026-03-01"
}

Erros comuns

400 — Dados inválidos (ex.: conclusion_date inválida).
401 — Token inválido/ausente.
403 — Feature desabilitada no plano.
404 — group_id ou user_id não encontrado.
429 — Rate limit excedido.
500 — Erro inesperado ao emitir certificado.

🗑️ Revogar certificado

Endpoint

DELETE https://sua-plataforma.ensinio.cloud/public/api/v1/certificates/{id}

Depende da feature Public API – Revoke Certificate estar habilitada no seu plano.

Parâmetros de path

Parâmetro	Tipo	Obrigatório	Descrição
`id`	integer	✅	ID do certificado.

Exemplo

DELETE /public/api/v1/certificates/201

Respostas

204 No Content — Certificado revogado com sucesso.
200 OK — Algumas instalações podem retornar um corpo:
```
{ "message": "Certificado revogado com sucesso." }
```
401 — Token inválido/ausente.
403 — Feature desabilitada no plano.
404 — Certificado não encontrado.
429 — Rate limit excedido.
500 — Erro inesperado ao revogar certificado.

🔐 Observações de autenticação e limite

Autenticação via Bearer Token.
Requisições sujeitas a rate limit por minuto (HTTP 429 quando excedido).
Inclua sempre X-Requested-With: XMLHttpRequest.