Console e páginas públicas
Rotas que o console da Luna e a página pública do link de conexão usam: cadastro, login, sessão e conclusão do fluxo. Você normalmente não precisa delas. Elas existem aqui porque o console é cliente desta mesma API, sem rota privilegiada.
Ler o link de conexão (página do cliente)
GET/v1/public/onboarding-links/{token}
Para a página que o seu cliente abre. Devolve o nome da conta que pediu a conexão, o status do link e os identificadores públicos do aplicativo da Meta que a janela de conexão usa. Nada mais da sua conta sai aqui.
Parâmetros de caminho
tokenstringobrigatório
Respostas
200Sucesso.
accountNamestringobrigatórioO nome da conta que pediu a conexão.displayNamestring | nullobrigatórioO nome do cliente para quem o link foi criado (displayName do link), ou nulo. A página o mostra para o cliente reconhecer o pedido.statusstringobrigatórioValores:openusedexpiredexpiresAtstringobrigatóriometaAppIdstringobrigatóriometaConfigIdstringobrigatóriosdkVersionstringobrigatórioA versão da Graph API com que o seu código deve iniciar o SDK do Facebook (FB.init) e abrir a janela de conexão da Meta. A Luna a escolhe e a atualiza, então não a copie para o seu código.redirectUrlstring | nullobrigatórioPara onde a página leva o cliente quando a conexão termina, ou nulo para ficar na página.reconnectbooleanobrigatóriotrue quando o link está aberto e reconecta um número que já existe (foi criado com numberId): a página deve falar em renovar a autorização, e não em conectar um número novo. Num link já usado é sempre false.
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."
}
]
}404O recurso não existe, ou não é seu. As duas respostas são idênticas, byte a byte.
{
"error": "not_found",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Recurso não encontrado."
}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."
}Abrir a sessão de conexão pelo link
POST/v1/public/onboarding-links/{token}/sessions
Abre a sessão que a janela da Meta preenche, para a conta dona do link. É a mesma abertura de POST /v1/onboarding/sessions, pela porta do token.
Parâmetros de caminho
tokenstringobrigatório
Respostas
201Criado.
sessionIdstring (uuid)obrigatóriostatestringobrigatórioconfigIdstringobrigatóriosdkVersionstringobrigatórioA versão da Graph API com que o seu código deve iniciar o SDK do Facebook (FB.init) e abrir a janela de conexão da Meta. A Luna a escolhe e a atualiza, então não a copie para o seu código.csrfStatestringobrigatórioexpiresAtstringobrigató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."
}
]
}404O recurso não existe, ou não é seu. As duas respostas são idênticas, byte a byte.
{
"error": "not_found",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Recurso não encontrado."
}409O pedido está bem formado, mas o estado do recurso não o admite. O campo error diz qual é o caso.
{
"error": "account_at_capacity",
"docsUrl": "https://lunahia.com.br/docs/plano-e-numeros",
"message": "A conta que pediu esta conexão atingiu o máximo de números. Avise quem enviou este link: assim que ela abrir uma vaga, ele poderá enviar um link novo."
}410O link de conexão venceu ou já foi usado. O campo error diz qual dos dois.
{
"error": "link_expired",
"docsUrl": "https://lunahia.com.br/docs/conectar-numero",
"message": "Este link venceu. Peça um novo a quem enviou este."
}{
"error": "link_used",
"docsUrl": "https://lunahia.com.br/docs/conectar-numero",
"message": "Este link já foi usado. Se precisar conectar outro número, peça um novo a quem enviou este."
}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."
}Concluir a conexão pelo link
POST/v1/public/onboarding-links/{token}/sessions/{sessionId}/complete
Troca o código da janela da Meta por acesso à conta do cliente. É a mesma conclusão de POST /v1/onboarding/sessions/{id}/complete, pela porta do token, e vale o mesmo aviso: o código dura 30 segundos, então chame no instante em que ele chega.
Parâmetros de caminho
tokenstringobrigatóriosessionIdstring (uuid)obrigatório
Corpo da requisição
codestringobrigatóriocsrfStatestringobrigatóriowabaIdstring | nullopcionalphoneNumberIdstring | nullopcionalbusinessIdstring | nullopcional
Respostas
200Sucesso.
sessionIdstring (uuid)obrigatóriostatestringobrigatórioorientacaostringobrigatórioterminalbooleanobrigatóriomotivostring | nullobrigatóriopodeRetentarbooleanobrigatórionumberIdstring (uuid) | nullobrigatórioO número que resultou da conexão, quando a Luna já o registrou. Nulo logo depois de concluir: o registro acontece em seguida, e o seu servidor sabe quando ele fica pronto pelo evento number.connected.returnUrlstring | nullobrigatórioPara onde a página leva o cliente: a redirectUrl do link com status, numberId, externalId e signature na query. Nulo quando o link não tem redirectUrl ou a conexão ainda não aconteceu.
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."
}
]
}404O recurso não existe, ou não é seu. As duas respostas são idênticas, byte a byte.
{
"error": "not_found",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Recurso não encontrado."
}410O link de conexão venceu ou já foi usado. O campo error diz qual dos dois.
{
"error": "link_used",
"docsUrl": "https://lunahia.com.br/docs/conectar-numero",
"message": "Este link já foi usado. Se precisar conectar outro número, peça um novo a quem enviou este."
}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."
}Registrar abandono ou erro pelo link
POST/v1/public/onboarding-links/{token}/sessions/{sessionId}/abandon
Telemetria do que aconteceu na janela da Meta quando o cliente não concluiu. É o mesmo relato de POST /v1/onboarding/sessions/{id}/abandon, pela porta do token, e só vale para uma sessão aberta por este mesmo link.
Parâmetros de caminho
tokenstringobrigatóriosessionIdstring (uuid)obrigatório
Corpo da requisição
csrfStatestringobrigatóriocurrentStepstring | nullopcional1 a 120 caractereserrorCodeinteger | nullopcionalerrorMessagestring | nullopcional
Respostas
200Sucesso.
sessionIdstring (uuid)obrigatóriostatestringobrigatórioorientacaostringobrigatórioabandonedAtStepstring | 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."
}
]
}404O recurso não existe, ou não é seu. As duas respostas são idênticas, byte a byte.
{
"error": "not_found",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Recurso não encontrado."
}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."
}Criar uma conta
POST/v1/operators/signup
Cria a conta e o primeiro operador dela, numa única chamada e sem credencial.
Corpo da requisição
emailstringobrigatórioaté 254 caracterespasswordstringobrigatório12 a 512 caracterestenantNamestringobrigatório1 a 120 caracteres
Respostas
201Criado.
nextStepstringobrigatórioValores:login
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."
}
]
}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."
}Confirmar o e-mail de uma conta
GET/v1/operators/confirm
Destino do link enviado por e-mail quando a conta é criada. Ela responde com um redirecionamento para o console, e não com JSON, porque quem a abre é uma pessoa num navegador.
Parâmetros de consulta
tokenstringopcionalaté 512 caracteres
Respostas
200Sucesso.
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."
}
]
}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."
}Pedir a redefinição da senha
POST/v1/operators/password/forgot
Pede o envio de um link para escolher uma senha nova. Recebe só o e-mail da conta.
Corpo da requisição
emailstringobrigatórioaté 254 caracteres
Respostas
202Aceito: o pedido foi registrado e será processado.
acceptedbooleanobrigatórioValores:true
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."
}
]
}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."
}Escolher uma senha nova
POST/v1/operators/password/reset
Troca a senha do operador a partir do token do link enviado por e-mail, e responde 204.
Corpo da requisição
tokenstringobrigatórioaté 512 caracterespasswordstringobrigatório12 a 512 caracteres
Respostas
204Sem conteúdo: a operação foi feita e a resposta não tem corpo.
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."
}
]
}{
"error": "invalid_reset_token",
"docsUrl": "https://lunahia.com.br/docs/conta-e-chaves",
"message": "O link de redefinição não vale mais. Peça um novo."
}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."
}Conferir o link de redefinição
POST/v1/operators/password/reset/check
Responde 204 quando o token do link ainda vale e 400 quando não vale, sem consumi-lo. Serve para a tela avisar antes de a pessoa digitar a senha nova.
Corpo da requisição
tokenstringobrigatórioaté 512 caracteres
Respostas
204Sem conteúdo: a operação foi feita e a resposta não tem corpo.
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."
}
]
}{
"error": "invalid_reset_token",
"docsUrl": "https://lunahia.com.br/docs/conta-e-chaves",
"message": "O link de redefinição não vale mais. Peça um novo."
}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."
}Ler a regra de senha
GET/v1/public/password-policy
O comprimento mínimo de uma senha de operador, o mesmo no cadastro, na redefinição e na troca. Não pede credencial.
Respostas
200Sucesso.
minLengthintegerobrigatórioO mínimo de caracteres de uma senha de operador: no cadastro, na redefinição e na troca. Não há exigência de maiúscula, número ou símbolo.
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 a senha
POST/v1/operators/password/change
Troca a senha do operador da sessão apresentada, conferindo a senha atual, e responde 204. As outras sessões do mesmo operador são encerradas e a apresentada continua valendo. Senha atual errada, ou credencial sem operador (chave de integração), responde 401.
Corpo da requisição
currentPasswordstringobrigatórioA senha de hoje do operador da sessão.até 512 caracteresnewPasswordstringobrigatórioA senha nova, pela mesma regra do cadastro (GET /v1/public/password-policy diz o mínimo).12 a 512 caracteres
Respostas
204Sem conteúdo: a operação foi feita e a resposta não tem corpo.
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."
}Reenviar o e-mail de confirmação
POST/v1/operators/confirmation/resend
Envia de novo o link de confirmação para o e-mail do operador da sessão, e invalida o link anterior que ainda não tinha sido aberto. O link novo vale por sete dias e é aceito uma única vez.
Respostas
202Aceito: o pedido foi registrado e será processado.
emailConfirmedbooleanobrigató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."
}Autenticar um operador
POST/v1/operators/login
Troca email e senha por uma credencial de sessão de oito horas, usada pelo console web.
Corpo da requisição
emailstringobrigatório1 a 254 caracterespasswordstringobrigatório1 a 512 caracteres
Respostas
200Sucesso.
tenantIdstring (uuid)obrigatóriooperatorIdstring (uuid)obrigatóriotokenstringobrigatórioexpiresAtstringobrigatórioscopesarray<string>obrigató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."
}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."
}Reautenticar para uma ação sensível
POST/v1/operators/step-up
Confirma a senha do operador da sessão apresentada e abre uma janela de duas horas em que essa mesma sessão pode criar e revogar chaves de API.
Corpo da requisição
passwordstringobrigatório1 a 512 caracteres
Respostas
200Sucesso.
elevatedUntilstringobrigatórioscopesarray<string>obrigató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."
}Ler a sessão apresentada
GET/v1/operators/session
Quando a credencial apresentada expira, até quando vale a elevação aberta por POST /v1/operators/step-up (nulo sem elevação ou com a janela fechada) e os escopos que ela tem agora. Lê só a própria credencial: o identificador vem da autenticação e nunca do caminho.
Respostas
200Sucesso.
expiresAtstring | nullobrigatórioQuando a credencial apresentada expira. Nulo numa chave de integração, que vale até ser revogada.elevatedUntilstring | nullobrigatórioAté quando vale a elevação aberta por POST /v1/operators/step-up, que deixa a sessão criar e revogar chaves. Nulo sem elevação ou com a janela já fechada: nesse caso, peça a senha de novo.scopesarray<string>obrigatórioOs escopos da credencial agora, já contando os emprestados pela elevação enquanto a janela está aberta.
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."
}Encerrar a sessão
POST/v1/operators/logout
Revoga a credencial apresentada, e apenas ela. O identificador vem da própria autenticação e nunca do corpo, então esta rota não consegue revogar chave de terceiro.
Respostas
204Sem conteúdo: a operação foi feita e a resposta não tem corpo.
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."
}