Contrato común
URLs base
/v1.
Autenticación y encabezados
account_id en esta superficie: la capa pertenece a la organización, no a una de sus cuentas. Las claves de sandbox leen y escriben la capa de Test Mode, las claves de producción la de Live Mode, y ambas son completamente independientes.
Formatos de error
Recibes dos envolturas, y cuál recibes depende de dónde falló la solicitud. Errores de validación y autenticación de la API pública:application/problem+json:
violations está presente en los rechazos que validan un documento completo o un logotipo, y enumera todos los problemas a la vez en lugar de uno por viaje: corrígelos juntos en lugar de reenviar para descubrir el siguiente.
Qué debes saber antes de escribir
La lista de permitidos es opt-in
Un proveedor se ofrece solo cuando una entrada de la lista de permitidos lo nombra.filtered te indica si tu organización tiene al menos una entrada:
filtered: false: no tienes ninguna entrada en la lista de permitidos. Para una organización white-label esto significa que no se ofrece ningún proveedor en el Dashboard hasta que habilites algunos; no es un estado de “mostrar todo”. (La capa solo filtra organizaciones white-label: una organización estándar siempre ve el catálogo completo.)filtered: true: tienes una lista de permitidos, yalloweden cada proveedor indica si ese proveedor está en ella.
filtered, nunca según la longitud de providers. La lista tampoco está vacía cuando tus únicas entradas son reemplazos de instrucciones o de logotipo, y un proveedor que tiene textos o un logotipo personalizados sin estar ofrecido aparece en ella con allowed: false.
Los reemplazos sustituyen, nunca se combinan
Un reemplazo de instrucciones es un documento completo.PUT guarda lo que envías y borra lo que omites, así que un campo que dejas fuera vuelve al valor del catálogo de Yuno. La edición segura es leer con GET, cambiar el único campo y volver a enviar el documento completo.
La misma regla se aplica campo por campo al leer: un campo ausente significa “conservar el valor del catálogo”; un campo presente pero vacío significa “reemplazarlo por nada”.
La identidad pertenece a los proveedores propios de Yuno
Los textos de un proveedor puedes cambiarlos tú. Su identidad no:namey un logotipo personalizado se aceptan solo para proveedores propiedad de Yuno: un ID de catálogo que contengaYUNO, comoYUNO_3DSoYUNO_FRAUD_SCREENING.- Cualquier otro proveedor se rechaza con
400y una entrada deviolationsque nombra el ID.
more_info_url en todos los proveedores.
Los enlaces deben ser https
more_info_url y cada link dentro de un paso de instrucciones deben ser una URL https: el dashboard los muestra como href. Cualquier otra cosa se rechaza.
Los logotipos son independientes de las instrucciones, y logo_url es efímero
Las instrucciones y los logotipos son recursos independientes: eliminar uno no afecta al otro, y ninguno agrega el proveedor a tu lista de permitidos.
Las cargas de logotipos viajan en base64 dentro de JSON, no como multipart. La imagen debe ser PNG o JPEG (se determina por los bytes del propio archivo, así que un SVG renombrado como .png se rechaza), cuadrada, de al menos 200x200 píxeles y de como máximo 64 KB decodificada. Los cuerpos de solicitud de más de 256 KB se rechazan con 413.
Las escrituras se atribuyen a la API
Una escritura hecha mediante estos Endpoints muestracreated_by y updated_by con el valor centinela de ceros 00000000-0000-0000-0000-000000000000: “escrito mediante la API” en lugar de por una persona en el dashboard. Las escrituras hechas por un usuario en el Dashboard llevan el ID de ese usuario.
El Dashboard y la API son los mismos datos
Los cambios hechos aquí aparecen de inmediato en la pestaña Providers white-label del Dashboard, y los cambios hechos allí los devuelven estos Endpoints. No hay un paso de sincronización ni una segunda fuente de verdad.Un flujo típico
Lee lo que tienes
filtered para saber si tienes una lista de permitidos y lee allowed por proveedor. Combina el resultado con el catálogo de proveedores de Yuno para mostrar un selector completo.Define lo que ofreces
Escribe tus textos, un proveedor a la vez
Agrega logotipos donde puedas hacerlo
Replica Test Mode en Live Mode
https://api.y.uno con tus claves de producción. Como PUT reemplaza el documento completo y el PUT de la lista de permitidos reemplaza el conjunto completo, repetir una lectura basta para que Live Mode coincida con Test Mode, sin necesidad de comparar diferencias.