Conta e plano
A conta da credencial, o plano, a capacidade de números e quantos estão em uso no período.
Consultar o plano e a assinatura
GET/v1/subscription
O plano da conta (teste grátis ou contratado), a capacidade de números e quantos estão em uso, e o que é cobrado pela Helsen no período: a capacidade de números ativos, e nada além disso.
Parâmetros de consulta
iniciostring (date-time)opcionalfimstring (date-time)opcional
Respostas
200Sucesso.
planNamestring | nullobrigatórioO nome do plano: Teste grátis enquanto a conta está no teste, e o nome da faixa que comporta a capacidade depois que ela é contratada (Avulso, Starter, Growth, Scale, ou Sob consulta acima de 60). Nulo enquanto a conta não começou plano.statusstringobrigatórionone: a conta ainda não começou plano (o e-mail não foi confirmado). trial: teste grátis em curso. active: conta contratada. suspended: escrita e envio recusados; suspendedReason diz por quê.Valores:nonetrialactivesuspendedsuspendedReasonstring | nullobrigatórioQuando status é suspended: trial_expired (o teste grátis terminou) ou account_blocked (a Helsen bloqueou a conta). Nulo nos outros casos.Valores:trial_expiredaccount_blockedcapacityinteger | nullobrigatórioQuantos números a conta pode manter ativos ao mesmo tempo. Nulo enquanto a conta não começou plano.activeNumbersintegerobrigatórioQuantos números estão ativos agora. É a contagem que a capacidade usa; a da assinatura do mês é numerosAtivos, que soma os que ficaram ativos em algum momento do período.trialEndsAtstring | nullobrigatórioQuando o teste grátis termina. Fica preenchido depois que a conta é contratada, como registro. Nulo se a conta nunca teve teste.trialDaysLeftinteger | nullobrigatórioQuantos dias faltam para o teste terminar, calculados pela API (arredondados para cima, mínimo 0). Nulo fora do teste.periodoobjectobrigatórioperiodo.iniciostringobrigatórioperiodo.fimstringobrigatóriocanConnectNumberbooleanobrigatórioSe esta conta pode abrir a conexão de um número novo agora: o e-mail está confirmado, a conta não está suspensa e ainda há vaga na capacidade. É a mesma decisão que a abertura da conexão e a criação do link de conexão aplicam, então a tela pode mostrar ou esconder o botão sem comparar nada.capacityLeftinteger | nullobrigatórioQuantos números ainda cabem na capacidade (nunca negativo). Nulo enquanto a conta não começou plano.capacityNoticestring | nullobrigatórioQuando canConnectNumber é false, o texto da recusa, o mesmo que a API devolve ao tentar conectar: e-mail por confirmar, conta suspensa ou capacidade cheia. Nulo quando pode conectar.writesAllowedbooleanobrigatórioSe a conta pode fazer alterações agora. É false só com a conta suspensa, e então suspendedNotice diz por quê. Ler, desconectar número e revogar chave continuam valendo.suspendedNoticestring | nullobrigatórioO texto da suspensão, o mesmo das recusas 403 de escrita. Nulo quando a conta não está suspensa.pricePerMonthnumber | nullobrigatórioO valor mensal da faixa de capacidade contratada, em reais, que a Helsen cobra pela capacidade de números e por mais nada. Nulo no teste grátis, enquanto a conta não começou plano e acima da última faixa (Sob consulta).currencystring | nullobrigatórioA moeda de pricePerMonth. Nulo quando pricePerMonth é nulo.Valores:BRLcontactEmailstringobrigatórioO e-mail do comercial da Helsen, para contratar, ampliar a capacidade ou sair da suspensão.numerosAtivosintegerobrigatórioQuantos números distintos estiveram ativos em algum momento do período consultado (periodo): a contagem que a assinatura do mês usa. Não é o mesmo que activeNumbers: este é o acumulado do período e inclui um número que já foi desconectado depois de ter sido ativo nele; activeNumbers é quantos estão ativos agora e é o que a capacidade compara.phoneNumberIdsarray<string>obrigatórioOs ids da Meta (metaPhoneNumberId) dos números que entraram em numerosAtivos, para você conferir a contagem. É uma lista de identificadores, sem contagem de mensagens.
400O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa.
{
"error": "invalid_request",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Requisição inválida.",
"campos": [
{
"campo": "text.body",
"motivo": "Não pode ficar vazio."
}
]
}401A chave está ausente, malformada, inexistente, expirada ou revogada. O corpo é sempre o mesmo, sem dizer qual.
WWW-AuthenticateSempre Bearer.
{
"error": "unauthorized",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Credencial ausente ou inválida."
}403A chave não tem o escopo que a rota exige. Em rota que abre conexão de número, também quando a conta ainda não pode conectar (connection_not_released). Nas rotas que escrevem ou enviam, também quando a conta está suspensa: trial_expired (o teste grátis terminou) ou account_blocked (a Helsen bloqueou a conta). A suspensão não toca o recebimento: o que chega continua sendo entregue ao seu webhook. Uma chave de teste (mode test) só usa POST /v1/messages e POST /v1/test-mode/inbound-messages; nas demais rotas recebe test_key_not_allowed.
{
"error": "forbidden",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.",
"requiredScope": "numbers:read"
}{
"error": "test_key_not_allowed",
"docsUrl": "https://lunahia.com.br/docs/modo-de-teste",
"message": "Esta é uma chave de teste: ela só envia mensagem simulada (POST /v1/messages) e pede mensagem recebida simulada (POST /v1/test-mode/inbound-messages). Para esta operação, use uma chave de produção."
}429Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key.
Retry-AfterSegundos a esperar antes de repetir.
{
"error": "rate_limited",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Requisições demais. Tente novamente em instantes."
}503A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver.
{
"error": "unavailable",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Não foi possível concluir a operação agora. Tente novamente em instantes."
}Ler os limites técnicos da plataforma
GET/v1/limits
Os tetos que a API aplica, cada um com o valor, a unidade e o motivo. São iguais para todos os clientes e não dependem do plano: existem por capacidade de infraestrutura ou porque a Meta os impõe. Não são contagem do seu uso e não entram em cobrança.
Respostas
200Sucesso.
dataarray<object>obrigatórioOs limites, na ordem em que devem aparecer.data[].keystringobrigatórioO identificador estável do limite, para o seu código comparar. Novos limites podem aparecer.data[].labelstringobrigatórioO nome do limite, em português.data[].valuenumberobrigatórioO valor, na unidade de unit.data[].unitstringobrigatórioA unidade de value: requests_per_minute, endpoints, seconds, hours, bytes ou messages_per_second.data[].reasonstringobrigatórioPor que o limite existe, em português. É sempre capacidade ou regra da Meta, nunca preço.
401A chave está ausente, malformada, inexistente, expirada ou revogada. O corpo é sempre o mesmo, sem dizer qual.
WWW-AuthenticateSempre Bearer.
{
"error": "unauthorized",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Credencial ausente ou inválida."
}403A chave não tem o escopo que a rota exige. Em rota que abre conexão de número, também quando a conta ainda não pode conectar (connection_not_released). Nas rotas que escrevem ou enviam, também quando a conta está suspensa: trial_expired (o teste grátis terminou) ou account_blocked (a Helsen bloqueou a conta). A suspensão não toca o recebimento: o que chega continua sendo entregue ao seu webhook. Uma chave de teste (mode test) só usa POST /v1/messages e POST /v1/test-mode/inbound-messages; nas demais rotas recebe test_key_not_allowed.
{
"error": "forbidden",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.",
"requiredScope": "numbers:read"
}{
"error": "test_key_not_allowed",
"docsUrl": "https://lunahia.com.br/docs/modo-de-teste",
"message": "Esta é uma chave de teste: ela só envia mensagem simulada (POST /v1/messages) e pede mensagem recebida simulada (POST /v1/test-mode/inbound-messages). Para esta operação, use uma chave de produção."
}429Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key.
Retry-AfterSegundos a esperar antes de repetir.
{
"error": "rate_limited",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Requisições demais. Tente novamente em instantes."
}503A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver.
{
"error": "unavailable",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Não foi possível concluir a operação agora. Tente novamente em instantes."
}Ler as regras de preço da Meta
GET/v1/meta-pricing
As regras com que a Meta cobra o uso do WhatsApp do negócio dono do número, e o dia em que a Luna as leu. Não traz valor em moeda: a tabela de tarifas fica na Meta. A Luna não cobra nada disto.
Respostas
200Sucesso.
readAtstringobrigatórioO dia em que as regras foram lidas na página de preços da Meta (AAAA-MM-DD). Mostre-o junto das regras: é o que diz o quão fresca é a informação.sourceUrlstringobrigatórioA tabela de tarifas da Meta, que é a referência para qualquer valor.aiProvidersUrlstringobrigatórioA política própria da Meta para assistentes de IA de uso geral (Provedores de IA).rulesarray<object>obrigatórioAs regras, na ordem em que devem aparecer.rules[].keystringobrigatórioO identificador estável da regra, para o seu código comparar.rules[].titlestringobrigatóriorules[].textstringobrigatórioA regra, em português. Não traz valor em moeda.
401A chave está ausente, malformada, inexistente, expirada ou revogada. O corpo é sempre o mesmo, sem dizer qual.
WWW-AuthenticateSempre Bearer.
{
"error": "unauthorized",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Credencial ausente ou inválida."
}403A chave não tem o escopo que a rota exige. Em rota que abre conexão de número, também quando a conta ainda não pode conectar (connection_not_released). Nas rotas que escrevem ou enviam, também quando a conta está suspensa: trial_expired (o teste grátis terminou) ou account_blocked (a Helsen bloqueou a conta). A suspensão não toca o recebimento: o que chega continua sendo entregue ao seu webhook. Uma chave de teste (mode test) só usa POST /v1/messages e POST /v1/test-mode/inbound-messages; nas demais rotas recebe test_key_not_allowed.
{
"error": "forbidden",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.",
"requiredScope": "numbers:read"
}{
"error": "test_key_not_allowed",
"docsUrl": "https://lunahia.com.br/docs/modo-de-teste",
"message": "Esta é uma chave de teste: ela só envia mensagem simulada (POST /v1/messages) e pede mensagem recebida simulada (POST /v1/test-mode/inbound-messages). Para esta operação, use uma chave de produção."
}429Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key.
Retry-AfterSegundos a esperar antes de repetir.
{
"error": "rate_limited",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Requisições demais. Tente novamente em instantes."
}503A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver.
{
"error": "unavailable",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Não foi possível concluir a operação agora. Tente novamente em instantes."
}Ler a própria conta
GET/v1/account
Devolve a conta da credencial apresentada: identificador, nome, se o e-mail já foi confirmado e quando a conta foi criada.
Respostas
200Sucesso.
idstring (uuid)obrigatórionamestringobrigatórioemailConfirmedbooleanobrigatóriocreatedAtstringobrigatóriooperatorEmailstring | nullobrigatório
401A chave está ausente, malformada, inexistente, expirada ou revogada. O corpo é sempre o mesmo, sem dizer qual.
WWW-AuthenticateSempre Bearer.
{
"error": "unauthorized",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Credencial ausente ou inválida."
}403A chave não tem o escopo que a rota exige. Em rota que abre conexão de número, também quando a conta ainda não pode conectar (connection_not_released). Nas rotas que escrevem ou enviam, também quando a conta está suspensa: trial_expired (o teste grátis terminou) ou account_blocked (a Helsen bloqueou a conta). A suspensão não toca o recebimento: o que chega continua sendo entregue ao seu webhook. Uma chave de teste (mode test) só usa POST /v1/messages e POST /v1/test-mode/inbound-messages; nas demais rotas recebe test_key_not_allowed.
{
"error": "forbidden",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.",
"requiredScope": "numbers:read"
}{
"error": "test_key_not_allowed",
"docsUrl": "https://lunahia.com.br/docs/modo-de-teste",
"message": "Esta é uma chave de teste: ela só envia mensagem simulada (POST /v1/messages) e pede mensagem recebida simulada (POST /v1/test-mode/inbound-messages). Para esta operação, use uma chave de produção."
}429Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key.
Retry-AfterSegundos a esperar antes de repetir.
{
"error": "rate_limited",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Requisições demais. Tente novamente em instantes."
}503A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver.
{
"error": "unavailable",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Não foi possível concluir a operação agora. Tente novamente em instantes."
}Trocar o nome da conta
PATCH/v1/account
Troca o nome da conta, o mesmo que GET /v1/account devolve. Devolve a conta já com o nome novo. Só a sessão do console faz isto.
Corpo da requisição
namestringobrigatórioO novo nome da conta, de 1 a 120 caracteres: o mesmo limite do cadastro.1 a 120 caracteres
Respostas
200Sucesso.
idstring (uuid)obrigatórionamestringobrigatórioemailConfirmedbooleanobrigatóriocreatedAtstringobrigatóriooperatorEmailstring | nullobrigatório
400O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa.
{
"error": "invalid_request",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Requisição inválida.",
"campos": [
{
"campo": "text.body",
"motivo": "Não pode ficar vazio."
}
]
}401A chave está ausente, malformada, inexistente, expirada ou revogada. O corpo é sempre o mesmo, sem dizer qual.
WWW-AuthenticateSempre Bearer.
{
"error": "unauthorized",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Credencial ausente ou inválida."
}403A chave não tem o escopo que a rota exige. Em rota que abre conexão de número, também quando a conta ainda não pode conectar (connection_not_released). Nas rotas que escrevem ou enviam, também quando a conta está suspensa: trial_expired (o teste grátis terminou) ou account_blocked (a Helsen bloqueou a conta). A suspensão não toca o recebimento: o que chega continua sendo entregue ao seu webhook. Uma chave de teste (mode test) só usa POST /v1/messages e POST /v1/test-mode/inbound-messages; nas demais rotas recebe test_key_not_allowed.
{
"error": "forbidden",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.",
"requiredScope": "numbers:read"
}{
"error": "test_key_not_allowed",
"docsUrl": "https://lunahia.com.br/docs/modo-de-teste",
"message": "Esta é uma chave de teste: ela só envia mensagem simulada (POST /v1/messages) e pede mensagem recebida simulada (POST /v1/test-mode/inbound-messages). Para esta operação, use uma chave de produção."
}415O corpo veio com um content-type que a rota não lê. Envie application/json, ou multipart/form-data nas rotas de arquivo.
{
"error": "unsupported_media_type",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Envie o corpo como application/json."
}429Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key.
Retry-AfterSegundos a esperar antes de repetir.
{
"error": "rate_limited",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Requisições demais. Tente novamente em instantes."
}503A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver.
{
"error": "unavailable",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Não foi possível concluir a operação agora. Tente novamente em instantes."
}Ver o resumo da conta
GET/v1/account/overview
O que a conta precisa olhar agora (avisos em ordem de gravidade), os quatro primeiros passos e os números por estado de conexão. Tudo decidido pela API, para uma tela inicial não precisar calcular nada.
Respostas
200Sucesso.
attentionarray<object>obrigatórioO que a conta precisa olhar, na ordem em que deve aparecer: o que está parado primeiro, depois o mais antigo.attention[].codestringobrigatórioO tipo do aviso, para o seu código comparar.Valores:number_action_requirednumber_credential_expiringnumber_payment_missingaccount_restrictedaccount_disabledsubscription_trial_endingsubscription_suspendedemail_not_confirmedwebhook_endpoint_failingwebhook_no_endpointwebhook_rejected_pendingtemplate_pausedtemplate_rejectedlink_failedattention[].severitystringobrigatórioblocking: algo está parado e precisa de ação. warning: algo vai parar ou funciona pela metade. info: vale olhar.Valores:blockingwarninginfoattention[].titlestringobrigatórioO aviso em poucas palavras, em português.attention[].messagestringobrigatórioO que está acontecendo, em português, pronto para mostrar.attention[].solutionstringobrigatórioO que fazer a respeito, em português.attention[].resourceobjectobrigatórioA que o aviso se refere.attention[].resource.typestringobrigatórioValores:numberlinkwebhook_endpointtemplatesubscriptionbusiness_accountaccountattention[].resource.idstringobrigatórioO identificador do recurso na Luna. Para account e subscription é o da própria conta.attention[].actionstring | nullobrigatórioA ação que resolve o aviso, quando há: send_pin, reconnect, reconnect_link, meta_manager, wait, contact_helsen, confirm_email, add_webhook_endpoint, review_webhook_endpoint, requeue_webhook_events, edit_template ou create_link. Novos valores podem aparecer.attention[].actionUrlstring | nullobrigatórioO endereço da conta no WhatsApp Manager da Meta. Só vem quando action é meta_manager.attention[].sincestringobrigatórioDesde quando o aviso vale, em ISO-8601 UTC.checklistarray<object>obrigatórioOs quatro primeiros passos, sempre nesta ordem: connect_number (há um número conectado), create_key (há uma chave de integração não revogada), add_webhook_endpoint (há um endereço de webhook) e send_message (já saiu uma mensagem).checklist[].keystringobrigatórioValores:connect_numbercreate_keyadd_webhook_endpointsend_messagechecklist[].donebooleanobrigatóriochecklist[].doneAtstring | nullobrigatórioQuando o passo foi cumprido pela primeira vez. Nulo enquanto não foi.numbersobjectobrigatórioOs números da conta por estado de conexão (connection.status). A soma dos quatro estados é total.numbers.totalintegerobrigatórionumbers.byStatusobjectobrigatórionumbers.byStatus.connectedintegerobrigatórionumbers.byStatus.connectingintegerobrigatórionumbers.byStatus.action_requiredintegerobrigatórionumbers.byStatus.disconnectedintegerobrigatório
401A chave está ausente, malformada, inexistente, expirada ou revogada. O corpo é sempre o mesmo, sem dizer qual.
WWW-AuthenticateSempre Bearer.
{
"error": "unauthorized",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Credencial ausente ou inválida."
}403A chave não tem o escopo que a rota exige. Em rota que abre conexão de número, também quando a conta ainda não pode conectar (connection_not_released). Nas rotas que escrevem ou enviam, também quando a conta está suspensa: trial_expired (o teste grátis terminou) ou account_blocked (a Helsen bloqueou a conta). A suspensão não toca o recebimento: o que chega continua sendo entregue ao seu webhook. Uma chave de teste (mode test) só usa POST /v1/messages e POST /v1/test-mode/inbound-messages; nas demais rotas recebe test_key_not_allowed.
{
"error": "forbidden",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.",
"requiredScope": "numbers:read"
}{
"error": "test_key_not_allowed",
"docsUrl": "https://lunahia.com.br/docs/modo-de-teste",
"message": "Esta é uma chave de teste: ela só envia mensagem simulada (POST /v1/messages) e pede mensagem recebida simulada (POST /v1/test-mode/inbound-messages). Para esta operação, use uma chave de produção."
}429Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key.
Retry-AfterSegundos a esperar antes de repetir.
{
"error": "rate_limited",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Requisições demais. Tente novamente em instantes."
}503A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver.
{
"error": "unavailable",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Não foi possível concluir a operação agora. Tente novamente em instantes."
}