Skip to content

Getting Started

Este passo a passo foi escrito para ser direto: siga na ordem e valide cada etapa antes de avançar.

Antes de começar

Tenha em mãos:

  • URL base da API (https://dev3.tomodat.com/api ou https://tomo3.tomodat.com/api).
  • Um ambiente de backend no sistema parceiro para chamadas server-to-server.
  • Capacidade de enviar header X-Integration-API-Key.

Sobre nomenclatura:

  • No TOMODAT, tenant = conta/ambiente isolado de um cliente final.
  • Se no seu sistema isso se chama "conta", "cliente", "workspace" ou "organização", o conceito é o mesmo.

Etapa 1: registrar o sistema parceiro

Faça o registro do parceiro para obter o api_key:

  • Endpoint: POST /api/integration/partners
  • Esse endpoint e o retorno estão detalhados em API de Integração.

Importante:

  • O api_key é exibido uma única vez.
  • Guarde com segurança (vault/secret manager).
  • Nunca exponha o api_key no frontend.

Print de referência:

Registro de parceiro

Etapa 2: conectar um tenant

Você pode conectar tenant de 2 formas.

Opção A: criar tenant novo via API

Use POST /api/tenant/register com X-Integration-API-Key.

Quando o tenant nasce por esse fluxo, ele já fica vinculado ao parceiro.

Opção B: vincular tenant já existente

Fluxo com papéis explícitos:

  1. Cliente final (admin no TOMODAT) gera código temporário na interface do TOMODAT.
  2. Sistema parceiro recebe esse código.
  3. Sistema parceiro chama POST /api/integration/tenants/link.

Resultado:

  • O tenant é vinculado ao parceiro.
  • Os tipos integrados informados já podem ser configurados.

Print de referência:

Código de vínculo no TOMODAT

Etapa 3: configurar tipos integrados

Após vínculo, configure os tipos que o parceiro vai sincronizar:

  • Endpoint: POST /api/integration/tenants/{tenant_id}/configure-types
  • Slugs disponíveis (vertical hídrica):
  • cliente-hidrico
  • reservatorio
  • poco

Recomendação:

  • Configure apenas tipos que você realmente vai operar.
  • Defina external_base_url quando fizer sentido para deep-link do seu sistema.
  • Consulte a tabela de tipos em API de Integração antes de configurar.

Etapa 4: sincronizar itens

Você pode sincronizar de 2 maneiras:

  • Operações individuais:
  • POST /api/integration/items
  • PUT /api/integration/items/{external_id}
  • DELETE /api/integration/items/{external_id}
  • POST /api/integration/items/{external_id}/restore
  • Reconciliação em lote por tipo:
  • POST /api/integration/items/sync

Regras essenciais:

  • item_type_slug deve ser integrável e configurado no vínculo do tenant.
  • Itens podem ser criados sem geometria; o usuário final posiciona no mapa depois.
  • item_model (opcional): identifica o modelo/subcategoria do item pelo code (ex.: "casa"). Define o ícone exibido no mapa e distingue subcategorias dentro de um tipo.
  • Geometria enviada via PUT ou sync é aplicada apenas quando o item ainda não tem geometria. Se o item já foi posicionado manualmente, a coordenada enviada é ignorada silenciosamente — nenhum erro é retornado.
  • O sync não desativa itens ausentes do payload. Para desativar um item, use DELETE /api/integration/items/{external_id} explicitamente.
  • Soft delete marca item como inativo sem perda de histórico; pode ser restaurado via restore.
  • Itens inválidos no lote (tipo incompatível, coordenadas inválidas, item_model inexistente) são pulados e reportados em skipped — sem derrubar o lote inteiro.

Etapa 5: exportar KML (opcional)

Para gerar um arquivo KML com todos os itens com geometria do tenant:

  • Endpoint: GET /api/export/kml
  • Autenticação: JWT do usuário logado (não usa API key de parceiro).
  • Acessível também pelo iframe embed.

O KML agrupa itens por tipo, carrega ícones do mapa e está pronto para abrir no Google Earth Pro.

Etapa 6: abrir o mapa em iframe

  1. Sistema parceiro chama POST /api/integration/embed-token.
  2. Recebe embed_token.
  3. Monta iframe:
  4. https://dev3.tomodat.com/#/embed/map?tenant=<tenant_id>&token=<embed_token>

Obs.: após leitura, o TOMODAT remove token e tenant da URL.

Print de referência:

Mapa embed em execução

Etapa 7: implementar renovação automática do token

Quando o token expira:

  1. Iframe envia postMessage com type: tomodat-embed-token-expired.
  2. Sistema parceiro gera novo token.
  3. Sistema parceiro envia de volta postMessage com type: tomodat-embed-auth.

Guia completo e código pronto em Renovação de Embed Token.

Checklist final de go-live

  • API key armazenada de forma segura.
  • Tenant vinculado corretamente.
  • Tipos integrados configurados com slugs corretos (ex.: cliente-hidrico, não cliente).
  • item_model mapeado para cada subcategoria que seu sistema distingue.
  • Sync em lote validado com dados reais; campo skipped monitorado.
  • Desativação de itens feita via DELETE explícito (sync nunca desativa).
  • Iframe abrindo com token válido.
  • Renovação automática validada em ambiente de teste.
  • Logs e monitoramento de erro (401, 403, 422, 429) ativos.