[ES] – Documentación API REST DMDS v2 con cURL

Documentación API REST DMDS v2 con comandos cURL

En este tutorial se van a mostrar diferentes ejemplos de como llamar la api rest del DMDS (Data-Mining and Delivery Services) utilizando llamadas cURL. Siempre tener en cuenta que método (GET, POST, DELETE, etc) se esta usando para cada llamada, los datos que se pasan y la url de la llamada.

Importante: recordar que el nombre de host y authorization es própio de cada uno.

Curl en Microsoft Windows

Pueden descargar curl aquí :
http://www.paehl.com/open_source/?CURL_7.72.0

Devuelve información de un contacto

En este ejemplo se ve como devolver la información de un contacto en concreto. En la llamada, en la url, hay que especificar el email del usuario ya existente en la base de datos de la api. Así de esta manera, se nos presentará todo la información de un contacto, como su nombre, apellido, a que grupo pertenece, sus eventos, etc.

curl -X GET "https://api-dmds-host/v1/contacto/correo@dominio.com" -H "accept: application/json" -H "Authorization: xxxxxxxxxxx
Listar contactos inválidos

Con esta llamada se nos mostrarán todos los usuarios que están inválidos.

curl -X GET "https://api-dmds-host/v1/contactos/invalidos/" -H "accept: application/json" -H 'Authorization: xxxxxxxxxxxxxx'
Crear de nuevo o actualizar un contacto

Con la siguiente llamada se puede crear un contacto de nuevo o actualizar uno existente.

La primera variable que se define es el correo electrónico, para entenderlo es como una primary key en la base de datos. Siempre para actualizar algún contacto nos basaremos en su email ya que es único.

En la parte de datos definimos diferentes atributos, que pueden definir un usuario. Todos esos campos se pueden ir cambiado a medida que el usuario cambia algún de los valores. Para especificar que usuario queremos modificar usaremos su email.

curl -X POST "https://api-dmds-host1/v1/contacto/" -H  "accept: application/json" -H  "Content-Type: application/json" -d "{ \"email\":\"email@\", \"nombre\": \"xxxxx\",  \"apellido\": \"xxxxx\",  \"edad\": \"xx\",  \"sexo\": \"x\",  \"invalido\": false,  \"campos\": [{\"nombre\": \"xxxxxxx\",\"valor\": \"+xxxx..xxx\"}]}"
Asociar a uno o más orígenes al usuario nuevo o existente
curl -X POST "https://api-dmds-cualquiera.planisys.net/v1/contacto/" -H "accept: application/json" -H "Authorization: mitoken" -H "Content-Type: application/json" -d '{"email": "hjose4@planisys.com", "sexo": "F", "nombre":"Hernan", "apellido":"Perez", "grupos":["Testing Planisys","facturas de prueba"] }'
Setear valores de campos al usuario nuevo o existente
curl -X POST "https://api-dmds-nombre.planisys.net/v1/contacto/" -H "accept: application/json" -H "Authorization: mitoken" -H "Content-Type: application/json" -d '{"email": "juan4@planisys.com", "campos":  [ {"nombre":"XYZDNIXYZ","valor":"13111423"}]  }'
Eliminar un usuario

Para eliminar un usuario usamos el método Delete, en la llamada sólo tenemos que indicar el email de usuario, que es el atributo que define que usuario a eliminar.

curl -X DELETE "https://api-dmds-host/v1/contacto/email"-H 'Authorization: xxxxxxxx'  -H "accept: application/json"
Invalidar un contacto

En la misma actualización de un contacto, se puede invalidar o validar un contacto. Por defecto la variable invalido siempre está en falso. Pero en el caso que un usuario se quiere desuscribir o invalidar, poniendo esa variable a uno, (invalido: true). Nos permite definir que este contacto esta en la lista de los inválidos.

curl -X POST "https://api-dmds-host/v1/contacto/" -H 'Authorization: xxxxxxxx' -H "accept: application/json" -H "Content-Type: application/json" -d '{"email": "correo@dominio.com", "nombre": "xxxx", "apellido": "xxxx", "edad": "x","sexo":"x","invalido": true}'
Enviar un correo

Para enviar un correo vamos a diferenciar los tipos que queremos enviar. Primero hay dos diferentes llamadas para enviar un correo a uno sólo destinatario y un correo a varios destinatarios. Para eso el cambio es muy básico, cambiar contacto por contactos. Otras dos llamadas se diferencian en enviar un html inline o un html mediante uri.

Llamada genérica

curl  -X POST https://api-dmds-host/v1/envio/enviar/ -H "Accept:application/json" -H "Authorization:xxxxx" -H "Content-Type:application/json" -d'{"campana_id":"xxxxxxxxxx,"email":true,"contacto":{"email":"correo@dominio.com","nombre":"xxxxx","apellido":"xxxxx"}}'
Enviar un correo a uno sólo destinatario con html uri

Para realizar este envío es necesario definir algunos campos, como por ejemplo: el campo de email tiene que ser siempre verdadero, ya que esto nos permite enviar el correo. Si este valor esta en falso, no se podrán enviar mensajes. Otros valores a definir son la id de la campaña y el correo destinatario. Los otros valores como nombre, apellido, asunto son opcionales. En el caso que quiera enviar un html mediante uri, este se añade en la apartad de html_url. En el apartado de headers, recordar definir su valor de autorización.

curl -X POST https://api-dmds-host/v1/envio/send_one_uri/ -H "Accept:application/json" -H "Authorization:xxxxxxx" -H "Content-Type:application/json" -d '{"campana_id":"xxxxxxx","email":true,"contacto":{"email":"correo@dominio.com","nombre":"xxxx","apellido":"xxxx"},"html_url":"http://xxxxxxx.html"}'
Enviar un correo a uno sólo destinatario con html URL y adjuntos
curl -X POST "https://api-dmds-xyz.planisys.net/v1/envio/send_one_form/" -H "accept: application/json" -H "Authorization: AABBCC1234" -F 'campana_id=13' -F 'contacto=soporte@planisys.com' -F 'html_url=http://planisys.net/prueba.html' -F 'attach1=@/root/attach-example-1.pdf' -F 'attach2=@/root/attach-example-1.docx'
Enviar un correo a uno sólo destinatario con html inline

La diferencia de la llamada previa esta es como definir el html dentro del código.

curl -X POST https://api-dmds-host/v1/envio/send_one_inline/-H "Accept:application/json"-H "Authorization:xxxxxxx"-H "Content-Type:application/json" -d '{"campana_id":"xxxxxxxxxx","email":true,"contacto":{"email":"correo@dominio.com","nombre":"xxxxx","apellido":"xxxx"}, "html":"<html><head><title>Page Title</title></head><body><h1>This is a Heading</h1><p>This is a paragraph.</p></body></html>"}'
Enviar un correo a más de un destinatario con html uri

Para esta llamada vamos a seguir el mismo concepto que para las otras a la hora de enviar un mensaje. En este caso queremos enviar a mucho destinatarios, para esto vamos a definir un array de usuarios que quienes queremos enviar y cambiar contacto por contactos. En el ejemplo que se muestra más abajo, enviamos un correo a dos personas, pero su puede definir muchas más personas.

curl -X POST https://api-dmds-host/v1/envio/send_many_uri/ -H "Accept:application/json" -H "Authorization:xxxxx" -H "Content-Type:application/json" -d '{"campana_id":"xxxxxxxx","email":true,"contactos":[{"email":"contacto1@dominio.com","nombre":"xxxx","apellido":"xxxxxx"},{"email":"contacto2@doinio.com","nombre":"xxxxx","apellido":"xxxxx"}],"html_url":""}'
Enviar un correo a más de un destinatario con html inline
curl -X POST https://api-dmds-host/v1/envio/send_many_inline/ -H "Accept:application/json" -H "Authorization:xxxxxxx" -H "Content-Type:application/json" -d '{"campana_id":"xxxxxx","email":true,"contactos":[{"email":"contacto1@dominio.com","nombre":"xxxxx","apellido":"xxxxxx"},{"email":"contacto2@dominio.com","nombre":"xxxx","apellido":"xxxxxx"}],"html":"<html><head><title>Page Title</title></head><body><h1>This is a Heading</h1><p>This is a paragraph.</p></body></html>"}'
Listar la campañas

Con la misma estructura,  como listar los contactos inválido o listar las variables globales, podemos lista todas las campañas existentes. Para esto se utiliza el método get.

curl -X GET "https://api-dmds-host/v1/campania/" -H "accept: application/json" -H 'Authorization: xxxxxxxx'
Crear un grupo

Como hemos visto anteriormente, cuando creamos o modificamos un usuario podemos asignarle un grupo. Para poder asignar un grupo, hay que ver si este grupo existe, sino existe, podemos crearlo de la siguiente manera.

curl -X POST "https://aapi-dmds-host/v1/grupo/" -H "accept: application/json" -H 'Authorization: xxxxxxxx' -H "Content-Type: application/json" -d '{"nombre": "xxxxx"}'
Listar los filtros

En el sistema de la api, se pueden crear diferentes filtros, que ayudan a especificar los envíos.

Para ver esta lista de filtros existentes, seguimos el código mencionado abajo.

curl -X GET "https://api-dmds-host/v1/filtros/" -H "accept: application/json" -H 'Authorization: xxxxxx' -H "Content-Type: application/json"
Listar las variables globales y sus valores

En la api hay definidas una serie de variables globales. Para ver cuales son estas variables y sus valores podemos ver el siguiente código.

curl -X GET "https://api-dmds-host/v1/global/" -H "accept: application/json" -H 'Authorization: xxxxxxxx'
Crear variables globales

Siempre podemos crear las variables globales. Para la creación vamos a usar el método post, donde le pasamos un variable, cual nos va a indicar el nombre de la variable global.

curl -X POST "https://api-dmds-host/v1/global/" -H "accept: application/json" -H 'Authorization: xxxxxxx' -H "Content-Type: application/json" -d '{"nombre": "newglobal","valor": "hola"}'
Borrar variables globales

De la misma manera que creamos unas variables globales, podemos eliminar estas. Sólo que en este vamos a usar un método que se llama  ‘Delete’.

curl -X DELETE "https://api-dmds-host/v1/global/" -H "accept: application/json" -H 'Authorization: xxxxxx' -H "Content-Type: application/json" -d '{ "nombre": "newglobal", "valor": ""}'