Sandbox

Como o sandbox funciona

O sandbox é uma instância separada do Lumen, com banco de dados, filas, rotinas automáticas e arquivos próprios. Ele roda sempre a mesma versão da produção, então os endpoints, as validações e o formato das respostas são idênticos: o código que funciona no sandbox funciona em produção trocando só as credenciais.

• Só chaves de teste (lmn_test_…) funcionam no sandbox, e só nos clientes de teste do seu app. Nenhum outro parceiro vê os seus dados, e você não vê os deles.
• Filas e rotinas agendadas rodam como em produção: processamento de faltas, alertas, lembretes, PDFs e demais tarefas em segundo plano acontecem de verdade, e geram os mesmos webhooks.
• Toda resposta traz o cabeçalho X-Lumen-Environment: test. Use-o para confirmar em qual ambiente a sua integração está falando.
• Os dados ficam como você deixou: não há limpeza automática. Para voltar ao estado inicial, use "Recriar dados" (veja Limites e regras).

Preparando o ambiente

Tudo é feito por você, no Portal do Parceiro, em poucos minutos e sem depender de aprovação.

1. 1

   Crie a conta e o app

   Cadastre-se no portal, confirme o e-mail e crie um app. Todo app nasce no status Sandbox.

2. 2

   Gere uma chave de teste

   Na aba Credenciais do app, gere uma chave lmn_test_… e guarde-a: ela é exibida uma única vez. Ela vai no cabeçalho X-Partner.

3. 3

   Crie os clientes de teste

   Ainda na aba Credenciais, clique em "Criar cliente" no cartão Rede privada e/ou Rede pública (SEDUC). Em alguns segundos o cartão mostra o endereço da API, o X-Client, o X-Authorization, o CNPJ da escola e o login no sistema. A senha do login aparece uma única vez.

4. 4

   Configure o endpoint de teste dos webhooks

   Na aba Webhooks, informe o Endpoint de teste e os eventos que quer receber. Tudo o que acontece nos seus clientes de teste é entregue ali.

5. 5

   Faça a primeira chamada

   Chame a API do sandbox com a chave, o X-Client e o X-Authorization do cliente de teste. Use o quadro Dados de teste para preencher os parâmetros dos endpoints.

6. 6

   Entre no sistema como a escola

   Clique em "Entrar no sandbox" no cartão do cliente para abrir o sistema web já logado como a rede de ensino, e use-o como a escola usaria.

Clientes de teste

Cada app pode ter até dois clientes de teste: uma rede privada e uma rede pública (SEDUC). Os dois são criados pelo mesmo processo de implantação de um cliente real, com uma escola, o Colégio Demonstração, com CNPJ próprio e dados de demonstração. Crie o tipo que corresponde aos clientes que vão usar a sua integração, ou os dois, se ela atende ambos.

O que o cartão do cliente mostra

Dados de teste

O Colégio Demonstração já vem com dados em todos os módulos da referência da API: turmas, alunos, responsáveis, professores, horários, aulas, notas, frequência, diário de classe, conselho de classe, ocorrências, fotos e os módulos de ERP. Todo endpoint GET documentado devolve dados desde o primeiro dia.

Para não ter de procurar IDs, abra o quadro Dados de teste no cartão do cliente. Ele traz um valor pronto para cada parâmetro de caminho:

• Os valores se encaixam entre si: a turma é a que tem mais dados, o aluno está matriculado nela, o CPF é do responsável dele e a data é de uma aula com frequência e plano de aula registrados.
• O quadro também traz o ID de um registro de cada recurso endereçado por {id} (turma, professor, disciplina, ano letivo, aviso da agenda, aula, conselho de classe, ocorrência disciplinar, portão, espaço físico…). Parâmetros nomeados como {event} e {contract} aparecem junto com os demais. Valores de módulos que o tipo de rede não tem (contrato e CRM na rede pública, por exemplo) não aparecem.
• Os valores são lidos na hora em que você abre o quadro, então acompanham o que você alterou ou excluiu.
• Os dados são fictícios. Nunca cadastre dados reais de alunos, responsáveis ou funcionários no sandbox.

Chamando a API do sandbox

Guarde o endereço da API e as três credenciais em variáveis de ambiente, nunca no código. Assim, ir para a produção é só trocar a configuração. Este exemplo busca a frequência de um dia da turma de demonstração, com os valores do quadro Dados de teste:

LUMEN_API_URL=https://sandbox.lumenerp.app.br/api/v1
LUMEN_KEY=lmn_test_{sua_chave}
LUMEN_CLIENT={X-Client do cliente de teste}
LUMEN_TOKEN={X-Authorization do cliente de teste}

use GuzzleHttp\Client;

$lumen = new Client([
    'base_uri' => getenv('LUMEN_API_URL') . '/',
    'headers'  => [
        'X-Partner'       => getenv('LUMEN_KEY'),
        'X-Client'        => getenv('LUMEN_CLIENT'),
        'X-Authorization' => getenv('LUMEN_TOKEN'),
    ],
]);

$response = $lumen->get('partners/school/{cnpj}/classroom/{classroom_id}/attendance/day', [
    'query' => ['date' => '{date}'],
]);

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

const headers = {
    'X-Partner':       process.env.LUMEN_KEY,
    'X-Client':        process.env.LUMEN_CLIENT,
    'X-Authorization': process.env.LUMEN_TOKEN,
};

const url = `${process.env.LUMEN_API_URL}/partners/school/{cnpj}/classroom/{classroom_id}/attendance/day?date={date}`;
const response = await fetch(url, { headers });

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

Substitua {cnpj}, {classroom_id} e {date} pelos valores do quadro Dados de teste.

Usando o sistema web

O sandbox tem o sistema web completo do Lumen. Use-o para fazer, como a escola, o que vai disparar a sua integração, e para conferir na tela o que a sua integração gravou pela API.

Caixa de saída e serviços simulados

Nada sai do sandbox para o mundo real. Os serviços externos que o Lumen usa em produção são capturados ou simulados, sem custo e sem risco de atingir pessoas reais.

Webhooks no sandbox

O endpoint de teste recebe todos os eventos dos seus clientes de teste, qualquer que seja a origem: uma chamada da sua integração à API, uma ação feita no sistema web ou uma rotina automática. Isso permite testar o caminho de volta, quando a escola faz algo e a sua integração precisa reagir.

• As entregas têm o mesmo formato e a mesma assinatura da produção, com "environment": "test" e "client" com o slug do cliente de teste. Veja como validar a assinatura.
• O endpoint precisa ser público. Endereços como localhost, domínios .local/.test e IPs de rede privada são recusados. Para receber na sua máquina, use um túnel público (ngrok, Cloudflare Tunnel ou similar).
• Mudanças no endpoint de teste, nos eventos escolhidos ou no segredo chegam ao sandbox em poucos segundos.
• Na aba Webhooks do portal você envia eventos de teste, vê o histórico de entregas e reenvia uma entrega, o que serve para testar se a sua integração descarta repetições pelo webhook-id.

Roteiro para validar a integração

Antes de pedir a aprovação para produção, percorra no sandbox todos os caminhos que a sua integração vai usar. Este roteiro cobre o que a equipe Lumen avalia na revisão do app.

Limites e regras

Erros comuns no sandbox

Além dos erros gerais da API e dos erros de acesso do portal: