Resumo: escritórios de contabilidade e empresas que usam o Questor Empresarial ou a Sieg costumam copiar dados entre sistemas à mão. Desenvolvi integrações que tratam cada plataforma como uma fonte com regras próprias: conexões que atendem várias empresas, sincronização idempotente que só grava o que mudou, download paginado de XMLs de NF-e e NFS-e, regras de etiquetas aplicadas automaticamente e autorização OAuth com tokens criptografados e renovados.
Neste artigo
Por que integrar ERP contábil e repositório de XMLs
O Questor concentra cadastros, estoque, financeiro e notas de muitas empresas. A Sieg reúne os XMLs dos documentos fiscais. Quando o sistema de gestão da empresa, ou o portal do escritório, conversa com essas fontes, desaparecem tarefas como exportar planilhas, baixar XMLs um a um e reclassificar documentos manualmente.
| Fonte | O que a integração traz |
|---|---|
| Questor Empresarial | Entidades, materiais, estoque, títulos a pagar e a receber, notas de compra e pedidos |
| Sieg | XMLs de NF-e e NFS-e, com etiquetas para classificação e organização |
Integração com o Questor Empresarial
Uma conexão, várias empresas
Uma conexão com a API pode atender várias empresas. Cada empresa é cadastrada com o identificador usado pela API, e todos os dados espelhados ficam separados pela combinação de conexão e empresa. Assim, um escritório gerencia vários clientes sem risco de misturar informações.
Cobertura tipada da API
A integração implementa a autenticação e as consultas publicadas na documentação oficial do Questor, com um objeto de dados tipado para cada esquema. Na prática, outros módulos do sistema consultam entidades, estoque, títulos financeiros, notas de compra e pedidos por uma interface única, sem montar requisições à mão.
Sincronização idempotente
- A cada 30 minutos, o agendador percorre as conexões e empresas ativas.
- Para cada registro remoto, a chave é única dentro da empresa.
- Um hash do conteúdo decide se o registro é novo, se mudou ou se apenas foi visto de novo.
- Só o que mudou é gravado, e o JSON original da API é preservado para auditoria.
- O painel mostra o resultado da última sincronização e destaca empresas que precisam de atenção.
Espelho não é cadastro interno
Os dados do Questor ficam em tabelas espelho próprias, sem se misturar automaticamente com os cadastros internos de clientes e produtos. Quando a empresa quer ligar os dois mundos, isso é feito por um mapeamento separado e explícito. Essa decisão evita que uma sincronização sobrescreva dados que outra área mantém.
A estrutura também foi preparada para outros produtos do ecossistema Questor: cada produto entra como um adaptador próprio, sem reaproveitar credenciais ou regras de outro.
Integração com a Sieg
Download de XMLs
A rotina percorre todas as conexões ativas e baixa os XMLs de NF-e e NFS-e pela API, paginando os resultados. Na primeira execução, busca os últimos 31 dias. Nas seguintes, retoma da última execução bem-sucedida com 15 minutos de sobreposição, para não perder documentos que chegaram com atraso. Os XMLs são gravados de forma idempotente, separados por conexão, e um diretório local pode complementar a importação.
Etiquetas e regras
A Sieg permite classificar documentos com etiquetas. A integração mantém um espelho local dessas etiquetas e um motor de regras que decide quais aplicar a cada documento, logo depois da importação.
- Uma ação manual, uma regra ou uma sugestão de IA define as etiquetas do documento.
- A atribuição é salva localmente.
- O estado desejado entra em uma fila de sincronização.
- O serviço envia as inclusões e remoções para a API da Sieg.
- Falhas permanecem na fila com retentativa progressiva, processada pelo agendador.
Sugestões geradas por IA passam pelo mesmo caminho das regras: mesma validação, mesma fila e mesma idempotência. A IA ajuda a classificar, mas não ganha um atalho para gravar direto na plataforma.
Autorização OAuth
Além das credenciais da integração, cada empresa autoriza o acesso na própria Sieg. O painel gera um state de uso único e validade curta, redireciona para a autorização, recebe o token temporário, troca pelo token definitivo, armazena criptografado e renova antes do vencimento.
Boas práticas que valem para as duas integrações
- Credenciais e tokens sempre criptografados no banco.
- Dados separados por conexão e empresa em todas as tabelas.
- Sincronização incremental com margem de segurança no período.
- Gravação idempotente: rodar duas vezes não duplica nada.
- JSON ou XML original preservado para auditoria.
- Painel com resumo, situação da última sincronização e alertas.
- Filas com retentativa para qualquer escrita em sistema externo.
Perguntas frequentes
A integração altera dados dentro do Questor?
Nas rotinas de sincronização descritas aqui, o fluxo é de consulta: os dados do Questor são espelhados no sistema. Operações de escrita, quando necessárias, são tratadas como integrações específicas e controladas.
Preciso de uma conexão por cliente do escritório?
Não necessariamente. Uma conexão pode atender várias empresas, cada uma cadastrada com seu identificador na API.
Os XMLs baixados da Sieg ficam no meu sistema?
Sim. Eles são armazenados localmente, separados por conexão, e podem alimentar conciliações, relatórios e outros módulos fiscais.
A IA pode classificar os documentos?
Pode sugerir etiquetas, mas as sugestões passam pelas mesmas regras, validações e fila de sincronização das etiquetas manuais.
Quer conectar seu sistema ao Questor ou à Sieg?
Desenvolvo integrações com ERPs contábeis e plataformas de documentos fiscais, com sincronização segura, várias empresas por conexão, classificação automática e rastreabilidade completa.