GUIA COMPLETO DE INTEGRAÇÃO DE ERPS

1. Finalidade

O Sentinela Fiscal é uma camada de governança fiscal. Ele se conecta ao ERP que a empresa já utiliza — por exemplo, Omie, Bling, Conta Azul, TOTVS, SAP ou Senior — para organizar os documentos fiscais que a empresa emite, recebe ou já lançou internamente.

Depois, cruza esses fatos operacionais com fontes fiscais oficiais disponíveis, regras de IBS/CBS, classificação tributária, eventos de cancelamento/substituição e, em fases posteriores, informações de apuração e pagamento.

Princípio de escopo: o ERP informa o que a empresa registrou; as fontes oficiais ajudam a validar o que ocorreu no ambiente fiscal nacional; o Sentinela mantém a trilha de evidências e aponta o que precisa ser revisado.

O Sentinela não substitui Receita Federal, CGIBS, prefeituras, contador ou assessoria jurídica. Ele não garante apropriação automática de créditos, não assegura ausência de glosa e não realiza atos fiscais ou de movimentação financeira sem autorização expressa.

2. Escopo Inicial Recomendado — Somente Fiscal

A primeira integração deve ser somente leitura e limitada a dados fiscais. Isso reduz risco de vazamento, acelera a homologação junto à TI e já captura a totalidade do valor de IBS/CBS.

2.1 Dados importados no MVP

• Notas fiscais de entrada e saída.
• XML autorizado ou referência segura ao XML de emissão.
• Chave de acesso, número, série e status de validação nacional.
• Itens, serviços, NCM, NBS, CFOP e códigos municipais de serviço.
• CST, cClassTrib e demais indicadores tributários disponíveis.
• Base de cálculo e valores destacados de IBS UF, IBS Município e CBS.
• Emitente, destinatário/tomador, CNPJ, filial e município.
• Eventos fiscais: cancelamento, substituição, devolução, complemento e ajuste.
• Competência, data de emissão e metadados do lançamento fiscal.

2.2 Dados que ficam fora da primeira fase

• Contas a pagar e a receber das contas financeiras.
• Bancos, cartões, Pix, boletos ou extratos bancários.
• Folha de pagamento e dados de colaboradores.
• Contabilidade e escrituração completa.
• Permissões para emitir, cancelar ou alterar documentos fiscais na SEFAZ.
• Permissões de pagamento ou aprovação financeira.
• Acesso de escrita no banco de dados corporativo do ERP.

3. Como o Cliente Autoriza

A forma de autorização varia conforme o sistema de ERP do cliente. Adotamos o princípio do menor privilégio:

3.1 Regra prática

A autorização de acesso e a comunicação técnica operam em conjunto:

• OAuth: A autorização direta do cliente gera tokens temporários e seguros para a API.
• Usuário técnico: O usuário restringe permissões no Protheus/SAP; a API é a rodovia de transporte dos dados.
• Certificado digital: É utilizado exclusivamente na comunicação direta com as bases governamentais, independente da API do ERP.

4. Arquitetura de Referência

4.1 Modelo de Integração Push (Recomendado para MVP)

O modelo recomendado é o **ERP enviar dados para o Sentinela** via HTTPS (POST), em vez de expor as portas internas do cliente na internet.

Vantagens: Não há exposição pública do servidor Protheus/SAP; dispensa a liberação de acesso de entrada (firewall/VPN); trafega apenas documentos modificados ou novos; facilita a revogação de acesso a qualquer momento pelo cliente.

5. Integrações por ERP

5.1 TOTVS Protheus

No Protheus, a integração é feita por serviços REST configurados no AppServer, com rotinas oficiais ou em ADVPL/TL++ desenvolvidas pelo parceiro TOTVS do cliente.

Configuração do Cliente:

1. Criação de usuário técnico exclusivo de leitura.
2. Exposição de rotas REST seguras com mTLS ou JWT se suportado.
3. Parametrização do conector para POST ativo.

5.2 Omie

A Omie possui conexões baseadas em chaves de aplicativos e webhooks para envio de eventos.

O cliente cria uma aplicação Omie Developer, copia a App Key e App Secret e as informa na aba Integrações do Sentinela. O sincronismo é feito por webhook com contingência incremental via API.

5.3 Bling & Conta Azul

Ambas as plataformas utilizam OAuth 2.0. O cliente clica no botão "Conectar ERP", é direcionado para a página segura do Bling/Conta Azul, realiza login e confirma as permissões fiscais solicitadas.

5.4 SAP S/4HANA & SAP Business One

• S/4HANA: Conexão via Communication Arrangement e API oficial OData para Notas Fiscais no Business Accelerator Hub.
• Business One: Acesso através do Service Layer (OData V4) com usuário técnico de leitura.

6. Fontes Fiscais Oficiais

O Sentinela confronta o que foi registrado no ERP com os canais governamentais oficiais:

• ADN / NFS-e Nacional: Captura preventiva de notas de serviços.
• DF-e / SEFAZ: Monitoramento de chaves emitidas contra o CNPJ da matriz e filiais.
• CFF / SVRS: Base oficial de créditos presumidos, convênios e anexos.
• RTC / Apuração CBS: Cruzamento com a declaração oficial da Receita.

7. API do Sentinela Fiscal (Ingestão)

O conector fiscal deve realizar requisições POST para as seguintes rotas de ingestão:

POST /v1/integrations/totvs/fiscal-documents
POST /v1/integrations/totvs/fiscal-events
POST /v1/integrations/totvs/sync-status

7.1 Exemplo de Payload - Documento Fiscal

{
  "external_id": "PROTHEUS-FISCAL-000123",
  "company_cnpj": "00000000000100",
  "branch_code": "01",
  "document_type": "NFE",
  "document_key": "35260815072021000190550010000123451000012345",
  "document_number": "12345",
  "series": "1",
  "issue_date": "2026-08-03",
  "supplier_cnpj": "00000000000200",
  "gross_amount": 100000.00,
  "tax_base": 100000.00,
  "cst": "000",
  "cclass_trib": "000001",
  "ibs_uf_amount": 0.00,
  "ibs_municipio_amount": 0.00,
  "cbs_amount": 0.00,
  "xml_base64": "XML_ASSINADO_OU_REFERENCIA_SEGURA"
}

8. Idempotência e Antiduplicidade

Para garantir a segurança cadastral, toda chamada deve enviar a chave do cabeçalho Idempotency-Key (UUID v4). O Sentinela rejeita envios duplicados, mantendo as informações da primeira transmissão íntegras, evitando que faturas sejam registradas duas vezes no caso de matrizes e fornecedores integrados simultaneamente.

9. Solicitação à TI em uma Única Frase

Última atualização: 01 de julho de 2026 · NIT IBEDIS em parceria com GovTech