Resumen 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

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.

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.

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.

{
  "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"
}

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

curl "$TED_URL/v1/transfers/6f1c2b3a-4d5e-4f60-8a9b-0c1d2e3f4a5b" \
  -H "Authorization: Bearer $TED_BEARER_TOKEN"

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 muestra cada código con su causa y su corrección.

Resumen

API de Transferencias

API de TEDs recibidas

API de Conciliación

API de Operaciones

API de Políticas

API de Participantes

Manejo de errores

Resumen de la API de TED Lerian

Conceptos

Integra en cuatro pasos

Estados

Autenticación y permisos

Convenciones

Errores

​Conceptos

​Integra en cuatro pasos

​Estados

​Autenticación y permisos

​Convenciones

​Errores

Conceptos

Integra en cuatro pasos

Estados

Autenticación y permisos

Convenciones

Errores