1. Fiduciary process
Maat.ai API
  • v4
    • Authentication
      • Get AccessToken by Email
    • BlackLists
      • OFAC Generate Report
      • PEPS Generate Report
      • SAT69
      • SAT69-B
    • Dextract
      • Extract information
    • Files
      • Upload file
      • Get file
    • SocialEconomic
      • Generate Report
      • Download PDF
    • SAT
      • Validate RFC
    • Quizes
      • Import answers from API
    • Fiduciary process
      • Download file
        GET
      • Generate/update fiduciary requests
        POST
      • Get business data with participants
        GET
      • Get participant personal information
        GET
      • Notification business complete from external (delete all information)
        POST
      • Notification of person with matches resolved
        POST
  1. Fiduciary process

Generate/update fiduciary requests

POST
/api/v4/fiduciary/request

Creación y actualización de solicitudes fiduciarias#

Este endpoint realiza una solicitud POST para crear un nuevo negocio fiduciario o actualizar uno existente mediante una solicitud complementaria.
Dependiendo del valor enviado en tipo_sol, el endpoint crea un negocio nuevo o sincroniza uno existente, permitiendo agregar, actualizar o eliminar participantes.
⚠️ IMPORTANTE: En las solicitudes complementarias (tipo_sol = 2), el arreglo participantes representa el estado completo y actual del negocio. Los participantes existentes que no sean enviados serán eliminados.#

Tipos de solicitud#

tipo_solDescripciónResultado cuando no se envía folio_juridicoResultado cuando sí se envía folio_juridico
1Inicial. Crea un negocio nuevo junto con sus participantes.Se crea el negocio y todos los participantes quedan sin folio jurídico.Se crea el negocio y todos los participantes reciben el folio jurídico, ya que todos son participantes nuevos.
2Complementaria. Actualiza un negocio existente sincronizando la información enviada.Los participantes nuevos se crean sin folio jurídico y los existentes únicamente se actualizan.Solo los participantes nuevos (id = 0, null o ausente) reciben el folio jurídico. Los participantes existentes conservan el folio jurídico que ya tenían.

Comportamiento de solicitudes complementarias#

Cuando tipo_sol = 2:
El negocio debe existir previamente.
El participante se identifica mediante id eid_persona.
Si los identificadores corresponden a un participante existente, éste es actualizado.
Si los identificadores no existen en el negocio, se crea un nuevo participante.
El arreglo participantes representa la lista completa vigente del negocio.
Todo participante existente que no sea enviado será eliminado del negocio.

Ejemplo de Solicitud#

Body#

Solicitud inicial (tipo_sol = 1)#

{
  "id_negocio": 0,
  "cod_negocio": "COD-0",
  "business_name": "",
  "tipo_sol": 1,
  "folio_juridico": "FJ-0",
  "responsible_user": {
    "name": "",
    "first_last_name": "",
    "second_last_name": "",
    "email": ""
  },
  "participantes": [
    {
      "id_persona": 0,
      "tipo_per": "FIS",
      "tipo_part": "",
      "nombre": "",
      "apellido_paterno": "",
      "apellido_materno": "",
      "email": "",
      "codigo_telefonico": "",
      "telefono": "",
      "mod_carga": "PER",
      "roles": [
        "A",
        "B"
      ],
      "tipo_doctos": [],
      "id_per_base": 0,
      "alias": "",
      "ocupacion": "",
      "id_fiscal": "",
      "codigo_pais_id_fiscal": ""
    },
    {
      "id_persona": 0,
      "tipo_per": "MOR",
      "nombre": "",
      "apellido_paterno": "",
      "apellido_materno": "",
      "email": "",
      "telefono": "",
      "mod_carga": "REP",
      "representante": {
        "nombre": "",
        "apellido_paterno": "",
        "apellido_materno": "",
        "email": "",
        "codigo_telefonico": "",
        "telefono": ""
      },
      "roles": [
        "A"
      ],
      "tipo_doctos": [
        {
          "cod_tipo_docto": "0",
          "id_descarga": 0
        }
      ]
    }
  ]
}

Solicitud complementaria (tipo_sol = 2)#

{
  "id_negocio": 0,
  "cod_negocio": "COD-0",
  "business_name": "",
  "tipo_sol": 2,
  "folio_juridico": "FJ-0",
  "responsible_user": {
    "name": "",
    "first_last_name": "",
    "second_last_name": "",
    "email": ""
  },
  "participantes": [
    {
      "id": 123,
      "id_persona": 5001,
      "tipo_per": "FIS",
      "tipo_part": "",
      "nombre": "",
      "apellido_paterno": "",
      "apellido_materno": "",
      "email": "",
      "codigo_telefonico": "",
      "telefono": "",
      "mod_carga": "PER",
      "roles": ["A", "B"],
      "tipo_doctos": [],
      "id_per_base": 0,
      "alias": "",
      "ocupacion": "",
      "id_fiscal": "",
      "codigo_pais_id_fiscal": ""
    },
    {
      "id": 0,
      "id_persona": 5002,
      "tipo_per": "MOR",
      "nombre": "",
      "apellido_paterno": "",
      "apellido_materno": "",
      "email": "",
      "telefono": "",
      "mod_carga": "REP",
      "representante": {
        "nombre": "",
        "apellido_paterno": "",
        "apellido_materno": "",
        "email": "",
        "codigo_telefonico": "",
        "telefono": ""
      },
      "roles": ["A"],
      "tipo_doctos": [
        {
          "cod_tipo_docto": "0",
          "id_descarga": 0
        }
      ]
    }
  ]
}

Descripción de contenido en el body#

Campos principales#

NombreObligatorioDescripción
id_negocioSíIdentificador externo del negocio. Debe ser mayor que 0.
cod_negocioSíCódigo externo del negocio.
business_nameNoNombre del negocio.
tipo_solSíTipo de solicitud: 1 = Inicial, 2 = Complementaria.
folio_juridicoNoFolio del acto jurídico que será asignado únicamente a los participantes nuevos creados durante la solicitud.
responsible_userNoInformación del responsable del negocio.
participantesSíLista de participantes del negocio. Debe contener al menos un participante.

Campos del participante#

CampoObligatorioDescripción
idNoIdentificador interno del participante. Si es mayor que 0, el participante se considera existente. Si es 0, null o no se envía, el participante se considera nuevo.
id_personaSíIdentificador externo de la persona.
tipo_perSíTipo de persona. Valores permitidos: FIS (Persona Física) o MOR (Persona Moral).
tipo_partNoTipo de participante.
nombreSíNombre del participante.
apellido_paternoSíApellido paterno.
apellido_maternoSíApellido materno.
emailSíCorreo electrónico.
codigo_telefonicoNoLada o código telefónico internacional.
telefonoSíNúmero telefónico.
mod_cargaSíModo de carga documental. Valores permitidos: PER (documentación propia) o REP (mediante representante).
representanteCondicionalObligatorio cuando mod_carga es REP.
rolesSíLista de roles del participante dentro del negocio.
tipo_doctosNoLista de documentos asociados al participante.
id_per_baseNoIdentificador de la persona base asociada al participante.
aliasNoAlias del participante.
ocupacionNoOcupación.
id_fiscalNoRFC o identificador fiscal.
codigo_pais_id_fiscalNoCódigo ISO del país del identificador fiscal.

Funcionamiento de roles#

El campo roles permite enviar uno o varios roles para un mismo participante.
"roles": [ "A", "B"]
Cada elemento del arreglo:
Debe corresponder exactamente a una clave configurada en el catálogo fiduciario del cliente.
No es un valor libre.
Se valida contra el catálogo de roles configurado para el cliente.
Puede enviarse uno o varios roles.
Cuando el nodo tipo_doctos no se envía o se envía vacío, los roles serán utilizados para determinar los documentos que deberán solicitarse al participante.
Si se envía el nodo tipo_doctos con uno o más documentos, éstos serán utilizados y los documentos asociados a los roles no serán considerados.
Si alguno de los roles enviados no existe en el catálogo correspondiente, la solicitud devolverá un error indicando que uno o más roles no pudieron ser asignados.
Si un rol ya se encuentra asignado al participante, éste no se duplica.

Funcionamiento de folio_juridico#

El campo folio_juridico es opcional y representa el folio asociado a un acto jurídico.
Cuando se envía:
Se asigna únicamente a los participantes nuevos (id = 0, null o ausente).
No modifica el folio jurídico de participantes existentes (id > 0).
El negocio queda marcado automáticamente como que contiene participantes asociados a un acto jurídico.
Cuando no se envía:
Los participantes se crean o actualizan normalmente.
Ningún participante recibe un folio jurídico.

Ejemplo de Respuesta#

{
  "data": {},
  "success": true,
  "message": "Business request processed successfully"
}
IMPORTANTE:
tipo_sol únicamente acepta los valores 1 (Inicial) y 2 (Complementaria).
En solicitudes iniciales (tipo_sol = 1), el negocio no debe existir previamente.
En solicitudes complementarias (tipo_sol = 2), el negocio debe existir previamente.
Es obligatorio enviar al menos un participante dentro del arreglo participantes.
Si mod_carga es REP, el objeto representante es obligatorio.
Los valores enviados en roles deben existir previamente en el catálogo fiduciario configurado para el cliente; de lo contrario, la solicitud devolverá un error.
folio_juridico es opcional y únicamente se asigna a los participantes nuevos de la solicitud.
En solicitudes complementarias, el arreglo participantes representa el estado completo del negocio; los participantes omitidos serán eliminados.
Es necesario enviar los headers x-api-key, service y Authorization con un Bearer Token válido para evitar errores de autenticación.
En caso de error general, la respuesta incluirá el campo code_message, el cual puede variar dependiendo del tipo de error (por ejemplo: invalid_request, unauthorized o server_error).

Solicitud

Parámetros de Header

Parámetros del Body application/json

Ejemplos

Respuestas

🟢200Success generate/update
application/json
Bodyapplication/json

🟠400Invalid request
🔴500Error processing fiduciary requests
Solicitud Ejemplo de Solicitud
Shell
JavaScript
Java
Swift
curl --location '/api/v4/fiduciary/request' \
--header 'x-api-key: {{api-key}}' \
--header 'service: {{service}}' \
--header 'Content-Type: application/json' \
--data '//  Initial
{
  "id_negocio": 0, // ID externo del negocio (obligatorio, > 0)
  "cod_negocio": "COD-0", // Código externo del negocio (obligatorio)
  "business_name": "", // Nombre del negocio (opcional)
  "tipo_sol": 1, // Tipo de solicitud: 1 = alta inicial, 2 = complementaria (obligatorio)
  "folio_juridico": "FJ-0", // Folio de acto jurídico (opcional, todos los participantes son nuevos, el folio se les asigna a todos)
  "responsible_user": { // Usuario responsable del negocio (opcional)
    "name": "", // Nombre (requerido)
    "first_last_name": "", // Apellido paterno (requerido)
    "second_last_name": "", // Apellido materno (requerido)
    "email": "" // Correo (requerido)
  },
  "participantes": [ // Arreglo de participantes (obligatorio, mínimo 1)
    {
      "id_persona": 0, // ID externo de la persona (obligatorio)
      "tipo_per": "FIS | MOR", // Tipo de persona: física o moral (obligatorio)
      "tipo_part": "", // Tipo de participante (opcional)
      "nombre": "", // Nombre (obligatorio)
      "apellido_paterno": "", // Apellido paterno (obligatorio)
      "apellido_materno": "", // Apellido materno (obligatorio)
      "email": "", // Correo (obligatorio)
      "codigo_telefonico": "", // Lada/código de país del teléfono (opcional)
      "telefono": "", // Teléfono (obligatorio)
      "mod_carga": "PER", // Modo de carga de documentos: "PER" = propia, "REP" = vía representante (obligatorio)
      "roles": ["A","B"], // Roles del participante en el negocio, debe coincidir con el nombre definido en el catalogo de cliente (obligatorio)
      "tipo_doctos": [], // Documentos requeridos (opcional)
      "id_per_base": 0, // ID de persona base, a la cual esta ligada (opcional)
      "alias": "", // Alias del participante (opcional)
      "ocupacion": "", // Ocupación (opcional)
      "id_fiscal": "", // RFC / ID fiscal (opcional)
      "codigo_pais_id_fiscal": "" // Código país ISO del ID fiscal, ej. MX, US (opcional)
    },
    {
      "id": null,
      "id_persona": 0,
      "tipo_per": "FIS | MOR",
      "nombre": "",
      "apellido_paterno": "",
      "apellido_materno": "",
      "email": "",
      "telefono": "",
      "mod_carga": "REP", // Con "REP" se debe incluir "representante"
      "representante": { // Datos del representante legal (obligatorio si mod_carga="REP")
        "nombre": "", // Nombre (obligatorio)
        "apellido_paterno": "", // Apellido paterno (obligatorio)
        "apellido_materno": "", // Apellido materno (obligatorio)
        "email": "", // Correo (obligatorio)
        "codigo_telefonico": "", // Lada/código de país (opcional)
        "telefono": "" // Teléfono (obligatorio)
      },
      "roles": ["A"],
      "tipo_doctos": [
        {
          "cod_tipo_docto": "0", // Código del tipo de documento (obligatorio)
          "id_descarga": 0 // ID de descarga del documento en el sistema externo (opcional)
        },
        {
          "cod_tipo_docto": "0",
          "id_descarga": 0
        }
      ]
    }
  ]
}

// Complementary
// Se requiere enviar todo el payload completo como en tipo_sol = 1.
/*{
  "id_negocio": 0, // ID externo del negocio YA EXISTENTE (obligatorio, debe existir o da error)
  "cod_negocio": "COD-0", 
  "business_name": "",
  "tipo_sol": 2, // 2 = complementaria (obligatorio)
  "folio_juridico": "FJ-0", // Opcional. Solo se asigna en participantes que NO existían
  "responsible_user": {
    "name": "",
    "first_last_name": "",
    "second_last_name": "",
    "email": ""
  },
  "participantes": [ // OJO: se trata como la lista COMPLETA vigente. Cualquier participante que YA
    // estaba en el negocio y NO aparezca aquí, se ELIMINA
    {
      "id": 0, // Necesario para asignar folio juridico a los nuevos y no a todos (incluyendo existentes)
      "id_persona": 5001, // OBLIGATORIO en complementaria. Es lo que hace el match contra BD:
      //   - si coincide con un participante ya guardado -> se ACTUALIZA
      //   - si no coincide con ninguno -> se CREA como nuevo
      "tipo_per": "FIS | MOR",
      "tipo_part": "",
      "nombre": "",
      "apellido_paterno": "",
      "apellido_materno": "",
      "email": "",
      "codigo_telefonico": "",
      "telefono": "",
      "mod_carga": "PER",
      "roles": ["A","B"],
      "tipo_doctos": [], 
      "id_per_base": 0,
      "alias": "", //
      "ocupacion": "",
      "id_fiscal": "",
      "codigo_pais_id_fiscal": ""
    },
    {
      "id": null,
      "id_persona": 0,
      "tipo_per": "FIS | MOR",
      "nombre": "",
      "apellido_paterno": "",
      "apellido_materno": "",
      "email": "",
      "telefono": "",
      "mod_carga": "REP",
      "representante": {
        "nombre": "",
        "apellido_paterno": "",
        "apellido_materno": "",
        "email": "",
        "codigo_telefonico": "",
        "telefono": ""
      },
      "roles": ["A"],
      "tipo_doctos": [
        {
          "cod_tipo_docto": "0",
          "id_descarga": 0
        }
      ]
    }
  ]
}*/'
Respuesta Ejemplo de Respuesta
200 - Success generate/update
{
  "data": {
    "code_message": "data_saved",
    "business_id": 0
  },
  "message": "Fiduciary data saved successfully",
  "success": true
}
Modificado en 2026-07-10 22:01:24
Anterior
Download file
Siguiente
Get business data with participants
Built with