Espacios de Trabajo

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

​

Endpoints principales

• 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

• 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

Authorization: Bearer YOUR_API_KEY

​

Crear un espacio de trabajo

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" }'

{
  "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"
}

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()
}

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

curl "https://api.firma.dev/functions/v1/signing-request-api/workspaces/workspace_123" \
  -H "Authorization: Bearer $FIRMA_API_KEY"

​

Actualizar un espacio de trabajo

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" }'

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

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

​

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 dentro de espacios de trabajo (100 solicitudes/min)
• Configurar webhooks para hacer seguimiento de la actividad del espacio de trabajo (60 solicitudes/min)
• Autenticación JWT para flujos de trabajo incrustados (120 solicitudes/min)