WinThor
Conectar WinThor à operação da sua empresa. Confira os campos necessários, a obtenção das credenciais e o funcionamento na Zild.
Conectar WinThor à operação da sua empresa.
Onde configurar
Abra Zild Admin → Integrações → Conectores, localize o provedor e use Configurar ou Editar. Informe os dados deste guia, habilite o conector para o fluxo e salve.
Credenciais da sua empresa
O cliente deve obter e configurar suas próprias chaves de API ou a forma de autenticação exigida por este conector. A assinatura Zild é definida pelo tamanho da empresa; o consumo dos serviços externos é cobrado pelo respectivo provedor, separado da assinatura. Não é necessário configurar conectores que sua operação não utiliza.
Campos necessários
Os requisitos abaixo são os dados necessários ao fluxo que utiliza o conector. O cadastro genérico pode aceitar campos vazios que serão exigidos somente ao executar uma operação. O botão Salvar não confirma que a credencial funciona no provedor.
| Campo | Requisito para o fluxo |
|---|---|
Url | URL base HTTPS do serviço WinThor, sem acrescentar o caminho de login ou da operação. |
CustomProperties.Login | Login do usuário WinThor. |
ApiSecret | Senha original do usuário; não informe um hash. |
Como obter as credenciais
- Solicite ao administrador WinThor um usuário de integração, senha e URL HTTPS do serviço de autenticação e APIs.
- Preencha CustomProperties.Login e ApiSecret com login e senha originais. A Zild faz a conversão exigida pelo WTA; não cole um hash e não envie a senha a conversores externos.
- Em Url, informe a base do serviço, sem acrescentar winthor/autenticacao/v1/login. A Zild adiciona esse caminho ao autenticar; confirme o prefixo de publicação com o administrador.
- Confirme permissões para clientes, produtos, estoque e pedidos que o agente utilizará. O caminho de criação do usuário depende da instalação; consulte o administrador TOTVS.
Como funciona na Zild
A Zild obtém o token de sessão a partir do login; não precisa de uma chave de API copiada manualmente.
Como conferir a configuração
Depois de salvar, use o fluxo correspondente (consulta, agente, chamada ou processamento) para verificar o acesso. Se houver erro, confira credencial, permissões e recurso escolhido no provedor. Para tipos limitados ou legados, confirme a disponibilidade com a administração antes de tentar usar.
Na edição, a Zild mostra credenciais protegidas como asteriscos. Preserve o valor mascarado para manter a credencial atual ou cole uma nova credencial para substituí-la.
Documentação oficial
Confira o tipo e a conexão selecionada
Cadastre e selecione explicitamente o tipo WinThor. Preencher Login ou usar “WinThor” no nome não transforma uma conexão de outro tipo em uma conexão WinThor. A ferramenta requer uma conexão habilitada, do tipo correto e pertencente à mesma empresa.
Se um cadastro antigo não aparecer para seleção, confira tipo, empresa e estado com a administração antes de criar outro registro. Revise também as ferramentas que dependem dessa conexão; corrigir a configuração não implica executar novamente pedidos anteriores.
Configure as regras comerciais no conector
Além do login, confirme com o responsável pelo ERP os códigos de filial (BranchId), empresa (CompanyId), cobrança à vista (CashBillingId), plano de pagamento à vista (CashPaymentPlanId) e matrícula do emitente (EmployeeId), conforme as operações habilitadas. A ferramenta exige os campos obrigatórios da operação e utiliza a configuração do conector para esses valores, mesmo que o agente envie outro argumento.
Use códigos confirmados no ambiente. O código de cobrança aceita até quatro caracteres; os demais códigos configurados acima devem ser inteiros positivos, sem zeros à esquerda. A configuração não substitui as permissões nem a validação comercial do ERP.
Ao revisar uma ferramenta antiga, transfira os códigos fixos confirmados para a configuração do conector antes de salvar e testar. Valores legados na ferramenta ou enviados pelo agente não suprem uma configuração obrigatória ausente. Uma alteração no conector passa a valer para as ferramentas que o utilizam; confira todos os processos dependentes antes de mudar a filial ou as condições comerciais. Não duplique propriedades com nomes que diferem apenas em maiúsculas e minúsculas.
Praça do cliente e tabela de preços da venda
RegiaoId no cadastro do cliente representa a região da praça. Não comprova o vínculo da tabela de venda por cliente e filial da rotina 3314. Confirme regiaoPrecoId com a equipe comercial; não deduza o valor pela UF, pela praça ou por uma lista de regiões retornada pela API.
Quando o preço depende da região da rotina 201 e não há campanha de preço fixo válida retornada pelo ERP, a integração exige a tabela confirmada. Se retornar tabela_venda_nao_informada ou tabela_venda_nao_retornada, confira o cliente, a filial e a tabela antes de continuar. A ausência de preço na resposta não prova que a tabela inexiste no WinThor. Selecionar regiaoPrecoId não altera o vínculo cadastral no ERP.
No cadastro de cliente, a filial de referência (dados.branchParameterId) é preenchida pela configuração BranchId do conector. A praça (dados.squareId) continua sendo um dado obrigatório da ferramenta, confirmado para o cliente. A API não fornece um vínculo automático de praça por CEP. Confirme esse vínculo com o responsável pelo ERP; não use a praça de outro cliente como valor padrão. Se uma lista de opções falhar, digitar um código manualmente não valida que ele corresponde ao endereço.
Para diagnosticar uma tabela não retornada, registre clienteId, filialId, produtoId, regiaoPrecoSolicitadaId e regioesPrecoDisponiveis da resposta. A lista de regiões disponíveis ajuda a equipe do ERP a conferir a integração; não autoriza escolher outra tabela automaticamente. Se houver preço ausente ou ambíguo, resolva a divergência antes de apresentar um valor como confirmado.
Confira o resultado antes de repetir ou confirmar
Ao cadastrar um cliente, informe a praça confirmada para o endereço. Se registradoNoErp=true vier acompanhado de cadastro_divergente ou cadastro_registrado_conferencia_pendente, o registro já foi incluído: não repita a inclusão. Confira a praça e as regras de CEP no ERP antes de seguir para a venda.
Para criar o pedido, o fluxo exige aprovação, referência do orçamento e revisão comercial. As condições são consultadas novamente; condicoes_alteradas_confirmacao_necessaria indica que a revisão aprovada mudou e precisa de nova conferência. Em homologação, valide uma consulta de preço, um cadastro com conferência de praça e um orçamento antes de habilitar pedidos reais. Não invente preços, fatores de embalagem ou códigos ausentes.