Autenticação

Para acessar qualquer endpoint da API do Lumen ERP você deve incluir três cabeçalhos HTTP em todas as suas requisições. Esses cabeçalhos identificam o parceiro, o token de autorização e o cliente (rede escolar) sendo acessado.

Cabeçalhos obrigatórios

X-Authorization

Token de autorização

Token de acesso ao cliente. Apps do Portal do Parceiro usam o token do cliente de teste (sandbox) ou o token da conexão com o cliente (produção).

X-Partner

Token do parceiro

Chave do app no Portal do Parceiro (lmn_test_… ou lmn_live_…). Integrações anteriores ao portal usam o token de parceiro recebido da equipe Lumen.

X-Client

Slug do cliente

Identificador em texto da rede escolar (cliente) que está sendo acessada. Exemplo: colegio-exemplo.

Apps do Portal do Parceiro

Novas integrações usam os mesmos três cabeçalhos com credenciais geradas no Portal do Parceiro: crie um app, gere uma chave e teste no sandbox antes de pedir a aprovação para produção. O passo a passo completo está no guia Portal do Parceiro.

X-Partner

Chave do app. lmn_test_… funciona somente no sandbox (https://sandbox.lumenerp.app.br/api/v1), uma instância separada da produção com os clientes de teste do app; lmn_live_… acessa a produção e só existe depois que o app é aprovado.

X-Client

No sandbox, o slug de um dos clientes de teste do app, mostrado no portal. Em produção, o slug do cliente cujo acesso foi liberado para o app.

X-Authorization

No sandbox, o token desse cliente de teste, mostrado no portal. Em produção, o token da conexão do app com aquele cliente (lmn_conn_…), gerado no portal depois que a equipe Lumen libera o acesso.

Chaves e tokens são exibidos uma única vez. Guarde-os num cofre de segredos; o Lumen armazena apenas um hash.
Toda resposta traz o cabeçalho X-Lumen-Environment (test ou live) e os limites de requisição por minuto do app (X-RateLimit-*).
Respostas específicas: 400 X-Client ou X-Authorization ausente, 401 chave ou token inválido/revogado, 403 app não aprovado ou suspenso (ou, com "code": "SANDBOX_HOST", chave de teste usada em produção), 429 limite excedido.

Exemplo de requisição autenticada

Adicione os três cabeçalhos em todas as chamadas à API. Substitua os valores pelas credenciais do seu app no Portal do Parceiro (ou pelas recebidas da equipe Lumen, nas integrações anteriores ao portal).

curl https://lumenerp.app.br/api/v1/partners/schools/all \
  -H "X-Authorization: lmn_conn_{token_da_conexao}" \
  -H "X-Partner: lmn_live_{sua_chave}" \
  -H "X-Client: colegio-exemplo"

use GuzzleHttp\Client;

$client = new Client();

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

$data = json_decode($response->getBody(), true);

const response = await fetch('https://lumenerp.app.br/api/v1/partners/schools/all', {
    headers: {
        'X-Authorization': '{api_token}',
        'X-Partner':       '{partner_token}',
        'X-Client':        '{client_slug}',
    },
});

const data = await response.json();

Autenticação inválida

Os cabeçalhos são verificados antes de qualquer outra regra do endpoint. Toda recusa vem em JSON com "success": false e uma mensagem fixa, em inglês, que você pode usar para distinguir os casos:

400

Missing required headers.

Um dos três cabeçalhos está ausente ou vazio.

401

Partner unauthorized.

X-Partner não corresponde a nenhum parceiro (credenciais recebidas da equipe Lumen).

401

Invalid or revoked API key.

Chave do Portal do Parceiro inválida, revogada ou expirada após uma rotação.

401

Unauthorized.

X-Client e X-Authorization não correspondem a um cliente acessível com essa chave.

403

This API is offline. …

O cliente desativou o acesso à API. Fale com o administrador do cliente.

404

CNPJ not found.

O {cnpj} da rota não pertence a nenhuma escola do cliente autenticado.

401

Only Portal do Parceiro test keys (lmn_test_) work in the sandbox.

Credenciais de parceiro anteriores ao portal enviadas ao sandbox. Use a chave de teste de um app.

403

Production keys (lmn_live_) do not work in the sandbox. …

Chave de produção enviada ao sandbox. Use uma chave lmn_test_.

Chaves do Portal do Parceiro podem receber ainda 403 (app não aprovado ou suspenso, ou chave de teste usada em produção, com "code": "SANDBOX_HOST"); veja a tabela completa no guia Portal do Parceiro.

Resposta de erro 401

{
  "success": false,
  "message": "Unauthorized."
}