Manual Integração De Bombas Via Api

---
title: Manual Integração De Bombas Via Api
slug: integracao-bombas-via-api
sistema: 
  - Gestão Administrativa
tipo: how-to
chamado: "0000580037"
categoria: user_manual
publico: ""
keywords: [integração, bombas, API, EPTA SGA, CTA Smart, abastecimento]
autor: Antonio Marcos Zampier
setor: Qualidade
modulo: Gestão Administrativa
versao_doc: "01"
revisao: Paulo Bley
aprovado_em: "Outubro de 2026"
ultima_revisao: "2026-10-05"
versao_pipeline: ia-forja
---

## Visão Geral

A integração de bombas via API (Application Programming Interface) permite importar abastecimentos de sistemas de terceiros no Teorema. Este documento descreve a instalação, configuração e utilização da integração, contemplando EPTA SGA e CTA Smart.

O processo inclui: instalação do serviço **SrvBombasAPI**, preenchimento de configurações obrigatórias, definição de parâmetros para geração de abastecimentos e financeiros, configuração e relacionamento de bombas entre sistemas, e inicialização do serviço no Windows.

As regras de funcionamento abrangem como os abastecimentos são importados, os critérios para identificar registros já existentes e as limitações atuais da sincronização com CTA Smart. A integração realiza apenas a **importação dos abastecimentos**, sem atualização posterior de registros já importados. Alterações na CTA Smart após importação devem ser ajustadas manualmente no Teorema para evitar reprocessamento indevido e duplicidades.

## Integrações Disponíveis

- EPTA SGA
- CTA Smart

## Instalar o serviço de integração

### Executar comando de instalação

No Prompt de Comando em modo Administrador, execute o comando na pasta onde estão salvos os executáveis do Teorema:

```
srvbombasapi -install
```

![Prompt de Comando com comando srvbombasapi -install e mensagem de confirmação "Service installed successfully"](https://teorema-spaces.nyc3.digitaloceanspaces.com/base_conhecimento/avulsos-ia/integracao-bombas-via-api/integracao-bombas-via-api-02.png)

Após executar, será exibida a mensagem confirmando que o serviço foi instalado.

### Executar comando GUI para abrir configuração

Em seguida, execute o comando:

```
srvbombasapi GUI
```

![Prompt de Comando executando srvbombasapi GUI com a interface de configuração iniciando](https://teorema-spaces.nyc3.digitaloceanspaces.com/base_conhecimento/avulsos-ia/integracao-bombas-via-api/integracao-bombas-via-api-03.png)

Este comando abre a tela de configuração do serviço.

## Configurações do serviço

Todos os itens da configuração são obrigatórios e devem ser preenchidos de acordo.

![Tela de configuração do SrvBombasAPI com campos para usuário, tipo de API, dados de abastecimento e financeiro, token empresa, posto, e parâmetros de integração](https://teorema-spaces.nyc3.digitaloceanspaces.com/base_conhecimento/avulsos-ia/integracao-bombas-via-api/integracao-bombas-via-api-04.png)

### Campo 1: Usuário do sistema

Usuário que receberá as mensagens (Recados) quando ocorrem erros na integração.

### Campo 2: Tipo de API e dados de Abastecimento e Financeiro

Opções disponíveis:

- **Gerar Financeiro**: gera uma cobrança contra o abastecimento
- **Finaliza Abastecimento**: finaliza o lançamento de abastecimento e gera movimentação de estoque
- **API**: define a qual serviço será feita a conexão

### Campo 3: Token Empresa

Chave de acesso fornecida pela EPTA ou CTA Smart.

### Campo 4: Posto

Quando se deseja trazer os abastecimentos de uma unidade específica associada à chave.

### Campos 5 e 6: Credenciais EPTA

Disponíveis apenas para EPTA. Além da chave, solicitam usuário e senha de acesso à integração.

### Campos 7 a 12: Dados padrão para geração de abastecimentos

Dados padrão que receberão os movimentos para geração de abastecimentos quando não forem encontrados os dados vindos da integração.

### Campos 8 a 13: Dados padrão para geração de financeiros

Dados padrão baseados nos itens de 7 a 12, como complemento da geração do abastecimento.

### Campo 14: Tipo de consulta

Define como os dados dos veículos serão integrados:

- **Placa**: integração por placa (o valor da placa deve estar exatamente igual ao cadastro)
- **Frota**: busca pelo número destacado da frota no cadastro de veículo

### Campo 15: Horário de leitura

Define um horário ao qual serão realizadas as leituras diárias. De preferência, não use 00:00, pois os filtros são baseados em D-1 das 00:00 às 23:59.

## Configuração de Bombas

Se nenhuma bomba for configurada, a integração lançará todos os dados para os padrões configurados na primeira aba.

![Tela de configuração de bombas com tabela listando bombas cadastradas e botões para editar e excluir](https://teorema-spaces.nyc3.digitaloceanspaces.com/base_conhecimento/avulsos-ia/integracao-bombas-via-api/integracao-bombas-via-api-05.png)

### Campos da configuração de bombas

- **Campo 1**: pesquisa as bombas por data para serem integradas de acordo com os movimentos realizados naquele período. Não é possível criar novas bombas, apenas apontar o mapeamento (de/para) entre os sistemas.
- **Campo 2**: edita uma bomba associada, exibindo o mapeamento de/para.
- **Campo 3**: exclui uma bomba associada.

## Editar o mapeamento de/para das bombas

![Tela de configuração de mapeamento de bombas com campos para posto origem, código da bomba/bico, empresa destino, bomba de destino, e tipo de bomba (Interna/Externa/Ignorar)](https://teorema-spaces.nyc3.digitaloceanspaces.com/base_conhecimento/avulsos-ia/integracao-bombas-via-api/integracao-bombas-via-api-06.png)

### Campo 1: Número do posto

Representa o número do posto recebido pela integração.

### Campo 2: Código da bomba e do bico

Representa o código da bomba e do bico que serão integrados.

### Campo 3: Empresa destino

Define para qual empresa o movimento do posto será realizado.

### Campo 4: Bomba do sistema

Define para qual bomba do sistema será feito o mapeamento. As informações de produto devem estar cadastradas na bomba do Teorema.

### Campos 5 a 7: Dados padrão da bomba

Informações padrão quando os dados de integração não encontrarem registros no Teorema. Os mesmos serão preenchidos pelos padrões definidos na bomba e dispara o recado para o usuário padrão definido na aba anterior.

### Campo 8: Tipo de bomba

Define o tipo de bomba sendo integrada:

- **Interna**: o abastecimento está dentro da própria empresa
- **Externa**: foi realizado em um posto ou empresa credenciada
- **Ignorar**: esta bomba não gerará nenhum tipo de movimento no sistema

## Iniciar o serviço no Windows

Após realizar todas as configurações e salvar adequadamente, acesse o gerenciamento de serviços do Windows e inicie o serviço de integração.

Passos:

1. Procure nos serviços pelo "ServicoBombasAPI"
2. Clique sobre o mesmo
3. Clique com o botão direito e selecione a opção "Iniciar"

![Gerenciador de Tarefas do Windows mostrando a lista de Serviços com o ServicoBombasAPI destacado e opções de contexto incluindo Iniciar](https://teorema-spaces.nyc3.digitaloceanspaces.com/base_conhecimento/avulsos-ia/integracao-bombas-via-api/integracao-bombas-via-api-01.png)

## Regras da integração

### A integração não realiza atualização de registros

> **Nota:** Depois que um abastecimento da CTA Smart entra no sistema, o integrador não atualiza mais esse registro. Se ele for alterado depois na CTA Smart, a mudança não chega ao Teorema.

Quando importado os abastecimentos pela primeira vez, caso sofra alguma alteração diretamente na ferramenta de controle da CTA Smart em um abastecimento já importado para o sistema, não existe rotina de atualização desse movimento. Após importado a primeira vez, o registro não sofre alterações vindas do outro sistema.

### Como funciona a importação: serviço SrvBombasAPI

**Qual data ele busca**: roda uma vez por dia, no horário configurado, e solicita à API os abastecimentos do dia anterior. Pela tela também é possível rodar manualmente informando uma data.

**Como sabe que um abastecimento já foi importado**: procura em TRA_ABASTECIMENTO por empresa + data de emissão + abastec_numero_nf. Esse número é o ID que a CTA Smart atribui ao abastecimento.

**O que faz se já existe**: pula para o próximo registro.

**O que faz se não existe**: grava um registro novo e, se estiver configurado, gera o financeiro.

> **Atenção:** Não existe UPDATE em TRA_ABASTECIMENTO (tabela dos abastecimentos) com dados vindos da API. O único UPDATE marca a situação 'F' (finalizado) logo depois de gravar. A API também não informa se o abastecimento foi alterado: a consulta é feita apenas por data (data_inicio/data_fim), sem nenhuma data de alteração.

### Efeitos das alterações na CTA Smart

| Alteração na CTA Smart | Efeito no Teorema |
|---|---|
| Litros, valor, odômetro/horímetro, veículo, motorista | Ignorada. O registro já existe e é pulado, mesmo rodando novamente a mesma data. |
| Exclusão do abastecimento | Ignorada. O registro continua no Teorema. |
| Data do abastecimento | Na rotina diária, ignorada. Mas se rodar manualmente a nova data, a busca procura pela data nova, não acha o registro e importa de novo, gerando duplicidade (inclusive no financeiro). |
| Origem/bomba configurada para uma empresa diferente da original e da empresa padrão | Mesmo risco de duplicidade ao rodar a data novamente. |
| Abastecimento lançado na CTA com data já importada (lançamento retroativo) | Entra apenas se aquela data for rodada novamente manualmente. Os que já existem são pulados e o novo é importado. |

### Recomendação para o Suporte

Responder ao cliente: a integração só importa, ela não sincroniza. Correções feitas na CTA Smart depois da importação precisam ser feitas também no Teorema, diretamente no movimento de abastecimento.

Orientar o cliente a não rodar novamente pela tela uma data cujos abastecimentos tiveram a data alterada na CTA Smart.

## Informações do documento

> Autor: Antonio Marcos Zampier
> 
> Setor: Qualidade
> 
> Módulo: Gestão Administrativa
> 
> Chamado: 0000580037
> 
> Versão do Sistema: 
> 
> Versão do documento: 01
> 
> Revisão: Paulo Bley
> 
> Aprovado em: Outubro de 2026

---

> 📎 **Arquivos originais:** [MANUAL_INTEGRAÇÃO_DE_BOMBAS_VIA_API.docx](https://drive.google.com/uc?export=download&id=1aaMZC9XDLU1qEpr7DmbRNGILJanXdxnC)