Gestiona equipos y permisos por organización

Esta guía explica cómo invitar usuarios a una organización, consultar accesos, crear roles personalizados y reasignar permisos en Facturapi. Todo lo expuesto en esta guía puede hacerse usando la API de Facturapi o desde el dashboard.

Conceptos base

Antes de integrar este flujo, vale la pena distinguir 3 conceptos:

Invitación (invite): una invitación pendiente enviada a un correo electrónico.
Acceso (access): un acceso ya activo dentro de la organización.
Rol (role): un conjunto de permisos que puedes asignar a un acceso o a una invitación.

info

Según el endpoint, puedes autenticarte con User Key, Live Key o Test Key. En particular, las operaciones relacionadas con invitaciones recibidas y su respuesta sí requieren autenticarse como el usuario invitado, por lo que normalmente usarás su User Key.

Flujo recomendado

Esta guía asume que la organización emisora ya existe. Si todavía no la has creado, empieza por Organizaciones (Multi-RFC) y luego vuelve aquí para administrar usuarios y permisos.

Invita al usuario a la organización.
Si no quieres darle acceso administrativo completo, crea antes un rol personalizado y úsalo en la invitación.
El usuario invitado revisa y responde la invitación pendiente.
Después puedes administrar accesos, roles y permisos según evolucione tu operación.

1. Invitar a un usuario

Al enviar la invitación, el usuario recibe un correo para unirse a la organización. Ese usuario podrá aceptar o rechazar la invitación. Si aún no tiene cuenta en Facturapi, el flujo lo llevará a crearla primero.

Por defecto, una invitación crea acceso administrativo completo. Si requieres un acceso más limitado, puedes crear un rol de antemano y especificarlo en la invitación, o en la API enviando el ID del rol en el atributo role.

Dashboard: Acceso de equipo
API: Invitar usuario a organización

Ejemplo

Node.js
C#
PHP
cURL

import Facturapi from 'facturapi'
const facturapi = new Facturapi('sk_user_API_KEY')

const invite = await facturapi.organizations.inviteUserToTeam('ORG_ID', {
  email: 'alex@example.com',
  role: 'ROLE_ID', // opcional
})

var facturapi = new FacturapiClient("sk_user_API_KEY");

var invite = await facturapi.Organization.InviteUserToTeamAsync(
  "ORG_ID",
  new Dictionary<string, object>
  {
    ["email"] = "alex@example.com",
    ["role"] = "ROLE_ID" // opcional
  }
);

$facturapi = new Facturapi("sk_user_API_KEY");

$invite = $facturapi->Organizations->inviteUserToTeam("ORG_ID", [
  "email" => "alex@example.com",
  "role" => "ROLE_ID" // opcional
]);

curl "https://www.facturapi.io/v2/organizations/ORG_ID/team/invites" \
  -X POST \
  -H "Authorization: Bearer sk_user_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "alex@example.com",
    "role": "ROLE_ID"
  }'

Si quieres monitorear invitaciones pendientes, revisa también Listar invitaciones enviadas.

El objeto retornado (invite) incluye el identificador de invitación (id), el correo invitado y metadatos como expiración. Guarda ese id porque se usa para responder invitaciones por API.

2. Crear un rol personalizado (opcional)

Esta sección es opcional. Úsala cuando no quieras que la invitación otorgue acceso administrativo completo y necesites un permiso más granular desde el inicio. Puedes configurar este rol desde el dashboard o desde API.

Dashboard: Roles del equipo
API: Crear rol de organización

Actualmente las plantillas base estables disponibles son:

`template_code`	Nombre	Uso sugerido
`org-admin`	Organization admin	Acceso total a la organización
`org-readonly`	Read only	Consulta sin permisos de escritura
`org-billing`	Billing manager	Operación enfocada en facturación y recibos
`org-developer`	Developer	API keys, webhooks, logs, herramientas y descargas SAT
`org-team-manager`	Team manager	Invitaciones, accesos, roles y permisos del equipo

Al crear o actualizar un rol puedes usar estos campos:

name: nombre del rol
template_code: plantilla base, si aplica
add: operaciones adicionales
remove: operaciones removidas

Ejemplo: partir de la plantilla org-developer, conservar acceso técnico y agregar lectura de clientes, pero remover la capacidad de crear descargas SAT.

Ejemplo

Node.js
C#
PHP
cURL

import Facturapi from 'facturapi'
const facturapi = new Facturapi('sk_user_API_KEY')

const role = await facturapi.organizations.createTeamRole('ORG_ID', {
  name: 'Developer (limited)',
  template_code: 'org-developer',
  add: ['read.customers.list', 'read.customers.detail'],
  remove: ['write.sat_downloads.create'],
})

var facturapi = new FacturapiClient("sk_user_API_KEY");

var role = await facturapi.Organization.CreateTeamRoleAsync(
  "ORG_ID",
  new Dictionary<string, object>
  {
    ["name"] = "Developer (limited)",
    ["template_code"] = "org-developer",
    ["add"] = new[] { "read.customers.list", "read.customers.detail" },
    ["remove"] = new[] { "write.sat_downloads.create" }
  }
);

$facturapi = new Facturapi("sk_user_API_KEY");

$role = $facturapi->Organizations->createTeamRole("ORG_ID", [
  "name" => "Developer (limited)",
  "template_code" => "org-developer",
  "add" => ["read.customers.list", "read.customers.detail"],
  "remove" => ["write.sat_downloads.create"]
]);

curl "https://www.facturapi.io/v2/organizations/ORG_ID/team/roles" \
  -X POST \
  -H "Authorization: Bearer sk_user_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Developer (limited)",
    "template_code": "org-developer",
    "add": ["read.customers.list", "read.customers.detail"],
    "remove": ["write.sat_downloads.create"]
  }'

Si quieres diseñar una política más fina, puedes consultar además Listar plantillas de roles y Listar operaciones de permisos.

La idea es usar template_code como base estable y luego ajustar con add / remove, en lugar de construir toda la matriz de permisos desde cero.

El objeto retornado (role) incluye el ID del rol (id). Ese ID es el que debes usar en la invitación (role) o al reasignar accesos.

3. Aceptar o rechazar una invitación pendiente

La invitación la responde el usuario invitado, ya sea desde la API autenticándose con su propia User Key, o desde el dashboard iniciando sesión con el correo al que fue invitado.

Dashboard: Mis organizaciones
API: Responder invitación

Ejemplo

Node.js
C#
PHP
cURL

import Facturapi from 'facturapi'
const facturapi = new Facturapi('sk_user_API_KEY')

const result = await facturapi.organizations.respondTeamInvite('INVITE_ID', {
  accept: true,
})

var facturapi = new FacturapiClient("sk_user_API_KEY");

var result = await facturapi.Organization.RespondTeamInviteAsync(
  "INVITE_ID",
  new Dictionary<string, object>
  {
    ["accept"] = true
  }
);

$facturapi = new Facturapi("sk_user_API_KEY");

$result = $facturapi->Organizations->respondTeamInvite("INVITE_ID", [
  "accept" => true
]);

curl "https://www.facturapi.io/v2/organizations/invites/INVITE_ID/response" \
  -X POST \
  -H "Authorization: Bearer sk_user_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "accept": true
  }'

Si necesitas mostrarle al usuario sus invitaciones pendientes antes de responder, puedes usar Listar invitaciones recibidas.

La respuesta de este paso regresa { "ok": true }. Después de aceptar, el usuario ya aparece como acceso activo de la organización y podrás administrarlo con access_id.

4. Administrar accesos, roles y permisos

Una vez que el usuario ya aceptó la invitación, puedes seguir administrando su acceso sin generar una nueva invitación. Este mantenimiento también puede hacerse desde el dashboard o desde API.

Dashboard: Acceso de equipo
API: Reasignar rol a usuario

Ejemplo

Node.js
C#
PHP
cURL

import Facturapi from 'facturapi'
const facturapi = new Facturapi('sk_user_API_KEY')

const access = await facturapi.organizations.updateTeamAccessRole(
  'ORG_ID',
  'ACCESS_ID',
  'ROLE_ID'
)

var facturapi = new FacturapiClient("sk_user_API_KEY");

var access = await facturapi.Organization.UpdateTeamAccessRoleAsync(
  "ORG_ID",
  "ACCESS_ID",
  "ROLE_ID"
);

$facturapi = new Facturapi("sk_user_API_KEY");

$access = $facturapi->Organizations->updateTeamAccessRole(
  "ORG_ID",
  "ACCESS_ID",
  "ROLE_ID"
);

curl "https://www.facturapi.io/v2/organizations/ORG_ID/team/ACCESS_ID/role" \
  -X PUT \
  -H "Authorization: Bearer sk_user_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "role": "ROLE_ID"
  }'

Para obtener ese access_id, usa Listar usuarios con acceso o Obtener acceso de usuario.

Si necesitas automatización o controles más finos, en Referencia API tienes:

Cancelar invitaciones enviadas: Cancelar invitación
Remover accesos existentes de una organización: Remover acceso de usuario
Listar, obtener, actualizar o eliminar roles: Roles de organización
Consultar plantillas y operaciones disponibles para permisos: Plantillas y operaciones

Conceptos base​

Flujo recomendado​

1. Invitar a un usuario​

Ejemplo​

2. Crear un rol personalizado (opcional)​

Ejemplo​

3. Aceptar o rechazar una invitación pendiente​

Ejemplo​

4. Administrar accesos, roles y permisos​

Ejemplo​

Conceptos base

Flujo recomendado

1. Invitar a un usuario

Ejemplo

2. Crear un rol personalizado (opcional)

Ejemplo

3. Aceptar o rechazar una invitación pendiente

Ejemplo

4. Administrar accesos, roles y permisos

Ejemplo