CRUD-Signup-Invitation-Code

Ver en Git

---

CRUD Signup Invitation Codes

APIs para administrar los códigos de invitación de signup externo.

Para poder usar estas APIs:

• el espacio debe tener configurado el signup_invitation_code_config en la tabla escritorios. Ver "../Playbooks/Reglas de Espacios"
• el usuario que las consulta debe ser administrador del espacio

APIs

Objetos

{
      "invitation_code": "code4",
      "initial_quota": 12,
      "signup_params": null,
      "quota": 12
}

• invitation_code: str, el código
• initial_quota: int, quota inicial, es decir el cupo de códigos que se crea
• quota: int, quota actual, es decir el cupo de códigos que aún queda disponible
• signup_params: puede ser null o un object con los parámetros.

Errores

En caso de fallar algúna consulta, la respuesta tendrá un código http > 400 y un cuerpo en formato json con un código que indicará lo sucedido.

Ejemplo:

{
  "res": "error", 
  "code": <CODE>, 
  "info": <INFO>
}

Según el código, se le debe informar al usuario lo que sucedió. Existen códigos de error generales que pueden ocurrir en todos los endpoints. A su vez, cada endpoint tiene códigos especificos detallados en la especificación de cada uno.

codigos generales:

Los códigos generales son numéricos, van desde el -1 hacia el -7 y es un error no contemplado, por lo que se debe avisar al usuario que se falló y que si el problema persiste contacte a soporte. Conviene identificarlos verificando si el código es numérico, ya que los específicos son Strings

En particular, el error -5 indica que los datos enviados no coinciden con el schema

codigos específicos:

CODE	INFO	descripcion
INVALID_WORKSPACE	'Invalid Workspace'	Solo ocurrirá si el usuario que consulta no pertenece a un espacio
UNAUTHORIZED	'Only administrator can perform this operation'	EL usuario que consulta no es administrador
INVALID_WORKSPACE_CONFIG	'The current workspace does not allow signup_invitation_codes'	El espacio tiene la funcionalidad de códigos de invitación habilitada
EXISTING_CODE	'The invitation code already exists'	El código que se quiere dar de alta ya existe
INVALID_SIGNUP_PARAMS	'Invalid signup_params'	Los parámetros del código son invalidos. Se envían campos extras con más información
INVALID_CODE	'The specified code is invalid'	Sólo se usa en el DELETE para indicar que el código no se pudo borrar
FILE_ERROR	'Could not process file'	No se puede procesar el archivo
INVALID_FILE	'File is invalid'	El archivo no respeta el formato
REPEATED_CODES	'File contains codes that already exist'	El archivo contiene códigos que ya existen. Se envía un campo con los códigos que ya existen

Ejemplo:

{
  "info": "The invitation code already exists",
  "res": "err",
  "code": "EXISTING_CODE"
}

parámetros de los códigos

Cada código puede setear características del usuario que se está dando de alta. Acualmente se soportan dos:

• desktop_user_type: id del plan. El plan debe pertenecer a la oferta comercial del espacio.
• max_surface_area: hectáreas asignadas (puede ser nulo, indicando ilimitada)

Al crear un código se debe permitir definir estos parámetros aunque son opcionales. Es decir, si no se envían, el alta se da con los default del espacio.

Tipos de usuarios soportados

Obtener un listado de los tipos de usuario soportados para el parámetro desktop_user_type. Los nombres se entran ya traducidos.

GET /api/workspaces/signup_invitation_codes/user_types

Respuesta ejemplo:

{
  "code": 0,
  "data": [
    {
      "desktop_user_type": 78,
      "user_type": "Profesional Full 5000"
    },
    {
      "desktop_user_type": 70,
      "user_type": "Gestión 1000"
    },
    {
      "desktop_user_type": 73,
      "user_type": "Profesional 1000"
    }
  ]
}

Errores específicos posibles: UNAUTHORIZED

CRUD de códigos individuales

Obtener listado de códigos del espacio

GET /api/workspaces/signup_invitation_codes

Respuesta ejemplo:

{
  "code": 0,
  "data": [
    {
      "invitation_code": "code1",
      "initial_quota": 20,
      "signup_params": {"desktop_user_type": 70},
      "quota": 0
    },
    {
      "invitation_code": "code2",
      "initial_quota": 20,
      "signup_params": {"max_surface_area": 4000, "desktop_user_type": 73},
      "quota": 19
    },
    {
      "invitation_code": "code3",
      "initial_quota": 12,
      "signup_params": {"max_surface_area": null},
      "quota": 12
    },
    {
      "invitation_code": "code4",
      "initial_quota": 12,
      "signup_params": null,
      "quota": 12
    },
    {
      "invitation_code": "code5",
      "initial_quota": 6,
      "signup_params": {},
      "quota": 6
    }
  ]
}

Errores específicos posibles: UNAUTHORIZED

Crear un código

Crear un código

POST /api/workspaces/signup_invitation_codes
Body: application/json
{
    "invitation_code": "prueba",
    "initial_quota": 20,
    "signup_params": {"max_surface_area": null, "desktop_user_type":78}
}

signup_params es opcional, de enviarse debe ser un objeto con alguno o todos los parámetros definidos previamente.

Respuesta ejemplo:

{
  "info": "invitation_code created",
  "code": 0,
  "data": {
    "invitation_code": "code5",
    "initial_quota": 20,
    "signup_params": {},
    "quota": 20
  }
}

Donde data contiene un objeto igual al del GET con el código nuevo, de manera de poder sumarlo a la lista.

Errores específicos posibles: UNAUTHORIZED, INVALID_WORKSPACE, INVALID_WORKSPACE_CONFIG, EXISTING_CODE, INVALID_SIGNUP_PARAMS

Para el error INVALID_SIGNUP_PARAMS, se envía un campo extra en el json de respuesta invalid_params con una lista de los parámetros inválidos. Ejemplo, si se envía un tipo de usuario que no corresponde al usuario.

{
  "info": "Invalid signup_params",
  "res": "err",
  "code": "INVALID_SIGNUP_PARAMS",
  "invalid_params": ["desktop_user_type"]
}

Eliminar un código

Eliminar un código

DELETE /api/workspaces/signup_invitation_codes
Body: application/json
{
    "invitation_code": "prueba",
}

Respuesta ejemplo:

{
  "info": "invitation_code deleted",
  "code": 0
}

Errores específicos posibles: UNAUTHORIZED, INVALID_CODE

Creación de códigos masiva

Se puede hacer el alta de múltiples códigos al mismo tiempo subiendo un archivo Excel.

Por ahora, no se permite asignar parámetros a los códigos

Formato

Se provee un template para tomar el formato correcto.

• El archivo a subir debe ser un Excel
• Debe tener 2 columnas: ['invitation_code', 'quota']
• No debe tener filas vacías
• Sólo se tomarán los que tengan quota > 0
• Si hay códigos duplicados, se procesa sólo 1
• No pueden enviarse códigos que ya existan

Descargar archivo modelo

Descarga un template para luego subir

GET /api/workspaces/signup_invitation_codes/batch

Subir archivo

Subir archivo con los códigos

POST /api/workspaces/signup_invitation_codes/batch
MultipartForm
    file: <archivo>

Ejemplo respuesta:

{"code": 0, "info": "codes created successfully"}

Errores específicos posibles: UNAUTHORIZED, INVALID_WORKSPACE, INVALID_WORKSPACE_CONFIG, FILE_ERROR, INVALID_FILE, REPEATED_CODES

Para el error REPEATED_CODES, se envía un campo extra en el json de respuesta codes con una lista de los códigos repetidos.

{
  "info": "File contains codes that already exist",
  "res": "err",
  "code": "REPEATED_CODES",
  "codes": ["code2", "code1"]
}