← Documentação TNK

TNK System suporte@tnksystem.com.br
(51) 2700-8001

Especificação de integração

Integração do ecommerce com o ERP TNK

Como o site troca dados com o ERP: o que o ERP publica, o que o site precisa devolver e as regras que, se ignoradas, fazem o pedido entrar errado sem gerar erro. Documento voltado a quem desenvolve a loja.

Formato OfficeWeb 1.4 · acompanha os schemas expOfficeWeb.xsd, impOfficeWeb.xsd, typesOfficeWeb.xsd e a pasta Exemplos.

Esta é a versão sempre atual. Ela vive em docs.tnksystem.com.br/integrador-ftp e é atualizada quando o protocolo muda. O pacote .rar que você recebeu continua valendo para os schemas .xsd e a pasta Exemplos — mas, se o texto divergir, o que vale é esta página.

1Quem faz o quê

O ERP TNK roda na infraestrutura do lojista, atrás do firewall dele. Não há API HTTP nem acesso ao banco: a integração é troca de arquivos XML por FTP, e o ponto de encontro é um servidor FTP acessível pelos dois lados.

Quem faz o quê:

• Integrador TNK (programa nosso, na máquina do lojista): lê o banco do ERP, escreve as remessas na pasta de export e lê os pedidos da pasta de import.
• Site (seu código): lê as remessas da pasta de export e escreve os pedidos na pasta de import.

As duas pontas nunca se falam em tempo real. O integrador roda em ciclos (por padrão, exportação a cada 30 minutos e importação a cada 5), então trate a integração como assíncrona: um pedido gravado no FTP entra no ERP na próxima rodada, não no mesmo instante.

2Transporte: o FTP

FTP simples na porta 21, modo passivo. Duas pastas, cujos nomes são configuráveis por instalação, mas na prática são sempre estes:

Numeração dos arquivos

O NN é um sequencial inteiro por prefixo, sem zeros à esquerda (ExpProdutos_1.xml, ExpProdutos_2.xml, …). Cada prefixo tem a sua contagem própria e o integrador nunca sobrescreve um arquivo existente: ele olha o maior número já presente na pasta e continua dali.

Na direção contrária, o integrador cuida da limpeza sozinho: o que ele lê de /import é movido para /import/processados. Não conte com o arquivo continuar em /import, e não use essa pasta como seu histórico.

3Regras do arquivo XML

O formato é validado por XSD, e há quatro detalhes que reprovam o arquivo mesmo com o conteúdo correto:

1. UTF-8 sem BOM. O BOM (EF BB BF) no início quebra a leitura. Vários frameworks o inserem por conta própria — confira o primeiro byte do arquivo gerado.
2. Sem a declaração <?xml … ?>. O arquivo começa direto na tag raiz. É assim que o integrador oficial do ERP sempre gerou, e é o que está nos exemplos.
3. A ordem dos elementos é obrigatória. Os schemas usam xs:sequence, não xs:all: trocar dois campos de lugar invalida o arquivo, ainda que os nomes estejam todos certos. Siga a ordem dos Exemplos, não a ordem alfabética nem a da sua struct.
4. O atributo versao na raiz é obrigatório: <ImpOfficeWeb versao="1.4">.

Ainda sobre tipos, o que mais causa retrabalho:

• Decimais com ponto, nunca vírgula: 1234.56.
• Datas em xs:date (2026-09-08) e horas em xs:time (14:30:00). Do horário, o ERP guarda só hora e minuto.
• Booleanos como true / false, não 1 / 0, nem S / N.
• Documentos (CPF/CNPJ) só com dígitos, sem ponto, barra ou hífen.
• Campos de texto são truncados no tamanho da coluna do ERP, sem erro. Nomes longos chegam cortados.

4ERP → site

A lista de campos está no expOfficeWeb.xsd e não vale repetir aqui. O que o schema não conta:

• <Produto Id> é a chave. É o código do produto no ERP, e é esse número que você devolve em <Item><Produto>. Guarde-o; não tente casar produto por nome.
• A remessa é sempre completa, não um delta. Cada ExpProdutos traz todo o recorte configurado — trate como sincronização de estado, não como lista de mudanças.
• O recorte é escolha do lojista, no painel do integrador: normalmente só produtos marcados como disponíveis para ecommerce e só ativos. Produto que não aparece na remessa quase sempre é filtro, não defeito.
• O bloco <Ecommerce> traz o que o lojista preencheu para a loja: disponibilidade, lançamento, destaque, descrição do site e dimensões. Frete/NaoFrete não são enviados.
• <Grades> descreve as variações (tamanho, cor). O <Grade Id> publicado aqui é o mesmo id que você devolve no pedido — é por ele que o estoque da variação é baixado.
• Preço: <PrecoVenda> é o preço do cadastro, salvo se o lojista configurar uma tabela de preço padrão. <TabelasPreco> lista as demais tabelas, cada uma com o seu Id.

5Imagens do produto

As imagens vão dentro do XML, em base64, nos formatos jpg, bmp ou png (o formato vem no atributo formato). O base64 é quebrado em linhas de 76 colunas.

São dois lugares, com papéis distintos:

Os dois blocos são opcionais: produto sem foto simplesmente não os traz, e produto só com capa não traz o <Imagens>. Trate a ausência como normal.

<Descricao> dentro da imagem é o nome do arquivo como está no ERP. Serve para você reconhecer a mesma imagem entre duas remessas e não reprocessar base64 que já baixou.

6Site → ERP: pedidos

Um único arquivo, ImpOfficeWeb_NN.xml, com dois blocos opcionais na ordem <Clientes> e depois <Pedidos>. Pode levar vários pedidos.

<ImpOfficeWeb versao="1.4">
  <Clientes>
    <Cliente CPFCNPJ="02945423022">
      <Nome>Nome do comprador</Nome>
      <CPF>02945423022</CPF>
      <Fone>51996784439</Fone>
      <Email>comprador@exemplo.com.br</Email>
      <Endereco>
        <CodigoIBGE>4307708</CodigoIBGE>
        <CEP>93265-000</CEP>
        <Bairro>Centro</Bairro>
        <Endereco>Rua Rio Grande</Endereco>
        <Numero>724</Numero>
      </Endereco>
    </Cliente>
  </Clientes>
  <Pedidos>
    <Pedido Id="1042">
      <Data>2026-09-08</Data>
      <Hora>14:30:00</Hora>
      <ClienteDoc>02945423022</ClienteDoc>
      <Vendedor>0</Vendedor>
      <ValorTotal>149.80</ValorTotal>
      <Itens>
        <Item Sequencial="1">
          <Produto>1116</Produto>
          <Quantidade>2.0000</Quantidade>
          <ValorUnitario>74.9000</ValorUnitario>
          <ValorTotal>149.80</ValorTotal>
        </Item>
      </Itens>
      <Observacao>Pedido do site</Observacao>
      <NaoCalcularIPI>false</NaoCalcularIPI>
      <Mobile>false</Mobile>
      <Ecommerce>true</Ecommerce>
      <Bonificacao>false</Bonificacao>
    </Pedido>
  </Pedidos>
</ImpOfficeWeb>

Identificando o comprador

O pedido aponta para o cliente de uma de duas formas — o schema exige exatamente uma (é um xs:choice):

• <Cliente> — um inteiro. Use quando o comprador já existe no ERP: é o Id que veio no ExpClientes. Também serve para apontar para um <Cliente Id="…"> do bloco <Clientes> do próprio arquivo.
• <ClienteDoc> — o CPF ou CNPJ. É o caminho recomendado para comprador novo: mande o cadastro completo em <Clientes> com <Cliente CPFCNPJ="…"> e referencie o mesmo documento aqui.

O integrador procura o comprador no cadastro do ERP nesta ordem: CPF/CNPJ, id externo gravado em importação anterior, código do cliente, e-mail. Achou, reaproveita; não achou, cria a partir do bloco <Clientes>.

<CodigoIBGE> é o que amarra a cidade. O ERP resolve cidade e UF por esse código, não pelo nome nem pelo CEP. Sem ele — ou com um código que não existe na tabela do ERP — o cliente é criado sem cidade e sem UF, e alguém vai ter que completar à mão. Mande sempre os 7 dígitos do IBGE do município.

Campos do pedido que costumam faltar

Estes são obrigatórios pelo schema mesmo quando não fazem sentido para uma loja — mande com valor neutro em vez de omitir: <Observacao> (pode ir vazio), <NaoCalcularIPI>, <Mobile>, <Ecommerce>, <Bonificacao>. Marque <Ecommerce>true</Ecommerce>: é o que identifica o pedido como vindo da loja.

<Itens>: cada <Item> exige o atributo Sequencial (1, 2, 3…), o <Produto> (o Id do ExpProdutos), quantidade, valor unitário e valor total. Item de produto com variação leva <Grades>, com a quantidade de cada <Grade Id="…"> — e a soma das grades tem que fechar com a <Quantidade> do item.

<Status> é opcional e vai pela descrição, não por código (ex.: Cancelado). A lista válida é a tabela de status daquele ERP; descrição que não casa entra como Aberto. Pedido com status de cancelado não baixa estoque.

7Códigos que vêm do ERP

Quatro campos do pedido são códigos internos do ERP daquele lojista. Não existe numeração padrão entre instalações, e nada no protocolo os sincroniza: a lista é levantada na base do cliente e passada a você pelo suporte TNK.

8Reenvio e duplicidade

A identidade do pedido é o atributo Id do <Pedido> — o número dele no seu sistema. Use um id estável e nunca o reutilize para outro pedido.

Com base nele, o integrador decide sozinho:

• Id novo → importa o pedido e baixa o estoque.
• Id já importado, conteúdo idêntico → ignora, sem tocar no banco. Reenviar o mesmo arquivo é seguro.
• Id já importado, conteúdo diferente → atualiza só o cabeçalho (status, valores, frete). Itens e estoque não são refeitos, porque recriá-los dobraria a baixa.

9Por que um pedido é recusado

Quando algo não fecha, o pedido é recusado inteiro e sem gravar nada — nunca entra pela metade. Os outros pedidos do mesmo arquivo seguem normalmente, e o arquivo só sai de /import quando todos os pedidos dele tiverem sido resolvidos.

Ou seja, um pedido recusado deixa o arquivo parado em /import e a rodada seguinte tenta de novo — os pedidos que já entraram são pulados, sem risco de duplicar. Corrigido o cadastro no ERP (o produto que faltava, por exemplo), o pedido entra sozinho na próxima rodada, sem precisar reenviar o arquivo.

As causas, em ordem de frequência:

• Produto inexistente. O <Produto> não é um Id válido no ERP. Costuma ser código do site em vez do código do ERP.
• Grade inexistente. O <Grade Id> não corresponde a nenhuma variação daquele produto. Use os ids do ExpProdutos, não índices seus.
• Comprador não encontrado. O pedido referencia um cliente que não está no ERP e cujo cadastro não veio no bloco <Clientes> do arquivo — ou veio indexado de outra forma (o pedido usa <ClienteDoc> e o bloco traz só Id, ou o contrário). A mensagem de erro diz por qual chave a busca foi feita.
• XML inválido. Quase sempre BOM, declaração <?xml?> ou ordem de elementos — veja a seção 3.

Antes de acusar o integrador, peça ao lojista o log: logs\integrador-ftp.jsonl, na pasta do programa. Ele registra arquivo, pedido e motivo de cada recusa.

10Checklist antes do primeiro envio

Valide contra o XSD e confira estes pontos antes de gravar o primeiro ImpOfficeWeb em ambiente de produção:

• Arquivo em UTF-8 sem BOM e sem <?xml … ?>.
• Raiz com versao="1.4" e elementos na ordem do XSD.
• Decimais com ponto; datas AAAA-MM-DD; booleanos true/false.
• Upload com nome temporário e rename para .xml no final.
• <Produto> e <Grade Id> são os ids do ExpProdutos.
• Comprador novo com cadastro completo em <Clientes> e <CodigoIBGE> preenchido.
• <Pedido Id> estável e único; reenvio do mesmo id é idempotente.
• Códigos de forma de pagamento confirmados com o suporte TNK — ou a tag omitida.
• Sua rotina remove de /export o que já consumiu.