Como automatizar via API de integração do Nexur

Hoje Estamos Lançando a Esta é a documentação oficial da nova integração via API do nexur. Com ela você lista, cria, atualiza, consulta, ativa e desativa alunos da sua conta a partir de outro sistema.

>> Ver a Documentação Oficial Da API De Integração do Nexur.

Versão 1.1 — atualizada em setembro de 2026.

Sumário

1. Antes de começar
2. Autenticação
3. Status do aluno: o conceito mais importante
4. Excluir x desativar (a regra de ouro)
5. Endpoints
6. Estrutura de dados
7. Códigos de status e erros
8. O que esta API não faz
9. Suporte

1. Antes de começar

2. Autenticação

Todas as requisições precisam do token no cabeçalho:

Authorization: Bearer {SEU_TOKEN}
Content-Type: application/json

O token é pessoal e dá acesso de escrita à sua base de alunos. Guarde-o como uma senha: não coloque em código publicado, em planilha compartilhada nem em aplicativo que roda no navegador do cliente final. Se suspeitar que ele vazou, fale com o suporte para gerar um novo.

3. Status do aluno: o conceito mais importante

O campo status controla se o aluno aparece na plataforma e o que ele consegue acessar. Ele não é um liga/desliga: são cinco estados diferentes.

Os status 2 e 3 são definidos automaticamente pela cobrança do Nexur. Na prática, a sua integração deve trabalhar com 1 (Ativo) e 4 (Desativado).

4. Excluir x desativar (a regra de ouro)

O que o DELETE realmente faz

O DELETE /delete não apaga o registro do banco. Ele marca o aluno como excluído (status 0, com a data gravada em deletedAt). Todas as telas do app e do painel filtram registros nesse estado — por isso o aluno some da lista, dos treinos e dos relatórios, mas continua existindo no banco de dados.

O erro mais comum das integrações

É este fluxo aqui:

1. O sistema chama DELETE /delete?id=42 para “pausar” um aluno que cancelou.
2. Semanas depois o aluno volta, e o sistema chama POST /upsert?id=42 com "status": 1 para reativar.
3. A API responde 200 OK. O campo status realmente volta para 1 no banco.
4. E mesmo assim o aluno não aparece no app nem no painel.

O motivo: o que esconde o aluno do sistema não é o valor de status, e sim a marcação de exclusão feita pelo DELETE. O upsert altera os dados cadastrais e o status, mas não desfaz essa marcação. O resultado é o pior dos dois mundos: um cadastro que existe no banco, ocupa e-mail e login, mas não aparece em lugar nenhum.

Não existe endpoint de restauração. Um aluno excluído por engano precisa ser tratado como perda definitiva: o histórico dele (treinos, avaliações, medidas) não volta.

O que fazer no lugar

Recomendação prática: se a sua integração hoje chama o DELETE, troque essa chamada por um upsert com status: 4. Você mantém o histórico, o aluno continua visível na lista de desativados e a reativação passa a ser um campo de status — não um chamado para o suporte.

5. Endpoints

5.1 Listar alunos

GET /aluno/index — retorna uma lista paginada de alunos, com busca, ordenação e filtro por status.

Requisição

GET https://api.nexur.com.br/aluno/index?search=braga&limit=10&offset=0&field=nome&order=ASC&active=1
Authorization: Bearer {SEU_TOKEN}

Resposta (200 OK)

{
  "count": 125,
  "items": [
    {
      "id": 42,
      "nome": "Thiago Braga",
      "email": "thiago.braga@nexur.com.br",
      "uuid": "e4d1c2f0-3b7a-4b2d-9c1a-abcdef123456",
      "dataNascimento": "15/04/1990",
      "dataMatricula": "01/02/2025",
      "sexo": "Male",
      "grupo": 2,
      "login": "tbraga",
      "phone": "81987654321",
      "cpf_cnpj": "12345678901",
      "status": 1
    }
  ]
}

O campo count traz o total de registros que atendem ao filtro — use-o junto com limit e offset para paginar. Alunos excluídos (status 0) não aparecem nesta listagem.

5.2 Criar ou atualizar aluno (upsert)

POST /aluno/upsert é um endpoint só, com dois comportamentos bem diferentes. Quem decide qual deles acontece é a presença do id na chamada:

Campos do corpo da requisição

5.2.1 Criar um aluno novo — sem id

Não envie o id em lugar nenhum: nem na URL (?id=), nem no corpo. É a ausência dele que diz à API para criar um cadastro.

POST https://api.nexur.com.br/aluno/upsert
Content-Type: application/json
Authorization: Bearer {SEU_TOKEN}

{
  "nome": "Thiago Braga",
  "email": "thiago.braga@nexur.com.br",
  "uuid": "e4d1c2f0-3b7a-4b2d-9c1a-abcdef123456",
  "dataNascimento": "15/04/1990",
  "dataMatricula": "01/02/2025",
  "sexo": "Male",
  "grupo": 2,
  "login": "tbraga",
  "phone": "81987654321",
  "cpf_cnpj": "12345678901",
  "status": 1,
  "senha": "SenhaSegura123"
}

A resposta traz o id do aluno criado. Guarde esse id no seu sistema — é com ele que você vai fazer todas as atualizações daqui em diante.

5.2.2 Atualizar um aluno existente — com id

O id vai na URL. O aluno precisa existir e não estar excluído.

POST https://api.nexur.com.br/aluno/upsert?id=42
Content-Type: application/json
Authorization: Bearer {SEU_TOKEN}

{
  "nome": "Thiago Braga Silva",
  "email": "thiago.braga@nexur.com.br",
  "uuid": "e4d1c2f0-3b7a-4b2d-9c1a-abcdef123456",
  "dataNascimento": "15/04/1990",
  "dataMatricula": "01/02/2025",
  "sexo": "Male",
  "grupo": 2,
  "login": "tbraga",
  "phone": "81999998888",
  "cpf_cnpj": "12345678901",
  "status": 1,
  "senha": "SenhaSegura123"
}

No exemplo acima mudaram o sobrenome e o telefone. O mais seguro é reenviar a ficha completa do aluno trocando só o que mudou — assim você não corre o risco de apagar um campo sem querer.

5.2.3 Desativar ou reativar um aluno

É uma atualização como qualquer outra: a mesma chamada com id, mudando só o status. Para desativar, use "status": 4:

POST https://api.nexur.com.br/aluno/upsert?id=42
Content-Type: application/json
Authorization: Bearer {SEU_TOKEN}

{
  (demais campos do aluno)
  "status": 4
}

Para reativar, a mesma chamada com "status": 1. Como o aluno nunca foi excluído, ele volta a aparecer normalmente, com todo o histórico preservado.

Esta é a única forma de ativar e desativar aluno. O upsert com status explícito (1 ou 4) é sempre previsível: não importa quantas vezes a chamada se repita, o aluno termina no estado que você mandou — o que é essencial em sincronizações e filas de reprocessamento.

5.3 Consultar um aluno

GET /aluno/view?id={id} — retorna a ficha completa de um aluno.

GET https://api.nexur.com.br/aluno/view?id=42
Authorization: Bearer {SEU_TOKEN}

Resposta (200 OK)

{
  "id": 42,
  "nome": "Thiago Braga",
  "email": "thiago.braga@nexur.com.br",
  "uuid": "e4d1c2f0-3b7a-4b2d-9c1a-abcdef123456",
  "dataNascimento": "15/04/1990",
  "dataMatricula": "01/02/2025",
  "sexo": "Male",
  "grupo": 2,
  "login": "tbraga",
  "phone": "81987654321",
  "cpf_cnpj": "12345678901",
  "status": 1,
  "createdAt": "2025-02-01T14:32:00Z",
  "updatedAt": "2025-07-15T09:20:10Z"
}

Use esta chamada para conferir o status atual de um aluno antes de decidir o que gravar no upsert.

5.4 Excluir um aluno

DELETE /aluno/delete?id={id} — arquiva o aluno (status 0).

DELETE https://api.nexur.com.br/aluno/delete?id=42
Authorization: Bearer {SEU_TOKEN}

Resposta (200 OK)

{
  "message": "Aluno excluído com sucesso"
}

Efeitos da exclusão: o aluno some da listagem (/index), perde o acesso ao app, sai dos relatórios e o histórico dele deixa de ser consultável. O registro permanece no banco, ocupando o e-mail e o login usados — então, se você tentar recriar o mesmo aluno depois, pode esbarrar em conflito de cadastro.

6. Estrutura de dados

7. Códigos de status e erros

Um 200 OK não garante o efeito esperado no caso descrito na seção 4: reativar um aluno excluído responde 200, mas não o traz de volta. Sempre que uma reativação for crítica, confirme com um GET /index se o aluno realmente voltou a aparecer.

8. O que esta API não faz

• Não restaura aluno excluído. Não existe endpoint para isso.
• Não gerencia treinos, dietas, avaliações físicas ou medidas. Esta versão cobre apenas o cadastro do aluno.
• Não trata faturas, planos ou dados da sua assinatura. Isso continua no painel do Nexur.
• Não envia webhooks. Não há notificação de eventos: para saber o estado atual de um aluno, sua integração precisa consultar a API.
• Não faz importação em massa. Cadastros em lote são feitos com uma chamada por aluno.

9. Suporte

Dúvidas sobre a integração, pedido de token ou erro persistente: fale com a gente por e-mail em contato@aplicativonexur.com.br ou pelo WhatsApp (61) 99908-2525.

Ao abrir um chamado sobre a API, envie o endpoint chamado, o corpo da requisição (sem o token), a resposta recebida e o horário — isso reduz bastante o tempo de resposta.