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

# Resumen de la API de TED Lerian

> Conceptos, una integración en cuatro pasos, estados, permisos, convenciones y familias de errores de la API de TED Lerian.

TED Lerian es la interfaz sobre Lerian SPB, el conector de mensajería propio de Lerian hacia el STR. Tu institución usa su API para enviar TEDs, hacer transferencias internas, seguir las TEDs recibidas y operar devoluciones, colas y políticas, todo sobre el ledger Midaz de la institución. En una TED, el dinero sale de la cuenta solo cuando el STR liquida. Cada operación con efecto es idempotente, así que puedes reenviar después de un timeout.

## Conceptos

***

| Término | Significado |
| - | - |
| TED | Una transferencia a otra institución, liquidada en tiempo real por el STR (Banco Central do Brasil). Es asíncrona: la respuesta del envío nunca incluye la liquidación. |
| Transferencia interna | El destinatario está en tu propia institución. Misma operación, `POST /v1/transfers`, liquidada de inmediato en el ledger (`type=INTERNAL`). |
| Cuenta de origen | La cuenta debitada, enviada en el header `X-Account-Id` (UUID), nunca en el cuerpo. Debe pertenecer a tu organización. |
| ISPB / COMPE | Identificadores del banco de destino: ISPB (8 dígitos) o código COMPE (3 dígitos, por ejemplo `001`). Envía uno de ellos en `recipient`. `GET /v1/participants` convierte uno en el otro. |
| Código de finalidad (`purposeCode`) | Código de 5 dígitos del Diccionario de Dominios del SFN. `99999` (otros) requiere `description`. |
| Retención | Monto más comisión bloqueados en la cuenta de origen hasta la liquidación (`SETTLED`). Se libera en `REJECTED` y `CANCELLED`. |
| Ventana operativa | El horario en que el STR acepta TEDs, reducido por el horario de corte de la institución y por el calendario de feriados. `GET /v1/policy/window` te dice si está abierta. |
| `nuop` | Número único de operación en el SPB (23 dígitos). Aparece cuando el STR acepta la TED e identifica la operación en comprobantes y eventos. |
| TED recibida | Una TED que otra institución envía a uno de tus clientes. TED Lerian la acredita, la devuelve o abre una revisión manual, dentro del plazo regulatorio de 60 minutos. |
| Devolución | Devolución total de una TED recibida al remitente, con un motivo oficial (`returnCode`, CodDevTransf). |

## Integra en cuatro pasos

***

**1. Configura la institución**

Haz esto una vez, con el rol `editor`. Define los límites de uso con `PUT /v1/policy/limits`; son obligatorios antes de la primera TED. Para las TEDs recibidas, define las vinculaciones de ISPB a organización con `PUT /v1/policy/ispb-bindings`. De forma opcional, define un horario de corte con `PUT /v1/policy/window`.

**2. Envía la TED**

Envía `X-Account-Id` (la cuenta debitada) y `X-Idempotency` (una clave nueva para cada pago). Para mostrar la comisión antes de confirmar, llama a `POST /v1/transfers/fee-quotes` con los mismos campos.

```bash theme={null}
curl -X POST "$TED_URL/v1/transfers" \
  -H "Authorization: Bearer $TED_BEARER_TOKEN" \
  -H "X-Account-Id: 0a2f4c6e-8b1d-4e3f-9a5b-7c9d1e3f5a7b" \
  -H "X-Idempotency: 9b4f1a6e-3c2d-4e5f-8a7b-6c5d4e3f2a1b" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "1500.00",
    "purposeCode": "00010",
    "description": "Supplier payment",
    "clientReference": "PED-2026-000123",
    "recipient": {
      "bankCode": "001",
      "agency": "1234",
      "bankAccount": "0001234567",
      "bankAccountType": "CACC",
      "name": "Maria da Silva",
      "document": "12345678901"
    }
  }'
```

El envío devuelve `201` con el estado que la TED alcanzó en esta llamada, normalmente `SUBMITTED`.

```json theme={null}
{
  "transferId": "6f1c2b3a-4d5e-4f60-8a9b-0c1d2e3f4a5b",
  "type": "TED",
  "status": "SUBMITTED",
  "amount": "1500.00",
  "feeAmount": "3.25",
  "totalAmount": "1503.25",
  "nuop": "87654321202610220000123",
  "createdAt": "2026-10-22T13:05:12Z"
}
```

**3. Síguela hasta la liquidación**

Consulta `GET /v1/transfers/{transferId}` hasta que `status` llegue a `SETTLED`, `REJECTED` o `CANCELLED`, o suscríbete a los eventos `transfer.*`. En `REJECTED`, `rejection.source` y `rejection.code` te dicen quién la rechazó y por qué.

```bash theme={null}
curl "$TED_URL/v1/transfers/6f1c2b3a-4d5e-4f60-8a9b-0c1d2e3f4a5b" \
  -H "Authorization: Bearer $TED_BEARER_TOKEN"
```

**4. Gestiona las TEDs recibidas**

Lístalas con `GET /v1/incoming-transfers`. El crédito al cliente es automático. Solo `status=MANUAL_REVIEW` requiere una decisión de un operador (`POST /v1/incoming-transfers/{incomingTransferId}/resolve-review`), y `POST /v1/incoming-transfers/{incomingTransferId}/return` devuelve una TED que ya está acreditada.

## Estados

***

Una TED enviada pasa por estos estados. Los estados finales son `SETTLED`, `REJECTED` y `CANCELLED`.

| Estado | Significado | Qué hacer |
| - | - | - |
| `CREATED` → `RESERVED` | Registrada; monto más comisión retenidos | Espera (se puede cancelar) |
| `SUBMITTED` | Aceptada por el riel y enviada al STR | Espera la liquidación; no se puede cancelar |
| `PENDING_STR` | El STR mantiene el asiento pendiente | Espera; puedes solicitar la cancelación |
| `SETTLED` | Liquidada; débito confirmado | Nada. Una devolución posterior aparece en `returned` |
| `REJECTED` | Rechazada; retención liberada | Consulta `rejection` |
| `CANCELLED` | Cancelada antes del envío, o cancelación confirmada por el STR | Nada |
| `AWAITING_RECONCILIATION` | Resultado no confirmado; la conciliación automática consulta el riel (de forma predeterminada, a partir de los 15 minutos, hasta 8 intentos) | Espera; no reenvíes |
| `EXHAUSTED` | La conciliación agotó los intentos sin evidencia | Un operador la resuelve con `POST /v1/transfers/{transferId}/unblock` |

Una TED recibida pasa de `RECEIVED` (decisión en curso) a `CREDITED` (acreditada al cliente), `RECORDED` (cuenta propia de la institución, final), `RETURN_REQUESTED` (TED Lerian no puede acreditarla) o `MANUAL_REVIEW` (espera a un operador; consulta `reviewReason`). Pasa de `RETURN_REQUESTED` a `RETURNED` cuando se devuelve. `slaDeadlineAt` es el plazo regulatorio de 60 minutos contado desde la liquidación interbancaria.

## Autenticación y permisos

***

Cada llamada, excepto los health checks públicos, envía `Authorization: Bearer <token>` emitido por Access Manager. Los roles predeterminados son `editor` (todas las operaciones), `operator` (todas las operaciones excepto las escrituras de políticas y de vinculaciones de ISPB) y `viewer` (lecturas, excepto las lecturas de conciliación).

| Operaciones | Permiso |
| - | - |
| `POST /v1/transfers`, `POST /v1/transfers/fee-quotes` | `transfers:create` |
| `GET /v1/transfers` y sus subrecursos | `transfers:read` |
| `POST /v1/transfers/{transferId}/cancel` · `POST /v1/transfers/{transferId}/unblock` | `transfers:cancel` · `transfers:unblock` |
| `GET /v1/incoming-transfers` y sus subrecursos | `incoming-transfers:read` |
| `POST /v1/incoming-transfers/{incomingTransferId}/return` · `POST /v1/incoming-transfers/{incomingTransferId}/resolve-review` | `incoming-transfers:return` · `incoming-transfers:resolve-review` |
| `GET /v1/reconciliation/*` · `POST /v1/reconciliation/reviews/{reviewId}/resolve`, `POST /v1/reconciliation/held-returns/{heldReturnId}/close` · `POST /v1/reconciliation/runs` | `reconciliation:read` · `reconciliation:resolve` · `reconciliation:create` |
| `GET /v1/operations/*` | `dashboard:read` |
| `GET` y `PUT` en `/v1/policy/window` y `/v1/policy/limits`, `PUT /v1/policy/holidays` | `policy-config:read` / `policy-config:write` |
| `GET` y `PUT` en `/v1/policy/ispb-bindings` | `policy-ispb-bindings:read` / `policy-ispb-bindings:write` |
| `GET /v1/participants` | `participants:read` |

Sin el permiso, o con una licencia del producto que no es válida para la organización: `403` `TED-0071`. Token ausente o inválido: `401` `TED-0070`.

## Convenciones

***

* **Tenant.** Nunca de la ruta, del query ni del cuerpo.
* **Montos.** Strings decimales en BRL con dos decimales (`"1500.00"`), nunca números JSON.
* **Fechas.** RFC 3339 en UTC (`2026-10-22T13:05:12Z`); los días como `YYYY-MM-DD`. La ventana operativa usa la zona horaria de la institución (`America/Sao_Paulo`).
* **Idempotencia.** Cada operación con efecto requiere `X-Idempotency` (de 1 a 128 caracteres ASCII; usa un UUID). La misma clave con el mismo cuerpo devuelve la respuesta original con `X-Idempotency-Replayed: true` y sin nuevo efecto. Un cuerpo diferente devuelve `422` `TED-0012`. Si la primera solicitud todavía se está procesando, recibes `409` `TED-0013` (reintenta después de `Retry-After`). La repetición dura `X-TTL` segundos (300 de forma predeterminada). En `POST /v1/transfers`, la clave queda vinculada a la transferencia que creó.
* **Protección contra duplicados.** `POST /v1/transfers` puede rechazar con `409` `TED-0014` una solicitud materialmente idéntica enviada poco después de otra, incluso con una clave diferente. Consulta la transferencia existente.
* **Paginación.** Las listas devuelven `items`, `limit`, `next_cursor` y `prev_cursor`. Pide hasta `limit=100` (20 de forma predeterminada) y sigue `next_cursor` hasta que sea `null`. El cursor es opaco.
* **Correlación.** Envía `X-Request-Id` (UUID) o recibe uno generado. Vuelve en cada respuesta e identifica la llamada para soporte.
* **Eventos.** Cada transición se publica como un CloudEvent con `ce-type` `studio.lerian.br-ted.<resource>.<event>`: `transfer.*`, `incoming_transfer.*` e `incoming_return.*`. La entrega es al menos una vez; deduplica por `ce-id`.
* **Entornos.** La URL base es por instalación (BYOC o Lerian Cloud), y Lerian la proporciona.

## Errores

***

Cada error es `application/problem+json` (RFC 9457) con un `code` estable. Gestiona los errores por `code`. `errors` lista los campos inválidos de un `422`.

Un `503` significa que la solicitud no tuvo efecto: reintenta más tarde con el mismo `X-Idempotency`. Hay tres excepciones:

* `TED-1000`: el ledger no confirmó el resultado, y la operación ya puede estar en el ledger. Lee el estado del recurso antes de volver a actuar.
* `TED-0080` en un envío: la transferencia ya puede existir. Búscala con `GET /v1/transfers` antes de enviarla de nuevo.
* `TED-1010` en una cancelación: la respuesta del conector del STR es desconocida, y la solicitud de cancelación sigue registrada. Reintenta con el mismo `X-Idempotency` y el mismo `reason`.

Una llamada limitada por el rate limit devuelve `429` con `Retry-After`: gestiónala por el estado y espera ese tiempo antes de reintentar.

| Familia | Códigos | Cuándo |
| - | - | - |
| Solicitud | `TED-0001` (400), `TED-0002` a `TED-0007` (422) | JSON mal formado; campo, código de finalidad, banco o documento inválido |
| Headers e idempotencia | `TED-0008` (400), `TED-0009` (403), `TED-0011` (400), `TED-0012` (422), `TED-0013`/`TED-0014` (409) | `X-Account-Id` ausente o de otra organización; `X-Idempotency` ausente, reutilizado o todavía en proceso; solicitud duplicada |
| Política | `TED-0020`/`TED-0021`/`TED-0030` (422), `TED-0022`/`TED-0040` (503) | Fuera de la ventana; día no hábil; límite; ventana o cálculo de comisión no disponible |
| Estado | `TED-0060`/`TED-0061`/`TED-0062`/`TED-0067` (409), `TED-0063` a `TED-0066` (422) | Acción no compatible con el estado; no se puede cancelar; no se puede devolver; devolución retenida aún vinculada a una transferencia; devolución o evidencia inválida |
| Acceso | `TED-0070` (401), `TED-0071` (403) | Token; permiso o licencia |
| Configuración | `TED-0080` (503), `TED-0081` (422) | A la institución le falta configuración obligatoria; horario de corte posterior al cierre oficial |
| Dependencias | `TED-1000`/`TED-1010`/`TED-1012`/`TED-1020` (503), `TED-1001`/`TED-1021` (422) | Ledger, conector del STR o registro no disponible o rechazando los datos |
| Interno | `TED-9000` (500), `TED-9002` (503) | Falla inesperada: contacta a soporte con el `X-Request-Id`; servicio no disponible, por ejemplo cuando el registro de auditoría no puede guardar un cambio de política |

En un envío, `TED-0031`, `TED-1001`, `TED-1011` y `TED-1013` nunca llegan como respuesta de error. Llegan en `rejection.code` de una transferencia con estado `REJECTED`, en la respuesta `201` o en una consulta posterior.

La [lista de errores](https://docs.lerian.studio/es/reference/interfaces/ted-lerian/ted-lerian-error-list.md) muestra cada código con su causa y su corrección.


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