Antes de marcar a data da instalação, vale conferir se o ambiente do cliente tem tudo o que a integração precisa. A lista abaixo é o que costuma travar uma implantação quando é descoberto no dia. Cada item traz o que verificar, quem é o responsável e o que acontece se faltar.
Índice
- Quem faz o quê
- Protheus: release, banco e customização
- Instância dedicada à integração
- Usuário Protheus da integração
- Rede e acesso
- Agente de impressão
- Dicionário: campos que precisam existir antes
- Parâmetros do ERP que afetam a integração
- Operação multi-filial
- Do lado do Vendelo
- Backup e janela
- Checklist rápido
- Perguntas frequentes
Quem faz o quê
A integração roda no Vendelo, na nuvem, e conversa com artefatos publicados no ambiente de customização do cliente. Não existe mais nenhum serviço a instalar no servidor do cliente: quem faz a leitura, a gravação e o controle é o próprio Vendelo.
| Frente | Responsável | Entrega |
|---|---|---|
| Publicação dos artefatos, instância dedicada, dicionário, licenças | Consultor TOTVS ou equipe de TI do cliente | Ambiente Protheus pronto e validado |
| Rede, certificado, firewall, VPN | Infraestrutura do cliente | Acesso liberado apenas pelo caminho aprovado |
| Configuração da empresa e da integração no Vendelo | Vendelo | Integração ativa e primeira carga executada |
| Massa, homologação funcional e aceite | Consultoria de implantação e cliente | Checklist assinado |
O trabalho manual no Protheus é curto, na casa de trinta minutos de rotina padrão TOTVS. O que costuma consumir tempo é conseguir a janela, a credencial e a liberação de rede, não a instalação em si.
Protheus: release, banco e customização
- Release 12.1.33 ou superior, com DBAccess ativo.
- Ambiente de customização disponível para publicar os artefatos da integração, pelo processo padrão TOTVS.
- Grupo de empresa definido. A integração precisa saber o grupo do dicionário, porque o nome físico das tabelas do Protheus depende dele.
Sobre o banco de dados, os três suportados estão homologados: SQL Server, Oracle e PostgreSQL. A preparação da estrutura resolve o dialeto sozinha, e o kit traz os artefatos equivalentes para quem preferir que o DBA execute.
O comportamento é o mesmo nos três bancos. A diferença de dialeto é resolvida na instalação, sem trabalho adicional.
Instância dedicada à integração
A integração conversa por uma instância de aplicação dedicada. Ou já existe uma, ou o cliente precisa ter como criar. A configuração acompanha o kit de instalação.
Um detalhe merece atenção antes de subir: a configuração define a empresa e a filial principal, e é essa filial que se torna a filial padrão do Vendelo. Se estiver apontando para a filial errada, todo o resto sai errado junto.
Instância dedicada não é preciosismo. A carga inicial e as rotinas de faturamento consomem thread e memória; separar da instância que atende os usuários evita que a integração derrube a operação.
Usuário Protheus da integração
- Crie um usuário Protheus dedicado à integração. Não reaproveite login de pessoa: o dia em que essa pessoa sair da empresa, a integração para.
- Revise as permissões desse usuário pelo princípio do menor privilégio, liberando as rotinas que a integração usa e nada além.
- A senha vai para um cofre de segredos do lado do Vendelo, nunca para arquivo de projeto, planilha ou e-mail.
- Combine desde já o procedimento de troca e de revogação da credencial.
Rede e acesso
O Vendelo precisa alcançar a porta da instância dedicada. Isso não significa expor essa porta para a internet inteira.
- Use allowlist do IP de origem da Vendelo, reverse proxy controlado ou VPN.
- Em produção, o endereço configurado deve ser HTTPS.
- Se o certificado for autoassinado, planeje desde já como ele será tratado, seja instalando a cadeia confiável do lado do Vendelo, seja registrando a identificação do certificado esperado.
Autenticação sobre HTTP em produção entrega usuário e senha do Protheus a quem estiver no caminho da rede. Se o cliente insistir em HTTP, o item vira uma pendência de segurança bloqueante, não uma escolha de projeto.
Agente de impressão
O agente de impressão que acompanha o SmartClient precisa estar presente em cada instância que atende a integração, a principal e a dedicada. Sem ele, qualquer PDF gerado pelo servidor falha e o console acusa agente de impressão não encontrado.
Isso vale para boleto, DANFE e para o DANFE nativo. É um arquivo copiado, mas é o tipo de item que ninguém lembra até o cliente pedir o primeiro boleto.
Dicionário: campos que precisam existir antes
Solicitação de compra
Se o cliente vai usar solicitação de compra pelo Vendelo, o campo de identificação C1_XVDOUID precisa existir no dicionário antes de habilitar a série correspondente. A especificação completa acompanha o kit de instalação; o resumo é este:
| Propriedade | Valor |
|---|---|
| Tabela | Solicitações de compra (SC1) |
| Campo | C1_XVDOUID |
| Tipo | Caractere |
| Tamanho | 32 ou maior |
| Decimais | 0 |
| Obrigatório no dicionário | Não, para permitir atualizar uma tabela que já tem linhas |
Crie o campo pelo Configurador ou UPDDISTR, em janela de manutenção, e confirme que a coluna física foi criada. Criar só por SQL deixa a coluna fora do dicionário e a gravação automática não a trata corretamente.
Campos de usuário
Campo de usuário criado no Protheus entra na integração sozinho, desde que seja cadastrado no Vendelo com o nome completo do campo. A regra de criação é a mesma: Configurador, nunca SQL.
Campo de tipo data ou lógico criado por comando SQL fica com o tipo fora de sincronia e derruba a gravação da tabela inteira. O sintoma é cruel: todo pedido passa a ser gravado sem itens, mesmo quando o campo novo nem é enviado.
Pedido do cliente na linha
Se o cliente quiser o número e o item do pedido dele na nota fiscal, os campos precisam já existir no dicionário. Há candidatos no dicionário padrão, e a escolha é confirmada com o cliente. A integração nunca cria campo.
Parâmetros do ERP que afetam a integração
Confira, antes da primeira venda, se o ambiente exige natureza financeira no cadastro do cliente. Quando exige, a natureza padrão precisa ser informada na configuração da integração; sem isso, o primeiro pedido de um cliente criado pelo Vendelo é recusado.
Vale também verificar, com o cliente, onde ficam as imagens de produto, caso ele queira importar foto do catálogo, e se a tesouraria tem tipos de documento cadastrados, porque a baixa financeira exige esse campo.
Operação multi-filial
Filial nova só fecha o ciclo financeiro depois que os cadastros exclusivos por filial existirem nela. São eles: condições de pagamento, contas correntes, naturezas, TES e armazéns.
- Sem a conta corrente, o adiantamento é recusado por conta inexistente na filial.
- Sem a natureza, o título da tarifa é recusado por natureza inválida.
A licença TOTVS é validada pelo CNPJ da filial. Se uma filial não tiver licença própria, o faturamento nela pode falhar com mensagem de licença expirada enquanto a matriz fatura normalmente. Confirme as licenças de todas as filiais que vão operar pelo Vendelo.
Do lado do Vendelo
- Empresa criada no Vendelo, com o identificador que será usado na configuração da integração.
- Usuário master definido. É ele quem executa a primeira carga e quem baixa os logs da integração.
- Vendedores previstos, com o e-mail que será usado para vincular a pessoa ao cadastro de vendedor do Protheus.
- Licenças de acesso disponíveis para os usuários que vão operar.
Backup e janela
- Backup do banco antes de qualquer atualização de dicionário.
- Janela combinada para a criação de campo, que exige modo exclusivo.
- Janela separada, fora do horário de uso, para a primeira carga. Ela consome recursos do Vendelo e do Protheus ao mesmo tempo.
Checklist rápido
| Item | Situação | Se faltar |
|---|---|---|
| Protheus 12.1.33+ com DBAccess | Obrigatório | Integração não é suportada |
| Ambiente de customização disponível | Obrigatório | Não há como publicar a integração |
| Instância dedicada à integração | Obrigatório | Sem canal de comunicação |
| Empresa e filial principal corretas | Obrigatório | Filial padrão errada no Vendelo |
| Usuário Protheus dedicado | Obrigatório | Risco operacional e de auditoria |
| HTTPS e acesso restrito por rede | Obrigatório | Credencial exposta |
| Agente de impressão nas instâncias | Obrigatório | Nenhum PDF é gerado |
Campo C1_XVDOUID na solicitação de compra | Se usar compras | Solicitação de compra bloqueada |
| Campos do pedido do cliente para a nota | Opcional | Informação não vai para a NF-e |
| Exigência de natureza no cliente conferida | Obrigatório | Pedido de cliente novo recusado |
| Cadastros por filial e licença por CNPJ | Se multi-filial | Financeiro e faturamento falham na filial |
| Backup e janela combinados | Obrigatório | Risco na atualização de dicionário |
Perguntas frequentes
Precisa instalar algum serviço no servidor do cliente?
Não. O antigo serviço instalado no cliente deixou de existir; a integração roda no Vendelo. No ambiente do cliente ficam apenas os artefatos publicados na customização e a instância dedicada.
Dá para usar a instância que já atende os usuários?
Tecnicamente sim, mas não é recomendado. A carga inicial e as rotinas de faturamento competem por thread e memória com quem está trabalhando. Uma instância dedicada isola o efeito.
O cliente usa Oracle. Podemos seguir?
Pode. Oracle, PostgreSQL e SQL Server estão homologados. A preparação da estrutura resolve o dialeto sozinha, sem trabalho adicional.
Quanto tempo leva a instalação?
O trabalho manual no Protheus fica em torno de trinta minutos. O prazo real depende de conseguir a janela de manutenção, a credencial e a liberação de rede, que costumam levar mais tempo do que a instalação.
Posso criar o campo por SQL para ganhar tempo?
Não. A coluna fica fora do dicionário e a gravação automática não a trata corretamente. Use o Configurador ou o UPDDISTR e confirme que a coluna física foi criada.
O cliente não tem certificado válido, só autoassinado. Isso impede a integração?
Não impede, mas exige decisão explícita: ou a cadeia do certificado é instalada como confiável na máquina do Back, ou a impressão digital do certificado é fixada na configuração. Aceitar qualquer certificado deixa a conexão cifrada porém sem garantia de com quem se está falando.
Precisamos de licença TOTVS extra?
A integração consome conexão como qualquer outro usuário, e a licença é validada pelo CNPJ da filial. Em operação multi-filial, confirme a licença de cada filial que vai faturar pelo Vendelo.
O que acontece se o DBAccess cair?
A integração passa a acusar falha de conexão com o banco. Depois de subir o DBAccess, reinicie o serviço dedicado: as threads ficam com a conexão morta e não se recuperam sozinhas.
Próxima leitura
Segurança da integração: rede, HTTPS e controle de acesso: Garanta uma integração segura: HTTPS, regras de rede, credenciais com privilégio mínimo e critérios de aceite.
