API REST
La API REST permite que el CRM, el sitio web o el sistema central de un prestamista lea y escriba en Mutio Core: 62 endpoints públicos (28 de lectura y 34 de escritura) bajo https://<site>/api/v1, descritos en OpenAPI 3.1 en /api/v1/openapi.json.
- Llaves. Los administradores crean llaves de API en Configuración › Desarrolladores: de solo lectura, o de lectura y escritura. La llave se envía como
Authorization: Bearer mutuo_sk_…y determina la organización; una sesión de navegador no cuenta. Una llave de lectura que intenta escribir recibe403. - Límites. 300 peticiones por minuto por llave (con encabezados
RateLimit-*, y429conRetry-Afteral rebasarlas); cuerpos JSON de hasta 1 MB; documentos de hasta 10 MB. - Reintentos seguros. Cualquier escritura puede llevar un
Idempotency-Key: la misma petición dentro de un día devuelve la primera respuesta en lugar de escribir dos veces; una petición distinta con la misma llave recibe422. - Listas. Se paginan con
limit(1–100, predeterminado 50) ystarting_after, y devuelvenhas_more. - Errores. Siempre tienen la misma forma (
type,message, todos los errores de campo a la vez yexisting_iden duplicados). Cada respuesta lleva unMutuo-Request-Id. - Suscripción. Mientras la organización está en solo lectura, las escrituras responden
402. - Bitácora de peticiones. Cada llamada se guarda 30 días; la página de Desarrolladores muestra las últimas 50.
Endpoints por área
| Área | Endpoints | Qué hacen |
|---|---|---|
| Conexión | 2 | Probar la llave (GET /api/v1); la descripción OpenAPI, sin llave. |
| Clientes | 7 | Listar con filtros (correo, RFC, CURP, ID externo, tipo, activo, empleador, búsqueda, actualizados o creados desde); crear con todos los campos del contrato y hasta 20 referencias; leer; cambiar solo los campos enviados; eliminar un cliente sin nada ligado; buscar y crear o actualizar (upsert) por el ID externo propio del prestamista. |
| Documentos de clientes | 3 | Listar, subir (multipart, hasta 10 MB) y leer uno con una liga de descarga de 5 minutos. |
| Créditos y empleo del cliente | 5 | Los créditos de un cliente por estatus, con totales; leer, definir o quitar su empleo; registrar una separación (baja), que pasa sus créditos de nómina a cobranza directa. |
| Créditos y pagos | 9 | Leer un crédito (opcionalmente con su calendario); crear un crédito agrícola con su plan; registrar una ministración; listar pagos; registrar un pago en cualquier tipo de crédito con su propio cálculo; previsualizar un pago (una llave de lectura puede hacerlo); revertir el último; pasar un crédito de nómina a cobranza directa y de regreso. |
| Empresas y remesas | 11 | Empresas y sus convenios (listar, crear, leer, cambiar, eliminar); sus empleados con capacidad de pago y créditos; la lista de descuentos (cédula) de un día de pago; registrar la remesa de un día de pago, todo o nada; listar, leer y deshacer remesas. |
| Créditos grupales | 23 | Grupos (listar, crear, leer, cambiar, eliminar); integrantes (agregar, asignar cargo en la mesa directiva, salir); ciclos (listar, iniciar con un crédito para cada integrante que pide prestado, leer, cerrar, reabrir, reestructurar como grupo); reuniones (listar, hoja de reunión, registrar todo o nada, leer, deshacer); garantías en efectivo (listar, depositar o devolver, eliminar un error). |
| Eventos | 2 | Los eventos de la organización de los últimos 30 días, filtrables por tipo, y un evento. |
Tareas programadas: un endpoint del programador dispara las entregas de webhooks pendientes, y fuera de la API Make ejecuta otras dos: el cierre mensual (el día 3 de cada mes) y la actualización diaria de las tasas de Banxico y del dólar.
Webhooks
Cada cambio se envía en el momento en que ocurre, como un POST firmado, a cada endpoint activo suscrito a su tipo de evento (o a todos los eventos, lo que incluye los tipos que se agreguen después).
| Grupo | Tipos de evento |
|---|---|
| Clientes | client.created, client.updated (con los campos cambiados y sus valores anteriores), client.deleted |
| Créditos | loan.created, loan.deleted, loan.restored, loan.payment_recorded, loan.payment_reverted, loan.collection_changed |
| Nómina | employer.created, employer.updated, employer.deleted, payroll.remittance_recorded, payroll.remittance_reverted |
| Grupos | group.cycle_started, group.cycle_restructured, group.meeting_recorded, group.meeting_reverted |
- 18 tipos de evento. Más
webhook.test, que se envía solo al endpoint que se está probando. - Contenido. Cada evento lleva un id, su tipo, su hora, la versión de la API, la organización, su origen (
app, oapicon el nombre de la llave, para que una sincronización en dos sentidos pueda saltarse sus propios cambios) y sus datos. Los cambios se registran en la misma transacción, así que un cambio deshecho no envía nada. Una importación de Excel envía unloan.createdpor crédito, no su historial. - Firma.
Mutuo-Signature: t=<time>,v1=<HMAC-SHA256>con el secretowhsec_del endpoint; los receptores deben rechazar marcas de tiempo de más de 5 minutos.Mutuo-Event-Idse mantiene igual entre entregas, para eliminar duplicados. - Entrega. Éxito es un 2xx en menos de 15 segundos. Las fallas se reintentan después de 1 minuto, 5 minutos, 30 minutos y 2, 5, 10 y 24 horas: 8 intentos en unas 42 horas; después, un administrador puede reenviar. Un endpoint que falla durante 3 días sin entregar nada se desactiva.
- Límites. Hasta 10 endpoints por organización, solo direcciones https públicas. Los eventos y las entregas se guardan 30 días.
- Página de Desarrolladores. Una primera llamada a la API lista para usar; las llaves de API con su alcance y último uso, creadas (se muestran una vez) y revocadas; los endpoints con su estatus y sus entregas pendientes y fallidas. La página de cada endpoint muestra y rota su secreto, lista las últimas 50 entregas con payload y respuesta, y puede reenviar una o mandar un evento de prueba.
Conector de Claude
Claude (claude.ai, las apps de escritorio y móvil, Claude Code) y otros asistentes pueden responder preguntas con datos en vivo de la cartera, hacer PDF de cotizaciones y, donde se permita, crear o cambiar registros después de una vista previa. Las cifras salen de los mismos cálculos que las páginas de la aplicación.
- Conexión. La página para hablar con Claude da la liga (
https://<site>/mcp), los pasos de configuración, el comando de Claude Code y siete preguntas de ejemplo. En claude.ai: Settings › Connectors › Add custom connector, pegar la liga, entrar a Mutio Core, elegir una organización y aprobar. - Una conexión por persona por organización. Con acceso mediante OAuth 2.1 con PKCE (códigos de 5 minutos, acceso de 1 hora, renovación de 60 días, rotados). Una conexión termina cuando la persona sale o es dada de baja, se desconecta o un administrador la revoca.
- Acceso de escritura. Requiere que la persona marque “También crear y cambiar registros” al aprobar, y un rol de miembro o superior en el momento de cada llamada. Para herramientas que no pueden iniciar sesión existen una contraseña compartida del conector y tokens de operador.
Las 34 herramientas
26 herramientas de lectura y 8 para crear o cambiar registros en dos pasos.
| Tipo | Herramientas |
|---|---|
| Clientes y crédito | search_clients, get_client, credit_case, client_documents, read_client_document |
| Originación | origination_case, prospect_documents, read_prospect_document, funding_pipeline (de fondeo o de originación) |
| Créditos | list_loans, get_loan, preview_payment |
| Cotizaciones | loan_quote, agro_loan_quote, funding_quote (cada una con una liga a PDF de 7 días) |
| Fondeos | list_funds, get_fund, funder_statement |
| Reportes | portfolio_summary, collections_report, upcoming_payments (1–92 días), payments_of_month, liquidity_forecast (1–60 meses o semanal), margin_report (1–36 meses), missing_contracts, data_quality_checks |
| Cambios en dos pasos | preview_new_loan → create_loan; preview_new_fund → create_fund; preview_loan_payment → record_loan_payment; preview_pipeline_change → apply_pipeline_change |
También hay un prompt, credit_case_summary, una redacción guiada del expediente de crédito de un cliente.
- Vista previa y luego confirmación. Una vista previa no cambia nada y devuelve una confirmación firmada, válida 30 minutos y ligada a esa conexión. La herramienta que crea, registra o aplica solo acepta esa confirmación, así que lo que se guarda es exactamente lo que se mostró. Un pago se rechaza si el crédito cambió desde su vista previa. Cada cambio se escribe en una tabla de auditoría.
- Lo que Claude puede crear. Créditos Simple, Actual/360 y Estacional; fondeos; pagos de créditos; prospectos y tareas de los pipelines.
- Manejo de datos. Las respuestas incluyen nombres, correos, teléfonos, RFC y domicilios, nunca CURP, números de identificación, fechas de nacimiento, estado civil ni cuentas bancarias fuera de documentos leídos a propósito. Cuando la suscripción terminó, las lecturas continúan y los cambios se rechazan.
Idiomas y marca
- Idiomas. Inglés y español por organización (unas 6,100 cadenas traducidas), incluidos mensajes y nombres de meses. Stripe Checkout y los correos de invitación siguen el idioma. Contratos, cotizaciones, estados de cuenta y correos a clientes siguen en español.
- Nombre y logo. El producto es Mutio Core. Los nombres técnicos se quedaron como estaban para que las integraciones existentes sigan funcionando: los encabezados
Mutuo-, el prefijo de llavemutuo_sk_y el nombre del servidor del conector. - La marca propia del prestamista. El nombre en documentos y el logo firman las cotizaciones en los tres diseños, los recordatorios de pago, los estados de cuenta a fondeadores y los PDF de estado de cuenta de fondeos, las cédulas de descuento de nómina y las hojas impresas de reuniones de grupo. Los correos cargan el logo desde una dirección pública, ya que los clientes de correo bloquean las imágenes incrustadas.