# Manual de uso - CIOT eFrete

Este manual orienta o uso da integracao CIOT/eFrete dentro da Operacao de Transporte.

## 1. Configuracao inicial

Antes de emitir CIOT, confirme a configuracao da filial:

1. Acesse o cadastro da filial.
2. Abra a configuracao de integrador CIOT/eFrete.
3. Informe:
   - Ambiente: homologacao ou producao.
   - Base URL da eFrete.
   - Integrador.
   - Usuario.
   - Senha.
   - Hash ou token, quando fornecido pela eFrete.
4. Salve a configuracao.

Observacao: o sistema ja possui o campo de Base URL. Para producao, utilize a URL oficial fornecida pela eFrete/NSTech para o seu contrato.

## 2. Cadastros obrigatorios

Antes da emissao, confira os dados abaixo.

### Motorista

No cadastro do motorista, preencha:

- Nome.
- CPF.
- RG, orgao emissor e data de emissao, quando exigidos.
- CNH, categoria, datas de emissao e vencimento.
- Data de nascimento.
- Cidade.
- Endereco: rua, numero, bairro e CEP.
- Dados bancarios ou PIX, conforme a forma de pagamento usada.

Se o numero do endereco estiver em branco, o sistema envia SN para a eFrete.

### Proprietario e veiculo

Confira:

- Proprietario do veiculo.
- CPF/CNPJ do proprietario.
- Placa.
- RNTRC, quando aplicavel.
- Tipo de propriedade do veiculo.

Para veiculo proprio, o sistema usa os dados da filial/contratante como referencia do proprietario.

### Contratante

Confira no cadastro da filial/empresa:

- CNPJ.
- Razao social.
- Endereco completo.
- Numero do endereco.
- Cidade e UF.

Se o numero estiver vazio, o sistema envia SN.

## 3. Conferencia da operacao

Na Operacao de Transporte, antes da emissao:

1. Abra a operacao.
2. Confira motorista, veiculo, proprietario e contratante.
3. Confira CT-es, notas fiscais e valores.
4. Confira o peso da carga.
5. Confira a aba Acerto.

O peso da operacao deve bater com a soma das quantidades das notas fiscais vinculadas para o mesmo NCM.

## 4. Pagamentos do CIOT

Os pagamentos enviados para a eFrete saem dos titulos financeiros vinculados na aba Acerto > Titulo Financeiro.

O sistema envia:

- Adiantamento: usa o titulo financeiro de adiantamento do motorista.
- Quitacao: usa o saldo/quitacao da operacao.

Cada pagamento recebe um identificador unico:

- Adiantamento: OP{operacao}-FIN{titulo}
- Quitacao: OP{operacao}-QUITACAO

Exemplo:

- OP115-FIN996
- OP115-QUITACAO

## 5. Forma de pagamento

A regra aplicada hoje e:

- Para emissao normal pela eFrete: TipoPagamento = eFRETE e EmissaoGratuita = false.
- Para pagamento PIX: o sistema envia a chave no formato esperado pela eFrete: Chave:valor.
- Para transferencia bancaria: o sistema envia os dados bancarios cadastrados do motorista.

Caso a eFrete informe que o cliente esta habilitado para outro tipo de pagamento, a regra pode ser ajustada na configuracao/rotina tecnica.

## 6. Emissao do CIOT

Para emitir:

1. Abra a Operacao de Transporte.
2. Acesse Acerto > CIOT.
3. Clique em Emitir CIOT.
4. Aguarde o retorno.

Quando a emissao for concluida, o sistema mostra mensagem de sucesso e grava:

- Status do CIOT.
- Codigo de identificacao.
- ID da operacao cliente.
- Documento da viagem.
- Ultimo evento retornado pela eFrete.

Depois de emitido, o sistema bloqueia nova emissao para evitar duplicidade.

## 7. Gerar JSON

Use o botao Gerar JSON apenas para conferencia tecnica do conteudo que sera enviado para a eFrete.

Esse botao nao emite CIOT.

## 8. Consultar retorno

Use Consultar Retorno para verificar o ultimo retorno salvo da eFrete.

Essa consulta ajuda a validar mensagens de erro, protocolo e dados retornados.

## 9. Operacao ja cadastrada na eFrete

Se a eFrete retornar que a operacao ja esta cadastrada, o sistema tenta recuperar automaticamente o codigo de identificacao usando o ID da operacao cliente.

Quando a recuperacao funcionar, o CIOT fica marcado como emitido no sistema.

## 10. Liberacao de parcelas eFrete

Na aba Acerto > Titulo Financeiro, use o botao Liberar eFrete no titulo financeiro desejado.

Essa acao altera a data de liberacao do pagamento na eFrete.

Use somente para parcelas vinculadas ao CIOT emitido.

## 11. Cancelamento do CIOT

Para cancelar:

1. Abra Acerto > CIOT.
2. Clique em Cancelar CIOT.
3. Confirme a acao na mensagem exibida pelo sistema.

O cancelamento e enviado para a eFrete.

Quando o CIOT estiver encerrado, o cancelamento fica bloqueado.

## 12. Encerramento do CIOT

Para encerrar:

1. Abra Acerto > CIOT.
2. Clique em Encerrar CIOT.
3. Confirme a acao na mensagem exibida pelo sistema.

Depois de encerrado:

- Nao e permitido cancelar.
- Nao e permitido liberar parcelas pela tela.
- O status fica como Encerrado.

## 13. PDF do CIOT

Use PDF CIOT para obter o documento da operacao de transporte emitida.

O botao depende de codigo de identificacao valido retornado pela eFrete.

## 14. Erros comuns

### Endereco sem rua ou numero

Confira o cadastro do motorista, contratante e proprietario.

Quando o numero estiver vazio, o sistema envia SN.

### Pagamento sem dados bancarios ou PIX

Confira a aba Dados Bancarios do motorista.

Para PIX, informe a chave PIX.

Para transferencia bancaria, informe banco, agencia, conta e dados do titular.

### IdCliente.Existente

Significa que a operacao ja existe na eFrete.

O sistema tenta recuperar o codigo automaticamente. Se nao recuperar, confira o ID da operacao cliente e tente Consultar Retorno.

### Peso difere das notas fiscais

Confira o peso da operacao e as quantidades das notas fiscais vinculadas.

### Cliente nao habilitado para tipo de pagamento

Confirme com a eFrete quais tipos de pagamento estao habilitados para o contrato.

## 15. Ambiente de producao

Antes de virar producao:

1. Solicite para a eFrete/NSTech a Base URL oficial de producao.
2. Solicite usuario, senha, integrador e hash/token de producao.
3. Configure esses dados no cadastro da filial.
4. Altere o ambiente para producao.
5. Emita uma operacao de teste controlada.
6. Confira CIOT, pagamentos, PDF, cancelamento ou encerramento conforme o procedimento combinado.

O sistema esta preparado para trocar a Base URL por configuracao, sem alteracao de codigo.
