Embed no seu sistema

Tipo

Visão geral

Para

Parceiro whitelabel, Desenvolvedor

Na tela

HEC › Clientes › Desenvolvedor

O embed mostra o DataViz dentro do seu sistema, num iframe, com login sem senha. O seu backend pede à API uma URL de login para o e-mail do usuário e entrega essa URL ao navegador.

Só o login exige a API. Tenants, usuários e permissões podem ser cadastrados no HEC ou pela API.

Os dois tokens

A API usa dois tokens Bearer.

O Client Token é do Cliente, a organização que licencia o Lumo (você, parceiro). Com ele você lista, cria, altera e exclui tenants e lista os templates. Ele serve para as rotas /v1/tenants e fica no HEC, no cadastro do Cliente, aba Desenvolvedor.

O Tenant Token é de um tenant só. Com ele você cadastra usuários, define permissões, gera o login transparente, aplica template e dispara cargas. Ele serve para as rotas /v1/tenant e fica no cadastro do tenant, aba Desenvolvedor. Também vem no campo token de cada tenant em GET /v1/tenants: quem tem o Client Token chega a todos os Tenant Tokens sem abrir o HEC.

Guarde os dois no seu backend e nunca mande para o navegador. Os dois dão acesso de administrador: quem tem o Tenant Token gera login como qualquer usuário daquele tenant.

O que você automatiza

Tarefa	No HEC	Pela API	Página
Abrir o DataViz sem senha no seu sistema	Não	Sim, com o Tenant Token	Login transparente
Cadastrar usuários e permissões	Sim	Sim, com o Tenant Token	Usuário automático
Criar o tenant e aplicar o template	Sim	Sim, com o Client Token	Tenant automático

Comece pelo login. Automatize o cadastro de usuários e a criação de tenants quando o número de clientes pedir.

Quando o template muda, Versão nova do template mostra como levar a versão aos tenants que já existem. Para erro e comportamento inesperado, veja Solução de problemas e Limitações atuais.

O caminho completo

A sequência abaixo faz tudo pela API. A etapa que você fizer no HEC sai do fluxo.

Antes de começar

Três cuidados valem para qualquer integração:

• Domínio próprio para o DataViz. Ponha o DataViz num subdomínio do seu sistema. A sessão do iframe fica num cookie do domínio do DataViz. Com o DataViz em bi.suaempresa.com.br e o seu sistema em app.suaempresa.com.br, o navegador vê os dois como o mesmo site e mantém a sessão. Com o DataViz em dataviz.horusbi.com.br dentro de um sistema em outro domínio, o navegador que bloqueia cookie de terceiros derruba a sessão. Veja Marca e domínio.
• Chamadas sempre do servidor. Os dois tokens ficam no seu backend. O navegador só recebe a URL de login, que vale por 1 hora e só para aquele usuário.
• Endereço da API. Todas as rotas ficam sob https://api.horusbi.com.br/v1. A referência da API traz cada operação com os campos completos.

Erros

Toda resposta de erro em JSON traz code, um código fixo ao lado da mensagem:

{
  "status": "error",
  "message": "Template not found",
  "code": "TEMPLATE_NOT_FOUND"
}

Decida pelo code. A mensagem foi escrita para gente ler e pode mudar de redação; o código fica. Os campos status, success, message e error continuam no corpo, então a integração que compara o texto da mensagem segue funcionando enquanto você passa a usar o código.

Nas rotas /v1/tenant (Tenant Token), o status HTTP segue a causa, como na referência. Até a versão de 28/10/2026 da API, esses erros voltavam com HTTP 200 e "success": false, e a franquia de usuários com HTTP 500; o corpo não mudou. Nas rotas /v1/tenants (Client Token), criar, alterar e excluir tenant recusam com HTTP 400. Em qualquer rota, erro interno é 500.

Duas respostas vêm sem JSON e sem code: token inválido, com HTTP 401 e o texto Unauthorized, e o limite de pedidos, com HTTP 429.

A lista de códigos, com o status HTTP de cada um, fica na referência da API. Os que mais aparecem no embed são TENANT_NAME_TAKEN (nome de tenant já usado na plataforma), TEMPLATE_NOT_FOUND (template de outro Cliente), USER_LOGIN_TAKEN (e-mail já vinculado ao tenant), USER_LOGIN_NOT_ALLOWED (e-mail que não entra por login transparente) e USER_QUOTA_EXCEEDED (franquia de usuários esgotada).

A carga, a execução e as conexões têm códigos próprios, como AGENT_OFFLINE, EXECUTION_NOT_FOUND e CREDENTIAL_NOT_FOUND, descritos em Tenant automático.

Erro sem código próprio recebe um genérico pelo status: VALIDATION_ERROR no 400, NOT_FOUND no 404, INTERNAL_ERROR no 500 e REQUEST_FAILED nos outros (este responde HTTP 400 onde o erro saía com 200). Código que você não conhece se trata do mesmo jeito: pelo status HTTP.

Limite de pedidos

A API aceita até 100 pedidos por segundo de cada endereço IP. Acima disso, responde HTTP 429 com o texto Too Many Requests e o header Retry-After, com os segundos que faltam para liberar (no mínimo 1). Espere esse tempo e repita o pedido.

O limite é contado em cada servidor da API, e o pedido pode cair em qualquer um deles. Planeje para 100 por segundo: o que passar disso pode ou não ser aceito.