> ## Knowledge Base Index
> Fetch the complete knowledge base index at: https://help.danaconnect.com/sitemap.xml
> Use this file to discover available pages before exploring further.
> Pure-Markdown content can be obtained by appending a '.md' suffix to the content URLs listed in the sitemap (without the trailing slash).

# API SOAP - Customer Allowance Webservices

# Privacy API

Webservice SOAP que permite hacer consultas y búsquedas de servicios y suscripciones. Adicionalmente, permite bloquear y desbloquear direcciones, suscribir direcciones a servicios y eliminar suscripciones de direcciones a servicios.

---

## Acceso

**Protocolo:** HTTP

---

## URL

### Web Service

```text
https://ws.danaconnect.com/danaconnect/privacy/PrivacyAPI
```

### Definición del Web Service

```text
https://ws.danaconnect.com/danaconnect/privacy/PrivacyAPI?wsdl
```

---

## Cómo empezar a utilizar el Web Service

La compañía que va a utilizar el Web Service debe contar con un usuario y contraseña válidos.

---

## Autenticación

Para poder acceder a los métodos de este API es necesario tener credenciales válidas. Se utiliza un método de autenticación BASIC para el acceso a los WebServices basado en un login y password.

**Login:** el login consiste en el nombre de usuario concatenado con un `@` y seguido del código de la compañía.

### Ejemplo

```text
Nombre de usuario: administrador
Código de compañía: suempresa
Login: administrador@suempresa
```

### Ejemplo de autenticación desde PHP

```php
$client = new SoapClient(
  "http://www03.danaconnect.com:18080/danaconnect/privacy/PrivacyAPI?wsdl",
  array(
    'login' => 'administrador@suempresa',
    'password' => 'mipassword',
    'authentication' => SOAP_AUTHENTICATION_BASIC
  )
);
```

---

## Métodos

### 1. getServices

Lista los servicios activos. No recibe ningún parámetro y devuelve un JSON con información de los servicios.

```text
String getServices()
```

#### Detalle de método getServices

Este método se emplea para consultar todos los servicios activos de la compañía.

#### Valor devuelto

Retorna un JSON con el listado de servicios activos.

#### Solicitud

```php
// Llamamos al método y obtenemos el resultado
$result = $client->getServices()->return;
```

#### Resultado

```json
[
  {
    "id": "1",
    "name": "Servicio 1",
    "description": "Primer Servicio"
  },
  {
    "id": "2",
    "name": "Servicio 2",
    "description": "Segundo Servicio"
  }
]
```

---

### 2. addService

Agrega un nuevo servicio al listado de servicios activos. Devuelve un JSON con información del nuevo servicio, incluyendo el ID generado.

```text
String addService(String name, String description)
```

#### Detalle de método addService

Este método se emplea para agregar un nuevo servicio activo a la compañía.

#### Parámetros

| Parámetro | Descripción |
| ---- |
| `name` | Nombre del servicio. Máximo 85 caracteres. |
| `description` | Breve descripción del servicio. Máximo 250 caracteres. |

#### Valor devuelto

Retorna un JSON con los detalles del servicio agregado. Puede lanzar `Exception`.

#### Solicitud

```php
// Llamamos al método y obtenemos el resultado
$params = array(
  'name' => 'Test Service',
  'description' => 'Test Service Description'
);

$result = $client->addService($params)->return;
```

#### Resultado

```json
{
  "id": 26,
  "name": "Test Service",
  "description": "Test Service Description"
}
```

---

### 3. updateService

Dado un ID de servicio, actualiza su nombre y/o descripción.

```text
String updateService(Integer id, String name, String description)
```

#### Detalle de método updateService

Este método se emplea para actualizar el nombre y/o la descripción de un servicio dado su ID.

#### Parámetros

| Parámetro | Descripción |
| ---- |
| `id` | ID del servicio. |
| `name` | Nombre del servicio. Máximo 85 caracteres. |
| `description` | Breve descripción del servicio. Máximo 250 caracteres. |

#### Valor devuelto

Retorna un JSON con los detalles del servicio actualizado. Puede lanzar `Exception`.

#### Solicitud

```php
// Llamamos al método y obtenemos el resultado
$params = array(
  'id' => 26,
  'name' => 'Test Cambio',
  'description' => 'Test Cambio Description'
);

$result = $client->updateService($params)->return;
```

#### Resultado

```json
{
  "id": 26,
  "name": "Test Cambio",
  "description": "Test Cambio Description"
}
```

---

### 4. deleteService

Elimina un servicio activo dado un ID.

```text
boolean deleteService(Integer id)
```

#### Detalle de método deleteService

Este método se emplea para eliminar un servicio activo dado su ID.

#### Parámetros

| Parámetro | Descripción |
| ---- |
| `id` | ID del servicio. |

#### Valor devuelto

Retorna un booleano con el estatus de la operación. Puede lanzar `Exception`.

#### Solicitud

```php
// Llamamos al método y obtenemos el resultado
$params = array(
  'id' => 26
);

$result = $client->deleteService($params)->return;
```

#### Resultado

```json
true
```

---

### 5. getRecords

Realiza una búsqueda sobre contactos en los registros del Privacy Policy. Permite filtrar por dirección y canales, además de paginar los resultados.

```text
String getRecords(
  String search,
  List<Integer> idChannels,
  Integer start,
  Integer limit,
  boolean displayTotal
)
```

#### Detalle de método getRecords

Este método se emplea para consultar registros de privacidad aplicando filtros opcionales.

#### Parámetros

| Parámetro | Descripción |
| ---- |
| `search` | Filtro opcional de dirección. Permite búsquedas parciales. |
| `idChannels` | Listado de filtros por canal. Por defecto incluye todos los canales. Ver canales. |
| `start` | Índice del primer registro. |
| `limit` | Cantidad total de campos a mostrar. |
| `displayTotal` | Si es `true`, despliega el total de elementos encontrados para la búsqueda realizada. |

#### Valor devuelto

Retorna un JSON con los registros de privacidad y, opcionalmente, el total de la búsqueda. Puede lanzar `Exception`.

#### Solicitud

```php
// Llamamos al método y obtenemos el resultado
$params = array(
  'search' => '@gmail.com',
  'idChannels' => array(1, 2, 3),
  'start' => 1,
  'limit' => 10,
  'displayTotal' => true
);

$result = $client->getRecords($params)->return;
```

#### Resultado

```json
{
  "total": 5,
  "records": [
    {
      "address": "rebotameX1000@gmail.com",
      "date": "2013-07-03 17:16:35",
      "idConversation": 11269,
      "hardBounced": true,
      "idChannel": 1,
      "idSource": 1,
      "description": "Bounce / failed / 5.1.1",
      "blocked": false,
      "spam": false
    },
    {
      "address": "marianisho@gmail.com",
      "date": "2013-07-03 12:46:26",
      "idConversation": 0,
      "hardBounced": false,
      "idChannel": 1,
      "idSource": 2,
      "description": "ggggggggggggggg gggg",
      "blocked": true,
      "spam": false
    },
    {
      "address": "rebotameXkjhq@gmail.com",
      "date": "2013-06-28 18:01:41",
      "idConversation": 0,
      "hardBounced": false,
      "idChannel": 1,
      "idSource": 4,
      "description": "Bounce / failed / 5.1.1",
      "blocked": true,
      "spam": false
    },
    {
      "address": "malosiouhsiud@gmail.com",
      "date": "2012-07-03 12:59:28",
      "idConversation": 0,
      "hardBounced": false,
      "idChannel": 1,
      "idSource": 1,
      "description": "Bounce / failed / 5.1.1",
      "blocked": true,
      "spam": false
    }
  ]
}
```

---

### 6. getSuscriptions

Realiza una búsqueda sobre el estatus de bloqueo y suscripción de una dirección, para un canal determinado, con respecto a los servicios.

```text
String getSuscriptions(String address, Integer idChannel)
```

#### Detalle de método getSuscriptions

Este método se emplea para consultar el estatus de suscripción de una dirección en un canal específico.

#### Parámetros

| Parámetro | Descripción |
| ---- |
| `address` | Dirección completa del contacto. |
| `idChannel` | ID del canal. Ver canales. |

#### Valor devuelto

Retorna un JSON con los detalles de suscripción. Puede lanzar `Exception`.

#### Solicitud

```php
// Llamamos al método y obtenemos el resultado
$params = array(
  'address' => 'administrador@domain.com',
  'idChannel' => 1
);

$result = $client->getSuscriptions($params)->return;
```

#### Resultado

```json
[
  {
    "blocked": false,
    "id": 26,
    "name": "Test Service",
    "description": "Test Service Description",
    "suscribed": true
  },
  {
    "blocked": false,
    "id": 25,
    "name": "Test 2",
    "description": "Test 2",
    "suscribed": true
  },
  {
    "blocked": false,
    "id": 21,
    "name": "Mercadeo",
    "description": "M",
    "suscribed": false
  },
  {
    "blocked": false,
    "id": 20,
    "name": "Newsletter",
    "description": "Negocios",
    "suscribed": true
  },
  {
    "blocked": false,
    "id": 11,
    "name": "Politica",
    "description": "Politica",
    "suscribed": true
  },
  {
    "blocked": false,
    "id": 9,
    "name": "Test",
    "description": "Test",
    "suscribed": true
  }
]
```

---

### 7. unblock

Desbloquea una dirección para un canal determinado.

```text
Void unblock(String address, Integer idChannel)
```

#### Detalle de método unblock

Este método se emplea para desbloquear una dirección asociada a un canal.

#### Parámetros

| Parámetro | Descripción |
| ---- |
| `address` | Dirección completa del contacto. |
| `idChannel` | ID del canal. Ver canales. |

#### Valor devuelto

No regresa ningún valor. Puede lanzar `Exception`.

#### Solicitud

```php
// Llamamos al método y obtenemos el resultado
$params = array(
  'address' => 'administrador@domain.com',
  'idChannel' => 1
);

$result = $client->unblock($params)->return;
```

---

### 8. block

Bloquea una dirección para un canal determinado. Permite definir parámetros adicionales para especificar si el bloqueo debe ser categorizado como spam, así como una breve descripción de la razón del bloqueo.

```text
Integer block(
  String address,
  Integer idChannel,
  boolean isSpam,
  Integer idSource,
  String description
)
```

#### Detalle de método block

Este método se emplea para bloquear una dirección asociada a un canal.

#### Parámetros

| Parámetro | Descripción |
| ---- |
| `address` | Dirección completa del contacto. |
| `idChannel` | ID del canal. Ver canales. |
| `isSpam` | Si se desea marcar como spam, usar `true`. |
| `idSource` | ID del source. Ver sources. |
| `description` | Razón del bloqueo. |

#### Valor devuelto

Retorna un `Integer` con el ID del registro bloqueado. Puede lanzar `Exception`.

#### Solicitud

```php
// Llamamos al método y obtenemos el resultado
$params = array(
  'address' => 'administrador@domain.com',
  'idChannel' => 1,
  'isSpam' => true,
  'idSource' => 4,
  'description' => 'Solicitud del cliente'
);

$result = $client->block($params)->return;
```

#### Resultado

```json
26
```

---

### 9. suscribe

Habilita la recepción de comunicaciones a la dirección, para los servicios y canal indicados. Esta suscripción es particular a los servicios y canales especificados. No hay parámetros opcionales.

```text
Void suscribe(Integer idChannel, String address, List<Integer> services)
```

#### Detalle de método suscribe

Este método se emplea para suscribir una dirección a uno o varios servicios dentro de un canal.

#### Parámetros

| Parámetro | Descripción |
| ---- |
| `address` | Dirección completa del contacto. |
| `idChannel` | ID del canal. Ver canales. |
| `services` | Listado de IDs de servicios a los cuales suscribirse. |

#### Valor devuelto

No regresa ningún valor. Puede lanzar `Exception`.

#### Solicitud

```php
// Llamamos al método y obtenemos el resultado
$params = array(
  'address' => 'administrador@domain.com',
  'idChannel' => 1,
  'services' => array(26, 27, 28)
);

$result = $client->suscribe($params)->return;
```

---

### 10. unsuscribe

Deshabilita la recepción de comunicaciones a la dirección, para los servicios y canal indicados. Esta suscripción es particular a los servicios y canales especificados. No hay parámetros opcionales.

```text
String unsuscribe(
  Integer idChannel,
  String address,
  Integer idSource,
  List<Integer> services
)
```

#### Detalle de método unsuscribe

Este método se emplea para desuscribir una dirección de uno o varios servicios dentro de un canal.

#### Parámetros

| Parámetro | Descripción |
| ---- |
| `address` | Dirección completa del contacto. |
| `idChannel` | ID del canal. Ver canales. |
| `idSource` | ID del source. Ver sources. |
| `services` | Listado de IDs de servicios de los cuales desuscribirse. |

#### Valor devuelto

Regresa un listado de IDs de registros de suscripción en el orden correspondiente al enviado. Puede lanzar `Exception`.

#### Solicitud

```php
// Llamamos al método y obtenemos el resultado
$params = array(
  'address' => 'administrador@domain.com',
  'idChannel' => 1,
  'idSource' => 1,
  'services' => array(26)
);

$result = $client->unsuscribe($params)->return;
```

#### Resultado

```json
[
  1831600
]
```