Invitar Usuario

Invita a un usuario a una organización con un rol específico. Si el usuario no existe, se crea automáticamente y se le envía un email con las credenciales.

Endpoint

POST https://api.lummy.io/v1/organizations/{organizationId}/users/invite

Entorno	URL
Producción	`https://api.lummy.io/v1/organizations/{organizationId}/users/invite`
Sandbox	`https://sandbox.lummy.io/v1/organizations/{organizationId}/users/invite`

Path Parameters

{

"organizationId": stringrequerido

↳Identificador único de la organización en formato UUID a la cual se invitará al usuario. El usuario autenticado debe tener permisos de administración sobre esta organización para poder invitar a otros usuarios.

↳Formato: uuid

↳Ejemplo: "550e8400-e29b-41d4-a716-446655440000"

}

Headers

{

"Authorization": stringrequerido

↳Token de autenticación en formato Bearer (JWT) que valida la identidad del usuario. Este token debe ser enviado en cada petición para acceder a los recursos protegidos de la API. El usuario debe tener permisos de administración en la organización para poder invitar usuarios.

↳Ejemplo: "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

}

Body Parameters

Request Body

{

"email": string,requerido

↳Dirección de correo electrónico del usuario a invitar. Debe ser una dirección de email válida. Si el usuario con este email ya existe en el sistema, se le agregará a la organización con el rol especificado. Si no existe, se creará una nueva cuenta y se le enviará un correo con las credenciales de acceso.

↳Formato: email

↳Ejemplo: "nuevo.usuario@empresa.com"

"name": string,requerido

↳Nombre completo del usuario a invitar. Este campo es obligatorio y se utilizará para identificar al usuario en la plataforma y en las comunicaciones por correo electrónico.

↳Longitud: 1-255 caracteres

↳Ejemplo: "Juan Pérez"

"role": string,requerido

↳Rol que se asignará al usuario dentro de la organización. Los roles predefinidos son: owner (control total de la organización), admin (puede administrar usuarios y configuraciones), user (solo puede emitir facturas). También puedes usar custom si deseas asignar un rol personalizado especificado en customRoleId.

↳Valores permitidos: "owner""admin""user""custom"

↳Ejemplo: "user"

"customRoleId": stringopcional

↳Identificador único en formato UUID de un rol personalizado. Este campo es opcional y solo debe proporcionarse cuando el campo role tiene el valor custom. Los roles personalizados permiten definir permisos específicos más allá de los roles predefinidos.

↳Formato: uuid

↳Ejemplo: "123e4567-e89b-12d3-a456-426614174000"

}

Ejemplos de Código

cURL
Node.js (TypeScript)
Python
PHP (Guzzle)

curl -X POST https://sandbox.lummy.io/organizations/${ORG_ID}/users/invite \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -d '{
    "email": "nuevo.usuario@empresa.com",
    "name": "Juan Perez",
    "role": "user"
  }'

import axios from 'axios';

interface InviteUserPayload {
  email: string;
  name: string;
  role: 'owner' | 'admin' | 'user';
  customRoleId?: string;
}

interface InviteUserResponse {
  userId: string;
  email: string;
  role: string;
  status: 'invited' | 'existing_user_added';
  message: string;
}

async function invitarUsuario(
  organizationId: string,
  payload: InviteUserPayload
): Promise<InviteUserResponse> {
  const API_URL = `https://sandbox.lummy.io/organizations/${organizationId}/users/invite`;
  const ACCESS_TOKEN = process.env.ACCESS_TOKEN!;

  const response = await axios.post<InviteUserResponse>(API_URL, payload, {
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${ACCESS_TOKEN}`,
    },
  });

  console.log('Usuario invitado:', response.data.message);
  return response.data;
}

invitarUsuario('your-organization-uuid', {
  email: 'nuevo.usuario@empresa.com',
  name: 'Juan Perez',
  role: 'user',
});

import os
import requests

def invitar_usuario(organization_id, email, name, role, custom_role_id=None):
    api_url = f"https://sandbox.lummy.io/organizations/{organization_id}/users/invite"
    access_token = os.getenv("ACCESS_TOKEN")

    headers = {
        "Content-Type": "application/json",
        "Authorization": f"Bearer {access_token}",
    }

    payload = {
        "email": email,
        "name": name,
        "role": role,
    }

    if custom_role_id:
        payload["customRoleId"] = custom_role_id

    response = requests.post(api_url, json=payload, headers=headers)
    response.raise_for_status()

    data = response.json()
    print(f"Usuario invitado: {data['message']}")
    return data

if __name__ == "__main__":
    invitar_usuario(
        "your-organization-uuid",
        "nuevo.usuario@empresa.com",
        "Juan Perez",
        "user"
    )

<?php

require 'vendor/autoload.php';

use GuzzleHttp\Client;

function invitarUsuario(
    string $organizationId,
    string $email,
    string $name,
    string $role
): array {
    $apiUrl = "https://sandbox.lummy.io/organizations/{$organizationId}/users/invite";
    $accessToken = getenv('ACCESS_TOKEN');

    $client = new Client([
        'headers' => [
            'Content-Type' => 'application/json',
            'Authorization' => 'Bearer ' . $accessToken,
        ],
    ]);

    $response = $client->post($apiUrl, [
        'json' => [
            'email' => $email,
            'name' => $name,
            'role' => $role,
        ],
    ]);

    $data = json_decode($response->getBody(), true);
    echo "Usuario invitado: " . $data['message'] . "\n";
    return $data;
}

invitarUsuario(
    'your-organization-uuid',
    'nuevo.usuario@empresa.com',
    'Juan Perez',
    'user'
);

Respuestas

Todas las respuestas siguen el formato estándar StandardResponse.

201 Created

Usuario invitado exitosamente.

{
  "requestId": "abc123-def456",
  "data": {
    "userId": "550e8400-e29b-41d4-a716-446655440000",
    "email": "nuevo.usuario@empresa.com",
    "role": "user",
    "status": "invited",
    "message": "Usuario invitado exitosamente. Se ha enviado un email con las credenciales."
  },
  "timestamp": "2025-01-15T10:30:00.000Z",
  "path": "/organizations/org-uuid/users/invite",
  "method": "POST"
}

201 Created (Usuario Existente)

Usuario existente agregado a la organización.

{
  "requestId": "abc123-def456",
  "data": {
    "userId": "550e8400-e29b-41d4-a716-446655440000",
    "email": "usuario.existente@empresa.com",
    "role": "admin",
    "status": "existing_user_added",
    "message": "Usuario agregado a la organizacion exitosamente."
  },
  "timestamp": "2025-01-15T10:30:00.000Z",
  "path": "/organizations/org-uuid/users/invite",
  "method": "POST"
}

400 Bad Request

Datos de invitación inválidos.

{
  "requestId": "abc123-def456",
  "error": {
    "message": "El email es requerido",
    "code": "ValidationError",
    "status": 400
  },
  "timestamp": "2025-01-15T10:30:00.000Z",
  "path": "/organizations/org-uuid/users/invite",
  "method": "POST"
}

403 Forbidden

No tienes permisos para invitar usuarios.

{
  "requestId": "abc123-def456",
  "error": {
    "message": "No tienes permisos para invitar usuarios a esta organizacion",
    "code": "ForbiddenException",
    "status": 403
  },
  "timestamp": "2025-01-15T10:30:00.000Z",
  "path": "/organizations/org-uuid/users/invite",
  "method": "POST"
}

409 Conflict

El usuario ya es miembro de la organización.

{
  "requestId": "abc123-def456",
  "error": {
    "message": "El usuario ya es miembro de esta organizacion",
    "code": "ConflictException",
    "status": 409
  },
  "timestamp": "2025-01-15T10:30:00.000Z",
  "path": "/organizations/org-uuid/users/invite",
  "method": "POST"
}

Endpoint​

Path Parameters​

Headers​

Body Parameters​

Ejemplos de Código​

Respuestas​

201 Created​

201 Created (Usuario Existente)​

400 Bad Request​

403 Forbidden​

409 Conflict​