Integração regional não é copiar campos. Omie, SIGE Cloud, Zoho Creator, planilhas e bancos SQL representam clientes, produtos, serviços, pedidos, notas, pagamentos e workflows de formas diferentes. Uma boa arquitetura preserva essas diferenças e oferece um modelo operacional estável.
Defina qual sistema controla cada fato. O ERP pode ser dono de produtos fiscais, notas, contas a receber e estoque. Zoho Creator pode controlar um workflow de serviços, aprovações ou formulários. CRM controla interação comercial. SQL preserva evidência e história analítica. Sheets apresenta um relatório controlado para pessoas.
Dois sistemas podem guardar o nome do cliente, mas apenas um deve controlar o cadastro legal enquanto outro mantém um rótulo operacional. Sem ownership por campo, sync bidirecional vira loop de sobrescrita.
Omie organiza APIs por serviços de negócio; SIGE Cloud expõe recursos do ERP; Zoho Creator trabalha com forms, reports, field link names, validações, workflows, paginação e bulk jobs. Não são CRUDs intercambiáveis.
Cada fonte precisa de adapter que conheça auth, paginação, quotas, filtros, status, produto versus serviço, envelope de erro, retries e comportamento de mutation. O pipeline central consome um contrato normalizado.
Armazene payload original com provider, tenant, recurso, external ID, extração, source update time, versão da API, janela, hash e run ID. A camada raw permite reproduzir transformações, investigar drift e provar o que chegou.
Normalização gera tabelas ou eventos separados. Campo desconhecido não deve sumir. Drift vai para quarantine ou compatibilidade explícita.
Não assuma que CNPJ/CPF, email, SKU ou nome é globalmente único. Guarde tenant, fonte, tipo, external ID, canonical ID, validade, método, confiança e histórico de merge/split. Preserve aliases para eventos atrasados.
Use chaves determinísticas onde houver garantia e matching limitado com review no restante. Filiais, contatos duplicados e códigos de produto locais exigem policy.
Use updated_at ou cursor quando confiável, com janela sobreposta para mudanças tardias. Registre intervalo, páginas, primeiro/último timestamp, vistos, únicos, rejeitados e watermark committed.
Separe sync recente de backfill. Não avance watermark se página falhar ou validação detectar gap.
Repetir leitura é barato; repetir criação de cliente, nota, cancelamento, estoque ou lançamento financeiro pode causar dano. Toda mutation precisa de operation ID, versão, precondições, lookup, hash, result ledger e retry class.
Antes de criar, procure pela integration key. Após timeout, consulte status. Separe erro de transporte/rate limit de validação, permissão, fiscal e negócio. Preserve a causa mais específica em vez de substituí-la por “falha no sync”.
Serviço não é produto sem estoque. Eles podem usar impostos, notas, códigos e ciclos diferentes. Compartilhe campos comuns sem apagar o tipo fiscal.
Use decimal, moeda, base, desconto, frete e rounding explícitos. Preserve códigos fiscais e documentos da fonte. Não recalcule imposto genericamente se o ERP já resolveu a nota.
Sheets é útil para finanças e operação, mas não é event store nem banco transacional. Publique snapshot versionado ou ranges com ownership claro. Proteja fórmulas, headers e row keys.
A API tem quotas por minuto e recomenda backoff. Use batch reads/writes e atualização atômica em vez de linha a linha. Grave run marker com janela, horário, linhas, schema e status.
PostgreSQL guarda metadata raw, identity maps, projeções, ledgers, watermarks, conciliação e exceções. Unique constraints aplicam idempotência, FKs relacionam, checks protegem estados e transações fazem commit conjunto.
Raw responde o que a fonte enviou; canônico responde o significado; view responde a pergunta atual. Isso permite mudar relatórios sem refazer chamadas antigas.
| Domínio | Owner típico | Leitura | Escrita | Evidência de conciliação |
|---|---|---|---|---|
| Cliente/fornecedor legal | ERP ou master data. | Incremental com overlap e revisão de duplicata. | Upsert por integration key com validação fiscal. | ID map, documento, status, endereço e atualização. |
| Workflow customizado | Zoho Creator ou aplicação. | Reports, paginação, janela recente ou bulk. | Update sujeito a validação e workflows. | Record ID, form/report, workflow, histórico e erro. |
| Catálogo | ERP. | Referência completa e mudanças operacionais. | Paths separados para produto/serviço. | SKU, tipo fiscal, ativo, preço e estoque. |
| Pedidos e documentos | ERP no fiscal; app pode controlar intenção. | Janelas recentes, refresh e webhook. | Criar uma vez e transicionar com versão. | IDs, itens, totais, número fiscal, cancelamento e pagamento. |
| Snapshot de reporting | Modelo SQL; Sheets apresenta. | View/export versionado. | Batch replacement atômico ou append limitado. | Run, schema, linhas, totais, horário e watermark. |
| Controle da integração | SQL/control plane. | Jobs, mappings, policies e resultados. | Attempts append-only e projeções transacionais. | Trace, request/response, idempotência, retry e owner. |
Webhook serve para baixa latência, mas deve disparar fetch ou verificação do estado. Polling cobre backfill, eventos perdidos e recursos sem webhook. Ambos entram no mesmo pipeline deduplicado.
Monitore idade, autenticação, event ID, versão e resultado. Falha no webhook aumenta freshness e ativa polling fallback.
Normalize timeout, rate limit, auth, permissão, not found, validação, duplicate, rejeição fiscal, workflow, conflict e erro interno. Preserve código e mensagem sanitizada com entidade, operação, payload, tentativa, policy e owner.
“Falha ao sincronizar cliente” é fraco quando o ERP informou código municipal ausente ou etapa não cancelável. Mantenha a causa de maior valor corretivo.
Contagem detecta página ausente, mas não prova negócio. Compare totais de pedido, notas, recebíveis, pagamentos, estoque, clientes ativos, etapas e freshness. Encontre registros só na fonte, só no destino ou divergentes.
Exceção precisa de owner, severidade, impacto, idade, evidência, ação e prova de fechamento. Não corrija divergência fiscal ou financeira por overwrite automático.
Guarde app keys, secrets, refresh tokens, credenciais SQL e service accounts em secret manager ou CI protegida. Escopo por tenant e capacidade. Nunca logue segredo ou payload sensível completo.
Tabelas, filas, cache e traces precisam de tenant context. Autorização ocorre na fronteira de write.
Crie fixtures de paginação, páginas vazias, null, decimal, timezone, enum novo, validação, rate limit, partial success, timeout pós-commit, webhook duplicado e drift. Use sandbox ou conta controlada.
Teste backfill e replay em banco descartável. Rerun não duplica e evento antigo não sobrescreve versão nova.
Meça requested, received, normalized, inserted, updated, unchanged, rejected, retried e reconciled. Acompanhe latência, quota, watermark lag, exceção mais velha, duração do Sheets e freshness.
Correlacione run, request, raw, entidade, operação, resultado, snapshot e caso. Worker verde não basta se o dashboard ainda mostra a nota de ontem.
Eu construiria uma plataforma com adapters por provider, scheduler durável, landing raw, schemas canônicos, identity mapping, operation ledger, projeções SQL, conciliação, console de exceções e publishers. Reads e writes usariam credenciais e filas separadas.
Cada package declararia recursos, paginação, incremental key, limites, webhooks, idempotência, distinções fiscais, taxonomia de erro e fixtures.
Integração regional bem-sucedida não finge que todos os sistemas são iguais. Ela explicita diferenças, preserva a verdade da fonte, traduz significado por contratos controlados e prova o outcome de cada sincronização.
Artigo sobre integração de ERP na América Latina entre Omie, SIGE Cloud, Zoho Creator, Google Sheets e SQL, incluindo ownership, ingestão raw, modelos canônicos, identity mapping, sync incremental, mutations idempotentes, fiscal, conciliação, erros, segurança, testes e observabilidade.