ShortAE Documentación

Para autenticarse y obtener un token de acceso para futuras consultas, se debe realizar una solicitud POST al endpoint /api/authentication. El token de acceso es necesario para todas las próximas solicitudes del API.

Endpoint

POST https://shortae.com/api/authentication

Parámetros

• UserApi (requerido): Nombre de usuario asignado por el sistema.
• PasswordApi (requerido): Contraseña asignada por el sistema.

Nota: Los parámetros UserApi y PasswordApi para autenticación se encuentran en el menú superior derecho del sistema para los usuarios con rol de administrador.

Respuesta

La respuesta es un objeto JSON con las siguientes claves:

• success: Indica si la solicitud tuvo éxito.
• answer: Contiene un objeto con las siguientes claves:
  • access_token: Token de acceso necesario para las próximas solicitudes del API.
  • date: Fecha y hora en que se creó el token.

Ejemplo

curl -X POST https://shortae.com/api/authentication \
     -u "UserApi:PasswordApi"

Es importante adaptar este ejemplo a tu API específica, incluyendo la autenticación y los parámetros necesarios. Recuerda que el token de acceso debe ser incluido como el parametro access_token en las próximas solicitudes al API.

Introducción

En ShortAE, al realizar una solicitud a través del API, es posible recibir respuestas con el valor de success igual a false. En estos casos, se retorna un mensaje de error en la clave answer del objeto JSON de respuesta.

Errores Comunes

A continuación, se detallan algunos de los errores más comunes que se pueden recibir en ShortAE:

Falta del Access Token

Si la solicitud realizada requiere autenticación, pero no se envió el access_token correspondiente, se recibirá un mensaje de error similar al siguiente:

{
  "success": false,
  "answer": "Access Token Missing"
}

Menú no Existe

Si se está consultando un menú con un alias que no existe en el sistema, se recibirá un mensaje de error similar al siguiente:

{
  "success": false,
  "answer": "Menu Alias Not Found"
}

Campos Requeridos

Si se está realizando una solicitud que requiere campos específicos, y estos no son enviados, se recibirá un mensaje de error similar al siguiente:

{
  "success": false,
  "answer": "Missing Required Fields: campo1, campo2, campo3"
}

Permisos Insuficientes

Si se está intentando realizar una acción para la que no se tienen los permisos necesarios, se recibirá un mensaje de error similar al siguiente:

{
  "success": false,
  "answer": "Insufficient Permissions: permiso1, permiso2"
}

Contraseña o Usuario Incorrecto

Si se está intentando iniciar sesión en el sistema y la contraseña o el usuario son incorrectos, se recibirá un mensaje de error similar al siguiente:

{
  "success": false,
  "answer": "Incorrect Username or Password"
}

Archivos no Cargados

Si se está intentando cargar archivos, y por alguna razón no se pudieron cargar algunos de ellos, se recibirá un mensaje de error similar al siguiente:

{
  "success": false,
  "answer": "Failed to Upload Files: archivo1, archivo2"
}

Conclusión

Es importante tener en cuenta que en ShortAE, los errores se manejan a través del valor de success y la clave answer. Es recomendable revisar el mensaje de error recibido para solucionar los problemas de manera efectiva.

Endpoint:

POST https://shortae.com/api/login

Función:

Esta solicitud POST se utiliza para hacer inicio de sesión y obtener un token de acceso para autenticar futuras solicitudes en la API de ShortAE.

Parámetros opcionales:

• UserApi: El nombre de usuario utilizado para autenticar la solicitud.
• PasswordApi: La contraseña utilizada para autenticar la solicitud.

Respuesta:

La respuesta es un objeto JSON con las siguientes claves:

• success: Indica si la solicitud tuvo éxito.
• answer: Contiene información de usuario, incluyendo el token de acceso, el nombre de usuario, el id_rol y otros datos del usuario.

Ejemplo de solicitud utilizando cURL con autenticación básica y el access_token:

curl -u "TuNombreDeUsuario:TuContraseña" \
     -X POST https://shortae.com/api/login \
     -d access_token="TuTokenDeAcceso"

Ejemplo de solicitud utilizando cURL con parámetros opcionales y el access_token:

curl -X POST https://shortae.com/api/login \
     -d UserApi="TuNombreDeUsuario" \
     -d PasswordApi="TuContraseña" \
     -d access_token="TuTokenDeAcceso"

Nota:

Recuerda que el access_token es un parámetro obligatorio que debe ser incluido en todas las consultas a la API de ShortAE para autenticar la solicitud. El token de acceso obtenido en la respuesta de esta solicitud debe ser utilizado en las siguientes solicitudes para identificar al usuario autenticado. Además, es importante asegurarse de que la conexión sea segura (por ejemplo, utilizando HTTPS en lugar de HTTP) para proteger la información de autenticación del usuario.

Este POST te permitirá consultar los datos de cualquier menú creado utilizando su alias como referencia dentro de la URL a la que se consulta.

Endpoint

GET https://shortae.com/api/{alias-de-menu}

Parámetros

• u (obligatorio): Token de usuario utilizado para autenticar la solicitud, que se envía mediante autenticación básica (-u) en el comando curl.
• access_token (obligatorio): Token de acceso necesario para la solicitud, que se envía como un parámetro mediante el comando curl.
• XML (opcional): Si se agrega esta variable a la consulta, en vez de recibir la respuesta en formato JSON, se recibirá en formato XML.
• debug (opcional): Si se agrega esta variable a la consulta, se imprimirá la respuesta usando la función var_dump(), para ayudar en la depuración del código.
• search (opcional): Si se utiliza esta variable, se buscará en los datos del menú para asegurarse de que contenga lo indicado.
• UserApi (opcional): Si se utiliza esta variable, se puede evitar enviar el usuario en la autenticación con la opción -u del comando curl.
• PasswordApi (opcional): Si se utiliza esta variable, se puede evitar enviar la contraseña en la autenticación con la opción -u del comando curl.
• orden y order (opcional): Ambas variables son por defecto ascendentes "ASC". Si se envía DESC, la consulta será descendente.
• aordenar y orderby (opcional): Se utilizan para señalar el campo del menú por el cual se desea ordenar la consulta.
• desde y limite (opcional): Se utilizan para la paginación de los resultados. Limite indica cuántos datos tendrá la respuesta y desde indica el inicio de la consulta.

Todas estas variables pueden ser enviadas tanto por GET como por POST.

Respuesta

La respuesta es un objeto JSON con las siguientes claves:

• success: Indica si la solicitud tuvo éxito.
• answer: Contiene los datos del menú consultado.

Ejemplo

curl -X GET 'https://shortae.com/api/{alias-de-menu}?XML&search=valor-buscado&orden=DESC&aordenar=nombre-campo&limite=10&desde=20' \
  -u "{token-de-usuario}:" \
  -d access_token="Your access_token"

Es importante que adaptes este ejemplo a tu API específica, incluyendo el alias de menú y los parámetros necesarios. Además, recuerda que debes incluir el token de acceso (access_token) en la consulta, el cual se obtiene utilizando la función Authentication del API.

Esta consulta permite conocer los campos que tiene agregados un menú, así como sus tipos de datos y si son requeridos o no. Para realizar esta consulta se requiere hacer previamente la autenticación y el inicio de sesión para obtener el access_token y el token correspondiente.

URL

https://shortae.com/api/camp/{alias_de_menu}

Donde {alias_de_menu} es el alias asignado al menú que se quiere consultar.

Método

GET

Parámetros

Cabeceras

Respuesta

En caso de éxito, se devuelve un objeto JSON con la siguiente estructura:

{
  "success": true,
  "answer": [
    {
      "alias_campo_1": {
        "tipo": "tipo_de_dato",
        "requerido": true/false
      }
    },
    {
      "alias_campo_2": {
        "tipo": "tipo_de_dato",
        "requerido": true/false
      }
    }
  ]
}

Donde cada objeto dentro del array answer corresponde a un campo del menú, y su contenido muestra el tipo de dato y si es requerido o no. Los valores de tipo_de_dato pueden ser:

• texto
• entero
• decimal
• booleano
• fecha
• hora
• fecha_hora
• opción
• archivo

Ejemplo

Petición

GET https://shortae.com/api/camp/menu_ejemplo
Authorization: Bearer {token_de_sesion}

Respuesta

{
  "success": true,
  "answer": [
    {
      "campo_texto": {
        "tipo": "texto",
        "requerido": true
      }
    },
    {
      "campo_numero": {
        "tipo": "entero",
        "requerido": false
      }
    },
    {
      "campo_fecha": {
        "tipo": "fecha",
        "requerido": true
      }
    }
  ]
}

En las consultas del API de nuestro administrador, se pueden utilizar las siguientes variables para personalizar los resultados:

Variables

• XML: Si se agrega esta variable a la consulta, en vez de recibir la respuesta en formato JSON, se recibirá en formato XML.
• debug: Si se agrega esta variable a la consulta, se imprimirá la respuesta usando la función var_dump(), para ayudar en la depuración del código.
• search: Si se utiliza esta variable, se buscará en los datos del menú para asegurarse de que contenga lo indicado.
• UserApi: Si se utiliza esta variable, se puede evitar enviar el usuario en la autenticación con la opción -u del comando curl.
• PasswordApi: Si se utiliza esta variable, se puede evitar enviar la contraseña en la autenticación con la opción -u del comando curl.
• order y orden: Ambas variables son por defecto ascendentes (ASC). Si se envía DESC, la consulta será descendente.
• orderby y aordenar: Se utilizan para señalar el campo del menú por el cual se desea ordenar la consulta.
• desde y limite: Se utilizan para la paginación de los resultados. Limite indica cuántos datos tendrá la respuesta y desde indica el inicio de la consulta.

Todas estas variables pueden ser enviadas tanto por GET como por POST.

Endpoint

GET/POST https://shortae.com/api/{alias del menú}

Parámetros

• access_token: Token de acceso necesario para todas las próximas solicitudes del API. Se obtiene utilizando la función Authentication del API.
• token: Token de usuario necesario para las solicitudes del API, se obtiene utilizando la funcion Login del API.

Opcionales:

• XML
• debug
• search
• UserApi
• PasswordApi
• order
• orden
• orderby
• aordenar
• desde
• limite

Respuesta

La respuesta es un objeto JSON con los datos del menú solicitado.

Ejemplo

curl https://shortae.com/api/{alias del menú}?XML&search=valor-buscado&orden=DESC&aordenar=nombre-campo&limite=10&desde=20 -u "{token user}:" -d access_token="Your access_token"

En este ejemplo se están utilizando varias variables en la consulta: XML para recibir la respuesta en formato XML, search para buscar un valor específico, orden y aordenar para ordenar la consulta, limite y desde para la paginación.

Recuerda que siempre debes incluir el token de acceso (access_token) en la consulta.

Esta solicitud permite agregar nuevos datos a un menú existente. Para hacerlo, se debe utilizar el endpoint con el prefijo "add" seguido del alias del menú y enviar los campos necesarios en la solicitud.

Endpoint

POST/GET https://shortae.com/api/add{alias-de-menu}

Parámetros

Respuesta

La respuesta es un objeto JSON con las siguientes claves:

Ejemplo

curl https://shortae.com/api/addcasas \
-u "{token-de-usuario}:" \
-d access_token="Your access_token" \
-d "direccion=Av. 123" \
-d "ciudad=Bogotá" \
-d "precio=100000"

En este ejemplo se están agregando los campos direccion, ciudad y precio al menú con alias casas. Recuerda adaptar el ejemplo a tu API específica y enviar los campos que correspondan al menú que estés utilizando.

Esta función se utiliza para editar un elemento del menú utilizando su identificador y su alias como referencia dentro de la URL a la que se consulta.

Endpoint

GET/POST https://shortae.com/api/edit{alias-de-menu}/{identificador}

Parámetros

• u: Token de usuario utilizado para autenticar la solicitud.
• access_token: Token de acceso necesario para la solicitud.

Además de los campos que se deseen editar en el elemento del menú.

Respuesta La respuesta es un objeto JSON con las siguientes claves:

• success: Indica si la solicitud tuvo éxito.
• answer: Contiene la información actualizada del elemento del menú.

Ejemplo

curl https://shortae.com/api/editcasas/123 \
  -u "{token-de-usuario}:" \
  -d access_token="Your access_token" \
  -d titulo="Nueva casa en venta" \
  -d precio="100000" \
  -d descripcion="Hermosa casa de dos pisos con jardín y piscina"

Es importante que adaptes este ejemplo a tu API específica, incluyendo el alias del menú, el identificador del elemento a editar y los parámetros necesarios que desees modificar.

Endpoint GET/POST https://shortae.com/api/del{alias-de-menu}/{identificador}

Descripción Este endpoint se utiliza para eliminar un elemento de un menú previamente creado.

Parámetros

• u: Token de usuario utilizado para autenticar la solicitud.
• d access_token: Token de acceso necesario para la solicitud.

Respuesta La respuesta es un objeto JSON con las siguientes claves:

• success: Indica si la solicitud tuvo éxito.
• answer: Un mensaje en texto que indica si el elemento fue eliminado satisfactoriamente.

Ejemplo

curl https://shortae.com/api/delcasas/123 \
  -u "{token-de-usuario}:" \
  -d access_token="Your access_token"

Notas

• La eliminación del elemento es permanente y no puede deshacerse.
• Se debe especificar el alias del menú y el identificador del elemento a eliminar en la URL del endpoint.
• Se recomienda tener precaución al utilizar este endpoint, ya que eliminará permanentemente el elemento especificado.

Descripción

Esta función es utilizada para consultar todos lo Menús disponibles para consulta de un usuario

Endpoint GET/POST https://shortae.com/api/menus

Parámetros

Respuesta

La respuesta es un objeto JSON con las siguientes claves:

Cada objeto dentro del array answer contiene la siguiente información:

Ejemplo

curl https://shortae.com/api/menus \
  -u "{token-de-usuario}:" \
  -d access_token="Your access_token"

Es importante que adaptes este ejemplo a tu API específica, incluyendo los parámetros necesarios.

Espero que este POST te sea de ayuda. Si necesitas algo más, no dudes en preguntar.

Esta solicitud POST se utiliza para registrar un nuevo usuario en el sistema.

Endpoint

POST https://shortae.com/api/register

Parámetros

• access_token: (required) Token de acceso necesario para la solicitud.
• username: (required) Nombre de usuario del nuevo usuario. Debe ser único y tener una longitud entre 3 y 20 caracteres.
• email: (required) Correo electrónico del nuevo usuario. Debe ser válido y no estar asociado a otra cuenta en el sistema.
• password: (required) Contraseña del nuevo usuario. Debe tener una longitud mínima de 8 caracteres y contener al menos una letra minúscula, una letra mayúscula, un número y un carácter especial.

Respuesta La respuesta es un objeto JSON con las siguientes claves:

• success: Indica si la solicitud tuvo éxito.
• answer: Contiene todos los datos del usuario, mas el identificador del nuevo usuaario

Ejemplo

curl -X POST https://shortae.com/api/register \
  -d access_token="Your access_token" \
  -d username="newuser" \
  -d email="newuser@example.com" \
  -d password="newpassword"

Es importante que adaptes este ejemplo a tu API específica, incluyendo los parámetros necesarios.