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

# Espacios de Trabajo

> Los espacios de trabajo te permiten crear entornos aislados para cada uno de tus clientes o unidades de negocio. Cada espacio de trabajo tiene sus propias plantillas, documentos y uso de sobres, así que los equipos permanecen separados sin esfuerzo adicional.

* **Acceso particionado:** Los usuarios, plantillas y actividad están limitados a un único espacio de trabajo.
* **Seguimiento de uso:** Consulta los sobres enviados por espacio de trabajo para obtener informes claros.
* **Seguridad por diseño:** Sin exposición cruzada de documentos o datos entre espacios de trabajo.

Esto hace que sea sencillo darle a cada cliente o equipo su propio entorno de firma privado, mientras gestionas todo a través de la misma API.

## Endpoints principales

Endpoints principales (consulta la referencia de la API para más detalles):

* POST `/workspaces` — crear un espacio de trabajo
* GET `/workspaces/{workspace_id}` — obtener los detalles de un espacio de trabajo
* PUT `/workspaces/{workspace_id}` — actualizar un espacio de trabajo
* GET `/workspaces` — listar espacios de trabajo (paginación)
* GET `/workspace/{workspace_id}/settings` — obtener la configuración del espacio de trabajo
* PUT `/workspace/{workspace_id}/settings` — actualizar la configuración del espacio de trabajo

<Note>
  Consulta la guía de [Límites de Frecuencia](rate-limits).
</Note>

También puedes encontrar páginas de referencia dedicadas en `api-reference/v01.15.00/workspaces`:

* `api-reference/v01.15.00/workspaces/create-a-new-workspace`
* `api-reference/v01.15.00/workspaces/list-workspaces`
* `api-reference/v01.15.00/workspaces/update-a-workspace`

Autenticación

Todas las solicitudes deben incluir un encabezado Authorization con tu clave API:

```
Authorization: Bearer YOUR_API_KEY
```

Nota: nunca expongas tu clave API principal a los navegadores de los usuarios finales. Para operaciones por espacio de trabajo que deban iniciarse desde el frontend, llama a tu backend, que es quien guarda la clave.

## Crear un espacio de trabajo

Endpoint: POST `/workspaces`

Cuerpo requerido: `{ "name": "string" }`

Ejemplo (curl):

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/workspaces" \
  -H "Authorization: Bearer $FIRMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Acme Corp Workspace" }'
```

Una respuesta exitosa (201) devuelve el recurso `Workspace`, incluyendo el `api_key` (en vivo) del espacio de trabajo y el `test_api_key`. Ejemplo de estructura:

```json theme={null}
{
  "id": "workspace_123",
  "name": "Acme Corp Workspace",
  "protected": false,
  "api_key": "firma_live_…",
  "test_api_key": "firma_test_…",
  "created_date": "2025-09-04T12:00:00Z",
  "updated_date": "2025-09-04T12:00:00Z"
}
```

El `api_key` es la clave en vivo del espacio de trabajo y `test_api_key` es su clave de prueba. Consulta [Autenticación](authentication) para saber cómo funciona el modo de prueba.

Ejemplo de servidor — Node (fetch):

```js theme={null}
import fetch from 'node-fetch'

export async function createWorkspace(name) {
  const resp = await fetch('https://api.firma.dev/functions/v1/signing-request-api/workspaces', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ name })
  })
  if (!resp.ok) throw new Error(`create workspace failed: ${resp.status}`)
  return resp.json()
}
```

Ejemplo de servidor — Python (requests):

```py theme={null}
import os
import requests

def create_workspace(name):
    url = 'https://api.firma.dev/functions/v1/signing-request-api/workspaces'
    resp = requests.post(url, headers={
        'Authorization': f"Bearer {os.environ['FIRMA_API_KEY']}",
        'Content-Type': 'application/json'
    }, json={ 'name': name })
    resp.raise_for_status()
    return resp.json()
```

## Obtener un espacio de trabajo

Endpoint: GET `/workspaces/{workspace_id}`

Ejemplo (curl):

```bash theme={null}
curl "https://api.firma.dev/functions/v1/signing-request-api/workspaces/workspace_123" \
  -H "Authorization: Bearer $FIRMA_API_KEY"
```

Respuesta: el recurso `Workspace` (ver ejemplo arriba).

## Actualizar un espacio de trabajo

Endpoint: PUT `/workspaces/{workspace_id}` — reemplazo completo del recurso. El cuerpo requerido es el mismo que `CreateWorkspace` (por ejemplo, `{ "name": "New name" }`).

Ejemplo (curl):

```bash theme={null}
curl -X PUT "https://api.firma.dev/functions/v1/signing-request-api/workspaces/workspace_123" \
  -H "Authorization: Bearer $FIRMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Acme Corp - East Coast" }'
```

Ejemplo de servidor — Node (fetch):

```js theme={null}
export async function updateWorkspace(workspaceId, name) {
  const resp = await fetch(`https://api.firma.dev/functions/v1/signing-request-api/workspaces/${workspaceId}`, {
    method: 'PUT',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ name })
  })
  if (!resp.ok) throw new Error(`update workspace failed: ${resp.status}`)
  return resp.json()
}
```

## Listar espacios de trabajo

Endpoint: GET `/workspaces`

Admite los parámetros de consulta `page` y `page_size`. Ejemplo:

```bash theme={null}
curl "https://api.firma.dev/functions/v1/signing-request-api/workspaces?page=1&page_size=20" \
  -H "Authorization: Bearer $FIRMA_API_KEY"
```

La estructura de la respuesta contiene `results` (un array de `Workspace`) y metadatos de `pagination`.

## Control de acceso basado en roles (RBAC) y buenas prácticas para claves API

* Usa claves API con alcance limitado siempre que sea posible: mantén una clave API maestra solo en el servidor y crea claves API por espacio de trabajo para tus socios de integración, si tu plataforma lo permite.
* Nunca devuelvas claves API al navegador. Para operaciones iniciadas por usuarios finales, llama a tu backend, que es quien realiza la llamada a la API de Firma.
* Usa idempotencia cuando esté disponible (para los endpoints que aceptan `Idempotency-Key`) para evitar duplicados por reintentos.

## Casos límite y solución de problemas

* Nombres duplicados: los nombres de los espacios de trabajo son solo para visualización y pueden no ser únicos; usa el `id` para referencias programáticas.
* Espacios de trabajo protegidos: el indicador `protected` señala espacios de trabajo propiedad del sistema que no pueden eliminarse ni modificarse mediante los flujos normales.
* Límites de frecuencia y errores: revisa las respuestas que no sean 2xx para obtener `{ error, code }` y muestra mensajes claros a los operadores.
* **Límite de frecuencia excedido (429)**: monitorea el encabezado `X-RateLimit-Remaining` e implementa un retroceso exponencial para los reintentos.

## Próximos pasos

* [Enviar solicitudes de firma](sending-signing-request) dentro de espacios de trabajo (100 solicitudes/min)
* [Configurar webhooks](webhooks) para hacer seguimiento de la actividad del espacio de trabajo (60 solicitudes/min)
* [Autenticación JWT](embeddable-template-editor#jwt-authentication) para flujos de trabajo incrustados (120 solicitudes/min)