Criação do lote
Método e rota
- Criação (POST):
/frete/lote/operacaoTransporte/{enterpriseID}
O payload é composto por um array de operações, contido na raiz loteOT. Cada item do array representa uma Operação de Transporte (OT) a ser processada.
observação
O payload permite o envio de múltiplas operações (de 1 a N) num único lote.
Corpo
Exemplo payload envolvendo pagamento de parcela
{
"loteOT": [
{
"ide": {
"cnpj": "52818076000122",
"numero": "123456789",
"serie": "1",
"ptEmissor": "Ponto Emissor X",
"dtInicio": "2025-01-01",
"dtFim": "2025-01-15",
"contrato": "CT-12345",
"TipoViagem": 1,
"gerPgtoFin": 1
},
"carga": {
"codigoSH": "1234",
"quantidade": 100.5,
"remetente": {
"cpfCnpj": "12345678901234",
"nome": "Remetente Exemplo",
"endereco": {
"UF": "SP",
"codigoMunicipio": "3550308",
"bairro": "Centro",
"logradouro": "Rua das Flores",
"numero": "100",
"CEP": "01001000",
"complemento": "Sala 101"
}
},
"destinatario": {
"cpfCnpj": "43210987654321",
"nome": "Destinatário Exemplo",
"endereco": {
"UF": "RJ",
"codigoMunicipio": "3304557",
"bairro": "Bairro Novo",
"logradouro": "Avenida Principal",
"numero": "500",
"CEP": "20020000",
"complemento": "Bloco A"
}
},
"documentosOriginarios": [
{
"tipo": "NF-e",
"numero": "12345"
},
{
"tipo": "CT-e",
"numero": "67890"
}
]
},
"transp": {
"rntrc": "123456789",
"cpfCnpj": "12345678901234",
"cadastro": {
"nomeRazao": "Exemplo Transporte LTDA",
"telefone": "99111112222",
"email": "teste@teste.com.br",
"tipo": 2,
"IE": "12345678901234",
"atividadePrincipal": "1",
"formaConstituicao": "101-5",
"dataConstituicao": "1985-06-15",
"endereco": {
"logradouro": "Rua da Logística",
"numero": "123",
"complemento": "Bloco A",
"bairro": "Centro",
"cidade": "São Paulo",
"UF": "SP",
"CEP": "01001000"
},
"dadosPF": {
"identidade": "MG-1234567",
"nomeMae": "Fulano da Silva",
"nomePai": "Fulano da Silva",
"dataNascimento": "1985-06-15"
},
"dadosPJ": [
{
"cpf": "12345678901",
"identidade": "SP-9876543",
"nomeCompleto": "Sócio Exemplo ETC",
"nomeMae": "Fulano da Silva",
"nomePai": "Fulano da Silva",
"dataNascimento": "1970-02-10",
"telefone": "99111112222",
"email": "teste@teste.com.br",
"endereco": {
"logradouro": "Rua da Logística",
"numero": "123",
"complemento": "Bloco A",
"bairro": "Centro",
"cidade": "São Paulo",
"UF": "SP",
"CEP": "01001000"
}
}
]
}
},
"condutores": [
{
"cpf": "12345678901",
"nomeCompleto": "Fulano de Tal",
"nomeMae": "Maria de Tal",
"nomePai": "João de Tal",
"dataNascimento": "1985-06-15",
"identidade": "MG1234567",
"CNH": "1234567890",
"dataEmissaoCNH": "2020-01-10",
"dataRenovacaoCNH": "2025-01-10",
"telefone": "11999999999",
"RNTRCTransportador": "123456789",
"cpfCnpjTransportador": "12345678901234",
"endereco": {
"UF": "SP",
"cidade": "São Paulo",
"bairro": "Centro",
"logradouro": "Rua das Flores",
"numero": "123",
"CEP": "01001000",
"complemento": "Bloco A, Apto 101"
}
}
],
"veiculos": [
{
"placa": "ABC1234",
"RNTRCTransportador": "123456789",
"cadastro": {
"modelo": "Modelo XPTO",
"kmLitroModelo": 3.5,
"tipo": 1,
"kmLitroVeiculo": 4.7000000000000002
}
},
{
"placa": "ABC9536",
"RNTRCTransportador": "123456789",
"cadastro": {
"modelo": "Modelo XPTO",
"kmLitroModelo": 3.5,
"tipo": 2,
"kmLitroVeiculo": 4.7000000000000002
}
}
],
"valores": {
"vlrFrete": 1500.0,
"despesas": {
"vlrDespesas": 200.5,
"descricao": "Despesa de alimentação"
},
"parcelamento": {
"informacoes": {
"parcelas": [
{
"nome": "Adiantamento",
"tipoPgto": 1,
"finalidadeParcela": 1,
"dataPrevisao": "2025-01-05",
"valorAplicado": 500.0,
"valorReal": 480.0,
"descontos": [
{
"nmDesc": "Taxa",
"vlrDesc": 20.0,
"dsDesc": "Taxa administrativa"
}
],
"transferenciaAutomatica": {
"cpfCondutor": "12345678901"
}
},
{
"nome": "Saldo",
"tipoPgto": 2,
"finalidadeParcela": 2,
"dataPrevisao": "2025-01-10 15:00:00",
"valorAplicado": 1000.0
}
]
}
},
"retencoes": {
"irrf": 10.0,
"inss": 20.0,
"sestsenat": 15.0
},
"tipoRateio": 3,
"descontos": [
{
"nmDesc": "Seguro",
"vlrDesc": 30.0
}
],
"vlrCombustivel": 300.0,
"vlrPedagio": 75.0,
"tarifas": {
"quantidadeTotal": 2,
"valorTotal": 50.0
},
"dadosBancarios": {
"tipoPagamento": 1,
"codigoInstituicaoFinanceira": "999",
"numeroAgencia": "999999",
"digitoConta": "0",
"chavepix": "1234567891234567AAAdasd345",
"cpfCnpjFavorecido": "12345678901234",
"tipoChave": 4
}
},
"adicionais": [
{
"nome": "Observacao1",
"valor": "Entrega urgente"
},
{
"nome": "Observacao2",
"valor": "Veículo refrigerado"
}
]
}
]
}
Exemplo payload somente emissão de CIOT
{
"loteOT": [
{
"ide": {
"cnpj": "52818076000122",
"numero": "123456789",
"serie": "1",
"ptEmissor": "Ponto Emissor X",
"dtInicio": "2025-01-01",
"dtFim": "2025-01-15",
"contrato": "CT-12345",
"TipoViagem": 1,
"gerPgtoFin": 1
},
"carga": {
"codigoSH": "1234",
"quantidade": 100.5,
"remetente": {
"cpfCnpj": "12345678901234",
"nome": "Remetente Exemplo",
"endereco": {
"UF": "SP",
"codigoMunicipio": "3550308",
"bairro": "Centro",
"logradouro": "Rua das Flores",
"numero": "100",
"CEP": "01001000",
"complemento": "Sala 101"
}
},
"destinatario": {
"cpfCnpj": "43210987654321",
"nome": "Destinatário Exemplo",
"endereco": {
"UF": "RJ",
"codigoMunicipio": "3304557",
"bairro": "Bairro Novo",
"logradouro": "Avenida Principal",
"numero": "500",
"CEP": "20020000",
"complemento": "Bloco A"
}
},
"documentosOriginarios": [
{
"tipo": "NF-e",
"numero": "12345"
},
{
"tipo": "CT-e",
"numero": "67890"
}
]
},
"transp": {
"rntrc": "123456789",
"cpfCnpj": "12345678901234",
"cadastro": {
"nomeRazao": "Exemplo Transporte LTDA",
"telefone": "99111112222",
"email": "teste@teste.com.br",
"tipo": 2,
"IE": "12345678901234",
"atividadePrincipal": "1",
"formaConstituicao": "101-5",
"dataConstituicao": "1985-06-15",
"endereco": {
"logradouro": "Rua da Logística",
"numero": "123",
"complemento": "Bloco A",
"bairro": "Centro",
"cidade": "São Paulo",
"UF": "SP",
"CEP": "01001000"
},
"dadosPF": {
"identidade": "MG-1234567",
"nomeMae": "Fulano da Silva",
"nomePai": "Fulano da Silva",
"dataNascimento": "1985-06-15"
},
"dadosPJ": [
{
"cpf": "12345678901",
"identidade": "SP-9876543",
"nomeCompleto": "Sócio Exemplo ETC",
"nomeMae": "Fulano da Silva",
"nomePai": "Fulano da Silva",
"dataNascimento": "1970-02-10",
"telefone": "99111112222",
"email": "teste@teste.com.br",
"endereco": {
"logradouro": "Rua da Logística",
"numero": "123",
"complemento": "Bloco A",
"bairro": "Centro",
"cidade": "São Paulo",
"UF": "SP",
"CEP": "01001000"
}
}
]
}
},
"condutores": [
{
"cpf": "12345678901",
"nomeCompleto": "Fulano de Tal",
"nomeMae": "Maria de Tal",
"nomePai": "João de Tal",
"dataNascimento": "1985-06-15",
"identidade": "MG1234567",
"CNH": "1234567890",
"dataEmissaoCNH": "2020-01-10",
"dataRenovacaoCNH": "2025-01-10",
"telefone": "11999999999",
"RNTRCTransportador": "123456789",
"cpfCnpjTransportador": "12345678901234",
"endereco": {
"UF": "SP",
"cidade": "São Paulo",
"bairro": "Centro",
"logradouro": "Rua das Flores",
"numero": "123",
"CEP": "01001000",
"complemento": "Bloco A, Apto 101"
}
}
],
"veiculos": [
{
"placa": "ABC1234",
"RNTRCTransportador": "123456789",
"cadastro": {
"modelo": "Modelo XPTO",
"kmLitroModelo": 3.5,
"tipo": 1,
"kmLitroVeiculo": 4.7000000000000002
}
},
{
"placa": "ABC9536",
"RNTRCTransportador": "123456789",
"cadastro": {
"modelo": "Modelo XPTO",
"kmLitroModelo": 3.5,
"tipo": 2,
"kmLitroVeiculo": 4.7000000000000002
}
}
],
"valores": {
"vlrFrete": 1500.0,
"vlrPedagio": 75.0
},
"adicionais": [
{
"nome": "Observacao1",
"valor": "Entrega urgente"
},
{
"nome": "Observacao2",
"valor": "Veículo refrigerado"
}
]
}
]
}
Layout
| Nome do Campo | Tipo | Obrigatório? | Observação |
|---|---|---|---|
| loteOT | Object | Sim (1–1) | Raiz do payload de lote de Operação de Transporte. |
| ide | Object | Sim (1) | Informações sobre a Operação de Transporte. |
| cnpj (em ide) | String (14) | Sim (1) | CNPJ da Contratante (14 dígitos). |
| numero (em ide) | String (1–9) | Sim (1) | Número da Operação de Transporte (pode ser interpretado como number). |
| serie (em ide) | String (1–4) | Sim (1) | Série da Operação de Transporte. |
| ptEmissor (em ide) | String (1–30) | Sim (1) | Nome do ponto emissor (configurado no portal nddCargo). |
| dtInicio (em ide) | String | Não (0–1) | Data de início (AAAA-MM-DD). Obrigatório para OT padrão e não deve ser informado para TAC-Agregado. |
| dtFim (em ide) | String | Não (0–1) | Data final (AAAA-MM-DD). Se não informado, +30 dias após dtInicio. |
| contrato (em ide) | String (1–50) | Não (0–1) | Identificação do contrato entre Contratante e Transportador. |
| TipoViagem (em ide) | number | Sim (1) | 1 = TAC/ETC, 2 = TAC Agregado. |
| gerPgtoFin (atributo de ide) | number | Não (0–1) | Indica movimentação financeira: 1=Cartão NDD, 2=Sem Pagto nddCargo, 6=PIX/TED. |
| carga | Object | Sim (1) | Informações sobre o tipo de viagem. |
| codigoSH (em padrao) | number | Sim (1) | Código do Sistema Harmonizado (4 dígitos). |
| quantidade (em padrao) | decimal | Sim (1) | Quantidade em Kg (1–7, 2 decimais). |
| remetente | Object | Sim (1) | Dados do remetente da OT padrão. |
| cpfCnpj (em remetente) | String (14) | Sim (1) | CPF ou CNPJ do remetente. |
| nome (em remetente) | String (1–255) | Sim (1) | Nome/Razão Social do remetente. |
| endereco (em remetente) | Object | Sim (1) | Endereço do remetente. |
| UF (endereco – remetente) | String (2) | Sim (1) | Sigla da UF. |
| codigoMunicipio (endereco – remetente) | String (7) | Sim (1) | Código do município. |
| bairro (endereco – remetente) | String (1–255) | Sim (1) | Bairro. |
| logradouro (endereco – remetente) | String (1–255) | Sim (1) | Logradouro. |
| numero (endereco – remetente) | String (1–60) | Sim (1) | Número do endereço. |
| CEP (endereco – remetente) | String (8) | Sim (1) | CEP. |
| complemento (endereco – remetente) | String (1–255) | Não (0–1) | Complemento do endereço. |
| destinatario | Object | Sim (1) | Dados do destinatário da OT padrão. |
| cpfCnpj (em destinatario) | String (14) | Sim (1) | CPF ou CNPJ do destinatário. |
| nome (em destinatario) | String (1–255) | Sim (1) | Nome/Razão social do destinatário. |
| endereco (em destinatario) | Object | Sim (1) | Endereço do destinatário. |
| UF (endereco – destinatario) | String (2) | Sim (1) | Sigla da UF. |
| codigoMunicipio (endereco – destinatario) | String (7) | Sim (1) | Código do município. |
| bairro (endereco – destinatario) | String (255) | Sim (1) | Bairro. |
| logradouro (endereco – destinatario) | String (255) | Sim (1) | Logradouro. |
| numero (endereco – destinatario) | String (1–60) | Sim (1) | Número do endereço. |
| CEP (endereco – destinatario) | String (8) | Sim (1) | CEP. |
| complemento (endereco – destinatario) | String (255) | Não (0–1) | Complemento. |
Observação: Todos os campos devem ser validados quanto à sua presença e formato (datas, números, strings, etc.).
Validações e regras de negócio
Formato e obrigatoriedade:
Todos os campos obrigatórios devem ser validados quanto à sua presença e conformidade com os padrões estabelecidos (por exemplo, datas, CPF/CNPJ, CEP, RNTRC, etc.).
Cadastro integrado:
As seções internas de cadastro em transp, condutores e veiculos possibilitam o registro ou atualização dos respectivos cadastros automaticamente, integrando os dados transacionais aos cadastros de base.
Consistência dos dados:
- Verificar a integridade dos vínculos entre os dados operacionais e os cadastros (por exemplo, RNTRC, CPF/CNPJ).
- As informações financeiras (vlrFrete, parcelamento, descontos, tarifas, etc.) devem ser consistentes, sem valores negativos ou incoerentes.
Processamento assíncrono:
Ao receber o lote, a API processará as operações de maneira assíncrona. Um GUID será gerado para identificar o processamento do lote e poderá ser usado posteriormente para consultar os resultados.
Resposta do POST
Após o envio do lote, a resposta será imediata e informará se o lote foi aceito para processamento, retornando um GUID para acompanhamento.
Exemplo de resposta de sucesso:
{
"sucesso": true,
"guid": "xxxxxxxxxxxxxxx",
"codigo": "000",
"mensagem": "Lote recebido para processamento."
}
Observação:
sucesso: indica se o lote foi aceito para processamento (true) ou rejeitado (false).
guid: identificador único do lote, utilizado para acompanhar o processamento.
codigo: código de retorno da operação.
mensagem: descrição do resultado da requisição ou mensagens informativas.
Exemplo de resposta de erro:
{
"sucesso": false,
"guid": "",
"codigo": "400",
"mensagem": "Erro na validação dos parâmetros do lote."
}
Observação:
Quando sucesso for false, o lote não foi aceito para processamento.
O campo guid pode não ser retornado em caso de erro na validação inicial.
codigo e mensagem descrevem o motivo do erro ocorrido.
Próximos passos
Acesse a consulta do processamento do lote ou veja como cancelar uma operação de transporte.