Integração para parceiros (visão geral)¶
Este guia é o ponto de entrada para integrar sistemas externos ao TOMODAT3.
Objetivo: permitir que um sistema parceiro (ERP, CRM, plataforma operacional) use o TOMODAT como motor de mapa, sincronize itens e exiba o mapa embutido por iframe.
Papéis e responsabilidades¶
Entender essa distinção evita quase toda confusão de integração:
| Papel | Quem é | O que faz |
|---|---|---|
| Sistema parceiro | Seu sistema (ERP/plataforma) | Faz chamadas de API para o TOMODAT com API key, sincroniza itens, gera embed token |
| Cliente final | Empresa usuária do TOMODAT (ex.: associação, ISP) | Usa o TOMODAT no dia a dia, posiciona itens no mapa e, quando necessário, gera código de vínculo dentro do TOMODAT |
Regras práticas:
- Quem gera API key de parceiro é o sistema parceiro.
- Quem gera código temporário de vínculo de tenant é o admin do cliente final dentro do TOMODAT.
- Quem chama endpoints de integração (
/api/integration/...) é o sistema parceiro.
O que é "tenant"¶
No TOMODAT, tenant significa a conta/ambiente isolado de um cliente final.
Exemplo prático:
- Um parceiro pode atender 200 clientes finais.
- Cada cliente final terá seu próprio
tenant_id. - Todas as chamadas de integração que operam no banco do cliente usam esse contexto (header
X-Tenant).
Big picture da integração¶
Em alto nível, o ciclo funciona assim:
- Sistema parceiro se registra e recebe API key.
- Sistema parceiro cria tenant via API ou recebe um código de vínculo gerado pelo cliente final.
- Sistema parceiro configura quais tipos integráveis vai usar.
- Sistema parceiro sincroniza itens (individual ou lote).
- Usuário final posiciona no mapa itens que chegaram sem coordenadas.
- Sistema parceiro embute o mapa com embed token.
- Quando o token expira, o iframe pede renovação via
postMessage, o parceiro gera novo token e envia de volta.
Capacidades da integração¶
Atualmente a integração cobre:
- Sincronização de itens por API (
create,update,delete,restore,sync). - Dados externos cacheados no item (
external_data). - Ações externas no item (
external_actions). - Vínculo de tenant existente por código temporário.
- Renovação automática de embed token via
postMessagesem recarregar o iframe.
URLs base¶
| Ambiente | Frontend (páginas) | API (endpoints) |
|---|---|---|
| Testes / dev | https://dev3.tomodat.com |
https://dev3.tomodat.com/api |
| Produção | https://tomo3.tomodat.com |
https://tomo3.tomodat.com/api |
Próximos passos¶
- Comece pelo Getting Started.
- Para renovação do iframe, use Renovação de Embed Token.
- Para contratos de endpoint e payload, use API de Integração.
Visão visual (prints)¶
Registro do sistema parceiro¶
Código de vínculo gerado pelo cliente final¶
Mapa embed no sistema parceiro¶
Log de renovação de token via postMessage¶
