Conta e chaves
Tudo que o console faz com a sua conta também se faz pela API, porque o console é cliente dela. Este guia mostra o caminho completo: cadastrar, entrar, criar uma chave, usar os escopos, revogar, e ler a conta, o plano e o estado da plataforma.
Como a API autentica#
Toda rota de integração pede uma chave no cabeçalho Authorization, no formato Bearer hlsn_.... A chave carrega escopos: cada rota exige o seu, e uma chave sem o escopo recebe 403. Sem chave, ou com uma chave inválida ou revogada, a resposta é 401.
Há dois tipos de credencial. A chave de integração é a do seu servidor: vale até ser revogada. A sessão é a do console: vale oito horas, nasce do login, e não cria nem revoga chaves sozinha. Para criar uma chave, a sessão confirma a senha antes (passo 3 abaixo).
1. Cadastrar a conta#
POST /v1/operators/signup cria a conta e o primeiro operador numa chamada só, sem credencial. A senha tem no mínimo 12 caracteres, e quem monta a tela lê esse mínimo em GET /v1/public/password-policy ({ "minLength": 12 }, sem credencial), em vez de copiar o número. A resposta é 201 e não traz sessão: o próximo passo é entrar.
curl -X POST "https://api.lunahia.com.br/v1/operators/signup" \
-H "Content-Type: application/json" \
-d '{
"email": "ana@suaempresa.com.br",
"password": "uma frase longa que so voce sabe",
"tenantName": "Sua Empresa"
}'const res = await fetch('https://api.lunahia.com.br/v1/operators/signup', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
},
body: JSON.stringify({
"email": "ana@suaempresa.com.br",
"password": "uma frase longa que so voce sabe",
"tenantName": "Sua Empresa"
}),
});
console.log(res.status, await res.json());import requests
res = requests.post(
"https://api.lunahia.com.br/v1/operators/signup",
json={
"email": "ana@suaempresa.com.br",
"password": "uma frase longa que so voce sabe",
"tenantName": "Sua Empresa",
},
timeout=10,
)
print(res.status_code, res.json()){
"nextStep": "login"
}A Luna manda um e-mail com um link de confirmação. Ele vale por sete dias e é aceito uma vez. A conta já lê a documentação e cria chaves antes de confirmar, mas só a conta confirmada abre sessão de conexão de número. Se o e-mail não chegou, POST /v1/operators/confirmation/resend envia de novo (só com a sessão do console, e há um teto de poucos reenvios por hora).
2. Entrar#
POST /v1/operators/login troca e-mail e senha por uma credencial de sessão de oito horas. O campo token é o Bearer das próximas chamadas deste guia que usam a sessão. A recusa é sempre a mesma, seja senha errada ou conta inexistente.
curl -X POST "https://api.lunahia.com.br/v1/operators/login" \
-H "Content-Type: application/json" \
-d '{
"email": "ana@suaempresa.com.br",
"password": "uma frase longa que so voce sabe"
}'const res = await fetch('https://api.lunahia.com.br/v1/operators/login', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
},
body: JSON.stringify({
"email": "ana@suaempresa.com.br",
"password": "uma frase longa que so voce sabe"
}),
});
console.log(res.status, await res.json());import requests
res = requests.post(
"https://api.lunahia.com.br/v1/operators/login",
json={
"email": "ana@suaempresa.com.br",
"password": "uma frase longa que so voce sabe",
},
timeout=10,
)
print(res.status_code, res.json()){
"tenantId": "0b5e3c1a-7d42-4f6a-9c18-2e7a1d5b8f90",
"operatorId": "6a2d9f40-1b73-4e85-a0c6-3d8e5f7b9a12",
"token": "hlsn_...",
"expiresAt": "2026-10-28T20:00:00.000Z",
"scopes": [
"onboarding:write", "numbers:read", "numbers:write", "messages:read", "messages:write",
"templates:read", "templates:write", "webhooks:read", "webhooks:write", "keys:read",
"session:end", "session:elevate"
]
}export LUNA_SESSION="hlsn_..."Para trocar a senha sabendo a de hoje, sem passar pelo "Esqueci minha senha", use POST /v1/operators/password/change com a sessão e o corpo { "currentPassword": "...", "newPassword": "..." }. A resposta é 204. A senha nova segue a mesma regra do cadastro, as outras sessões do operador são encerradas e a que pediu a troca continua valendo. Senha atual errada responde 401, e há um teto de tentativas por sessão.
3. Confirmar a senha#
Criar e revogar chave é uma ação sensível. POST /v1/operators/step-up confirma a senha do operador da sessão e abre uma janela de duas horas em que essa mesma sessão pode criar e revogar chaves. A resposta traz elevatedUntil, o fim da janela, e em scopes o que a janela empresta à sessão (keys:write). Passadas as duas horas, a senha é pedida de novo.
curl -X POST "https://api.lunahia.com.br/v1/operators/step-up" \
-H "Authorization: Bearer $LUNA_SESSION" \
-H "Content-Type: application/json" \
-d '{
"password": "uma frase longa que so voce sabe"
}'{
"elevatedUntil": "2026-10-28T14:00:00.000Z",
"scopes": ["keys:write"]
}Para saber se a janela ainda está aberta sem pedir a senha à toa, leia GET /v1/operators/session com a sessão: expiresAt é o fim da sessão, elevatedUntil é o fim da janela (nulo sem janela ou com ela fechada) e scopes são os escopos que a sessão tem agora. Pede o escopo session:end, que a sessão do console já tem.
4. Criar uma chave#
POST /v1/api-keys cria a chave. Peça só os escopos de que ela precisa: uma chave que só envia mensagem não deveria poder conectar número nem criar outras chaves. Com externalId, a chave é de UM cliente seu e só enxerga o que é dele. Com mode: "test", a chave é de teste: ela envia sem ir à Meta, e só usa duas rotas (veja Modo de teste). A resposta traz o campo secret uma única vez: não há rota que o devolva depois, e quem o perde revoga a chave e cria outra.
curl -X POST "https://api.lunahia.com.br/v1/api-keys" \
-H "Authorization: Bearer $LUNA_SESSION" \
-H "Content-Type: application/json" \
-d '{
"label": "Integração de produção",
"scopes": [
"messages:write",
"messages:read",
"numbers:read"
]
}'{
"id": "7d1f4c02-9a3b-4e51-8c7d-2f0b6a91e334",
"label": "Integração de produção",
"kind": "integration",
"scopes": ["messages:write", "messages:read", "numbers:read"],
"mode": "live",
"externalId": null,
"createdAt": "2026-10-28T12:10:44.201Z",
"expiresAt": null,
"revokedAt": null,
"lastUsedAt": null,
"secret": "hlsn_..."
}export LUNA_API_KEY="hlsn_..."Os escopos#
A lista é fechada e igual para todas as contas. Estes são os escopos que uma chave de integração pode ter. Os escopos session:end e session:elevate existem só nas sessões do console.
| Escopo | O que deixa fazer |
|---|---|
keys:read | Listar e consultar as chaves da conta. |
keys:write | Criar e revogar chaves. |
numbers:read | Ler números, a saúde deles, as contas de negócio, os links de conexão, a conta e o plano. |
numbers:write | Editar o rótulo de um número, reconectar e desconectar. |
messages:read | Ler mensagens e conversas, e baixar a mídia que chegou. |
messages:write | Enviar mensagens, enviar arquivos de mídia, marcar como lida e mostrar “digitando”. |
templates:read | Listar e consultar templates. |
templates:write | Criar, editar e remover templates, e enviar os arquivos de exemplo. |
onboarding:write | Conectar números: abrir e concluir sessões, reconectar, informar o PIN, e criar e apagar links de conexão. |
webhooks:read | Ler os endpoints de webhook, os tipos de evento e os eventos que a Luna desistiu de entregar. |
webhooks:write | Cadastrar, editar, testar e remover endpoints, trocar o segredo, reenfileirar eventos e pedir que o evento de uma mensagem seja entregue de novo. |
GET /v1/api-keys/scopes devolve esta mesma lista pela API: cada escopo com o nome em português (label), o que ele permite (summary) e sensitive, que é true nas permissões que dão um poder que exige cuidado (criar chaves e redirecionar o webhook). GET /v1/api-keys/profiles devolve os perfis prontos, agent (atendimento), full (integração completa) e read_only (somente leitura), cada um com os escopos que concede. Ao criar a chave, mande profile no lugar de scopes, um dos dois e nunca os dois: a chave nasce com os escopos que o perfil concede naquele momento, e guarda os escopos, e o perfil fica só como rótulo, em profile (nulo quando você escolheu os escopos um a um). Cada chave da lista traz também status (active, revoked ou expired, decidido pela API) e allowedActions (revoke enquanto a chave de integração vale), para você mostrar o botão sem comparar datas. As duas rotas pedem keys:read.
Listar e revogar chaves#
GET /v1/api-keys lista as chaves, com escopos, criação, último uso e revogação. O segredo nunca aparece. Use kind=integration para ver só as chaves de integração e esconder as sessões do console. O escopo é keys:read.
curl -X GET "https://api.lunahia.com.br/v1/api-keys?kind=integration" \
-H "Authorization: Bearer $LUNA_API_KEY"const res = await fetch('https://api.lunahia.com.br/v1/api-keys?kind=integration', {
method: 'GET',
headers: {
Authorization: `Bearer ${process.env.LUNA_API_KEY}`,
},
});
console.log(res.status, await res.json());import os
import requests
res = requests.get(
"https://api.lunahia.com.br/v1/api-keys?kind=integration",
headers={
"Authorization": f"Bearer {os.environ['LUNA_API_KEY']}",
},
timeout=10,
)
print(res.status_code, res.json())POST /v1/api-keys/{id}/revoke invalida a chave na hora. Repetir a chamada devolve o mesmo resultado, sem erro, e a data da revogação fica registrada. Pede keys:write e, para a sessão do console, a janela do passo 3.
curl -X POST "https://api.lunahia.com.br/v1/api-keys/YOUR_KEY_ID/revoke" \
-H "Authorization: Bearer $LUNA_API_KEY"const res = await fetch('https://api.lunahia.com.br/v1/api-keys/YOUR_KEY_ID/revoke', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.LUNA_API_KEY}`,
},
});
console.log(res.status, await res.json());import os
import requests
res = requests.post(
"https://api.lunahia.com.br/v1/api-keys/YOUR_KEY_ID/revoke",
headers={
"Authorization": f"Bearer {os.environ['LUNA_API_KEY']}",
},
timeout=10,
)
print(res.status_code, res.json())Ler a conta e o plano#
GET /v1/account devolve a conta da credencial: identificador, nome, se o e-mail já foi confirmado e quando a conta foi criada. Não tem escopo próprio: pede numbers:read, o mais leve dos escopos de leitura. O campo operatorEmail só vem preenchido quando a credencial é uma sessão do console.
curl -X GET "https://api.lunahia.com.br/v1/account" \
-H "Authorization: Bearer $LUNA_API_KEY"const res = await fetch('https://api.lunahia.com.br/v1/account', {
method: 'GET',
headers: {
Authorization: `Bearer ${process.env.LUNA_API_KEY}`,
},
});
console.log(res.status, await res.json());import os
import requests
res = requests.get(
"https://api.lunahia.com.br/v1/account",
headers={
"Authorization": f"Bearer {os.environ['LUNA_API_KEY']}",
},
timeout=10,
)
print(res.status_code, res.json()){
"id": "0b5e3c1a-7d42-4f6a-9c18-2e7a1d5b8f90",
"name": "Sua Empresa",
"emailConfirmed": true,
"createdAt": "2026-10-28T11:58:02.114Z",
"operatorEmail": null
}PATCH /v1/account troca o nome da conta. O corpo é { "name": "..." }, de 1 a 120 caracteres, e a resposta é a conta já com o nome novo, no mesmo formato do GET. Só a sessão do console faz isto (escopo session:end), e a suspensão do plano não bloqueia.
GET /v1/subscription devolve o plano, a capacidade de números e quantos estão em uso. Ele tem um guia próprio: Plano e números.
curl -X GET "https://api.lunahia.com.br/v1/subscription" \
-H "Authorization: Bearer $LUNA_API_KEY"const res = await fetch('https://api.lunahia.com.br/v1/subscription', {
method: 'GET',
headers: {
Authorization: `Bearer ${process.env.LUNA_API_KEY}`,
},
});
console.log(res.status, await res.json());import os
import requests
res = requests.get(
"https://api.lunahia.com.br/v1/subscription",
headers={
"Authorization": f"Bearer {os.environ['LUNA_API_KEY']}",
},
timeout=10,
)
print(res.status_code, res.json())GET /v1/account/overview devolve o resumo que uma tela inicial precisa, já decidido pela API: attention, a lista do que a conta precisa olhar (cada item com code, severity, title, message, solution, o resource a que se refere, a action que resolve e since), na ordem em que deve aparecer, com o que está parado primeiro; checklist, os quatro primeiros passos (connect_number, create_key, add_webhook_endpoint e send_message), cada um com done e doneAt; e numbers, os números por estado de conexão. Pede numbers:read, e uma chave restrita a um cliente seu é recusada, porque o resumo é da conta inteira.
Ver se a plataforma está de pé#
GET /status não pede chave e não revela dado de nenhuma conta. Ele responde o estado da plataforma, medido a cada poucos minutos por uma mensagem sintética que entra pela mesma porta que a Meta usa e precisa chegar a um destino por HTTPS. O status é ok, degraded, down ou unknown; sem verificação recente, é unknown, e nunca ok. components separa a entrada (ingestion), a entrega (delivery) e o horizonte de partições do banco (partitions).
curl -X GET "https://api.lunahia.com.br/status"const res = await fetch('https://api.lunahia.com.br/status', {
method: 'GET',
});
console.log(res.status, await res.json());import requests
res = requests.get(
"https://api.lunahia.com.br/status",
timeout=10,
)
print(res.status_code, res.json()){
"status": "ok",
"checkedAt": "2026-10-28T12:05:00.000Z",
"components": { "ingestion": "ok", "delivery": "ok", "partitions": "ok" },
"since": "2026-10-27T09:30:00.000Z"
}GET /healthz é a sonda mais simples: responde 200 quando o processo está de pé, e não diz nada sobre o envio de mensagens. A página de status do site mostra o mesmo estado, para quem prefere ler a chamar.
Próximos passos#
Com a chave na mão, conecte um número em Conectar um número e envie a primeira mensagem em Primeiros passos. O contrato de cada rota está na referência da API.
Detalhes das rotas deste guia#
A referência da API diz como chamar cada rota, em poucas linhas. O que explica o motivo de cada decisão, os casos de borda e os avisos está aqui, na ordem da referência.
GET /v1/api-keys#
O segredo nunca volta aqui, nem em rota nenhuma. A Luna guarda apenas um resumo criptográfico dele. Se você perdeu a chave, revogue e crie outra.
Use kind=integration para ver só as chaves de integração e esconder as sessões do console.
POST /v1/api-keys#
Dê a ela só os escopos de que ela precisa. Uma chave que só envia mensagem não deveria poder conectar número nem cunhar outras chaves.
externalId, opcional, faz a chave ser de UM cliente seu: ela só lê e envia pelos números com aquele externalId (inclusive os que forem conectados depois com o mesmo rótulo), só cria link de conexão com ele, só vê templates e contas de negócio das WABAs desses números, e não lista nem cria endpoints de webhook nem chaves. Número de outro cliente seu responde 404, como um que não existe, e rota fora desse conjunto responde 403. Use para dar acesso direto ao cliente do seu cliente, ou para reduzir o estrago de uma chave vazada. O externalId não muda depois da criação.
POST /v1/api-keys/{id}/revoke#
Revogação não apaga a linha. A data fica registrada, para que uma auditoria consiga responder quando o acesso terminou.
GET /v1/subscription#
capacity é quantos números a conta pode manter ativos ao mesmo tempo, e activeNumbers é quantos estão ativos agora. Quando activeNumbers chega a capacity, abrir uma sessão de conexão ou criar um link de conexão responde 409 number_capacity_reached; reconectar um número que já conta não é recusado. Capacidade menor que o uso nunca desconecta ninguém: só recusa o próximo número.
status diz em que pé a conta está. No teste grátis (14 dias, 1 número), trialEndsAt traz o fim e trialDaysLeft traz os dias que faltam, calculados aqui. Com o teste terminado e a conta sem contratação, ou com a conta bloqueada pela Helsen, status é suspended e suspendedReason diz o motivo: o envio e as escritas são recusados, a leitura e o recebimento de mensagens continuam, e o número segue conectado na Meta.
A única grandeza faturável é a quantidade de números que este cliente manteve ativos no período. Nenhum evento da plataforma altera este valor: mensagem, conversa, template, mídia e sessão não entram nesta conta, por caminho nenhum.
O uso da plataforma WhatsApp é cobrado pela Meta, diretamente do negócio final, no método de pagamento que ele cadastra na conta dele. A Helsen não intermedeia esse pagamento, não o adianta e não o repassa.
Ativo significa capacidade configurada, e não apto a enviar agora. Um número aguardando o pagamento do cliente na Meta continua sendo capacidade configurada e continua contando. Um número ativo por três dias conta igual a um ativo o mês inteiro: não há fração de período.
O período é meio-aberto: o início entra, o fim não. inicio e fim vêm juntos ou nenhum dos dois: sem eles, vale o mês corrente em UTC, calculado pela API. Mande os dois quando precisar de uma resposta que não dependa do relógio.
A lista de identificadores traz os números que contaram no período, para que a contagem seja conferível.
POST /v1/operators/signup#
A resposta não traz sessão. Depois do 201, autentique em POST /v1/operators/login com o mesmo e-mail e a mesma senha.
A senha tem no mínimo 12 caracteres, sem exigência de composição. Comprimento protege mais que a mistura obrigatória de símbolos, que só produz senha previsível. Uma senha mais curta responde 400 com o campo password e o mínimo. Essa recusa pode ser dita: a regra é igual para todos e não revela nada de conta nenhuma.
A conta nova entra, lê a documentação, cria e revoga chave de API e integra contra esta API. O que ela ainda não pode é abrir sessão de conexão de número: isso espera a confirmação do e-mail, e nada além dela.
Um e-mail que já tem conta responde o mesmo 201, e o dono do endereço recebe um e-mail dizendo que a conta já existe e como entrar. Responder diferente entregaria de graça a lista de quem tem conta.
GET /v1/operators/confirm#
O link vale por sete dias e é aceito uma única vez. Abrir de novo não desfaz a confirmação, e a conta continua confirmada.
Toda recusa leva ao mesmo endereço, com erro=1. A resposta não diz se o token não existe, se expirou ou se já foi usado, porque distinguir os três entregaria informação sobre uma conta alheia.
Confirmar o e-mail é o que libera a conexão de número: a conta confirmada já pode abrir sessão de conexão.
POST /v1/operators/password/forgot#
A resposta é sempre 202, com o mesmo corpo, exista ou não uma conta com esse e-mail. Dizer qual dos dois entregaria de graça a lista de quem tem conta. O envio acontece depois da resposta, então o tempo também não distingue.
Quando a conta existe, o link vale por uma hora e pode ser aberto uma única vez, e um pedido novo invalida o anterior. Pedidos repetidos para a mesma conta deixam de gerar e-mail depois de alguns por hora, e a resposta continua igual.
O link aponta para a tela de redefinição do console. Quem integra pela API pura conclui com POST /v1/operators/password/reset, levando o token que vem no endereço.
POST /v1/operators/password/reset#
A senha segue a mesma regra do cadastro: no mínimo 12 caracteres, sem exigência de composição. Uma senha fora da regra responde 400 com o campo password e o mínimo, antes de olhar o token.
O token é aceito uma única vez e vale por uma hora. Token desconhecido, malformado, vencido ou já usado responde o mesmo 400, com o mesmo corpo, porque distinguir entregaria informação sobre uma conta alheia.
Trocar a senha encerra todas as sessões do console desse operador. As chaves de API de integração não são sessões e continuam valendo.
GET /v1/account#
Funciona com a sessão do console e com chave de API de integração. Não há escopo próprio para esta leitura: ela pede numbers:read, o mais leve dos escopos de leitura, e uma chave sem nenhum escopo de leitura recebe 403.
operatorEmail é o e-mail do operador, e só existe quando a credencial é uma sessão do console. Uma chave de integração não tem pessoa atrás, e para ela o campo vem null.
POST /v1/operators/confirmation/resend#
Só para a sessão do console: uma chave de API de integração não tem e-mail para receber o link e recebe 403.
Responde 202 nos dois casos. Se a conta já estava confirmada nada é enviado e emailConfirmed vem true; caso contrário vem false e o e-mail saiu. Se o envio falha, responde 503 e vale tentar de novo.
Há um teto de poucos reenvios por hora, por conta, e passado ele a resposta é 429.
POST /v1/operators/login#
A recusa é sempre a mesma, byte a byte. A API não distingue senha errada de conta inexistente, porque distinguir entregaria de graça a lista de quem tem conta.
A sessão não pode criar nem revogar chaves de API. Para isso existe a reautenticação.
Depois de 10 tentativas erradas para o mesmo e-mail em 15 minutos, o login desse e-mail responde 429 com Retry-After até a janela vencer, inclusive com a senha certa. Se esqueceu a senha, use POST /v1/operators/password/forgot.
POST /v1/operators/step-up#
Nenhuma credencial elevada é emitida. Não há segredo novo nesta resposta, nem linha nova no banco: o que muda é um instante gravado na própria sessão, e elevatedUntil é esse instante.
Passadas as duas horas a senha volta a ser pedida, e reabrir a janela exige confirmá-la de novo. Encerrar a sessão encerra a janela junto, sem passo próprio.
Não recebe email: a identidade vem da própria sessão. Assim a senha de um operador nunca eleva a sessão de outro.