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:

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:

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
• Exemplo comum:
• cliente
• poco
• caixa-d-agua

Recomendação:

• Configure apenas tipos que você realmente vai operar.
• Defina external_base_url quando fizer sentido para deep-link do seu sistema.

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.
• Itens podem ser criados sem geometria.
• Geometria de item existente não deve ser alterada via integração.
• Soft delete marca item como inativo, sem perda de histórico.

Etapa 5: 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:

Etapa 6: 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.
• Sync em lote validado com dados reais.
• 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.