SFTP para o integrador: conectar, enviar arquivos e ler o retorno

Para quem é

Este guia é para quem configura o envio automático de arquivos para a transportadora: a equipe de TI do embarcador, o fornecedor do ERP ou do WMS. A transportadora ativa a caixa SFTP no LogFrota e passa para você o usuário e a senha. Do seu lado, basta enviar os arquivos na pasta de entrada e ler o retorno na pasta de saída.

Dados de conexão

• Servidor: sftp.logfrota.com.br
• Porta: 8022
• Protocolo: SFTP (transferência de arquivos por SSH). Não é FTP nem FTPS: um programa configurado em FTP conecta, fica parado e cai sem erro claro.
• Usuário: edi- seguido do nome da base da transportadora (ex.: edi-minhatransportadora), exatamente como a transportadora informar.
• Senha: a que a transportadora gerou ao ativar a caixa.
• Chave do servidor: do tipo ECDSA. Na primeira conexão o programa pede para aceitar a impressão digital (fingerprint) do servidor: confira com a transportadora, que vê a mesma impressão na tela dela, e aceite.

Não é preciso liberar IP antes. Qualquer endereço conecta com o usuário e a senha certos. A lista de IPs que a transportadora vê na tela só serve para identificar de onde veio cada conexão.

No FileZilla

1. Abra Arquivo > Gerenciador de Sites > Novo site.
2. Em Protocolo, escolha SFTP - SSH File Transfer Protocol.
3. Preencha o host sftp.logfrota.com.br, a porta 8022, o tipo de logon Normal, o usuário e a senha.
4. Em Avançado > Diretório remoto padrão, informe a pasta de entrada da base (por exemplo /logfrota-edi/minhatransportadora/entrada/).
5. Conecte e aceite a chave do servidor depois de conferir a impressão digital.

A pasta /logfrota-edi é compartilhada e não abre: o programa mostra Acesso negado. Isso é normal e quer dizer que o login funcionou. No WinSCP o caminho é o mesmo: protocolo SFTP e, em Avançado > Diretórios, o diretório remoto.

No seu sistema

Trabalhe sempre com os caminhos completos da base, sem listar a raiz: envie para /logfrota-edi/<base>/entrada/ e busque o retorno em /logfrota-edi/<base>/saida/. O acesso é por usuário e senha: o comando sftp -b do OpenSSH não aceita senha, então use o WinSCP em modo script, o lftp ou uma biblioteca SFTP atual, que aceite senha e chave ECDSA.

As pastas

• entrada/: onde você coloca os arquivos. Pode usar subpastas, uma por carga ou por transferência (por exemplo entrada/2864679/): os arquivos de dentro delas também são lidos. A pasta é conferida a cada minuto e o arquivo sai dela depois de processado.
• saida/: onde volta o retorno. É só para leitura: não grave nem apague nada nela.

O que enviar e o que vira

• XML da NF-e (um .xml por nota, ou um .zip com até 50 notas de uma carga): vira CT-e da transportadora. Notas do mesmo destinatário viram um CT-e só.
• XML do CT-e do contratante (modelo 57), quando a transportadora foi subcontratada: vira CT-e de subcontratação. Quem emitiu o CT-e recebido passa a ser o tomador, e o CT-e recebido entra como documento anterior. Veja CT-e de subcontratação pelo SFTP.
• Relatório da transferência (.csv com as colunas transfer e chave_cte), junto dos XML dos CT-e do contratante: vira o manifesto da transferência, que mostra quais CT-e chegaram e quais faltam e fornece peso e valor para o frete. Veja Relatório de transferência.
• Planilha .csv no layout da DC-e (o modelo fica com a transportadora, em Integrações > SFTP): vira DC-e emitida, uma por id_documento.

Envie o arquivo original, sem editar. Os clientes da transportadora (o destinatário da nota, o emitente do CT-e do contratante) são reconhecidos pelo CNPJ que está dentro do arquivo e cadastrados automaticamente quando ainda não existem.

O que volta na saida/

• nome-do-arquivo.recebido.txt: recibo gravado assim que o arquivo chega, com o protocolo do envio, o tamanho, o SHA-256 e a hora (horário de Brasília). Arquivo sem recibo não chegou. Guarde o protocolo: é por ele que o suporte acha o envio.
• nome-do-arquivo.resultado.csv: uma linha por documento, com status, número, chave e mensagem e, no fim da linha, codigo, campo e etapa de cada erro, para o seu sistema decidir sozinho o que fazer.
• nome-do-arquivo-NUMERO.xml: o XML autorizado de cada documento.
• nome-do-arquivo.erro.txt: só quando algo deu errado ou ficou pendente, com o motivo e o que fazer.
• RASCUNHO-SEM-VALOR-FISCAL-PROTOCOLO.pdf e .xml: a prévia do CT-e que ficou em rascunho, só para conferência. Não importe como documento: veja CT-e em rascunho e a prévia sem valor fiscal.

Quando a transportadora termina pelo portal um documento que tinha ficado pendente, o XML autorizado chega depois na saida/, com um arquivo complemento. As colunas de cada arquivo estão em SFTP: emissão automática.

Frete

O arquivo não traz o frete da transportadora. Para emitir sozinho, cada cliente (contratante) precisa de uma tabela de frete vinculada na base da transportadora. Sem ela, o documento fica em rascunho, sem número, para a equipe da transportadora informar o frete: nada é emitido com frete zero. Isso se resolve do lado da transportadora; não é preciso reenviar o arquivo.

Avisos

Se a transportadora cadastrar o seu nome, WhatsApp e e-mail no quadro Integrador da caixa, você recebe os avisos de recebimento e de conclusão de cada arquivo e, sempre, o aviso quando um arquivo fica pendente ou dá erro. Veja Avisos para o integrador e para a transportadora.

Reenvio

Enviar de novo o mesmo arquivo, a mesma nota ou o mesmo CT-e do contratante não gera documento em dobro. O arquivo idêntico é ignorado como cópia, e a nota ou o CT-e que já está num documento volta no resultado como nota_ja_usada, com o número do documento existente (e o XML de novo na saida/, se já foi autorizado). Na DC-e, quem identifica a declaração é o id_documento: a mesma declaração volta como ja_emitida ou ja_recebida.

Erros

Comece pelo .erro.txt do arquivo. Os casos mais comuns, de conexão e de arquivo, estão em SFTP: erros comuns e o que fazer.

Homologação e produção

Enquanto a base da transportadora estiver em homologação, os documentos são autorizados no ambiente de testes da SEFAZ, sem valor fiscal: é o momento de validar a integração. A virada para produção é feita pelo administrador da base em Fiscal > Parâmetros Fiscais. Do seu lado nada muda: mesmo servidor, mesmo usuário, mesmas pastas.