Saltar al contenido principal
  • 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
Consulta la guía de Límites de Frecuencia.
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): 
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: 
{
  "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 para saber cómo funciona el modo de prueba. Ejemplo de servidor — Node (fetch): 
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): 
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): 
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): 
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): 
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: 
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