Criar um Tenant

POST

/tenants

Cria um Tenant no Cliente do token e, se houver template, aplica o template nele. O passo a passo do provisionamento completo está em Tenant automático.

Comportamento

1. Com external_id de um tenant que já existe no cliente, a chamada devolve esse tenant com created: false e não cria outro
2. O tenant é criado e vinculado ao cliente do token
3. Se token for informado, o Agente ETL dono desse token é vinculado ao tenant
4. Se templateId for informado, o template é aplicado. Com templateGroupId, vale a versão vigente da Linha de Produto. Sem os dois, vale o Template Padrão do cliente, se houver
5. A resposta traz o tenant criado, com o Tenant Token em data.token, o agente em agent e o que o template deixou vazio

A chamada é síncrona: só responde depois de aplicar o template inteiro, o que pode levar dezenas de segundos. Configure o timeout do seu cliente HTTP para pelo menos 2 minutos.

A criação não dispara carga. As tabelas do template nascem vazias e ficam assim até o primeiro horário dos agendamentos. Para carregar na hora, use POST /tenant/etl-schedules/run com o Tenant Token devolvido.

O campo token (Agente ETL)

token é o token de um Agente ETL já instalado, o mesmo que aparece em HorusETL › Agentes. Esse agente passa a executar as cargas do tenant novo. Use para um agente na nuvem que atende todos os seus tenants, mandando o mesmo token em todas as criações.

Sem token, o apply do template cria um agente novo só para o tenant, e os Dataflows ficam presos a ele. É o caminho para a origem num banco na rede do cliente final: a resposta traz esse agente em agent, com dedicado: true e o token dele em agent.token, para você instalá-lo lá. Até ele ser instalado, a carga disparada pela API fecha com AGENT_OFFLINE.

Variáveis globais

development_variables preenche as variáveis globais que os Dataflows do template leem ({API_KEY}, {CNPJ_EMPRESA}). Aceita objeto ou lista:

{ "API_KEY": "chave-da-api-deste-cliente", "CNPJ_EMPRESA": "12345678000190" }

[
  {"key": "API_KEY", "value": "chave-da-api-deste-cliente"},
  {"key": "CNPJ_EMPRESA", "value": "12345678000190"}
]

Cada variável precisa de valor: 0 e texto vazio são aceitos, null recusa a criação. Variável do template que não vier aqui entra no tenant vazia e aparece em variaveisVazias.

Na lista, cada item aceita também description e is_secret. Com is_secret: true a variável é protegida: o valor não volta mais nas leituras, nem pela API nem na tela. Valor por agente (agent_overrides) só entra pelo PUT /tenants, depois que o tenant existe.

Template

Só template do cliente do token. templateId de template de outro cliente responde Template not found, igual a um id que não existe.

Nome e domínio

• nome precisa ser único na plataforma inteira, não só no seu cliente. Inclua o ID do cliente final no seu sistema
• Sem dominio, o tenant fica em dataviz.horusbi.com.br, e a URL de login transparente sai com esse endereço
• Se o cliente tem domínio principal configurado no HEC, ele vence o dominio enviado

Falha no meio da criação

O tenant é gravado antes do template ser aplicado. Se o apply falhar, o tenant fica criado e incompleto, com status: failed e o passo em statusDetail.step.

Com external_id, repita a mesma chamada: ela devolve o tenant existente (created: false), inclusive quando duas chamadas chegam juntas. Sem external_id, uma nova tentativa com o mesmo nome é recusada; procure o tenant em GET /tenants. Nos dois casos, aplique o template nele com POST /tenant/templates/apply.

Mensagens de erro

Mensagem	Causa
Nome do Tenant indisponível para uso...	Já existe tenant com esse nome na plataforma
Token inválido!	token não corresponde a nenhum Agente ETL
Invalid development_variables format...	Variável sem key ou com valor null
Duplicated development_variables key: ...	A mesma key duas vezes na lista
Template not found	templateId não existe ou é de outro cliente
Envie templateId ou templateGroupId, não os dois.	Os dois campos no mesmo pedido
Linha de Produto não encontrada ou sem versão vigente.	templateGroupId não é do cliente ou a Linha não tem versão vigente

Autorizações

clientBearerAuth

Token de acesso do cliente

TipoHTTP (bearer)

Corpo da Requisição

application/json

Respostas

Tenant criado, ou o existente com o mesmo external_id

Tipo de Conteúdo

application/json

POST

/tenants

Playground

Autorização

clientBearerAuth

Corpo

Exemplos

Desenvolvido por VitePress OpenAPI