Liberar una cuota

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

POST/carriers/parcelas-repasse/liberar

liberarParcelaRepasseBase 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.

Declara que el evento que activa la cuota ocurrió en su sistema.

Con una regla MANUAL, liberar solo deja la cuota habilitada. Sigue sin vencimiento ni pago, esperando una orden de pago. Es deliberado: en modo manual, usted decide cuándo debe salir el dinero y el vencimiento corresponde al momento de esa decisión, no a una fecha derivada del evento.

Con una regla AUTOMÁTICA, los eventos internos ya liberan las cuotas automáticamente. Esta llamada permite desbloquear una cuota detenida: registra el vencimiento (fecha del evento + plazo de la regla) y el pago continúa sin otro paso.

ocorrido_em puede ser retroactiva: el evento puede haber ocurrido antes de que alguien lo registrara. Se rechazan las fechas futuras, porque crearían un vencimiento a partir de un evento que no ocurrió.

Volver a liberar es una operación sin efecto adicional, no un error: un reintento no duplica la cuota.

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`

LiberarParcelaRepasse ↗

documentostringObligatorio

Los mismos identificadores que acepta GET: ID interno de FleetPay, número del documento (internal_id) o clave de CT-e de 44 dígitos; para contra-CT-e, también counter_cte_id, el documento_financeiro del tramo (ROUTE:...) o la clave del contra-CT-e autorizado.

maxLength64

posicaointegerObligatorio

1 escaneo · 2 finalización en la app · 3 rendición de cuentas.

minimum1

maximum3

ocorrido_emstring · dateObligatorio

Cuándo ocurrió el evento. Se permiten fechas pasadas; las futuras se rechazan con data_no_futuro.

Respuestas

200 Respuesta HTTP

Cuota liberada (o ya liberada; la llamada es idempotente)

`application/json`

RespostaParcelaRepasse ↗

dataobjectOpcional

ParcelaRepasse ↗

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

Documento no encontrado o perteneciente a otro transportista.

`application/json`

Erro ↗

errorobjectOpcional

422 Respuesta HTTP

Se rechazó la liberación. El code es estable; úselo para decidir cómo proceder:

`code`	Qué hacer
`sem_regra_parcelada`	El documento no está sujeto a una regla de cuotas; no hay nada que liberar.
`parcela_inexistente`	La regla no tiene una cuota en esta posición.
`evento_fora_de_ordem`	Libere primero la cuota anterior.
`data_anterior_ao_evento_anterior`	La fecha indicada es anterior al evento de la cuota anterior.
`data_no_futuro`	Utilice una fecha no posterior a hoy.
`parcela_cancelada`	El CT-e fue cancelado ante SEFAZ; esta cuota no generará ningún pago.
`servico_ainda_nao_concluido`	La cuota de finalización debe preceder a la de rendición de cuentas.
`regra_sem_prestacao_de_contas`	Posición 3 en una regla sin cuota de rendición de cuentas.
`data_anterior_a_conclusao`	Posición 3 con fecha anterior a la finalización del servicio.
`falha_ao_liberar`	Error interno al guardar la liberación; repita la llamada.

`application/json`

Erro ↗

errorobjectOpcional

429 Respuesta HTTP

Límite de solicitudes excedido (limite_requisicoes). Espera el intervalo indicado en el encabezado Retry-After antes de reintentar. Puede provenir del proveedor o del límite antiabuso de FleetPay, calculado por empresa autenticada y grupo de rutas, con una ventana corta para ráfagas y otra larga para tráfico automatizado lento. Los límites son amplios deliberadamente: las integraciones reales, incluidos lotes grandes procesados de una vez, deberían quedar muy por debajo. Si tu integración alcanza un límite, contacta con FleetPay.

`application/json`

Erro ↗

errorobjectOpcional

500 Respuesta HTTP

Error interno (erro_interno)

`application/json`

Erro ↗

errorobjectOpcional

Definición Completa de la Operación

{
  "tags": [
    "Parcelas"
  ],
  "summary": "Liberar uma parcela",
  "operationId": "liberarParcelaRepasse",
  "description": "Declara que o evento âncora da parcela aconteceu no seu sistema.\n\n**Em regra MANUAL**, liberar deixa a parcela **apta** — e nada mais. Ela fica sem\nvencimento e sem pagamento, esperando a ordem de pagamento. Isso é deliberado: no modo\nmanual quem decide quando o dinheiro sai é você, e o vencimento é o momento dessa decisão,\nnão uma data derivada do evento.\n\n**Em regra AUTOMÁTICA**, os eventos internos já liberam sozinhos. Esta chamada serve como\ndestravamento de parcela presa, e aí ela grava o vencimento (evento + prazo da regra) e o\npagamento segue sem passo extra.\n\n`ocorrido_em` **pode ser retroativa** — o evento pode ter acontecido antes de alguém\nregistrar. Data futura é recusada: seria criar vencimento a partir de um evento que não\nocorreu.\n\nLiberar de novo é **no-op**, não erro: retry não vira parcela duplicada.\n",
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/LiberarParcelaRepasse"
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Parcela liberada (ou já liberada — a chamada é idempotente)",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/RespostaParcelaRepasse"
          }
        }
      }
    },
    "401": {
      "$ref": "#/components/responses/Erro401"
    },
    "403": {
      "description": "Credencial sem o escopo `operacao` habilitado.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Erro"
          }
        }
      }
    },
    "404": {
      "description": "Documento não encontrado, ou de outra transportadora.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Erro"
          }
        }
      }
    },
    "422": {
      "description": "A liberação foi recusada. O `code` é estável e é por ele que você deve ramificar:\n\n| `code` | O que fazer |\n|---|---|\n| `sem_regra_parcelada` | O documento não está sob regra parcelada — não há o que liberar. |\n| `parcela_inexistente` | A regra não tem parcela nessa posição. |\n| `evento_fora_de_ordem` | Libere a parcela anterior primeiro. |\n| `data_anterior_ao_evento_anterior` | A data informada é anterior ao evento da parcela anterior. |\n| `data_no_futuro` | Use uma data até hoje. |\n| `parcela_cancelada` | O CT-e foi cancelado na SEFAZ; esta parcela não vai pagar nada. |\n| `servico_ainda_nao_concluido` | A parcela de conclusão precisa vir antes da prestação de contas. |\n| `regra_sem_prestacao_de_contas` | Posição 3 numa regra que não tem a parcela de prestação de contas. |\n| `data_anterior_a_conclusao` | Posição 3 com data anterior à conclusão do serviço. |\n| `falha_ao_liberar` | Falha interna ao gravar a liberação; repita a chamada. |\n",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Erro"
          }
        }
      }
    },
    "429": {
      "$ref": "#/components/responses/Erro429"
    },
    "500": {
      "$ref": "#/components/responses/Erro500"
    }
  },
  "method": "POST",
  "path": "/carriers/parcelas-repasse/liberar",
  "parameters": []
}