Produto: MaxPromotor
O que é o erro 503
O erro 503 Service Unavailable no portal de integração MaxPromotor indica que o serviço de integração (ambiente "int") não conseguiu se comunicar com o banco de dados ERP do cliente. O sistema inicia, mas falha ao tentar estabelecer a conexão com o banco.
Mensagem de erro típica nos logs:
The Network Adapter could not establish the connection
Isso confirma que as configurações de conexão com o ERP do cliente estão incorretas ou que houve alguma alteração na infraestrutura (host, porta, service name, etc.).
Como validar os erros: lendo os logs
Antes de qualquer ação, leia os logs do ambiente "int" do cliente afetado. Isso garante que você está tratando o problema correto e já saberá exatamente quais informações solicitar ao cliente.
Dica
Sempre consulte os logs ANTES de entrar em contato com o cliente. Com o erro identificado, você transmite confiança e agiliza o atendimento.
Passo 1 — Ler os Logs via Pipeline
Acesse a pipeline de leitura de logs: MAXPROMOTOR-EKS_PRODUCAO-lerLogs
- Construir com parâmetros: informe o nome do cliente, código e ambiente = int
- Acesse o build gerado e clique em "Console output"
- Leia até o final: o início do log pode apresentar timeout — o erro real com o motivo da falha de conexão aparece mais abaixo.
Exemplos de erros já mapeados
Banco | Mensagem de erro no log |
SQL Server | com.microsoft.sqlserver.jdbc.SQLServerException:O número de porta 1433/PROTHEUS12 não é válido; |
Oracle | Erro de ES: The Network Adapter could not establish the connectionORA-12505: Cannot connect to database. SID bdmaxima2 is not registered.ORA-12514: Cannot connect to database. Service bdmaxima2 is not registered. |
Firebird | Erro de conexão ao tentar conectar — confirmar host, porta e service name com o cliente. |
Passo a passo para resolução
1 | Ler os logs da pipeline Acesse a pipeline lerLogs, construa com os parâmetros do cliente (código, ambiente = "int"), leia o Console output até o final e identifique o tipo de erro. |
2 | Verificar as configurações via LerConfigs Acesse a pipeline lerConfigs com o nome do cliente, leia o Console output e anote o valor de ds_erp.driver e ds_erp.url. |
3 | Identificar o tipo de banco (driver ERP) O valor de ds_erp.driver define o banco: Oracle, Firebird ou SQL Server. O banco determina os próximos passos. |
4 | Testar a conectividade no DBeaver (Workspace) Com os dados da URL, tente conectar no DBeaver. Se conectar, reinicie o serviço. Se não conectar, atualize com o cliente. |
5 | Corrigir as configurações no Jenkins Com as informações corretas, atualize os parâmetros na pipeline e reinicie o serviço. Verifique os logs para confirmar a resolução. |
Passo 2 — Verificando as Configurações (LerConfigs)
Sempre valide a configuração atual no workspace antes de contatar o cliente.
2.1 — Ler a configuração atual via Pipeline
Acesse: MAXPROMOTOR-EKS_PRODUCAO-lerConfigs
- Construir com parâmetros informando o nome do cliente
- Após o build, clique em "Console output" e busque por url
- Anote os dados da URL de integração — host, porta e service name/SID
2.2 — Testar a conexão no DBeaver (Workspace)
Com os dados extraídos do lerConfigs, tente conectar no DBeaver:
- Se conectar com sucesso: pare o serviço e inicie novamente. Se o erro 503 persistir e os logs mostrarem timeout, verifique com o cliente se pode haver interferência de firewall bloqueando o acesso do ambiente nuvem MaxPromotor.
- Se não conectar: repasse a URL atual de conexão ao cliente e solicite a URL correta. Valide novamente no DBeaver até a conexão ser bem-sucedida.
- Com a URL correta confirmada: atualize os parâmetros na pipeline:
Pipeline de atualização: MAXPROMOTOR-EKS_PRODUCAO-ATUALIZARCONF-INT-GITOPS
- Após atualizar, pare e inicie a aplicação na pipeline:
Pipeline de start/stop: MAXPROMOTOR-EKS_PRODUCAO-start-stop
Sempre valide a configuração atual no workspace antes de contatar o cliente.
2.1 — Ler a configuração atual via Pipeline
Acesse: MAXPROMOTOR-EKS_PRODUCAO-lerConfigs
- Construir com parâmetros informando o nome do cliente
- Após o build, clique em "Console output" e busque por url
- Anote os dados da URL de integração — host, porta e service name/SID
2.2 — Testar a conexão no DBeaver (Workspace)
Com os dados extraídos do lerConfigs, tente conectar no DBeaver:
- Se conectar com sucesso: pare o serviço e inicie novamente. Se o erro 503 persistir e os logs mostrarem timeout, verifique com o cliente se pode haver interferência de firewall bloqueando o acesso do ambiente nuvem MaxPromotor.
- Se não conectar: repasse a URL atual de conexão ao cliente e solicite a URL correta. Valide novamente no DBeaver até a conexão ser bem-sucedida.
- Com a URL correta confirmada: atualize os parâmetros na pipeline:
Pipeline de atualização: MAXPROMOTOR-EKS_PRODUCAO-ATUALIZARCONF-INT-GITOPS
- Após atualizar, pare e inicie a aplicação na pipeline:
Pipeline de start/stop: MAXPROMOTOR-EKS_PRODUCAO-start-stop
Cenário 1 — Banco Oracle (clientes WinThor)
A maioria dos clientes que utilizam Oracle são clientes WinThor. Para este cenário, é necessário acessar a máquina do cliente e testar a conexão diretamente.
Solicitando acesso e conectando
- Solicite acesso remoto à máquina do cliente onde está instalado o força de vendas
- Utilize uma ferramenta de banco disponível na máquina: TOAD, PL/SQL Developer ou DBeaver
Extraindo as informações de conexão do ds_erp.url
O parâmetro ds_erp.url contém todas as informações de conexão. Exemplo:
Service Name: ds_erp.url=jdbc:oracle:thin:@10.62.38.96:1521/pdbdb01 SID: ds_erp.url=jdbc:oracle:thin:@10.62.38.96:1521:pdbdb01 |
Parâmetro | Valor no exemplo | Onde usar na ferramenta de banco |
host / ip | 10.62.38.96 | Campo "Host" da conexão |
porta | 1521 | Campo "Port" da conexão |
service name | pdbdb01 | Campo "Service Name" (não SID) |
ds_erp.username | (valor no Jenkins) | Campo "User / Schema" |
ds_erp.password | (valor no Jenkins) | Campo "Password" |
🔍 O que verificar ao testar a conexão Oracle: |
• Se der erro de conexão, confirme com o cliente se houve alteração no servidor (migração do banco, mudança de IP, alteração de porta, etc.). |
• Com as novas configurações em mãos, atualize os parâmetros no Jenkins. |
Cenário 2 — Banco Firebird (clientes não-WinThor)
Clientes com banco Firebird geralmente não são WinThor. Neste cenário, não costumamos acessar a máquina do cliente diretamente. O foco é validar as configurações de rede.
ds_erp.url=jdbc:firebirdsql://10.62.38.96:3050/C:/bases/exemplo.fdb |
Como proceder
- Colete com o cliente as informações atuais de conexão: host/IP, porta e service name
- Compare com os valores configurados no Jenkins via "LerConfigs"
- Verifique se o IP do ambiente nuvem MaxPromotor está liberado no firewall do cliente
- Confirme se houve alguma migração de servidor ou alteração de infraestrutura recente
Atenção:
Cenário 3 — Banco SQL Server
Clientes com banco SQL Server utilizam o driver com.microsoft.sqlserver.jdbc.SQLServerDriver. O procedimento é similar ao Firebird: validar as configurações de rede e a URL de conexão.
⚠️ Pré-requisito obrigatório: |
Antes de qualquer configuração, o parâmetro CONFIG_INTEGRACAO_SQLSERVER deve estar habilitado nas Configurações de Sistema. Sem esse parâmetro ativo, a integração com SQL Server não funcionará. |
Extraindo as informações de conexão do ds_erp.url
O parâmetro ds_erp.url contém todas as informações de conexão. Exemplo:
ds_erp.url=jdbc:sqlserver://10.62.38.96:1433;databaseName=master |
Parâmetro | Valor no exemplo | Onde usar na ferramenta de banco |
host / ip | 10.62.38.96 | Campo "Host" da conexão |
porta | 1433 | Campo "Port" da conexão (padrão SQL Server) |
databaseName | PROTHEUS12 | Campo "Database" da conexão |
ds_erp.username | (valor no Jenkins) | Campo "User / Login" |
ds_erp.password | (valor no Jenkins) | Campo "Password" |
Como proceder
- Valide que o parâmetro CONFIG_INTEGRACAO_SQLSERVER está habilitado nas Configurações de Sistema
- Colete com o cliente as informações de conexão: host/IP, porta e nome do banco (databaseName)
- Tente conectar no DBeaver com os dados da URL atual do Jenkins
- Se não conectar, repasse a URL ao cliente e solicite os dados corretos
- Verifique se o IP do ambiente nuvem MaxPromotor está liberado no firewall do cliente para a porta 1433
🔍 Erro típico no log para SQL Server: |
com.microsoft.sqlserver.jdbc.SQLServerException: |
O número de porta 1433/PROTHEUS12 não é válido; |
Isso geralmente indica que a URL está mal formatada ou que o databaseName está incorreto. |
Resumo Comparativo: Oracle vs. Firebird vs. SQL Server
🔶 Oracle | 🔷 Firebird | 🟥 SQL Server | |
Clientes | WinThor | Não-WinThor | Variado |
Driver | oracle.jdbc.driver.OracleDriver | org.firebirdsql.jdbc.FBDriver | com.microsoft.sqlserver.jdbc.SQLServerDriver |
Porta padrão | 1521 | 3050 | 1433 |
Testar conexão | Acessar workspace — DBeaver | Acessar workspace — DBeaver | Acessar workspace — DBeaver |
Pré-requisito especial | Não ter regras de firewall que impacte na disponibilidade da conexão | Não ter regras de firewall que impacte na disponibilidade da conexão | Não ter regras de firewall que impacte na disponibilidade da conexão |
Ação Final — Atualizando no Jenkins
Após identificar e confirmar as configurações corretas com o cliente, atualize os parâmetros de conexão na pipeline e reinicie o serviço de integração do ambiente "int". Verifique novamente os logs para confirmar que o erro 503 foi resolvido.
✅ Checklist de resolução
☐ | Logs do ambiente "int" analisados via pipeline lerLogs — erro confirmado |
☐ | Tipo de banco identificado via ds_erp.driver (Oracle / Firebird / SQL Server) |
☐ | Configurações lidas via pipeline lerConfigs — ds_erp.url anotada |
☐ | |
☐ | Conexão testada no DBeaver com a URL atual |
☐ | Configurações corretas coletadas com o cliente (se necessário) |
☐ | Parâmetros atualizados na pipeline ATUALIZARCONF-INT-GITOPS |
☐ | Serviço reiniciado via pipeline start-stop |
☐ | Logs verificados sem erro 503 |
Artigo criado e revisado por Thais Regina Mendes Batista.