API de Equipos

Gestiona equipos, miembros, roles e invitaciones para la construcción colaborativa de formularios.

La API de Equipos te permite crear y gestionar equipos para la construcción colaborativa de formularios. Los equipos permiten que múltiples usuarios compartan formularios, con control de acceso basado en roles que gobierna quién puede ver, editar y eliminar formularios y respuestas.

Todos los cuerpos de solicitud y respuesta utilizan nombres de campo en snake_case.

Roles de Equipo

ownerrole

Acceso completo. Puede gestionar miembros, facturación y eliminar el equipo.

adminrole

Puede crear, editar y eliminar formularios, gestionar miembros y ver respuestas.

editorrole

Puede crear y editar formularios, ver respuestas. No puede gestionar miembros.

viewerrole

Puede ver formularios y respuestas. No puede crear ni editar.

Endpoints

GET/api/v1/teamsPOST/api/v1/teamsGET/api/v1/teams/:teamIdPUT/api/v1/teams/:teamIdDELETE/api/v1/teams/:teamIdGET/api/v1/teams/:teamId/membersPOST/api/v1/teams/:teamId/membersPUT/api/v1/teams/:teamId/members/:memberIdDELETE/api/v1/teams/:teamId/members/:memberIdGET/api/v1/teams/:teamId/invitationsPOST/api/v1/teams/:teamId/invitationsDELETE/api/v1/teams/:teamId/invitations/:invId

Listar Equipos

GET/api/v1/teams

Devuelve todos los equipos de los que el usuario autenticado es miembro.

Respuesta

json

{
  "teams": [
    {
      "id": "665b2c3d4e5f6a7b8c9d0e1f",
      "name": "Marketing",
      "slug": "marketing",
      "owner_id": "665a0a1b2c3d4e5f6a7b8c9d",
      "created_at": "2026-01-10T09:00:00.000Z",
      "updated_at": "2026-02-15T11:30:00.000Z",
      "member_count": 5,
      "your_role": "admin"
    },
    {
      "id": "665c3d4e5f6a7b8c9d0e1f20",
      "name": "Product",
      "slug": "product",
      "owner_id": "665a0a1b2c3d4e5f6a7b8c9d",
      "created_at": "2026-02-01T14:00:00.000Z",
      "updated_at": "2026-02-20T16:45:00.000Z",
      "member_count": 3,
      "your_role": "owner"
    }
  ]
}

Ejemplos de Código

bash

curl -X GET "https://api.nueform.io/api/v1/teams" \
  -H "Authorization: Bearer YOUR_API_KEY"

Crear Equipo

POST/api/v1/teams

Crea un nuevo equipo. El usuario autenticado se convierte en el propietario del equipo.

Cuerpo de Solicitud

namestring

Nombre del equipo

Ejemplo de Solicitud

json

{
  "name": "Marketing"
}

Respuesta

json

{
  "id": "665b2c3d4e5f6a7b8c9d0e1f",
  "name": "Marketing",
  "slug": "marketing",
  "owner_id": "665a0a1b2c3d4e5f6a7b8c9d",
  "created_at": "2026-02-28T12:00:00.000Z",
  "updated_at": "2026-02-28T12:00:00.000Z"
}

Ejemplos de Código

bash

curl -X POST "https://api.nueform.io/api/v1/teams" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Marketing" }'

Obtener Equipo

GET/api/v1/teams/:teamId

Obtiene un equipo individual por ID.

Parámetros de Ruta

teamIdstring

El ID del equipo

Respuesta

json

{
  "id": "665b2c3d4e5f6a7b8c9d0e1f",
  "name": "Marketing",
  "slug": "marketing",
  "owner_id": "665a0a1b2c3d4e5f6a7b8c9d",
  "created_at": "2026-01-10T09:00:00.000Z",
  "updated_at": "2026-02-15T11:30:00.000Z",
  "member_count": 5
}

Ejemplos de Código

bash

curl -X GET "https://api.nueform.io/api/v1/teams/665b2c3d4e5f6a7b8c9d0e1f" \
  -H "Authorization: Bearer YOUR_API_KEY"

Actualizar Equipo

PUT/api/v1/teams/:teamId

Actualiza las propiedades del equipo. Requiere rol owner o admin.

Parámetros de Ruta

teamIdstring

El ID del equipo

Cuerpo de Solicitud

namestring

Nuevo nombre del equipo

Ejemplo de Solicitud

json

{
  "name": "Marketing & Growth"
}

Respuesta

Devuelve el objeto del equipo actualizado.

Ejemplos de Código

bash

curl -X PUT "https://api.nueform.io/api/v1/teams/665b2c3d4e5f6a7b8c9d0e1f" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Marketing & Growth" }'

Eliminar Equipo

DELETE/api/v1/teams/:teamId

Elimina permanentemente un equipo. Solo el propietario del equipo puede eliminarlo.

Eliminar un equipo remueve todas las membresías e invitaciones del equipo. Los formularios que pertenecen al equipo no se eliminan automáticamente, pero serán inaccesibles para los antiguos miembros del equipo.

Parámetros de Ruta

teamIdstring

El ID del equipo

Respuesta

json

{
  "success": true
}

Ejemplos de Código

bash

curl -X DELETE "https://api.nueform.io/api/v1/teams/665b2c3d4e5f6a7b8c9d0e1f" \
  -H "Authorization: Bearer YOUR_API_KEY"

Listar Miembros

GET/api/v1/teams/:teamId/members

Devuelve todos los miembros de un equipo.

Parámetros de Ruta

teamIdstring

El ID del equipo

Respuesta

json

{
  "members": [
    {
      "id": "66d1e2f3a4b5c6d7e8f9a0b1",
      "user_id": "665a0a1b2c3d4e5f6a7b8c9d",
      "email": "alice@example.com",
      "first_name": "Alice",
      "last_name": "Johnson",
      "role": "owner",
      "joined_at": "2026-01-10T09:00:00.000Z"
    },
    {
      "id": "66d2e3f4a5b6c7d8e9f0a1b2",
      "user_id": "665a1b2c3d4e5f6a7b8c9d0e",
      "email": "bob@example.com",
      "first_name": "Bob",
      "last_name": "Smith",
      "role": "editor",
      "joined_at": "2026-01-15T14:30:00.000Z"
    }
  ]
}

Ejemplos de Código

bash

curl -X GET "https://api.nueform.io/api/v1/teams/665b2c3d4e5f6a7b8c9d0e1f/members" \
  -H "Authorization: Bearer YOUR_API_KEY"

Agregar Miembro

POST/api/v1/teams/:teamId/members

Agrega un usuario directamente a un equipo por ID de usuario. Requiere rol owner o admin. Para invitar a un usuario por email, usa Crear Invitación en su lugar.

Parámetros de Ruta

teamIdstring

El ID del equipo

Cuerpo de Solicitud

user_idstring

El ID del usuario a agregar

rolestring

Rol a asignar: "admin", "editor", "viewer" (por defecto: "viewer")

Ejemplo de Solicitud

json

{
  "user_id": "665a1b2c3d4e5f6a7b8c9d0e",
  "role": "editor"
}

Respuesta

json

{
  "id": "66d2e3f4a5b6c7d8e9f0a1b2",
  "user_id": "665a1b2c3d4e5f6a7b8c9d0e",
  "team_id": "665b2c3d4e5f6a7b8c9d0e1f",
  "role": "editor",
  "joined_at": "2026-02-28T12:00:00.000Z"
}

Ejemplos de Código

bash

curl -X POST "https://api.nueform.io/api/v1/teams/665b2c3d4e5f6a7b8c9d0e1f/members" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "665a1b2c3d4e5f6a7b8c9d0e",
    "role": "editor"
  }'

Actualizar Rol de Miembro

PUT/api/v1/teams/:teamId/members/:memberId

Actualiza el rol de un miembro del equipo. Requiere rol owner o admin. No puedes cambiar el rol del propietario.

Parámetros de Ruta

teamIdstring

El ID del equipo

memberIdstring

El ID del miembro del equipo

Cuerpo de Solicitud

rolestring

Nuevo rol: "admin", "editor", "viewer"

Ejemplo de Solicitud

json

{
  "role": "admin"
}

Respuesta

json

{
  "id": "66d2e3f4a5b6c7d8e9f0a1b2",
  "user_id": "665a1b2c3d4e5f6a7b8c9d0e",
  "team_id": "665b2c3d4e5f6a7b8c9d0e1f",
  "role": "admin",
  "joined_at": "2026-01-15T14:30:00.000Z"
}

Ejemplos de Código

bash

curl -X PUT "https://api.nueform.io/api/v1/teams/665b2c3d4e5f6a7b8c9d0e1f/members/66d2e3f4a5b6c7d8e9f0a1b2" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "role": "admin" }'

Eliminar Miembro

DELETE/api/v1/teams/:teamId/members/:memberId

Elimina un miembro de un equipo. Requiere rol owner o admin. El propietario del equipo no puede ser eliminado.

Parámetros de Ruta

teamIdstring

El ID del equipo

memberIdstring

El ID del miembro del equipo

Respuesta

json

{
  "success": true
}

Ejemplos de Código

bash

curl -X DELETE "https://api.nueform.io/api/v1/teams/665b2c3d4e5f6a7b8c9d0e1f/members/66d2e3f4a5b6c7d8e9f0a1b2" \
  -H "Authorization: Bearer YOUR_API_KEY"

Listar Invitaciones

GET/api/v1/teams/:teamId/invitations

Devuelve todas las invitaciones pendientes de un equipo. Requiere rol owner o admin.

Parámetros de Ruta

teamIdstring

El ID del equipo

Respuesta

json

{
  "invitations": [
    {
      "id": "66e1f2a3b4c5d6e7f8a9b0c1",
      "email": "carol@example.com",
      "role": "editor",
      "invited_by": "665a0a1b2c3d4e5f6a7b8c9d",
      "status": "pending",
      "expires_at": "2026-03-07T12:00:00.000Z",
      "created_at": "2026-02-28T12:00:00.000Z"
    }
  ]
}

Ejemplos de Código

bash

curl -X GET "https://api.nueform.io/api/v1/teams/665b2c3d4e5f6a7b8c9d0e1f/invitations" \
  -H "Authorization: Bearer YOUR_API_KEY"

Crear Invitación

POST/api/v1/teams/:teamId/invitations

Envía una invitación por email para unirse a un equipo. La invitación incluye un token único y expira después de 7 días. Requiere rol owner o admin.

Parámetros de Ruta

teamIdstring

El ID del equipo

Cuerpo de Solicitud

emailstring

Dirección de email a invitar

rolestring

Rol a asignar al aceptar: "admin", "editor", "viewer" (por defecto: "editor")

Ejemplo de Solicitud

json

{
  "email": "carol@example.com",
  "role": "editor"
}

Respuesta

json

{
  "id": "66e1f2a3b4c5d6e7f8a9b0c1",
  "email": "carol@example.com",
  "role": "editor",
  "invited_by": "665a0a1b2c3d4e5f6a7b8c9d",
  "status": "pending",
  "expires_at": "2026-03-07T12:00:00.000Z",
  "created_at": "2026-02-28T12:00:00.000Z"
}

Ejemplos de Código

bash

curl -X POST "https://api.nueform.io/api/v1/teams/665b2c3d4e5f6a7b8c9d0e1f/invitations" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "carol@example.com",
    "role": "editor"
  }'

Cancelar Invitación

DELETE/api/v1/teams/:teamId/invitations/:invId

Cancela una invitación pendiente. Requiere rol owner o admin. El token de la invitación dejará de ser válido.

Parámetros de Ruta

teamIdstring

El ID del equipo

invIdstring

El ID de la invitación

Respuesta

json

{
  "success": true
}

Ejemplos de Código

bash

curl -X DELETE "https://api.nueform.io/api/v1/teams/665b2c3d4e5f6a7b8c9d0e1f/invitations/66e1f2a3b4c5d6e7f8a9b0c1" \
  -H "Authorization: Bearer YOUR_API_KEY"

Respuestas de Error

Respuestas de error estándar devueltas por los endpoints de la API de Equipos.

Códigos de Error

400Bad Request

Campos requeridos faltantes, rol inválido

401Unauthorized

API key faltante o inválida

403Forbidden

Rol insuficiente para la acción

404Not Found

Equipo, miembro o invitación no encontrados

409Conflict

El usuario ya es miembro, invitación duplicada

500Server Error

Error interno del servidor

Ejemplo de Error

json

{
  "error": "Not authorized to manage team members"
}

Ultima actualizacion: 6 de abril de 2026