Tranzmit · Payers API v1.0
Qué encontré en el archivo que mandó tecnología, qué corregí, y lo que queda abierto sin frenar nada.
15 de octubre de 2026 · 9:30 pm
El spec pasa la validación limpio, sin errores ni advertencias, y la referencia interactiva ya está publicada en el portal de developers. El archivo corregido queda descargable desde ahí para que tecnología lo adopte como fuente.
Cinco son el mismo error de dedo. No se ven leyendo el archivo, pero rompen cualquier herramienta que lo lea.
Líneas 939, 950, 951, 968 y 969 — los campos created y
clientTimestamp de PayoutAssignment,
PayoutConfirmation y PayoutRejection.
La descripción decía create date-time in ISO-8601 format, utc dentro de
una línea con llaves. En YAML, la coma dentro de las llaves separa campos: el texto se
cortó en «format» y la palabra utc quedó interpretada como un campo del esquema
que no existe. Se arregla poniendo la descripción entre comillas.
nullable sin tipoLínea 959, el reasonCode de PayoutRejection. Declaraba que
el campo puede venir nulo sin decir de qué tipo es. El validador lo rechaza porque no
puede deducir qué generar.
El spec estaba bien armado en estructura, pero le faltaban dos cosas que cambian mucho la experiencia de quien integra.
status, deliveryMethod, accountType,
el parámetro delivery_method y el type de payout-updates.
Venían como texto libre con los valores escritos en la descripción, en prosa. Eso obliga
al desarrollador del banco a leer párrafos y escribir las constantes a mano, y hace que
un SDK generado trate el estado como un texto cualquiera en lugar de una lista cerrada.No son errores del archivo. Son decisiones que alguien tiene que tomar, y dos de ellas tienen filo comercial.
La dirección del remitente y del beneficiario tiene country,
state, city, line1 y line2. No hay
campo de código postal.
Para una remesa que sale de Estados Unidos, el ZIP del remitente es un dato que normalmente se pide en el reporte regulatorio. Si un partner tiene que reportarlo y la API no lo transmite, el dato se pierde en el camino. Vale confirmarlo con cumplimiento antes de que un banco lo pregunte en la mesa.
El objeto Transaction tiene 25 campos y el spec no marca ninguno como
requerido. En la práctica el id, el referenceNumber y el
status siempre vienen.
Mientras no se marquen, cualquier cliente generado los tratará como opcionales y el desarrollador del banco tendrá que verificar si vienen vacíos en cada uno de los 25. Es trabajo regalado y una fuente de errores evitable.
Como método de entrega existen cinco: depósito, ventanilla, billetera, domicilio y
cajero. Pero el parámetro de query-available solo acepta tres —depósito,
domicilio y billetera.
Que falte ventanilla tiene sentido: ese flujo entra por número de referencia. Lo que no cuadra es cajero. Si un pagador ofrece retiro en cajero, hoy no tiene por dónde recibir esas transacciones.
El spec no define webhooks. Eso significa que el pagador tiene que consultar
query-available cada cierto tiempo para ver si hay transacciones nuevas, y
el spec no dice cada cuánto es aceptable.
Es la primera pregunta que hace un equipo técnico serio. Conviene tener la respuesta escrita antes de que la hagan.
payout-confirmation documenta los diez códigos de respuesta posibles.
Los otros nueve endpoints documentan cuatro. Lo más probable es que todos puedan
devolver un 500; conviene homologarlo.
Nada de esto frena el proyecto: el spec está válido y publicado sin estos cinco puntos. Los dejo anotados para que estén a la vista el día que alguien pregunte, no como requisito.
| # | Punto abierto | Cuándo va a importar |
|---|---|---|
| 1 | La URL de producción | El spec declara staging. Se agrega el día que el primer partner pase a vivo —una línea en el archivo. |
| 2 | Cuáles campos son obligatorios | Hoy ninguno está marcado. Funciona igual; el desarrollador que integre simplemente valida más de lo necesario. |
| 3 | Los scopes del OAuth | La lista está vacía. Si no se usan scopes, así está correcto. |
| 4 | Límite de llamadas | Si existe y no está escrito, el partner lo descubre cuando le respondan un 429. |
| 5 | Cada cuánto consultar | Sin webhooks, el partner pregunta en el intervalo que él decida. Vale fijarlo cuando haya varios conectados a la vez. |
Lo pesado ya está. Queda la parte que hace que esto se mantenga solo.
Hoy el archivo me llegó por Telegram. Mientras viaje así, cada versión es una copia distinta y nadie sabe cuál es la buena. Con el archivo en un repositorio, el cambio al spec y su publicación son el mismo movimiento.
Un GitHub Action que valide el spec en cada cambio y republique el portal solo. Se escribe una vez y corre para siempre, sin que nadie —ni yo— tenga que acordarse.
Colección de Postman para que un partner pruebe sin escribir código, y un servidor simulado para que integre antes de que le demos acceso a staging. Las dos salen del mismo archivo y acortan semanas de onboarding.
La segunda API quedó en pausa el 23 de septiembre, con el material armado y sin publicar. Si tecnología tiene también su spec, entra por el mismo camino.