Liberar la cuota N de todos los CT-e de un MDF-e

Parámetros, estructura de datos y respuestas del contrato versionado.

POST/carriers/parcelas-repasse/liberar-por-mdfe

liberarParcelasPorMdfeBase de Pruebas: https://api.fleetpay.site/v1

Las descripciones técnicas se traducen del contrato versionado. Se conservan los identificadores y el JSON originales; se omiten los ejemplos de datos.

Liberación en lote por manifiesto: indique el MDF-e (UUID, clave de acceso o número) y la posición de la cuota. FleetPay aplica liberar a cada CT-e vinculado al viaje, incluidos los contra-CT-e de un lote de subcontratación, y devuelve un resultado por CT-e. El rechazo de una fila no impide procesar las demás.

Tres reglas que conviene conocer antes de llamar:

Solo cuotas existentes. La cuota se crea al escanear el documento; el MDF-e no se considera un evento de recogida. Un CT-e del manifiesto que aún no tenga una cuota en la posición indicada devuelve recusada / parcela_inexistente en su fila.
Solo el conductor del MDF-e. Una cuota de otro conductor devuelve ignorado / motorista_divergente.
Las mismas reglas que la liberación individual (evento_fora_de_ordem, parcela_cancelada...), con la misma idempotencia: una cuota ya liberada devuelve ja_liberada, no un error.

El MDF-e puede estar en borrador: solo selecciona los CT-e. Un manifiesto de otra transportista o inexistente devuelve 404; uno sin CT-e devuelve 422.

Autenticación

[
  {
    "oauth2": []
  },
  {
    "chaveApi": []
  }
]

La disponibilidad depende del entorno, los permisos habilitados y el proveedor. Esta referencia no ejecuta solicitudes ni recibe credenciales.

Parámetros

No hay parámetros declarados para esta operación.

Cuerpo de la Solicitud

Obligatorio

`application/json`

LiberarParcelasPorMdfe ↗

mdfestringObligatorio

UUID del MDF-e, clave de acceso (44) o número.

maxLength64

posicaointegerObligatorio

minimum1

maximum3

ocorrido_emstring · dateObligatorio

Fecha del evento; hoy o en el pasado.

Respuestas

200 Respuesta HTTP

MDF-e procesado; consulta resumo y documentos[].resultado.

`application/json`

RespostaParcelasPorMdfe ↗

dataobjectOpcional

ParcelaPorMdfeLinha ↗

401 Respuesta HTTP

Sin autenticación (autenticacao): credencial ausente, inválida o vencida, incluida una clave API utilizada en el entorno incorrecto. La clave de homologación no es válida en producción, ni la de producción en homologación; el mensaje de error indica el entorno esperado.

`application/json`

Erro ↗

errorobjectOpcional

403 Respuesta HTTP

La credencial no tiene habilitado el permiso operacao.

`application/json`

Erro ↗

errorobjectOpcional

404 Respuesta HTTP

MDF-e no encontrado o perteneciente a otro transportista (mdfe_nao_encontrado).

`application/json`

Erro ↗

errorobjectOpcional

422 Respuesta HTTP

MDF-e sin CT-e vinculado (mdfe_sem_documentos), o payload inválido.

`application/json`

Erro ↗

errorobjectOpcional

Definición Completa de la Operación

{
  "tags": [
    "Parcelas"
  ],
  "summary": "Liberar a parcela N de todos os CT-e de um MDF-e",
  "operationId": "liberarParcelasPorMdfe",
  "description": "A liberação em **lote pelo manifesto**: informe o MDF-e (uuid, chave de acesso ou número)\ne a posição, e a FleetPay aplica `liberar` a cada CT-e vinculado à viagem — inclusive os\ncontra-CT-e de um lote de subcontratação — devolvendo **um resultado por CT-e**. Uma recusa\nnuma linha não impede as outras.\n\nTrês regras que valem a pena saber antes de chamar:\n\n- **Só parcelas que já existem.** A parcela nasce na bipagem; o MDF-e não é tratado como\n  evento de coleta. CT-e do manifesto ainda sem parcela na posição responde\n  `recusada / parcela_inexistente` na linha dele.\n- **Só o condutor do MDF-e.** Parcela de outro motorista é `ignorado / motorista_divergente`.\n- **Mesmas regras da liberação unitária** (`evento_fora_de_ordem`, `parcela_cancelada`...),\n  e a mesma idempotência: parcela já liberada é `ja_liberada`, não erro.\n\nO MDF-e pode estar em rascunho — ele é só o seletor dos CT-e. Manifesto de outra\ntransportadora ou inexistente responde `404`; manifesto sem CT-e, `422`.\n",
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/LiberarParcelasPorMdfe"
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "O MDF-e foi processado; leia `resumo` e `documentos[].resultado`.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/RespostaParcelasPorMdfe"
          }
        }
      }
    },
    "401": {
      "$ref": "#/components/responses/Erro401"
    },
    "403": {
      "description": "Credencial sem o escopo `operacao` habilitado.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Erro"
          }
        }
      }
    },
    "404": {
      "description": "MDF-e não encontrado, ou de outra transportadora (`mdfe_nao_encontrado`).",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Erro"
          }
        }
      }
    },
    "422": {
      "description": "MDF-e sem CT-e vinculado (`mdfe_sem_documentos`), ou payload inválido.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Erro"
          }
        }
      }
    }
  },
  "method": "POST",
  "path": "/carriers/parcelas-repasse/liberar-por-mdfe",
  "parameters": []
}