winthor-api-wta

Cliente Node.js para integração com a API WTA do ERP Winthor

Biblioteca para conexão e consumo da API WTA do Winthor (TOTVS), facilitando operações como consulta de clientes, produtos, pedidos e outros recursos.

📦 Instalação

npm install winthor-api-wta
# ou
yarn add winthor-api-wta

🚀 Utilização

Configuração Inicial Configure suas credenciais (recomendado usar variáveis de ambiente ou arquivos de configuração como .env):

• lembrar de informar host + porta e também se é http ou https host completo.

const Wint = require('winthor-api-wta');

const config = {
  host: 'https://seu-servidor-winthor.com',
  login: 'usuario',
  senha: 'senha'
};

const wta = new Wint(config);

Exemplo com Promises (.then())

wta.conectar()
  .then(() => wta.cliente({ codigocliente: 22940 }))
  .then(cliente => console.log('Dados do cliente:', cliente))
  .catch(err => console.error('Erro:', err));

Exemplo com Async/Await (Recomendado)

async function buscarCliente(id) {
try {
  await wta.conectar();
  const cliente = await wta.cliente({ codigocliente: id });
  console.log(cliente);
  return cliente;
} catch (error) {
  console.error('Falha na requisição:', error);
  throw error;
}
}

buscarCliente(22);

📚 Métodos Disponíveis

conectar()

Descrição:
Autentica na API WTA.
Parâmetros:
Nenhum

cliente()

Descrição:
Retorna dados completos de um cliente, incluindo endereço de entrega quando solicitado.

Parâmetros:

{
  codigocliente: number    // Código do cliente (obrigatório)
  enderecoEntrega: boolean // Retorna endereço se true (opcional)
}

filiais()

Descrição:
Retorna dados da(s) Filial.

Parâmetros:

{
  codigofilial: number    // Código da filial (opcional)
}

estoque()

Descrição:
Retorna Estoque do produto e filial informados.

Parâmetros:

{
  codigofilial: number    // Código da filial (Obrigatório)
  codigoproduto: number    // Código da produto (Obrigatório)
}

preco()

Descrição:
Retorna Preço do produto na filial informados.

Parâmetros:

{
  codigofilial: number    // Código da filial (Obrigatório)
  codigoproduto: number    // Código da produto (Obrigatório)
  precoporembalagem: boolean  // Calcula o preço pelo fator de embalagem ou não (opcional)
}

buscaXml()

Descrição:
Retorna XML em formato String ou Base64.

Parâmetros:

{
  numeropedido: number    // Número Pedido de Venda (Obrigatório)
  numerotransacao: number    // Número Transação Venda (Obrigatório)
  retornabase64: boolean  // Retorna String *padrão ou Base64 se informado true (opcional)
}

**Só precisa informar o número do pedido ou número da transação de venda não precisa informar os dois!

cadastrarAtualizarCliente(params)

Descrição:
Cadastra ou atualiza um cliente. Se o CNPJ já existir, os dados serão atualizados.

Parâmetros críticos:
| Parâmetro | Tipo | Obrigatório? |
|-----------|------|--------------|
| CNPJ | string (18 chars) | ✅ Sim |
| CODIGOATIVIDADE | number | ✅ Sim |
| NOMECLIENTE | string (60 chars) | ✅ Sim |
| INSCRICAOESTADUAL | string (15 chars) | ✅ Sim (ou "ISENTO") |
| ENDERECOCOBRANCA | string (40 chars) | ✅ Sim |
| CEPCOBRANCA | string (9 chars) | ✅ Sim |
| BAIRROCOMERCIAL | string (40 chars) | ✅ Sim |
| CODIGOCIDADE | number | ✅ Sim |
| ENDERECOCOMERCIAL | string (40 chars) | ✅ Sim |
| CEPCOMERCIAL | string (9 chars) | ✅ Sim |
| CODIGOPAIS | number | ✅ Sim (default: 1058) |
| EMAIL | string (100 chars) | ✅ Sim |
| CODIGOPRACA | number | ✅ Sim |
| CODIGOVENDEDOR | number | ✅ Sim |

Exemplo:

await cadastrarAtualizarCliente({
  CNPJ: '12345678901234',
  CODIGOATIVIDADE: 1,
  NOMECLIENTE: 'Empresa Teste'
});

🔒 Boas Práticas

Nunca armazene credenciais no código: Use arquivos .env (com dotenv).

Exemplo com .env:

WTA_HOST=https://servidor-winthor.com
WTA_LOGIN=usuario
WTA_SENHA=senha

require('dotenv').config();
const config = {
  host: process.env.WTA_HOST,
  login: process.env.WTA_LOGIN,
  senha: process.env.WTA_SENHA
};

Opção 2: Usando config (ideal para ambientes múltiplos)

// config/default.json
{
  "wta": {
    "host": "https://servidor-winthor.com",
    "login": "usuario_api",
    "senha": "senha_ultra_secreta"
  }
}

// config/production.json (sobrescreve default.json em produção)
{
  "wta": {
    "host": "https://winthor-prod.totvs.com"
  }
}

// Uso no código
const config = require('config');

const wta = new Wint({
  host: config.get('wta.host'),
  login: config.get('wta.login'),
  senha: config.get('wta.senha')
});

⚠️ Importante:

Adicione .env e /config/*.json no seu .gitignore

Tratamento de Erros:

Sempre capture erros com try/catch ou .catch() para evitar falhas silenciosas.

📚 Recursos Úteis

• 🏢 Documentação Oficial API Integrações Winthor
• 🐙 Meu GitHub
• 🖥️ Portfólio

Obs.: Instale ou atualize os serviços no WTA (801)

• winthor-pedido-venda
• winthor-estoque-vtex
• winthor-compras-produto

📜 Licença

Este projeto não possui licença restritiva - sinta-se livre para:

• Usar em projetos comerciais
• Modificar e redistribuir
• Incorporar em outros sistemas

(Sugira novos métodos em Issues!)