Guia
Uso de la API
Como los clientes tecnicos aprobados se autentican, leen datos, envian solicitudes compatibles y reciben webhooks.
Esta guia es para
Para integradores aprobados y operadores tecnicos. Las claves API y suscripciones webhook las emiten administradores de MZ Bank.
Resumen
- La API de integracion esta pensada para clientes externos aprobados que necesitan acceso de maquina a datos y flujos de MZ Bank.
- La ruta base publica es
/api/v1/integrations/*. - El acceso a la API es independiente del inicio de sesion con Discord y de la sesion normal del portal.
Como se emite el acceso
- Las claves API se vinculan a un perfil activo y verificado de cliente de MZ Bank.
- Un administrador crea la clave y elige los alcances permitidos.
- Las suscripciones webhook tambien las crea un administrador y usan un secreto de firma separado.
Autenticacion y permisos
- Envia la clave API como bearer token en el encabezado
Authorization. - Cada clave esta limitada por alcances. Por ejemplo,
accounts:readcubre vistas de cuentas ytransfers:writepermite crear transferencias. - Las claves pueden rotarse o revocarse sin cambiar el acceso normal del cliente al sitio o al bot.
Que puede leer la API
- Los clientes pueden leer cuentas visibles, saldos, historial de transacciones, estados, beneficiarios, preferencias de notificacion, solicitudes y vistas empresariales cuando el alcance correcto esta presente.
- Las respuestas de cuentas incluyen informacion de subcuentas y referencias a familias raiz cuando corresponde.
- Las respuestas empresariales incluyen subcuentas, beneficiarios finales, accesos activos y capacidades del llamador.
Que puede escribir la API
- La API admite transferencias, creacion de subcuentas, solicitudes de cuenta, gestion de beneficiarios, preferencias de notificacion, retiros y depositos.
- Las rutas de movimiento de dinero deben cumplir las mismas reglas de autorizacion, limites y libro mayor que el bot y el portal.
- Usa claves de idempotencia cuando la ruta lo requiera para que los reintentos seguros no creen actividad duplicada.
Familias empresariales y subcuentas
- Las rutas de familias empresariales usan las mismas reglas de propiedad y acceso delegado que el portal.
- Las respuestas conscientes de subcuentas incluyen tanto el ID de la cuenta hoja como el ID de la familia empresarial raiz.
- Los operadores delegados solo pueden usar las cuentas y acciones permitidas por su rol y topes actuales.
Eventos webhook
- Las suscripciones webhook pueden recibir eventos del ciclo de vida de depositos, retiros y transferencias.
- Los webhooks de transferencias se emiten por separado para el lado saliente y el entrante para consumidores conscientes de subcuentas y familias.
- Cada webhook se firma con
x-mzb-signature-256, y los consumidores deben verificar la firma contra el cuerpo crudo exacto.
Estados, notificaciones y reportes
- Las rutas de estados y exportacion ofrecen el mismo historial publicado que el cliente puede consultar en el Statement Center.
- Las rutas de notificaciones exponen preferencias guardadas y resultados recientes de entrega.
- La actividad de la API debe conciliar con el estado del portal, los estados y los webhooks del mismo cliente o familia empresarial.
Empezar de forma segura
- Pide a un administrador una clave de prueba con solo los permisos que tu cliente necesita.
- Valida el manejo de webhooks con un endpoint descartable antes de enviar eventos a una URL de produccion.
- Si necesitas la referencia operativa completa de endpoints, alcances y diagnostico, solicita la documentacion interna de integraciones.