Introducción a DMDS API REST
****************************

Con la API REST podremos utilizar los siguientes métodos, siempr bajo **HTTPS**  (HTTP encriptado con SSL/TLS)

- **GET** para obtener información
- **PUT** para actualizar nueva información
- **POST** para actualizar o introducir nueva información
- **DEL** para borrar información

El **DMDS** (Data Mining and Delivery Services) es una implementación dedicada por cada cliente, es decir que no se comparten recursos ni de bases de datos ni de direcciones IP entre clientes.

Para ésto precisamos primero de un ``dmdsid`` , p.ej. **empresa1**, que otorga Planisys durante el proceso de Aprovisionamiento. En el mismo proceso se otorga una ``APIKEY``, que es un hash que se envía junto a un encabezado de Autenticación.

Luego podremos acceder a la interfaz web con el nombre dmds-empresa1.planisys.net.

Se distinguen primero la gestión de **Contactos** (también llamados "suscriptos") y de **Campañas**.

Las campañas se crean en la interfaz web y para poder utilizarlas en API REST deben ser de tipo **API**. Hay otros dos tipos de campaña que no se utilizarán en API REST, que son las A/B y las Normales.

La campaña API al ser creada, se crea con un envío default. A diferencia de las campañas Normales, donde se programan envíos repetitivos como p.ej. newsletters de frecuencia diaria/horaria/semanal, aquí el tipo de envío es puntual.


.. warning::
    Actualmente DMDS API REST v1 no soporta mas de un envío dentro de una campaña API, pero será soportado en una futura versión.

Cada vez que se envían mails a través de una llamada, se crea una tanda o **envío efectivo** que va a tener un **envio_efectivo_id** , que se devuelve en el JSON de respuesta. P.ej. si se envía a varios destinatarios en una llamada , todos irán con el mismo envio_efectivo_id. Luego se puede consultar con un GET por el estado de ese envio_efectivo_id junto a los eventos (p.ej. a cuáles usuarios se envió, quiénes y cuando abrieron o hicieron click en el mail).

En las llamadas para enviar mail, deberemos disponer de un **CampNumId** o **Identificador Numérico de Campaña** que se encontrará en la interfaz web cuando hacemos click en una campaña de tipo API.

En las llamadas donde se requiere un identificador de campaña, utilizaremos en el ``JSON`` un par key-value de la forma p.ej.

::

     "campana_id": 123


.. note::
    A partir DMDS API REST v2 también se puede utilizar el número de campaña dentro de un string, p.ej. "campana_id": "123" , aunque debe ser numérico

La respuesta al envío de mails puede contener un código 4xx , para el cual el usuario deberá tener analizar el error (p.ej. falta de un parámetro).

En caso de funcionar correctamente un envío, la respuesta por lo general es un JSON con estos 3 pares:

.. code-block:: json

    {"status":"ok", "sent":4, "eeid":"3abc993d-8i88-45e8-a6c9-e879378abba5"}

El **uuid** que se devuelve como eeid (*envio_efectivo_id*) puede ser consultado posteriormente con un GET. El número que sigue a *sent* es la cantidad de mails enviados durante la llamada, p.ej. un destinatario con 3 copias.

.. note::
    La documentación se muestra en la parte de **CURL** , y luego se puede aplicar al resto de los lenguajes de programación

Conceptos
+++++++++

**Contacto**: es una direccion de mail con metadatos como nombre, apellido, sexo, tambien conocido como *suscripto*

**Base**: es un grupo o lista de contactos, tambien conocido como *origen*

**Topico**: es un *sitio de desuscripcion*, es decir un topico del cual un contacto puede desuscribirse

Resumen
+++++++


.. list-table:: Title
   :widths: 50 50
   :header-rows: 1

   * - API Method
     - HTTP Supported Methods
   * - /v1/contacto/
     - GET, POST
   * - v1/contacto/desuscribir/
     - GET, POST
   * - v1/envio/enviar/
     - GET, POST
   * - v1/envio/send_one_uri/
     - GET, POST
   * - v1/envio/send_many_uri/
     - GET, POST
   * - v1/envio/send_one_inline_xml/
     - GET, POST
   * - v1/envio/send_one_inline_rawtext/
     - GET, POST
   * - v1/envio/send_one_inline/
     - GET, POST
   * - v1/envio/send_one_form/
     - GET, POST
   * - v1/envio/send_one_inline_raw/
     - GET, POST
   * - v1/envio/send_many_inline/
     - GET, POST
   * - v1/envio/
     - GET, POST
   * - v1/eeid_info/<eeid>
     - GET
   * - v1/global/
     - GET, POST
   * - v1/campania/
     - GET, POST
   * - v1/campania/resultados/<id>/<dia>
     - GET
   * - v1/grupo/
     - GET, POST
   * - v1/base/
     - GET, POST
   * - v1/contacto/
     - GET, POST
   * - v1/contacto/<email>
     - GET, POST
   * - v1/contacto_eventos/<email>
     - GET
   * - v1/sent/<email>
     - GET
   * - v1/enviados/<email>
     - GET
   * - v1/contactos/invalidos/
     - GET
   * - v1/filtros/
     - GET
   * - v1/campos/
     - GET, POST
   * - v1/sent_today/
     - GET
   * - v1/sent_yesterday/
     - GET
   * - v1/schedule_send/
     - POST
   * - v1/audiences/
     - GET
   * - v1/origenes/
     - GET
   * - v1/listas/
     - GET
   * - v1/grupos/
     - GET
   * - v1/bases/
     - GET
   * - v1/version/
     - GET
   * - v1/whitelist/<email>
     - GET, POST, PUT, DELETE
   * - v1/invalidar/<email>
     - GET
   * - v1/revalidar/<email>
     - GET
   * - v1/cantidad_eventos/
     - GET
   * - v1/ver_eventos/
     - GET


.. |date| date::

Last Updated on |date|