Portal do Parceiro

Do cadastro à produção

O caminho de uma integração nova tem seis etapas. As três primeiras você faz sozinho, em minutos; as demais dependem de aprovação.

1. 1

   Crie a conta

   Cadastre-se no portal e confirme o e-mail. O acesso ao painel só é liberado depois da confirmação.

2. 2

   Crie um app

   Cada integração é um app, com chaves, conexões, webhooks e logs próprios. O app nasce no status Sandbox.

3. 3

   Teste no sandbox

   Na aba Credenciais, gere uma chave lmn_test_…, crie os clientes de teste do app e chame a API no sandbox. Nada do que você faz ali chega à produção.

4. 4

   Peça a aprovação para produção

   Na aba Visão geral, descreva como o app usa a API: quais dados lê e grava, com que frequência, quem são os usuários finais e como os dados de alunos são protegidos (LGPD). A equipe Lumen revisa cada app e você recebe a decisão por e-mail.

5. 5

   Peça acesso a cada cliente

   Aprovado o app, informe na aba Clientes o CNPJ de uma escola do cliente que contratou a sua integração. A equipe Lumen confirma com o cliente e libera o acesso.

6. 6

   Gere o token da conexão

   Com o acesso liberado, gere uma chave lmn_live_… e o token da conexão com aquele cliente. A partir daí o app chama a API com os dados reais da escola.

Sandbox e produção

O sandbox é uma instância separada do Lumen, com banco de dados, filas e arquivos próprios, em https://sandbox.lumenerp.app.br. Chaves de teste só funcionam lá; chaves de produção só funcionam em produção. Os endpoints e o formato das respostas são os mesmos nos dois. O guia Sandbox explica como usá-lo para desenvolver e validar a sua integração.

• Toda resposta traz o cabeçalho X-Lumen-Environment (test ou live) e os cabeçalhos X-RateLimit-*. O limite é contado por app e por ambiente e vale para todos os endpoints da API de parceiros.
• Na aba Credenciais, crie o cliente de teste da rede privada e/ou da rede pública (SEDUC). Cada um vem com uma escola, o Colégio Demonstração, com dados em todos os módulos da referência da API: turmas, alunos, responsáveis, professores, notas, frequência, diário, conselho de classe, ocorrências, fotos, eventos, biblioteca, metas, cursos online e visitantes. Contratos e CRM têm dados só na rede privada, e o Orçamento Público só na rede pública.
• O quadro Dados de teste de cada cliente traz um valor pronto para cada parâmetro dos endpoints (CNPJ, turma, matrícula, CPF, aula, nota, evento, meta…) e o ID de um registro de cada recurso endereçado por {id}.
• Os clientes de teste são só do seu app: nenhum outro parceiro os vê, e os dados ficam como você deixou. Para voltar ao estado inicial, use "Recriar dados" — o cliente é apagado e criado de novo, com novo X-Client, X-Authorization e login.
• No sandbox, pagamentos e assinaturas eletrônicas são simulados: o link de uma cobrança abre uma página onde você "paga" (PIX, boleto ou cartão), e o link de assinatura abre uma página onde você "assina". A escola recebe a confirmação como receberia em produção, e os webhooks correspondentes são enviados.
• Uma chave de teste usada em produção recebe 403 com "code": "SANDBOX_HOST" e o endereço do sandbox.

Primeira chamada no sandbox

Com uma chave de teste e o slug e o token de um cliente de teste copiados da aba Credenciais, liste as escolas desse cliente no sandbox:

use GuzzleHttp\Client;

$client = new Client();

$response = $client->get('https://sandbox.lumenerp.app.br/api/v1/partners/schools/all', [
    'headers' => [
        'X-Partner'       => 'lmn_test_{sua_chave}',
        'X-Client'        => '{slug_do_cliente_de_teste}',
        'X-Authorization' => '{token_do_cliente_de_teste}',
    ],
]);

$environment = $response->getHeaderLine('X-Lumen-Environment'); // "test"

const response = await fetch('https://sandbox.lumenerp.app.br/api/v1/partners/schools/all', {
    headers: {
        'X-Partner':       'lmn_test_{sua_chave}',
        'X-Client':        '{slug_do_cliente_de_teste}',
        'X-Authorization': '{token_do_cliente_de_teste}',
    },
});

const environment = response.headers.get('X-Lumen-Environment'); // "test"

Para ir à produção, troque os três valores: a chave lmn_live_…, o slug do cliente e o token da conexão, ambos mostrados na aba Clientes. O código da integração não muda.

Status do app

Chaves de teste funcionam em qualquer status, exceto quando o app está suspenso. Chaves de produção só funcionam com o app em Produção.

Um app, ou a conta inteira do desenvolvedor, pode ser suspenso pela equipe Lumen. Enquanto estiver suspenso, todas as chaves respondem 403, inclusive as de teste.

Chaves e tokens

Segurança da conta

A conta de desenvolvedor dá acesso às credenciais das integrações com escolas. Na página Conta do portal, ative a verificação em duas etapas e cadastre uma chave SSH de recuperação.

Comprovar com uma chave de API

Chame a produção com uma chave do app, de onde a integração a guarda, enviando o desafio rec_… mostrado no portal. Só o cabeçalho X-Partner é necessário. Se a conta tiver chaves de produção, a comprovação exige uma chave lmn_live_….

curl -X POST https://lumenerp.app.br/api/v1/partner-portal/account-recovery \
  -H "X-Partner: $LUMEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"challenge":"rec_…"}'

Comprovar com uma chave SSH

Assine o desafio com a chave privada correspondente a uma chave SSH cadastrada e cole a assinatura no portal:

printf '%s' 'rec_…' | ssh-keygen -Y sign -n lumen-partner-2fa-recovery -f ~/.ssh/id_ed25519

Erros de acesso

Além dos erros gerais da API, requisições feitas com chaves do portal podem receber: