interfaz de programación de aplicaciones (api)

2022-06-09

Interfaz de Programación de Aplicaciones(API)

ii | Contents | ii

Contents

Información general................................................................................................................3

Generalidades............................................................................................................................ 5

Introducción................................................................................................................................6

REST (REpresentational State Transfer)....................................................................... 7Métodos HTTP..............................................................................................................................................................................................................................8Códigos de estado HTTP................................................................................................................................................................................................8

CURL............................................................................................................................................... 9

Primeros pasos........................................................................................................................10Crear un token de API......................................................................................................................................................................................................10Realizar una solicitud de inicio de sesión................................................................................................................................................... 13Realizar una solicitud de fin de sesión...........................................................................................................................................................15

Primeras consultas................................................................................................................ 17Consultar números de versión................................................................................................................................................................................ 17Consultar el ID de objeto.............................................................................................................................................................................................. 18Consultar correos electrónicos............................................................................................................................................................................... 18Consultar estadísticas de correos........................................................................................................................................................................19Consultar datos sobre personalizaciones.................................................................................................................................................. 20

Detección y solución de errores.................................................................................... 22Detectar y corregir errores.......................................................................................................................................................................................... 22

Cambiar el ámbito de aplicación........................................................................................................................................................ 24

Índice...................................................................................................................................................................... 25

Información general

Información generalAclaratoria sobre el género

En aras de una mejor legibilidad, este manual utiliza la forma de lenguaje del masculinogenérico. Cabe señalar aquí, que el uso exclusivo de la forma masculina debe entenderseindependientemente del género.

Símbolos utilizados

Los siguientes símbolos se utilizan para identificar mejor los pasos relevantes dentro de los capítulosde instrucciones:

SÍMBOLO SIGNIFICADO ACLARACIÓN

Requisito Requisito Condición que debe cumplirse antes del siguientepaso.

Resultadoprovisional

Resultado provisional Resultado, que se consigue en el interíndespués de un paso.

Resultado final Resultado obtenido según la secuencia de pasos de un capítuloque guía la acción.

Advertencias e instrucciones de seguridad

Las instrucciones de advertencia y seguridad se utilizan para informar al usuario sobre losriesgos y peligros residuales, y para evitarlos mediante un procedimiento recomendado. En estadocumentación se utilizan las siguientes advertencias e instrucciones de seguridad:


Información Información Hace referencia a la información general de unproducto y/o un servicio.

3

Información general


Indicación Indicación Información adicional dentro de un párrafo enparticular, que es relevante para la ejecución de pasosposteriores.

ATENCION Advertencia sobre los costes adicionales que se podrían produciren función a los servicios reservados.

CUIDADO Advertencia sobre la posible pérdida de datos

PELIGRO Consejos de seguridad sobre una posible infección del sistemacon malware

4

Generalidades

GeneralidadesEstas instrucciones tienen por objeto dar a conocer mejor nuestra API y solo explican los primerospasos con el producto. Encontrará una documentación completa con todos los puntos finales denuestra API en https://cp.<su dominio>.com/api/docs/.

5

Introducción

IntroducciónLas APIs sirven para intercambiar información entre una aplicación y partes de un programa deun modo normalizado. Una sintaxis predefinida permite una transmisión estructurada de datos yórdenes.

Nuestra API le ofrece las siguientes ventajas:

• Los datos y funciones de la versión HTML de Control Panel pueden incorporarse a interfacespropias.

• Es posible automatizar labores administrativas repetitivas (p. ej., provocar la clasificación de uncorreo con el tipo "Contenido", evaluar correos no deseados o editar registros de listas blancas ynegras).

6

REST (REpresentational State Transfer)

REST (REpresentational State Transfer)REST es un estándar empleado para comunicarse con los puntos finales (endpoints) de una APImediante solicitudes estructuradas (requests). REST se basa en el concepto de un recurso conubicación identificable mediante una dirección unívoca (Unique Ressource Identifier (URI)). Es posiblerealizar consultas a los recursos en diversos formatos (p. ej., JSON XML o EDN). Para que unasolicitud pueda realizarse con éxito, debe contener determinados datos:

1. Método: El método indica qué operación del servicio debe ejecutarse (véase Métodos HTTPen la página 8).

2. Dirección: La dirección es una ruta unívoca al recurso al que se dirige.

3. Argumento: El argumento indica el término por el que filtrar en la solicitud.

4. Encabezado (header): El encabezado sirve para intercambiar metadatos generales.

5. Contenido (body): El contenido sirve para intercambiar información específica.

Las solicitudes de API conforme al estándar REST pueden realizarse, por ejemplo, mediante CURL(véase CURL en la página 9).

7

REST (REpresentational State Transfer)

Métodos HTTPPara comunicarse con un punto final mediante la API es necesario formular un método en lasolicitud. El método indica qué operación del servicio debe ejecutarse al contactar con el recurso.Normalmente se emplean los siguientes métodos:

• GET solicita el recurso indicado al servidor.

• PUT crea un recurso. Si el recurso ya existe, lo modifica.

• POST crea un nuevo recurso dentro del recurso indicado y asigna un ID unívoco.

• PATCH modifica o actualiza la parte indicada de un recurso.

• DELETE elimina el recurso indicado.

Códigos de estado HTTPTras una solicitud, el sistema devuelve una respuesta (response) en forma de código de estado.Mediante el código de estado HTTP, el servidor comunica si la solicitud se ha procesado con éxito.En caso de error, el código de estado contiene información sobre su tipo. Los códigos de error sedividen en las siguientes categorías:

• Respuestas informativas (100–199).

• Operaciones correctas (200–299).

• Redirecciones (300–399).

• Errores del cliente (400–499).

• Errores del servidor (500–599).

Aquí se ofrece una vista general de todos los códigos de estado posibles: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status.

8

https://developer.mozilla.org/en-US/docs/Web/HTTP/Status

https://developer.mozilla.org/en-US/docs/Web/HTTP/Status

CURL

CURLCURL permite realizar solicitudes personalizadas a una API de REST.

Ejemplo de solicitud con CURL:

curl --request POST \ --url 'http://httpbin.org/anything?=&arg2=val2&arg1=val1'\ --header 'content-type: application/json'\ --data'{ "key": "value" }'

Los siguientes capítulos contienen ejemplos de solicitudes de API con CURL (véase Primerasconsultas en la página 17).

Puede descargar la versión actual de CURL para su sistema operativo en https://curl.haxx.se/download.html.

En https://curl.haxx.se/docs/httpscripting.html encontrará una documentación completa sobreCURL.

9

https://curl.haxx.se/download.html

https://curl.haxx.se/download.html

https://curl.haxx.se/docs/httpscripting.html

Primeros pasos

Primeros pasosPara establecer una conexión con nuestra API y poder realizar solicitudes precisas, es necesarioindicar siguientes datos:

INFORMACIÓN DESCRIPCIÓN RECURSO

ID de app El ID de la appempleada

Nosotros le proporcionamos el ID de app. Póngase encontacto con el soporte técnico.

Versión de app La versión de laaplicación empleada

La versión de app es la versión de la aplicación empleadapara realizar solicitudes a nuestra API.

Token de CP Su token de accesopersonal

Puede crear su token de CP en Control Panel (véase Crearun token de API en la página 10).

Para poder acceder a Control Panel a través de nuestra API es preciso que indique también sunombre de usuario y su contraseña. Una vez iniciada la sesión, los datos de acceso se envían en elencabezado de autenticación (authorization header) junto con un ID de objeto (object_id) así comoun token de autenticación. El ID de objeto representa el ámbito de aplicación en el que el usuarioautenticado ejerce su rol, mientras que el token es una clave de acceso personal para consultas a laAPI. Para más información, véase Realizar una solicitud de inicio de sesión en la página 13.

Crear un token de APILos tokens de API le permiten conceder a aplicaciones acceso a la API de Control Panel. Cadaaplicación necesita su propio token. En su configuración de usuario (véase Configuración de usuario)puede crear tokens de API para que se autoricen en Control Panel.

1. Inicie sesión en Control Panel con sus datos de acceso de administrador.

10

Primeros pasos

2. Haga clic en el icono , situado en la esquina superior derecha de Control Panel.

Se muestra la configuración de usuario.

Figura 1: Configuración de usuario3. Seleccione la pestaña Token de API.4. Haga clic en Crear token.

Figura 2: Creación de un token

Se muestran ajustes adicionales.

11

Primeros pasos

5. En el campo Nombre de la aplicación, introduzca el nombre de la aplicación que emplearáel token.

Nota:

Las acciones ejecutadas con dicho token se mostrarán en el módulo Registro deauditorías 2.0 a nombre del usuario que crease el token.

Figura 3: Introducir el nombre de la aplicación6. Opcional: En Caduca el, seleccione la fecha de caducidad del token.

Nota:

El valor por defecto es Nunca.

12

Primeros pasos

7.PRECAUCIÓN:

Por motivos de seguridad, el token solo se muestra una vez. Si no guarda el token, seperderá. Guarde el token inmediatamente.

Haga clic en Crear.

El token de API se crea y se muestra.

Figura 4: Token creado

Se ha creado un token de API.

Si un token de API deja de serle necesario, puede eliminarlo de Control Panel (véase Eliminar untoken de API).

Realizar una solicitud de inicio de sesiónPuede iniciar sesión en Control Panel con sus datos de acceso mediante nuestra API.

13

Primeros pasos

Importante:

Los datos de acceso deben ser válidos.

Ejecute la solicitud indicada a continuación sustituyendo los comodines por sus propios datos.

curl --request POST \ --url https://cp.<su dominio>.com/api/v0/auth/login/ \ --header 'app-id: <su ID de app>'\ --header 'app-version: <su versión de app en formato X.X.X.X>'\ --header 'cp-token: <su token de CP>\ --header 'content-type: application/json'\ --data'{ "username": "<su dirección de correo>", "password": "<su contraseña>" }'

La solicitud se envía. Si el inicio de sesión se efectúa correctamente, la API emitirá una respuestasegún el siguiente patrón:

{ "object_id": 133456, "token": "b332ec9e19b88f8fdf5bfc1def03291f361c479d" }

Nota:

El ID de objeto (object_id) es el ID de un ámbito de aplicación y solo se exige para algunassolicitudes relativas a dicho ámbito. El token emitido debe enviarse como elemento deautorización en todas las solicitudes posteriores.

Nota:

Si la respuesta contiene un mensaje de error, compruebe el código de estado (véase Códigosde estado HTTP en la página 8) y efectúe un análisis de errores (véase Detectar y corregirerrores en la página 22). Si el problema persiste, póngase en contacto con el soportetécnico.

Se ha efectuado el inicio de sesión en Control Panel.

14

Primeros pasos

Ejemplo de solicitud autorizada:

curl --request GET \ --url 'https://cp.<su dominio>.com/api/v0/user/format/?object_id=12345678'\ --header 'app-id: 0123456789'\ --header 'app-version: X.X.X.X'\ --header 'cp-token: m31nCpT0k3n'\ --header 'authorization: Token b332ec9e19b88f8fdf5bfc1def03291f361c479d'

Realizar una solicitud de fin de sesiónPuede cerrar sesión en Control Panel con sus datos de acceso mediante nuestra API.


curl --request POST \ --url https://cp.<su dominio>.com/api/v0/auth/logout/ \ --header 'app-id: <su ID de app>'\ --header 'app-version: <su versión de app en formato X.X.X.X>'\ --header 'cp-token: <su token de CP>'\ --header 'authorization: Token <su token de autorización>'

Nota:

El token de autorización se emite tras el inicio de sesión en Control Panel (Realizar unasolicitud de inicio de sesión en la página 13).

La solicitud se envía. Si la solicitud se ejecuta correctamente, la API emitirá una respuesta con elcódigo de estado 200. El token de autorización perderá a continuación su validez y no podrá volvera usarse.

Nota:

Si la respuesta contiene un mensaje de error, compruebe el código de estado (véase Códigosde estado HTTP en la página 8) y efectúe un análisis de errores (véase Detectar y corregirerrores en la página 22). Si el problema persiste, póngase en contacto con el soportetécnico.

15

Primeros pasos

Se ha cerrado sesión en Control Panel.

16

Primeras consultas

Primeras consultasEn esta sección se muestran ejemplos de primeras consultas. Estos ejemplos sirven parafamiliarizarse con y pueden emplearse como base para futuras solicitudes. Encontrará ladocumentación completa de todos los puntos finales disponibles de la API en https://cp.<sudominio>.com/api/v0/docs/.

Como ya se ha mencionado en la sección Primeros pasos en la página 10, es necesario enviar lossiguientes datos en cada solicitud:

• ID de app

• Versión de app

• Token de CP

• Nombre de usuario

• Contraseña

• ID de objeto

• Token

Consultar números de versiónPuede consultar el número de versión actual de Control Panel.


curl --request GET \ --url https://cp.<su dominio>.com/api/v0/version/ \ --header 'app-id: <su ID de app>'\ --header 'app-version: <su versión de app en formato X.X.X.X>'\ --header 'cp-token: <su token de CP>'\ --header 'authorization: Token <su token de autorización>'

Se muestra el número de versión. Por ejemplo:

6.17.0.0

17

Primeras consultas

Se ha consultado el número de versión de Control Panel.

Consultar el ID de objetoAlgunas solicitudes para dominios específicos solo pueden ejecutarse si el rol de usuario tienederecho a realizarlas y se ha elegido el ámbito de aplicación correcto. Si el usuario no tiene derechoa realizar una solicitud, recibe como respuesta un mensaje de error con el código de estado 400.En tal caso, al igual que en Control Panel, es necesario cambiar el ámbito de aplicación para poderefectuar la solicitud (véase Cambiar el ámbito de aplicación en la página 24). El ámbito sedetermina mediante el ID de objeto. Puede consultar el ID de objeto mediante el punto final /hierarchy/ y emplearlo en posteriores solicitudes.


curl --request POST \ --url https://cp.<su dominio>.com/api/v0/hierarchy/_search/ \ --header 'app-id: <su ID de app>'\ --header 'app-version: <su versión de app en formato X.X.X.X>'\ --header 'cp-token: <su token de CP>'\ --header 'authorization: Token <su token de autorización>'\ --header 'content-type: application/json'\ --data'{ "search_string":"<su dominio>", "filter":"customer" }'

Los datos consultados se muestran. Los datos contienen el ID de objeto (id).

[ { "id":1111111, "name":"partner", "is_user":false, "children_count":116, "children":[ { "id":2222222, "name":"<su dominio>", "is_user":false, "children_count":289 } ] } ]

Se ha consultado el ID de objeto del dominio.

A continuación puede emplear el ID de objeto para efectuar solicitudes a dominios específicos.

Consultar correos electrónicosPuede buscar correos de Control Panel y consultar los resultados de la búsqueda.

18

Primeras consultas


curl --request POST \ --url 'https://cp.<su dominio>.com/api/v0/emails/_search/?object_id=<su ID de objeto>'\ --header 'app-id: <su ID de app>'\ --header 'app-version: <su versión de app en formato X.X.X.X>'\ --header 'cp-token: <su token de CP>'\ --header 'authorization: Token <su token de autorización>'\ --header 'content-type: application/json'\ --data '{ "limit": 50, "date_from": "<fecha y hora de inicio en formato 2018-06-21T00:00:00Z>", "date_to": "<fecha y hora de finalización en formato 2018-07-21T00:00:00Z>" }

Sus correos se consultan y se muestran en la respuesta.

{ "source_ip":"94.100.135.100", "gateway":"mx-gate70-hz2", "comm_partner":"<dirección de correo del interlocutor>", ... "classification":{ "text":"clean", ... }, "owner":"<dirección de correo del propietario del correo>", "encryption":{ "text":"EMIG", ... }, "date":"<fecha y hora del correo en formato 2018-07-18T09:14:56Z>", "subject":"<asunto del correo>", ... }

Se han consultado correos de Control Panel.

Consultar estadísticas de correosPuede consultar la estadística de correos de Control Panel de un periodo determinado.


curl --request POST \ --url 'https://cp.<su dominio>.com/api/v0/emails/statistics/by_time/?object_id=12345678'\ --header 'app-id: <su ID de app>'\ --header 'app-version: <su versión de app en formato X.X.X.X>'\ --header 'cp-token: <su token de CP>'\ --header 'authorization: Token <su token de autorización>'\ --header 'content-type: application/json'\ --data '{ "date_from": "<fecha y hora de inicio en formato 2018-06-21T00:00:00Z>", "date_to": "<fecha y hora de finalización en formato 2018-07-21T00:00:00Z>" }'

La estadística de correos electrónicos se solicita a Control Panel.

[ { "type":2, "value":45, "name":"clean" }, { "type":1, "value":4, "name":"spam" }, { "type":11, "value":0, "name":"info" }, { "type":8, "value":0, "name":"content" },

19

Primeras consultas

{ "type":12, "value":0, "name":"atp" }, { "type":5, "value":0, "name":"virus" }, { "type":3, "value":0, "name":"rejected" } ]

Se ha consultado la estadística de correos de Control Panel.

Consultar datos sobre personalizaciones

Puede consultar a Control Panel los ajustes del módulo Personalización para su dominio.


curl --request GET \ --url 'https://cp.<su dominio>.com/api/v0/whitelabeling/?object_id=<su ID de objeto>'\ --header 'app-id: <su ID de app>'\ --header 'app-version: <su versión de app en formato X.X.X.X>'\ --header 'cp-token: <su token de CP>'\ --header 'authorization: Token <su token de autorización>'

Nota:

Para consultar datos sobre personalización al punto final /whitelabeling/, es necesarioindicar el ID de objeto (object_id) del dominio.

Nota:

Para consultar datos sobre la personalización de un dominio desconocido, emplee el puntofinal /whitelabeling/infos/ en lugar de /whitelabeling/. Este punto final devuelve datosactuales sobre personalización en base al encabezado del host.

Los datos sobre personalización se muestran. El código del siguiente ejemplo se muestra abreviado.

{ "theme":"dark", "primary_colour":"#15358B", "favicon":"data:image/x-icon;base64,AAAB...", "domain":"<dominio de Control Panel>", "logo":"data:image/png;base64,iVBOR...", "email_sender":"", "id":542 }

20

Primeras consultas

Nota:

El logotipo y el favicon se representan en la respuesta en forma de cadenas codificadas enbase 64.

Se han consultado los datos de personalización de Control Panel para el dominio.

21

Detección y solución de errores


Detectar y corregir erroresnuestra API responde con mensajes de error a solicitudes con parámetros incorrectos o a las quele falten parámetros. Para permitir una correcta interpretación de los errores, los mensajes de errorcontienen códigos de estado. El código de error le permite determinar el tipo de error que afecta asu solicitud (véase Códigos de estado HTTP en la página 8). Como los códigos de error suelen serpoco específicos, los errores contienen explicaciones adicionales.

Para interpretar correctamente los mensajes de error y tomar las medidas adecuadas,recomendamos el siguiente procedimiento:

1. Compruebe el código de estado (véase Códigos de estado HTTP en la página 8) e intenteaveriguar la causa a partir del mensaje de error.

22


2. Consulte los parámetros necesarios para la solicitud en la documentación de la API (véasehttps://cp.<su dominio>.com/api/v0/docs/).Ejemplo de mensaje de error

{ "error_data":{ "object_id":[ "This field is required." ] }, "error_message":"Validationerror", "error_id":2009, "status_code":400 }

En este ejemplo falta el object_id, indispensable para la solicitud conforme a ladocumentación de la API.

Figura 5: Consultar la documentación de la API3. Si no es capaz de resolver el error por sí mismo, póngase en contacto con el soporte técnico.

Se han detectado y corregido errores en solicitudes de API.

23


Cambiar el ámbito de aplicación

No tiene permiso acceder a información específica de dominio.

Falta de permiso

Algunas consultas específicas de dominios solo pueden efectuarse si el rol de usuario tiene derechoa realizarlas y se ha elegido el dominio correcto (véase Consultar el ID de objeto en la página 18).

24

| Índice | 25

Índice

AAPI

crear token, Ver token de API crear

Ccrear

token de API, Ver token de API crear

Ttoken de API

crear 10

interfaz de programación de aplicaciones (api)

Documents