Firma Virtual México - Clientes API
    • API
      • OAuth2
        • tokenExchange
        • getAuthorizationServerInfo
        • authMe
      • IntegrationMarketplace
        • marketplaceSetup
        • marketplaceProvision
        • marketplaceAuthorize
      • Documents
        • createDocument
        • getAllDocumentsByMe
        • getDocumentByIdAndMe
        • getDocumentStatisticsByMe
      • Files
        • uploadBiometryFiles
        • downloadByFileName
        • downloadBiometryMedia
      • Signatures
        • signDocument
      • SignatureCreditAccount
        • getSignatureCreditAccountByMe
      • SignatureCreditAccountMovement
        • getAllSignatureCreditAccountMovementsByMe
        • getSignatureCreditAccountMovementByIdAndMe
      • PurchaseOrder
        • getAllPurchasesByMe
      • SignaturePackages
        • getAllPackages
      • Mails
        • forwardBiometricValidation
      • SubUsers
        • getAllSubusersByMe
        • createSubuserByMe
      • SubClients
        • getAllSubclientsByMe
        • createSubclientByMe

    Firma Virtual Mexico - Clientes API

    La API "Firma Virtual México Clientes API" está diseñada para facilitar la gestión y automatización de procesos relacionados con la firma electrónica en México. Esta API RESTful permite la interacción con diversas funcionalidades para administrar documentos, pagos, archivos y transacciones de firma electrónica de manera segura y eficiente.

    Características principales:#

    Autenticación segura: Basada en OAuth2 (Authorization Code, Client Credentials y Refresh Token) para garantizar la integridad y confidencialidad de las operaciones.
    Manejo de documentos: Subida, consulta, descarga y administración de documentos para firma.
    Procesos de firma: Inicio, monitoreo y finalización de transacciones de firma electrónica.
    Cumplimiento normativo: Compatible con los estándares legales y regulatorios aplicables en México.
    Integración vía OAuth2: Soporte para integraciones directas API-to-API y para instalación desde marketplaces y ERPs de terceros (p. ej. Shopify, Odoo, Monday), mediante un flujo de autorización estándar, descubrimiento automático de configuración (metadata discovery) y renovación de tokens sin interrupción del servicio.
    Estructura multitenant: Administración jerárquica de subclientes y subusuarios, con políticas configurables de límites y permisos por cuenta.
    Gestión de créditos de firma: Consulta de saldo, historial de movimientos y órdenes de compra de paquetes de firma.

    Organización por carpetas:#

    La API está estructurada en carpetas para facilitar la navegación y pruebas:
    1.
    OAuth2: Endpoints para autenticación, intercambio/renovación de tokens y descubrimiento de la configuración del servidor de autorización.
    2.
    IntegrationMarketplace: Endpoints para instalar y aprovisionar la integración desde marketplaces o ERPs de terceros.
    3.
    Documents: Endpoints para crear y consultar documentos.
    4.
    Files: Endpoints para subida y descarga de archivos relacionados a los documentos.
    5.
    Signatures: Endpoint para realizar el proceso de firma de documentos.
    6.
    SubClients: Endpoints para crear y consultar subclientes bajo la cuenta del cliente autenticado.
    7.
    SubUsers: Endpoints para crear y consultar subusuarios bajo la cuenta del cliente autenticado.
    8.
    SignatureCreditAccount: Endpoint para consultar el saldo de créditos de firma del usuario autenticado.
    9.
    SignatureCreditAccountMovement: Endpoints para consultar el historial de movimientos de la cuenta de créditos de firma.
    10.
    PurchaseOrders: Endpoints para crear la orden de compra de los paquetes de firma y consultar las órdenes creadas.
    11.
    SignaturePackages: Endpoint que permite consultar el listado de los paquetes de firma disponibles en la plataforma.
    12.
    Mails: Endpoints que realizan el envío de mails específicos.
    Este diseño garantiza que los desarrolladores puedan integrarse rápidamente y aprovechar las funcionalidades de Firma Virtual México para sus soluciones empresariales.

    Flujo de Creación de Documentos#

    A continuación se describe el flujo completo del proceso para el registro de usuario, creación del documento, firma electrónica y entrega de documento firmado.
    creacion-y-firma-documentos-firma-virtual-mexico.webp
    1.
    Registro de usuario:
    a. El usuario accede al sistema de registro de nuestra plataforma.
    b. Proporciona la información requerida, como nombre, dirección de correo electrónico y contraseña.
    c. El sistema verifica la validez de los datos proporcionados y registra al usuario en la plataforma.
    d. El usuario recibe una confirmación de registro.
    2.
    Creación de Documento:
    a. El usuario inicia sesión en la plataforma utilizando sus credenciales.
    b. Accede a la funcionalidad de creación de documentos.
    c. Proporciona los detalles necesarios del documento, como partes involucradas.
    d. El documento se guarda en la plataforma y se asigna un identificador único.
    3.
    Validación biométrica y firma electrónica del documento:
    a. El usuario selecciona el documento que desea firmar electrónicamente.
    b. El sistema genera un enlace para iniciar el proceso de validación biométrica y lo envía al usuario por correo electrónico.
    c. El usuario recibe la notificación por correo y accede al enlace de firma.
    d. Desde su dispositivo (teléfono o PC), el usuario es guiado a través del proceso de firma electrónica.
    e. El usuario inicia el proceso de firma con el flujo de validación biométrica, donde se capturan fotográfias del rostro y el documento de identidad, para proceder a aceptar los términos y condiciones y firmar el documento. Este proceso lo deben realizar todos los firmantes del documento.
    f. El sistema registra las firmas electrónicas y las asocia al documento correspondiente.
    g. Se envía un correo electrónico de confirmación con el documento firmado y el NOM de validación para su posterior revisión.
    Este flujo de proceso completo permite a los usuarios registrarse, crear documentos y firmar documentos, todo ello de manera eficiente y segura dentro de nuestra plataforma.

    Flujo de Integración por OAuth2#

    A continuación se describe el flujo completo del proceso de integración vía OAuth2, desde la instalación de la aplicación (ya sea por un marketplace externo o de forma directa API-to-API) hasta el consumo de los recursos protegidos de la plataforma.
    oauth2-integration-flow.webp
    1.
    Registro e instalación (GET /marketplace/setup)
    a. El marketplace externo (Shopify, Odoo, etc.) redirige al navegador del cliente hacia el endpoint de setup, enviando los datos de la tienda/cuenta de origen y del contacto principal.
    b. Si el correo no existe, se crea el cliente (tipo PARTNER), su política de límites y el usuario administrador; si ya existe, se reutiliza el registro sin duplicar información.
    c. Se genera una sesión autenticada (cookie JWT) y se redirige automáticamente al siguiente paso.
    2.
    Aprovisionamiento (GET /oauth2/integration/marketplace/provision)
    a. Ya autenticado por la cookie de sesión, se crea (o recupera) el registro de la aplicación de integración para ese cliente.
    b. Si es una integración nueva, se genera automáticamente el client_secret correspondiente y se notifica por correo.
    c. Se redirige al paso de autorización con los parámetros OAuth2 necesarios (client_app_id, scope, redirect_uri, state).
    3.
    Autorización (GET /oauth2/integration/marketplace/authorize)
    a. Se validan los parámetros de la solicitud (tipo de respuesta, alcances solicitados, URI de redirección y protección CSRF vía state).
    b. Se genera un código de autorización de un solo uso, válido por tiempo limitado.
    c. Se redirige al callback con el código generado.
    4.
    Intercambio de credenciales (GET /oauth2/integration/marketplace/callback o POST /oauth/token)
    a. El código de autorización se intercambia por un access_token y un refresh_token.
    b. Si la aplicación es nueva, la respuesta incluye también el client_app_id y el client_secret a conservar por el desarrollador para futuras renovaciones.
    c. Para integraciones directas (sin marketplace), el mismo intercambio puede realizarse vía client_credentials (comunicación servidor a servidor) o refresh_token (renovación de un token vigente).
    5.
    Consumo de recursos protegidos (/oauth2/integration/*)
    a. Cada solicitud a los recursos de la API se autentica enviando el access_token en el header Authorization: Bearer, junto con el header X-Client-App-UUID que identifica a la aplicación integrada.
    b. Alternativamente, el flujo basado en navegador puede autenticarse mediante la cookie de sesión JWT.
    6.
    Renovación y rotación de tokens
    a. Cuando el access_token expira, se renueva mediante grant_type=refresh_token, obteniendo un nuevo par de tokens.
    b. Por seguridad, cada renovación invalida el refresh_token anterior; si se detecta su reutilización, se revoca toda la sesión de tokens asociada.
    7.
    Revocación (POST /oauth/revoke)
    a. El desarrollador puede desconectar la integración en cualquier momento, revocando todos los tokens activos y desactivando la aplicación registrada.
    b. Para reconectar posteriormente, el flujo de aprovisionamiento genera una nueva aplicación de integración.
    Este flujo de proceso completo permite a plataformas externas y desarrolladores integrarse con Firma Virtual México de forma segura y estandarizada, ya sea a través de un marketplace o de manera directa API-to-API, garantizando en todo momento la protección de las credenciales y de los recursos del cliente.
    Modificado en 2026-08-24 19:57:24
    Siguiente
    OAuth2
    Built with