> ## 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.

# Crear un nuevo espacio de trabajo

> Crea un nuevo espacio de trabajo para la empresa autenticada. Todos los espacios de trabajo se crean como no protegidos de forma predeterminada. El estado de protección solo se puede establecer durante la creación de la cuenta de la empresa.



## OpenAPI

````yaml api-reference/v01.30.00/openapi-v01.30.00.es.json post /workspaces
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:
  /workspaces:
    post:
      tags:
        - Workspaces
      summary: Crear un nuevo espacio de trabajo
      description: >-
        Crea un nuevo espacio de trabajo para la empresa autenticada. Todos los
        espacios de trabajo se crean como no protegidos de forma predeterminada.
        El estado de protección solo se puede establecer durante la creación de
        la cuenta de la empresa.
      operationId: createWorkspace
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - name
              properties:
                name:
                  type: string
                  description: Nombre del espacio de trabajo
                  maxLength: 255
            example:
              name: Marketing Workspace
      responses:
        '201':
          description: Espacio de trabajo creado correctamente
          headers:
            X-RateLimit-Limit:
              schema:
                type: integer
              description: 'Límite de tasa: 120 solicitudes por minuto'
            X-RateLimit-Remaining:
              schema:
                type: integer
              description: Solicitudes restantes en la ventana actual
            X-RateLimit-Reset:
              schema:
                type: integer
              description: Marca de tiempo Unix en la que se restablece el límite de tasa
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Workspace'
              example:
                id: abc12345-e89b-12d3-a456-426614174000
                name: Marketing Workspace
                protected: false
                api_key: fk_m1n2o3p4q5r6s7t8u9v0
                created_date: '2024-01-25T14:00:00Z'
                updated_date: '2024-01-25T14:00:00Z'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '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.workspaces.createWorkspace({
                name: "Marketing Workspace"
            });
            console.log(response);
components:
  schemas:
    Workspace:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Identificador único del espacio de trabajo
        name:
          type: string
          description: Nombre del espacio de trabajo
          maxLength: 255
        protected:
          type: boolean
          description: Los espacios de trabajo protegidos no se pueden eliminar
        api_key:
          type: string
          description: >-
            Clave API de modo real para este espacio de trabajo. Se usa para
            autenticar solicitudes de API limitadas a este espacio de trabajo.
          nullable: true
        test_api_key:
          type: string
          description: >-
            Clave API de modo de prueba para este espacio de trabajo. Las
            solicitudes autenticadas con esta clave no consumen créditos y
            generan solicitudes de firma marcadas como de prueba, con marca de
            agua.
          nullable: true
        created_date:
          type: string
          format: date-time
          description: Marca de tiempo de creación del espacio de trabajo
        updated_date:
          type: string
          format: date-time
          description: Marca de tiempo de la última actualización del espacio de trabajo
        webhook_enabled:
          type: boolean
          description: >-
            Indica si los webhooks a nivel de espacio de trabajo están
            habilitados
        webhook_secret:
          type: string
          description: Secreto de firma de webhook para este espacio de trabajo
          nullable: true
        webhook_secret_rotated_at:
          type: string
          format: date-time
          description: Marca de tiempo de la última rotación del secreto de webhook
          nullable: true
        webhook_secret_created_at:
          type: string
          format: date-time
          description: >-
            Marca de tiempo de cuando se creó el secreto de webhook por primera
            vez
          nullable: true
        ignore_company_webhooks:
          type: boolean
          description: >-
            Cuando es true, los webhooks a nivel de empresa no se disparan para
            eventos en este espacio de trabajo
        icon_url:
          type: string
          format: uri
          description: >-
            URL de acceso público a la imagen del logo del espacio de trabajo.
            Devuelve el logo específico del espacio de trabajo, o null si no
            está configurado (el logo de la empresa NO se incluye como
            alternativa en este campo).
          nullable: true
          example: >-
            https://ielmshcswdhuacyjlpiy.supabase.co/functions/v1/logo/workspace/company-id/workspace-id
      required:
        - id
        - name
        - created_date
    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:
    ValidationError:
      description: Solicitud Incorrecta - La validación falló
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: Validation Error
            message: Invalid input data
            details:
              name: Name is required
              email: Invalid email format
    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
    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.

````