API REST telecom: integração com TOTVS, SAP e Sankhya em 2026

Gerente de TI de empresa com 320 linhas multi-operadora prepara reunião com Financeiro: fechamento de mês de telecom passou de 14h em janeiro para 28h em maio. Causa: parque cresceu de 250 para 320 linhas, multi-operadora virou regra, planilha mestra de rateio não acompanha. Diretor Financeiro pergunta: “vamos integrar API com Protheus?”. TI responde honestamente: “depende dos endpoints disponíveis e do escopo de mapeamento”. Em 30-60 dias, com integração estruturada, fechamento volta para 1-2h. Sem integração, em 6 meses vira 40h por causa do crescimento.

Integração API REST entre gestão de telecom e ERP corporativo (TOTVS Protheus, SAP S/4HANA, Sankhya) elimina 8-22h/mês de reconciliação manual em parque 100+ linhas. A integração estruturada precisa de 6 endpoints essenciais — consumo por linha, fatura consolidada, rateio por centro de custo, plano contratado, eventos de mudança, ledger contábil. Em parque 200 linhas, implantação leva 30-60 dias e estabiliza fechamento de mês em 1-2h versus 12-30h manual.

Esse não é um post sobre vilanizar ERP ou operadora. ERPs brasileiros (TOTVS Protheus, SAP S/4HANA, Sankhya) entregam APIs robustas e bem documentadas. Operadoras Vivo, Claro e TIM mantêm portais corporativos com exportação de dados estruturada. A questão é estrutural: sem camada de consolidação entre operadora e ERP, reconciliação fica manual em planilha mestra. Camada de consolidação é o que API REST entrega.

Em anatomia da demo pública ContaClara cobrimos a navegação em 3 níveis. Em multi-CNPJ em telecom corporativo cobrimos governança e fechamento de mês. Em rateio de telefonia por centro de custo cobrimos as 5 regras canônicas. Este post aprofunda a camada técnica — os 6 endpoints essenciais, o mapeamento por ERP e o ciclo de implantação em 30-60 dias.

Por que API REST resolve o que planilha mestra não consegue

Reconciliação manual em parque 100+ linhas multi-operadora enfrenta três limites estruturais:

Limite 1 — Crescimento não-linear

Parque cresce linearmente (mais 30 linhas por trimestre típico em empresa em expansão). Reconciliação cresce quadraticamente — porque cada linha nova exige cadastro de centro de custo, validação de plano, conferência de SVA, integração com ledger. Em parque 200 linhas, fechamento ocupa 12-30h. Em parque 400 linhas, ocupa 40-90h se mantiver método manual.

Limite 2 — Multi-operadora multiplica estruturas

Vivo organiza fatura de um jeito, Claro de outro, TIM de outro. Sem camada de consolidação, reconciliação vira 3 fluxos paralelos com lógicas diferentes. ERP recebe 3 cargas, cada uma com mapeamento próprio. Erro de digitação ou divergência de classificação fica frequente.

Limite 3 — ERP tem semântica própria

TOTVS Protheus, SAP S/4HANA e Sankhya estruturam centro de custo, plano de contas e ledger em tabelas específicas com regras próprias. Sem mapeamento entre estrutura de telecom e estrutura do ERP, lançamentos contábeis ficam fora do padrão — vira chamado para contabilidade ajustar.

Os 6 endpoints essenciais de integração telecom-ERP

Endpoint 1 — Consumo por linha

GET /v1/linhas/consumo?periodo=2026-06&cnpj=12.345.678

Retorna dados, minutos e SMS consumidos por linha no período. Schema padrão:

{
  "linhas": [
    {
      "numero": "11912345678",
      "operadora": "Vivo",
      "dados_gb": 8.5,
      "minutos": 220,
      "sms": 15,
      "franquia_dados_gb": 10.0,
      "franquia_minutos": 500,
      "centro_custo": "CC-201"
    }
  ]
}

Endpoint 2 — Fatura consolidada

GET /v1/faturas?periodo=2026-06

Retorna fatura estruturada por linha, incluindo plano, SVA e equipamento. Diferenciação importante versus Endpoint 1 (que mostra consumo): este mostra cobrança efetiva.

Endpoint 3 — Rateio por centro de custo

GET /v1/rateio?periodo=2026-06&politica=padrao

Retorna valor a alocar por CC conforme política cadastrada. Política padrão geralmente é proporcional ao gasto direto da linha mais rateio de custo agregado (SVA corporativo, link compartilhado).

Endpoint 4 — Plano contratado

GET /v1/planos?linha=11912345678

Retorna plano vigente por linha. Útil para cruzamento com Endpoint 2 e identificação de plano divergente (cobrimos em plano contratado divergente da fatura cobrada).

Endpoint 5 — Eventos de mudança

POST /v1/eventos
{
  "tipo": "novo_colaborador",
  "linha": "11912345678",
  "centro_custo": "CC-201",
  "data_evento": "2026-06-15"
}

Envia para ERP eventos como novo colaborador, desligamento, mudança de função, ajuste de plano. Permite ERP refletir mudança em telecom no fechamento subsequente.

Endpoint 6 — Ledger contábil

GET /v1/ledger?periodo=2026-06

Retorna lançamentos contábeis no formato esperado pelo ERP. Em TOTVS Protheus, formato é compatível com tabela CT2. Em SAP S/4HANA, formato é compatível com BSEG. Em Sankhya, formato é compatível com TGFFIN.

Mapeamento por ERP — TOTVS, SAP, Sankhya

TOTVS Protheus

Versões suportadas: Protheus 12 (TSS — Total Service SOA) e Protheus 13 (REST nativo).

Estrutura de centro de custo: tabela CTT com chave CTT_CUSTO.

Plano de contas: tabela CT1 com chave CT1_CONTA.

Ledger: tabela CT2 com lançamentos contábeis.

Integração técnica: Web Service Protheus (TSS) ou API REST nativa (Protheus 13+). Autenticação via token bearer.

Setup típico: 8-12h de TI + Financeiro para mapeamento CTT/CT1/CT2 + configuração de webhook.

SAP S/4HANA

Versões suportadas: SAP S/4HANA 2020+ (OData REST API estabilizado).

Estrutura de centro de custo: tabela CSKS com chave KOSTL.

Plano de contas: tabela SKA1 (estrutura) e SKB1 (saldos).

Ledger: tabela BSEG com lançamentos.

Integração técnica: OData REST API ou SAP Cloud Platform Integration (SCPI). Autenticação OAuth 2.0 ou SAP Logon Ticket.

Setup típico: 12-20h de TI + Financeiro para mapeamento OData + configuração SCPI + validação de payload.

Sankhya

Versões suportadas: Sankhya OM 4.x+ (API REST nativa e WebService SAN consolidados).

Estrutura de centro de custo: tabela TGFCCS.

Plano de contas: tabela TGFCTA.

Ledger: tabela TGFFIN com lançamentos.

Integração técnica: API REST nativa Sankhya ou WebService SAN. Autenticação via token bearer.

Setup típico: 8-14h de TI + Financeiro para mapeamento TGFCCS/TGFCTA/TGFFIN + configuração de permissão de usuário API.

Tabela síntese — esforço de integração por ERP

Tabela é referência — valores reais dependem da customização do ERP, complexidade do plano de contas e número de centros de custo mapeados.

O ciclo de implantação em 30-60 dias

Fase 1 — Descoberta (semanas 1-2)

Semana 1:

• Levantar versão do ERP em produção
• Identificar endpoints disponíveis (Protheus Web Service, SAP OData, Sankhya WebService)
• Validar credencial técnica e ambiente de teste
• Documentar estrutura atual de centro de custo

Semana 2:

• Validar permissões de usuário API
• Confirmar conectividade entre ContaClara e ERP (rede, firewall, allowlist)
• Estabelecer ambiente sandbox para testes

Fase 2 — Mapeamento (semanas 3-4)

Semana 3:

• Mapeamento de centro de custo (estrutura ERP vs estrutura organizacional da empresa)
• Mapeamento de plano de contas (telecom vai para qual conta no ERP?)
• Definição de política de rateio (proporcional, por gestor, por filial)

Semana 4:

• Validação do mapeamento com Compras + Financeiro
• Documentação do dicionário de tradução

Fase 3 — Implementação técnica (semanas 5-6)

Semana 5:

• Configurar autenticação OAuth 2.0 ou token bearer
• Testar Endpoint 1 (consumo) em ambiente sandbox
• Testar Endpoint 2 (fatura) em ambiente sandbox
• Validar payload de retorno

Semana 6:

• Testar Endpoint 6 (ledger) com primeira carga simulada
• Validar lançamento contábil no ERP em ambiente sandbox
• Ajustar formato conforme expectativa do ERP

Fase 4 — Go-live e estabilização (semanas 7-8)

Semana 7:

• Migração paralela — fluxo manual + automático rodando simultaneamente
• Validação de números entre manual e automático
• Ajuste fino em divergências encontradas

Semana 8:

• Estabilização final — fluxo automático único
• Documentação para operação recorrente
• Treinamento de equipe Compras + Financeiro

Tabela síntese — impacto operacional pós-integração

Como a ContaClara expõe API REST

A ContaClara expõe API REST documentada em padrão OpenAPI 3.0 com 6 endpoints essenciais — consumo, fatura, rateio, plano, eventos, ledger. Autenticação OAuth 2.0 com escopo por cliente, rate limit configurável (padrão 100 req/min, ajustável conforme contrato), webhook para eventos críticos (nova fatura disponível, mudança de plano, alerta de excedente).

Conectores prontos:

• TOTVS Protheus (via TSS para Protheus 12, REST nativo para Protheus 13+)
• SAP S/4HANA (via OData REST API)
• Sankhya (via WebService SAN ou REST nativa)

Implantação típica em 30-60 dias com suporte técnico estruturado. Após integração, fechamento de mês cai de 12-30h para 1-2h em parque 200 linhas. Documentação técnica em usecontaclara.com.br/seguranca e em /docs/api (acesso liberado pós-contratação).

Para validação técnica antes de assinar contrato, demo pública sem cadastro em app.usecontaclara.com.br/demo (Mercearia Tem de Tudo · 387 linhas · R$ 47k fatura · navegação multi-nível ilustrando estrutura de dados). Calculadora pública em usecontaclara.com.br/#precos.

ContaClara é o painel claro de telecom corporativo. Consolidamos, organizamos e governamos cada linha, cada CNPJ, cada real da fatura — multi-operadora, multi-filial, integrável a TOTVS, SAP e Sankhya. AtraND ND Ltda. — CNPJ 28.726.886/0001-83.