> ## Documentation Index
> Fetch the complete documentation index at: https://docs.firma.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Obtener Solicitud de Firma

> Recupera una Solicitud de Firma específica por ID



## OpenAPI

````yaml api-reference/v01.30.00/openapi-v01.30.00.es.json get /signing-requests/{id}
openapi: 3.0.3
info:
  title: API de Socios de Firma
  description: >-
    API RESTful para firma de documentos y gestión de plantillas.


    **Autenticación**: Todos los endpoints requieren autenticación mediante
    clave API a través del encabezado `Authorization`. Usa tu clave API
    directamente sin ningún prefijo (por ejemplo, `your-api-key`). El prefijo
    Bearer es opcional pero no obligatorio.


    **Características de Seguridad**:

    - Validación de entrada usando esquemas Zod con mensajes de error detallados
    a nivel de campo

    - Tokens JWT firmados con RSA-256 para el acceso al Editor de Plantillas
    incrustado


    **Límite de Solicitudes**: Los límites de solicitudes están escalonados
    según el tipo de operación:

    - Operaciones de lectura (GET): 200 solicitudes por minuto

    - Operaciones de escritura (POST/PUT/PATCH/DELETE): 120 solicitudes por
    minuto

    - Operaciones CRUD de webhooks: 60 solicitudes por minuto

    - Prueba de webhook: 10 solicitudes por minuto

    - Regeneración/expiración de clave API: 1 solicitud por minuto

    - Rotación de secreto de webhook: 1 solicitud por minuto


    Cuando se superan los límites de solicitudes, la API devuelve una respuesta
    `429 Too Many Requests` con los encabezados:

    - `X-RateLimit-Limit`: Máximo de solicitudes por minuto para este endpoint

    - `X-RateLimit-Remaining`: Solicitudes restantes en la ventana actual

    - `X-RateLimit-Reset`: Marca de tiempo Unix de cuándo se restablece el
    límite

    - `Retry-After`: Segundos hasta que se permita reintentar


    **Manejo de Errores**: Todos los errores devuelven respuestas JSON
    estructuradas con `error` (mensaje legible para humanos), `code`
    (identificador legible por máquina) y `details` (errores de validación a
    nivel de campo cuando corresponda).


    **Integración del Editor de Plantillas Incrustado**: El Editor de Plantillas
    de Firma se puede incrustar en tu aplicación usando una biblioteca
    JavaScript independiente.


    ```html

    <!-- Carga la biblioteca del Editor de Plantillas de Firma -->

    <script
    src="https://api.firma.dev/functions/v1/embed-proxy/template-editor.js"></script>


    <script>

    // Genera el token JWT vía API primero

    fetch('https://api.firma.dev/functions/v1/signing-request-api/generate-template-token',
    {
      method: 'POST',
      headers: {
        'Authorization': 'YOUR_API_KEY',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        companies_workspaces_templates_id: 'template-id'
      })
    })

    .then(res => res.json())

    .then(data => {
      // Inicializa el editor con el token JWT
      window.FirmaTemplateEditor.init({
        container: '#firma-editor-container',
        jwt: data.token,
        templateId: 'template-id',
        theme: 'dark',
        readOnly: false,
        onSave: (savedData) => {
          console.log('Template saved:', savedData);
        },
        onError: (error) => {
          console.error('Editor error:', error);
        },
        onLoad: (template) => {
          console.log('Template loaded:', template);
        }
      });
    });

    </script>

    ```
  version: 01.30.00
  contact:
    name: API Support
    url: https://firma.com/support
servers:
  - url: https://api.firma.dev/functions/v1/signing-request-api
    description: API de Producción - Recomendada (Actual)
  - url: https://api.firma.dev/api/v1
    description: API de Producción - Planeada
security:
  - ApiKeyAuth: []
tags:
  - name: Company
    description: Información y configuración de la empresa
  - name: Workspaces
    description: Operaciones de gestión de espacios de trabajo
  - name: Templates
    description: Operaciones de gestión de plantillas
  - name: Signing Requests
    description: Operaciones de solicitudes de firma de documentos
  - name: Custom Fields
    description: >-
      Gestión de definiciones de campos personalizados para espacios de trabajo,
      plantillas y solicitudes de firma
  - name: Webhooks
    description: Configuración y gestión de webhooks
  - name: JWT Management
    description: Generación y revocación de tokens JWT para plantillas incrustadas
  - name: Workspace Settings
    description: Configuración y ajustes del espacio de trabajo
  - name: Email Domains
    description: >-
      Configuración y verificación de dominios de correo electrónico para enviar
      correos de solicitudes de firma desde dominios personalizados
  - name: Email Templates
    description: >-
      Gestión de plantillas de correo electrónico para personalización de
      notificaciones de solicitudes de firma a nivel de espacio de trabajo y de
      empresa
  - name: Signer Terms
    description: >-
      Términos de servicio / declaraciones de consentimiento personalizadas del
      firmante, a nivel de empresa con anulaciones por espacio de trabajo según
      el idioma
paths:
  /signing-requests/{id}:
    get:
      tags:
        - Signing Requests
      summary: Obtener Solicitud de Firma
      description: Recupera una Solicitud de Firma específica por ID
      operationId: getSigningRequest
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: >-
            Solicitud de Firma recuperada correctamente. Devuelve una estructura
            anidada detallada con status como un objeto y las marcas de tiempo
            agrupadas.
          headers:
            X-RateLimit-Limit:
              schema:
                type: integer
              description: 'Límite de tasa: 200 solicitudes por minuto'
            X-RateLimit-Remaining:
              schema:
                type: integer
            X-RateLimit-Reset:
              schema:
                type: integer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SigningRequestDetail'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '429':
          $ref: '#/components/responses/RateLimitError'
      security:
        - ApiKeyAuth: []
      x-codeSamples:
        - lang: TypeScript
          label: '@firma-dev/sdk'
          source: |-
            import { FirmaClient } from "@firma-dev/sdk";

            const firma = new FirmaClient({ apiKey: "YOUR_API_KEY" });

            const response = await firma.signingRequests.getSigningRequest({
                id: "id"
            });
            console.log(response);
components:
  schemas:
    SigningRequestDetail:
      type: object
      description: >-
        Solicitud de Firma detallada, tal como la devuelve GET
        /signing-requests/{id} (forma anidada con objeto status y timestamps)
      properties:
        id:
          type: string
          format: uuid
          description: Identificador único de la Solicitud de Firma
        name:
          type: string
          description: Nombre de la Solicitud de Firma
        template_description:
          type: string
          nullable: true
          description: Descripción de la Plantilla
        companies_workspaces_id:
          type: string
          format: uuid
          description: ID del Espacio de Trabajo al que pertenece esta Solicitud de Firma
        document_url:
          type: string
          format: uri
          description: URL prefirmada al documento PDF
        document_url_expires_at:
          type: string
          format: date-time
          nullable: true
        document_page_count:
          type: integer
          minimum: 1
          description: Cantidad de páginas del documento
        expiration_hours:
          type: integer
          description: Horas hasta que expira la Solicitud de Firma
        expires_at:
          type: string
          format: date-time
          nullable: true
          description: >-
            Timestamp ISO 8601 de cuándo expira la Solicitud de Firma. Se
            calcula a partir de sent_on + expiration_hours. Es null si aún no se
            envió o si no se estableció expiration_hours.
        credit_cost:
          type: integer
          description: Créditos consumidos al enviarse
        status:
          type: object
          description: >-
            Indicadores de estado (pueden ser true varios a la vez en estados
            terminales)
          properties:
            sent:
              type: boolean
            finished:
              type: boolean
            cancelled:
              type: boolean
            declined:
              type: boolean
            expired:
              type: boolean
        timestamps:
          type: object
          description: >-
            Todos los timestamps relevantes del ciclo de vida de la Solicitud de
            Firma
          properties:
            created_on:
              type: string
              format: date-time
            sent_on:
              type: string
              format: date-time
              nullable: true
            finished_on:
              type: string
              format: date-time
              nullable: true
            cancelled_on:
              type: string
              format: date-time
              nullable: true
            declined_on:
              type: string
              format: date-time
              nullable: true
            last_changed_on:
              type: string
              format: date-time
            last_signing_action_on:
              type: string
              format: date-time
              nullable: true
        settings:
          $ref: '#/components/schemas/SigningRequestSettings'
        use_signing_order:
          type: integer
          enum:
            - 0
            - 1
          deprecated: true
        allow_download:
          type: integer
          enum:
            - 0
            - 1
          deprecated: true
        allow_editing_before_sending:
          type: integer
          enum:
            - 0
            - 1
          deprecated: true
        hand_drawn_only:
          type: integer
          enum:
            - 0
            - 1
          deprecated: true
        attach_pdf_on_finish:
          type: integer
          enum:
            - 0
            - 1
          deprecated: true
        certificate:
          type: object
          nullable: true
          description: Información del estado de generación del certificado
          properties:
            generated:
              type: boolean
              description: Si el PDF del certificado final ya fue generado
            generated_on:
              type: string
              format: date-time
              nullable: true
              description: Timestamp de cuándo se generó el certificado
            has_error:
              type: boolean
              description: Si hubo un error al generar el certificado
        final_document_download_url:
          type: string
          format: uri
          nullable: true
          description: >-
            URL firmada para descargar el documento final firmado (PDF con
            certificado). La URL expira después de 1 hora.
        final_document_download_error:
          type: string
          nullable: true
          enum:
            - file_not_accessible
            - null
        document_only_download_url:
          type: string
          format: uri
          nullable: true
          description: >-
            URL firmada para descargar el PDF solo del documento. La URL expira
            después de 1 hora.
        document_only_download_error:
          type: string
          nullable: true
          enum:
            - file_not_accessible
            - null
        certificate_only_download_url:
          type: string
          format: uri
          nullable: true
          description: >-
            URL firmada para descargar el PDF solo del certificado. La URL
            expira después de 1 hora.
        certificate_only_download_error:
          type: string
          nullable: true
          enum:
            - file_not_accessible
            - null
      required:
        - id
        - name
        - status
        - companies_workspaces_id
    SigningRequestSettings:
      type: object
      description: >-
        Configuración devuelta por los endpoints de listado y detalle de
        Solicitudes de Firma. Las Plantillas usan el esquema TemplateSettings
        (sin campos de identidad).
      properties:
        allow_download:
          type: boolean
          description: Si los destinatarios pueden descargar el documento
          default: true
        attach_pdf_on_finish:
          type: boolean
          description: Si se debe adjuntar el PDF cuando se completa la firma
          default: true
        allow_editing_before_sending:
          type: boolean
          description: Si la Solicitud de Firma se puede editar antes de enviarse
          default: false
        use_signing_order:
          type: boolean
          description: >-
            Si se aplica un orden de firma entre los destinatarios. Cuando es
            true, los Firmantes reciben el documento en secuencia según su
            order. Cuando es false, todos los Firmantes reciben el documento al
            mismo tiempo.
          default: true
        hand_drawn_only:
          type: boolean
          description: >-
            Cuando está habilitado, los Firmantes solo pueden dibujar su firma a
            mano y no pueden usar firmas escritas/basadas en fuente
          default: false
        send_signing_email:
          type: boolean
          description: >-
            Si se deben enviar correos de notificación de la Solicitud de Firma
            a los Firmantes
          default: true
        send_finish_email:
          type: boolean
          description: >-
            Si se debe enviar un correo de finalización cuando todos los
            Firmantes terminan
          default: true
        send_expiration_email:
          type: boolean
          description: >-
            Si se debe enviar un correo de notificación de expiración cuando la
            solicitud expira
          default: true
        send_cancellation_email:
          type: boolean
          description: >-
            Si se debe enviar un correo de notificación de cancelación cuando se
            cancela la solicitud
          default: true
        require_otp_verification:
          type: boolean
          nullable: true
          description: >-
            Si los Firmantes deben verificar su correo con un código de un solo
            uso antes de acceder al documento. null = hereda la configuración
            del Espacio de Trabajo/empresa.
          default: null
        disable_guided_navigation:
          type: boolean
          nullable: true
          description: >-
            Desactiva el desplazamiento automático al siguiente campo requerido
            durante la firma. Hereda del Espacio de Trabajo o de la empresa si
            no está configurado.
        allow_presigning_download:
          type: boolean
          nullable: true
          description: >-
            Permite a los Firmantes descargar el documento original antes de
            firmar. Hereda de la configuración del Espacio de Trabajo o de la
            empresa cuando es null.
        show_qr_code:
          type: boolean
          nullable: true
          description: >-
            Muestra un código QR en la página de firma que permite a los
            Firmantes continuar desde su teléfono. Hereda de la configuración
            del Espacio de Trabajo o de la empresa cuando es null.
        identity_editable_fields:
          type: array
          nullable: true
          items:
            type: string
          description: >-
            Campos de identidad que los Firmantes pueden editar antes de firmar
            (por ejemplo, ["name", "company"]). null = desactivado. Cuando está
            configurado, un diálogo de confirmación permite a los Firmantes
            editar los campos especificados.
        notify_identity_change_email:
          type: boolean
          default: false
          description: >-
            Envía una notificación por correo cuando un Firmante cambia su
            identidad.
    Error:
      type: object
      properties:
        error:
          type: string
          description: Mensaje de error legible para humanos
        message:
          type: string
          description: Descripción detallada del error
        details:
          type: object
          description: Detalles adicionales del error
          additionalProperties: true
      required:
        - error
  responses:
    UnauthorizedError:
      description: No Autorizado - Clave API inválida o faltante
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: Unauthorized
            message: Invalid API key
    NotFoundError:
      description: No Encontrado - El recurso no existe
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: Not Found
            message: The requested resource was not found
    RateLimitError:
      description: Demasiadas Solicitudes - Se superó el límite de solicitudes
      headers:
        X-RateLimit-Limit:
          schema:
            type: integer
          description: Número máximo de solicitudes por minuto
        X-RateLimit-Remaining:
          schema:
            type: integer
          description: Solicitudes restantes
        X-RateLimit-Reset:
          schema:
            type: integer
          description: Marca de tiempo Unix del reinicio
        Retry-After:
          schema:
            type: integer
          description: Segundos hasta que se permita reintentar
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: Rate Limit Exceeded
            message: Too many requests. Please wait before retrying.
            details:
              retry_after: 45
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: >-
        Clave API para autenticación. Usa tu clave API directamente sin ningún
        prefijo (por ejemplo, 'your-api-key'). El prefijo Bearer es opcional
        pero no obligatorio.

````