Alterar parcelas de operação de transporte
Registre alterações nas parcelas de uma Operação de Transporte (OT) de forma integrada e em lote. Esse endpoint possibilita:
- Inclusão de novas parcelas (manual, automático ou imediato);
- Ajuste de datas de pagamento;
- Ajuste de valores (adicionais, descontos, retencoes e valor de validação);
- Atualização de dados bancários e configurações de transferência automática.
O processamento é assíncrono, retornando um GUID que pode ser utilizado para acompanhar os resultados.
Método e rota
- Solicitação (POST):
/frete/lote/alterarParcela/{enterpriseID} - Consulta (GET):
/frete/lote/alterarParcela/{enterpriseID}/{guid}{guid}é o identificador único retornado pelo POST, que permite acompanhar o processamento do lote.
Estrutura da requisição
Cabeçalhos
-
O token JWT deve ser enviado no header, por exemplo:
Authorization: Bearer {token}
Corpo
POST – Alterar Parcelas de OT
Consulte aqui as referências do POST
Layout
| Nome do Campo | Tipo | Obrigatório? | Observação |
|---|---|---|---|
| alterarParcelas | Object | Sim (1) | Raiz do POST “Alterar Parcelas OT”. |
| └─ OT | Array | Sim (1–N) | Cada item representa uma OT a ter parcelas alteradas. |
| └─ └─ infOT | Object | Sim (1) | Informações de identificação da operação e do que será alterado. |
| └─ └─ └─ cnpj | String(14) | Sim (1) | CNPJ da Contratante (14 dígitos). |
| └─ └─ └─ ciot | Object | Sim (1) | Informações sobre a Operação de Transporte (código e verificador). |
| └─ └─ └─ └─ numero | String(12) | Sim (1) | Código Identificador da OT (até 12). |
| └─ └─ └─ └─ ciotCodVerificador | String(4) | Sim (1) | Protocolo de autorização ANTT (4 chars). Usar “XXXX” se contingência. |
| └─ └─ └─ motivo | String(1–1000) | Sim (1) | Motivo textual da alteração (até 1000 caracteres). |
| └─ └─ alteracoes | Object | Sim (1) | Grupo de alterações financeiras da OT. |
| └─ └─ └─ alteracao | Array | Sim (1–N) | Cada item descreve um bloco de alterações. |
| └─ └─ └─ └─ financeiro | Object | Sim (1) | Dados para alteração financeira (novaParc, ajustaParc). |
| └─ └─ └─ └─ └─ novaParc | Object | Não (ou ajustaParc) | Dados para adição de nova parcela. |
| └─ └─ └─ └─ └─ └─ nome | String(50) | Sim (1) | Nome da parcela para apresentação. |
| └─ └─ └─ └─ └─ └─ tipoPgto | Object | Sim (1) | Identifica o tipo de pagamento (manual, automático, imediato). |
| └─ └─ └─ └─ └─ └─ └─ manual | Object | Não (1) | Se usar manual, não usar automático ou imediato. |
| └─ └─ └─ └─ └─ └─ └─ └─ dataPrevisao | Date | Sim (1) | AAAA-MM-DD. |
| └─ └─ └─ └─ └─ └─ └─ automatico | Object | Não (1) | Se usar, não usar manual/imediato. |
| └─ └─ └─ └─ └─ └─ └─ └─ dataHora | Date | Sim (1) | AAAA-MM-DD HH:MM:SS. |
| └─ └─ └─ └─ └─ └─ └─ imediato | number | Não (1) | Informar "2" se imediato. |
Nova parcela – Pagamento manual
{
"alterarParcelas": {
"OT": [
{
"infOT": {
"cnpj": "12345678901234",
"ciot": {
"numero": 123456789012,
"ciotCodVerificador": "ABCD"
},
"motivo": "Inclusão de nova parcela manual",
"alteracoes": {
"alteracao": [
{
"financeiro": {
"novaParc": {
"nome": "Adiantamento Manual",
"tipoPgto": {
"manual": {
"dataPrevisao": "2025-02-10"
}
},
"valorAplicado": 500.0,
"valorReal": 450.0,
"descontos": {
"desconto": [
{
"nmDesc": "Taxa",
"vlrDesc": "30.00",
"dsDesc": "Taxa administrativa"
}
]
},
"retencoes": {
"irrf": 0.0,
"inss": 0.0,
"sestsenat": 0.0,
"rubrica": 1
},
"transferenciaAutomatica": {
"cpfCondutor": "12345678901",
"finalidadeParcela": 1
}
}
}
}
]
}
}
}
]
}
}
Nova parcela – Pagamento automático
{
"alterarParcelas": {
"OT": [
{
"infOT": {
"cnpj": "12345678901234",
"ciot": {
"numero": 123456789012,
"ciotCodVerificador": "ABCD"
},
"motivo": "Inclusão de nova parcela automática",
"alteracoes": {
"alteracao": [
{
"financeiro": {
"novaParc": {
"nome": "Adiantamento Automático",
"tipoPgto": {
"automatico": {
"dataHora": "2025-02-10 12:00:00"
}
},
"valorAplicado": 500.0,
"valorReal": 450.0,
"descontos": {
"desconto": [
{
"nmDesc": "Taxa",
"vlrDesc": "30.00",
"dsDesc": "Taxa administrativa"
}
]
},
"retencoes": {
"irrf": 0.0,
"inss": 0.0,
"sestsenat": 0.0,
"rubrica": 1
},
"transferenciaAutomatica": {
"cpfCondutor": "12345678901",
"finalidadeParcela": 1
}
}
}
}
]
}
}
}
]
}
}
Nova parcela – Pagamento imediato
{
"alterarParcelas": {
"OT": [
{
"infOT": {
"cnpj": "12345678901234",
"ciot": {
"numero": 123456789012,
"ciotCodVerificador": "ABCD"
},
"motivo": "Inclusão de nova parcela imediata",
"alteracoes": {
"alteracao": [
{
"financeiro": {
"novaParc": {
"nome": "Adiantamento Imediato",
"tipoPgto": {
"imediato": 2
},
"valorAplicado": 500.0,
"valorReal": 450.0,
"descontos": {
"desconto": [
{
"nmDesc": "Taxa",
"vlrDesc": "30.00",
"dsDesc": "Taxa administrativa"
}
]
},
"retencoes": {
"irrf": 0.0,
"inss": 0.0,
"sestsenat": 0.0,
"rubrica": 1
},
"transferenciaAutomatica": {
"cpfCondutor": "12345678901",
"finalidadeParcela": 1
}
}
}
}
]
}
}
}
]
}
}
Ajuste da data de pagamento da parcela
{
"alterarParcelas": {
"OT": [
{
"infOT": {
"cnpj": "12345678901234",
"ciot": {
"numero": 123456789012,
"ciotCodVerificador": "ABCD"
},
"motivo": "Ajuste na data de pagamento da parcela",
"alteracoes": {
"alteracao": [
{
"financeiro": {
"ajustaParc": {
"altData": {
"data": "2025-02-10 12:00:00"
}
}
}
}
]
}
}
}
]
}
}
Ajuste de valores em parcela
{
"alterarParcelas": {
"OT": [
{
"infOT": {
"cnpj": "12345678901234",
"ciot": {
"numero": 123456789012,
"ciotCodVerificador": "ABCD"
},
"motivo": "Ajuste de valores na parcela",
"alteracoes": {
"alteracao": [
{
"financeiro": {
"ajustaParc": {
"nome": "Parcela Ajustada - AltValores",
"altValores": {
"adicional": {
"valor": 100.0,
"rubrica": 1
},
"desconto": {
"nmDesc": "Desconto Ajuste",
"vlrDesc": "20.00",
"dsDesc": "Desconto revisado"
},
"retencoes": {
"irrf": 5.0,
"inss": 10.0,
"sestsenat": 3.0,
"rubrica": 1
},
"valorValidacao": 1500.0
}
}
}
}
]
}
}
}
]
}
}
Ajuste de dados bancários em parcela
{
"alterarParcelas": {
"OT": [
{
"infOT": {
"cnpj": "12345678901234",
"ciot": {
"numero": 123456789012,
"ciotCodVerificador": "ABCD"
},
"motivo": "Ajuste de dados bancários na parcela",
"alteracoes": {
"alteracao": [
{
"financeiro": {
"ajustaParc": {
"nome": "Parcela Ajustada - Dados Bancários",
"dadosBancarios": {
"codigoInstituicaoFinanceira": "001",
"numeroAgencia": "1234-5",
"numeroConta": "67890-1",
"digitoConta": 1,
"chavePix": "email@example.com",
"tipoChave": 1
}
}
}
}
]
}
}
}
]
}
}
Ajuste de transferência automática em parcela
{
"alterarParcelas": {
"OT": [
{
"infOT": {
"cnpj": "12345678901234",
"ciot": {
"numero": 123456789012,
"ciotCodVerificador": "ABCD"
},
"motivo": "Ajuste de transferência automática na parcela",
"alteracoes": {
"alteracao": [
{
"financeiro": {
"ajustaParc": {
"nome": "Parcela Ajustada - Transferência Automática",
"transferenciaAutomatica": {
"novaConfiguracao": {
"cpfCondutor": "12345678901",
"finalidadeParcela": 1
}
}
}
}
}
]
}
}
}
]
}
}
Resposta do POST
Exemplo de resposta de sucesso:
{
"sucesso": true,
"guid": "xxxxxxxxxxxxxxx",
"codigo": "000",
"mensagem": "Lote recebido para processamento."
}
GET – Consulta do pedido de alteração de parcela
Consulte aqui as referências do GET
Resposta do GET
Exemplo de resposta:
{
"retornoLoteAlteracaoParcela": [
{
"cnpj": "12345678901234",
"numero": 123456789012,
"ciotCodVerificador": "ABCD",
"nomeParcela": "Saldo",
"sucesso": true,
"erros": []
},
{
"cnpj": "12345678901234",
"numero": 123456789013,
"ciotCodVerificador": "ABCD",
"nomeParcela": "Saldo",
"sucesso": false,
"erros": [
{
"codigo": 400,
"mensagem": "mensagem de erro ocorrido na alteração"
}
]
}
]
}
Códigos de Status HTTP
- 200 ou 201:
- Para o POST: indica que o lote de alterações foi recebido com sucesso e iniciado o processamento assíncrono.
- Para o GET: indica que a consulta do processamento do lote foi realizada com sucesso.
- 400: erro de validação, seja no payload do POST ou no GUID fornecido no GET.
- 401: não autorizado (token JWT ausente ou inválido).
- 500: erro interno do servidor.
Consulte aqui todas as mensagens e códigos de retorno
Próximos passos
Veja como consultar o status de uma parcela