Introducción

Aquí se describen todos los componentes del sistema.

Usuarios y Permisos

User

{
  "user": {
    "id": 4001,
    "user_id": "google-oauth2|103170969289978119959",
    "email": "[email protected]",
    "given_name": "Eduardo",
    "family_name": "Miranda",
    "name": "Eduardo Miranda",
    "picture": "https://lh4.googleusercontent.com/-RWO5TA9iUmM/AAAAAAAAAAI/AAAAAAAAAAA/ACHi3rfPeI0HanYku3Qj1CZKX6gBLDNG6Q/photo.jpg",
    "nickname": "eduardo.miranda",
    "job_title": "Desarrollador",
    "last_login": "2019-11-29T22:07:31.893Z",
    "logins_count": 17,
    "role": "admin"
  }
}

Atributo	Validaciones
user_id	typeOf:string, unique:users,user_id
email	typeOf:string, min:1, max:120, regex:alphabetic, unique:users,email
given_name	typeOf:string, min:1, max:120, regex:alphabetic
family_name	typeOf:string, min:1, max:120, regex:alphabetic
name	typeOf:string, min:1, max:255, regex:alphabetic
picture	typeOf:string, min:1, max:255, regex:url, nullable
nickname	typeOf:string, min:10, max:100, regex:alphabetic
job_title	typeOf:string, min:1, max:120, regex:alphabetic, nullable
last_login	typeOf:date
logins_count	typeOf:number
role	in:admin,rh,manager,employee,requester

Clientes, Marcas, Proyectos

Customer

{
  "group" : {
    "id" : 1,
    "name" : "Cemex México"
  }
}

Atributo	Validaciones
name	typeOf:string, min:1, max:120, regex:alphanumeric

Brand

Compañia o Marca.

{
  "brands" : [
    {
      "id" : 1,
      "name" : "Construrama",
      "description" : "Marca Construrama de...",
      "customer" : 1
    },
    {
      "id" : 2,
      "name" : "Tolteca",
      "description" : null,
      "customer" : 1
    }
  ]
}

Atributo	Validaciones
name	typeOf:string, min:3, max:20, regex:alphanumeric
description	typeOf:string, min:1, max:120, regex:alphanumeric, nullable

Project

Proyectos de marcas.

{
  "project" : {
    "id" : 1,
    "folio" : "000544",
    "name" : "La gran regaliza",
    "description" : "Campaña de publicidad...",
  }
}

Atributo	Validaciones
folio	typeOf:string, min:3, max:10, regex:numeric
name	typeOf:string, min:3, max:30, regex:alphanumeric
description	typeOf:string, min:0, max:255, regex:alphanumeric, nullable

ProjectNote

Notas sobre proyectos.

{
  "project_note" : {
    "id" : 1,
    "project": 2,
    "user" : 1,
    "note" : "¿Por qué Alberto es el contacto de este proyecto?",
    "type" : ""
  }
}

Atributo	Validaciones
note	typeOf:string, min:0, max:512, regex:alphanumeric

Quote

Información sobre la cotización

{
  "quote" : {
    "id" : 1,
    "project": 2,
    "created_by" : 1,
    "cost" : 100000, //Costo en centavos
    "authored_cost" : 100000, //Costo autorizado por el cliente
    "accepted_at" : "2019-11-15 13:00:00", //Fecha de autorización
    "accepted_by" : 1, //ID persona que autorizó
    "rejected_at" : null, //Fecha de rechazo de la cotización
    "rejected_by" : null //ID persona que rechazó
  }
}

Atributo	Validaciones
cost	typeOf:number, min:0, max:9007199254740991
authored_cost	typeOf:number, min:0, max:9007199254740991
name	typeOf:string, min:3, max:30, regex:alphanumeric
description	typeOf:string, min:0, max:255, regex:alphanumeric, nullable
contact_name	typeOf:string, min:3, max:120, regex:alphabetic
contact_email	typeOf:string, min:3, max:120, regex:alphabetic
status	typeOf:string, in:active,finished,pending

Proveedores

Supplier

{
  "id": 5,
  "company_name": "Proveedor 01 S.A. de C.V.",
  "contact_name": "Juan Ramirez",
  "email": "[email protected]",
  "phone": "+525541878844",
  "business_activity": "Telecomunicaciones"
}

Atributo	Validaciones
company_name	required, typeOf:string, regex:name, min:2, max:100, unique:supplier,company_name
contact_name	required, typeOf:string, regex:name, min:2, max:100
phone	required, typeOf:string, regex:phone, min:10, max:15
email	required, typeOf:string, email, min:10, max:100
business_activity	required, typeOf:string, min:2, max:255

Gastos (Egresos)

Expense

{
  "expense" : {
    "id" : 1,
    "project" : null, //ID del proyecto
    "quote" : 1, //ID de cotización
    "company" : null, //ID de marca
    "amount" : 50000, //Gasto total en centavos
    "type" : "cash", //cash: Efectivo, card: Tarjeta
    "concept" : "Alimentos", //cash: Efectivo, card: Tarjeta
    "description" : "Gasto de $500 en alimentos para el equipo de producción", //Nota
    "note" : "Gasto de comida en Corna Capital", //Nota extra
    "status" : "accepted",
    "accepted_at" : null,
    "accepted_by" : null, //ID de usuario que rechazo el gasto
    "rejected_by" : 22, //ID de usuario que rechazo el gasto
    "rejected_at" : "2019-11-15 15:00:00" //Fecha en que el gasto se rechazó
  }
}

Atributo	Validaciones
amount	typeOf:number, min:0, max:9007199254740991
type	typeOf:string, in:cash,card
concept	typeOf:string, min:2, max:30, regex:alphabetic
description	typeOf:string, min:1, max:512, regex:alphanumeric
note	typeOf:string, min:1, max:512, regex:alphanumeric, nullable
status	typeOf:string, in:accepted,pending,rejected

Validaciones

{
  "email": "sometimes|typeOf:string|email|unique:user,email",
  "name": "sometimes|typeOf:string|min:1|max:120|regex:alphabetic",
  "father_surname": "sometimes|typeOf:string|min:1|max:120|regex:alphabetic",
  "mother_surname": "sometimes|typeOf:string|min:1|max:120|regex:alphabetic",
  "card_digits": "sometimes|typeOf:string|exact:8|typeOf:numeric|unique:customer,card_digits",
  "cell_phone": "sometimes|typeOf:string|exact:10|typeOf:numeric|unique:customer,cell_phone",
}

• typeOf:[type]: Validación sobre el tipo de dato recibido. Los tipos pueden ser:

Tipo	Descripción	Código de Error
string	Cadena ("Hola", "Mundo", "007")	42217
numeric	Cadena de números ("0001", "0431.99")	42222
number	Valor númerico (1, 431.99)	42218
object	Objeto JSON ({ "name" : "Omar"})	42219
array	Arreglo ([1, "pez", 0.3])	42220
boolean	Tipo booleano (0, 1, true, false, True, False)	42221

• nullable : El valor puede ser null. Los atributos que NO tengan esta etiqueta, no tienen permitido ser null.

• required : El campo bajo validación debe estar presente en los datos de entrada y no estar vacío. Un campo se considera "vacío" si se cumple una de las siguientes condiciones:

  • El valor es nulo.
  • El valor es una cadena vacía.
  • El valor es una matriz vacía o un objeto contable vacío.
  • El valor es un archivo cargado sin ruta.

HTTP	Código de Error
400	4001

• sometimes : El resto de las validacions será procesado si y sólo sí el campo está presente.

• email : El campo bajo validación debe estar formateado como una dirección de correo electrónico.

HTTP	Código de Error
422	42216

• file: El campo bajo validación debe ser un archivo cargado correctamente.

HTTP	Código de Error
415	4154

• image: El archivo bajo validación debe ser una imagen (jpeg, png, bmp, gif o svg).

HTTP	Código de Error
415	4151

• size:[value]: El campo bajo validación debe tener un tamaño que coincida con el valor dado. Para los datos de cadena, el valor corresponde al número de caracteres. Para datos numéricos, el valor corresponde a un valor entero dado. Para una matriz, el tamaño corresponde al recuento de la matriz. Para los archivos, el tamaño corresponde al tamaño del archivo en kilobytes.

Tipo	HTTP	Código de Error
string, number	422	4226
image, file	415	4153

• unique:[tabla],[columna] : Validación de unicidad en la base. No debe existir en la tabla [tabla] en la columna [columna] ninguna coincidencia con el valor del atributo a validar.

Dato	HTTP	Código de Error
{{thing}}, {{value}}	409	4093

• exists:[tabla],[columna] : Validación de existencia en la base. Debe existir en la tabla [tabla] en la columna [columna] al menos una coincidencia con el valor del atributo a validar.

Dato	HTTP	Código de Error
{{model}}	404	4042

• confirmation : Debe ser enviado otro parámetro llamado attr_confirmation cuyo valor sea el mismo que el del parámetro attr. Comunmente usado para validar que las contraseñas coincidan.

HTTP	Código de Error
422	4225

• date: El valor será validado como fecha, la cadena recibida, tratara de convertirse en fecha, si no es posible, se lanza error.

HTTP	Código de Error
422	4225

• date:[format]: El valor será validado como fecha en el formato que sea indicado. Aquí pueden encontrarse los formatos disponibles.
  

Dato	HTTP	Código de Error
{{format}}	422	4229

• min:[len]: Si se está validado un número se validará que el número a validar sea mayor o igual que len. Si se valida una cadena la longitud de la cadena debe ser mayor o igual que len.

Dato	HTTP	Código de Error
{{len}}	422	4222

• min:[len]: Si se está validado un número se validará que el número a validar sea menor o igual que len. Si se valida una cadena la longitud de la cadena debe ser menor o igual que len.

Dato	HTTP	Código de Error
{{len}}	422	4223

• exact:[len]: Si se está validado un número se validará que el número a validar tenga el valor exacto que len. Si se valida una cadena la longitud de la cadena sea exactamente len.

Dato	HTTP	Código de Error
{{len}}	422	4226

• in:foo,bar: El campo validado debe existir en la lista de valores.

Dato	HTTP	Código de Error
{{list}}	422	42210

• regex: Valida expresiones regulares conocidas:

  • alphanumeric: /^[A-Za-z\d]*$/
  • letters: /^[A-Za-zÁÉÍÓÚÜÑáéíóúüñ][A-Za-zÁÉÍÓÚÜÑáéíóúüñ\- ]*$/
  • name: /^[A-Za-zÁÉÍÓÚÜÑáéíóúüñ][A-Za-zÁÉÍÓÚÜÑáéíóúüñ\-. ]*$/
  • url: /^(?:http(s)?:\/\/)?[\w.-]+(?:\.[\w.-]+)+[\w\-._~:/?#[\]@!$&'()*+,;=.]+$/
  • digits : /^\d*$/
  • device_uuid : /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/
  • phone : /^\(?\+?[0-9]{1,3}\)? ?-?[0-9]{1,3} ?-?[0-9]{3,5} ?-?[0-9]{4}$/
  • email : /(([^<>()[\].,;:\s@"]+(\.[^<>()[\].,;:\s@"]+)*)|(".+"))@(([^<>()[\].,;:\s@"]+\.)+[^<>()[\].,;:\s@"]{2,})$/
  • video_url : /^(http:\/\/www\.|https:\/\/www\.|http:\/\/|https:\/\/)?[a-z0-9]+([-.]{1}[a-z0-9]+)*\.[a-z]{2,5}(:[0-9]{1,5})?(\/.*)?$/

Regex	Código de Error
alphanumeric	4228
letters	4227
name	42224
url	42213
digits	42222
device_uuid	42225
phone	42226

Errors

Formato

    {
     code :  422,
     message :  "Hay errores semánticos y no se puede procesar el contenido de la solicitud.",
     errors : [
      {
       code : 4222,
       fields : "email",
       message : "El formato del correo electrónico es incorrecto"
      },
      {
       code : 4221,
       fields : "name",
       message : "El nombre no puede contener caracteres especiales"
      }
     ]
    }

Todos los errores del API deben proveer una respuesta JSON que informe sobre el error. El formato de los errores se dividen en 2 dependiendo su código de estado HTTP:

1. Los errores de validación de campos que corresponden en mayor parte a códigos 400 y 422. Por ejemplo, La contraseña no debe tener más de 16 caracteres, El campo email no puede ser vacío, etc.

• message : es el mensaje corres ondiente para el código HTTP enviado. Por ejemplo, si se envía el código HTTP 400 el mensaje es: Algún campo no ha sido enviado.

• errors : es un arreglo de objetos que contienen el detalle de los campos que fallarón. Cada objeto del arreglo contiene:

  • fields : Campo que no pasó las validaciones.
  • message : Mensaje detallado del error.

    {
     code : "4033",
     message :  "No fue posible verificar la autenticidad de la firma."
    }

2. Los errores que no correspondan a errores de campos. Por ejemplo, No cuentas con los permisos necesarios para realizar esta acción, Token inválido, etc.

Para este tipo de errores se envía un JSON con el siguiente formato:

El lenguaje del mensaje de error depende del código de lenguaje que se envíe en la cabecera Accept-Language de la petición que provoque el error. Si la cabecera no se encuentra o el código es diferente de es o en el lenguaje por defecto es Español.

 HTTP Errors y Códigos de Error

Error Code	Meaning
400	Bad Request - No se puede procesar la solicitud debido a algo que se percibe como un error del cliente.
401	Unauthorized - Hay un error con la autorización.
403	Forbidden - No es posible otorgar acceso.
404	Not Found - No se encontró el recurso de destino.
409	Conflict - La solicitud no pudo completarse debido a un conflicto con el estado actual.
410	Gone - El recurso objetivo ya no está disponible.
415	Unsupported Media Type - Hay un problema con el archivo.
422	Unprocessable Entry - Hay errores semánticos y no se puede procesar el contenido de la solicitud
423	Locked - No puedes realizar esta acción ya que esta bloqueada
424	Failed Dependency - La acción solicitada dependía de otra acción y esa acción falló
500	Server Error - El servidor encontró una condición inesperada que le impidió cumplir con la solicitud.
1081	El pago fue realizado con éxito, pero no se ha recibido la confimación.
4001	El campo no ha sido enviado.
4002	Tiene valores duplicados.
4011	Token inválido.
4012	Credenciales incorrectas.
4013	La sesión no es válida.
4014	Se requiere el encabezado Authorization.
4015	Falta subject en payload.
4016	La sesión expiró.
4031	No cuentas con los permisos para realizar esta acción.
4032	No existe una solicitud para establecer contraseña.
4033	No fue posible verificar la autenticidad de la firma.
4041	El recurso que buscas no existe.
4042 {{model}}	La instancia del modelo {{model}} no se encontró.
4091	El administrador debe tener los permisos básicos.
4092	Este correo electrónico ya ha sido tomado.
4093 {{thing}} {{value}}	{{thing}} {{value}} ya ha sido tomado.
4101	El recurso solicitado ya no está disponible
4151	El formato debe ser uno de los siguientes: jpg, jpeg, png, pdf.
4152 {{h}} {{w}}	El tamaño de la imagen debe ser mayor a {{h}} x {{w}} px.
4153 {{size}}	El archivo debe pesar a lo más {{size}} Kb.
4154	Debe ser un archivo (Hint: Content-Type: multipart/form-data)
4221	No puede ser vacío onull.
4222 {{len}}	Debe tener {{len}} o más caracteres.
4223 {{len}}	Debe tener a lo más {{len}} caracteres.
4224	El formato no es válido.
4225	Las contraseñas no coinciden.
4226 {{len}}	La longitud del debe ser {{len}}.
4227	Debe tener sólo letras.
4228	Debe tener sólo letras y números.
4229 {{format}}	Debe tener el formato {{format}}
42210 {{list}}	Debe ser uno de los siguientes valores: {{list}}
42211	Debe ser true o false
42212 {{min}} {{max}}	Debe ser mayor que {{min}} y menor o igual que {{max}}
42213	No es una URL válida.
42214 {{type}}	Debe ser del tipo: {{type}}
42215	El rango de fechas es incorrecto.
42216	Correo electrónico inválido.
42217	Debe ser una cadena.
42218	Debe ser un número.
42219	Debe ser un Objeto JSON.
42220	Debe ser un arreglo.
42221	Debe ser un valor booleano.
42222	Debe ser una cadena de números.
42223	Debe ser una fecha.
42224	Debe tener sólo letras y .
42225	Identificador Único inválido.
42226	Número de teléfono inválido.
4231	No puedes cambiar tu rol.
4232	No puedes desactivarte.
4241	No fue posible enviar el correo electrónico debido a problemas con el servidor SMTP.