> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt
> Use this file to discover all available pages before exploring further.

# Reglas de negocio de TED Lerian

> Cómo TED Lerian aplica la ventana operativa, los límites de uso, las comisiones, la idempotencia, los plazos regulatorios y las reglas de datos personales.

## Ventana operativa

***

La ventana efectiva de un día combina tres fuentes. `GET /v1/policy/window` devuelve cuál de ellas decidió (`source`).

* **El horario oficial del STR**, publicado por Lerian SPB. Los cambios de horario que el STR anuncia durante el día se aplican sin reiniciar.
* **El horario de corte de la institución**, opcional, siempre igual o anterior al cierre oficial. TED Lerian rechaza un horario posterior con `TED-0081`.
* **El calendario nacional de feriados**, mantenido por año. Un año cargado cubre todas sus fechas. Carga cada año una vez, antes de que empiece.

| Situación | Respuesta cuando envías una TED |
| - | - |
| Fuera del horario o después del horario de corte | `422 TED-0020`, nada retenido |
| Fin de semana o feriado | `422 TED-0021`, nada retenido |
| No se pudo determinar la ventana, o el calendario de feriados del año no está cargado | `503 TED-0022`. TED Lerian rechaza en lugar de adivinar. |
| Transferencia interna | La ventana del STR no aplica |

## Límites de uso

***

* Por cuenta de origen: un máximo por transferencia, un total por día y un total por mes, por día y mes calendario en hora de Brasilia (`America/Sao_Paulo`). Los topes siguen el orden transferencia ≤ día ≤ mes. Un tope ausente significa que no hay tope.
* TED Lerian verifica los topes contra el monto más la estimación de comisión. Después de la retención, los límites cuentan el monto más la comisión que Midaz cobró.
* Una institución debe configurar sus límites antes de la primera TED. Sin ellos, TED Lerian rechaza cada envío con `503 TED-0080`.
* Por encima de un límite, TED Lerian rechaza la TED antes de la retención con `422 TED-0030`. La respuesta indica el límite.
* Una transferencia rechazada o cancelada los libera de nuevo.
* Con `enabled=false`, los límites no cuentan nada y no rechazan nada.
* Solo el administrador los cambia. Cada cambio registra quién lo hizo y cuándo.

## Comisiones

***

* Los [paquetes de comisiones de Midaz](https://docs.lerian.studio/es/products/midaz/fees/using-fee-engine.md) de tu ledger tarifican cada TED, excepto una TED que envía una cuenta con un [plan de tarifas](https://docs.lerian.studio/es/products/midaz/fees/account-plans.md) activo. El plan cobra a esa cuenta, no los paquetes de comisiones, y solo cuando una comisión del plan coincide con la TED.
* TED Lerian marca cada asiento que hace en Midaz con claves de metadatos. Un paquete de comisiones selecciona por ellas con `metadataSelector`:
  * `tedOperation`, una de:
    * `ted_sent`: una TED que envías.
    * `ted_internal`: una transferencia interna.
    * `ted_received`: una TED entrante.
    * `ted_refund`: el monto acreditado de vuelta cuando otra institución devuelve tu TED, si la comisión no se reembolsa.
  * `tedPurposeCode`: el código de finalidad de la TED.
* Un paquete que no selecciona por `tedOperation` también puede cobrar comisión a las TED entrantes y a los reembolsos.
* En una TED que envías, el paquete debe cobrar toda comisión al remitente. Si el paquete aplicado toma alguna comisión del monto enviado, TED Lerian cancela la retención y rechaza la TED con `503 TED-0080`. Hace lo mismo cuando no puede leer ese paquete. Nada va al STR.
* La cotización de comisión es una estimación. TED Lerian la calcula a partir del paquete de comisiones que indica la configuración de runtime `fee.package_id`. Sin esa configuración, la estimación es cero.
* La comisión que Midaz cobró al remitente aparece en el `feeAmount` de la transferencia, después de la retención o después de la liquidación de una transferencia interna.
* Si TED Lerian no puede obtener la estimación, rechaza la cotización y el envío con `503 TED-0040`.
* En una TED entrante, TED Lerian acredita el monto completo. Un paquete de comisiones que le cobra comisión debe deducirla del crédito (`isDeductibleFrom: true`). La comisión aparece entonces en `feeAmount` y el monto acreditado en `creditedAmount`.
* En una TED entrante o en un reembolso, Midaz cobra a `@external/BRL` una comisión que no es deducible, y el cliente recibe el monto completo.
* Cuando otra institución devuelve una TED, TED Lerian no reembolsa la comisión de envío de forma predeterminada. La institución puede habilitar el reembolso, y `returned.feeRefunded` muestra lo que pasó.

## Idempotencia y solicitudes duplicadas

***

* Cada escritura necesita el header `X-Idempotency`: de 1 a 128 caracteres ASCII imprimibles. Sin él, la respuesta es `400 TED-0011`.
* La misma clave con el mismo cuerpo devuelve la respuesta original con `X-Idempotency-Replayed: true`. TED Lerian no crea ninguna transferencia nueva.
* `X-TTL` define durante cuántos segundos TED Lerian repite la respuesta (predeterminado 300). Solo cuenta el TTL de la primera solicitud.
* En `POST /v1/transfers`, la misma clave con la misma solicitud, `metadata` incluido, también repite la respuesta después del `X-TTL`. La respuesta es `201` con `X-Idempotency-Replayed: true` y la transferencia en su estado actual.
* Una solicitud con la misma clave y otro cuerpo recibe `422 TED-0012`. En `POST /v1/transfers`, una solicitud posterior con la misma clave nunca crea una segunda transferencia.
* Una solicitud con la misma clave todavía en curso recibe `409 TED-0013` con `Retry-After`.
* Con una clave nueva, `POST /v1/transfers` rechaza una solicitud materialmente idéntica en la misma ventana antiduplicidad (5 minutos de forma predeterminada) con `409 TED-0014`.

## Plazos regulatorios

***

| Plazo | Empieza en | Termina en | Límite |
| - | - | - | - |
| Del débito al envío | La retención del débito | El envío al STR | 30 min |
| De la liquidación al crédito | La liquidación interbancaria en el STR | El crédito al destinatario | 60 min |
| De la liquidación a la devolución | La liquidación interbancaria en el STR | La devolución | 60 min |

`GET /v1/operations/sla` muestra p50, p95 y p99 de cada plazo, los incumplimientos del día y los ítems en riesgo.

## Datos personales

***

* **Respuestas de la API:** el nombre y el CPF o CNPJ del remitente y del destinatario vienen completos, para los roles que tienen permiso para leerlos.
* **Logs:** TED Lerian enmascara los documentos y los nombres.
* **Eventos de TEDs enviadas** (`transfer.*`) no llevan datos de la contraparte.
* **Eventos de TEDs entrantes** (`incoming_transfer.*`) llevan completo al destinatario, el cliente de la propia institución. El remitente, cliente de otra institución, está enmascarado.
* La descripción en texto libre de una TED entrante se publica tal como la escribió la institución emisora.

## Aislamiento entre instituciones

***

Cada registro pertenece a una institución. La institución siempre viene del token autenticado, nunca de un campo de la solicitud. Un identificador de otra institución responde como no encontrado (`404`), sin revelar que existe.

## Auditoría

***

Cada transferencia tiene una línea de tiempo que nunca se edita. Registra cada cambio de estado con la fecha y la hora, el origen (`API`, `RAIL`, `STR`, `LEDGER`, `WORKER`, `OPERATOR`, `SYSTEM`), el motivo oficial y, en las acciones de operador, quién actuó. TED Lerian no elimina ningún registro de negocio.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.