Saltar al contenido principal

API de contacto

Con la API de contacto puedes gestionar fácilmente tus objetos de contacto. Ofrece una implementación CRUD completa para objetos de contacto y ofrece métodos para añadir, eliminar y actualizar la taxonomía de los contactos. 

URL

Puedes acceder a la API REST de contacto con la siguiente URL base:

https://<system_id>.<server_id>.quentn.com/public/api/V1/contact

 

Recuperar un contacto [GET]

URL Parámetro Requerido Requisitos Descripción
fields No list Lista de campos de contacto a devolver.Ejemplo: Apellido, teléfono, email

Petición:

GET https://<system_id>.<server_id>.quentn.com/public/api/V1/contact/<contact_id>?fields=<fields> HTTP/1.1

Respuesta:

{
  "id": 123,
  "first_name": "John",
  "family_name": "Doe",
  "mail": "johndoe@example.com",
  "terms": [1,2,3]
}

Siempre se devolverá el Id del contacto. Si se omite el parámetro fields, se devolverán por defecto los siguientes campos: id, nombre, apellido, email.

 

Recuperar contactos por correo [GET]

URL Parámetro Requerido Requisitos Descripción
fields No list

Lista de campos de contacto a devolver.Ejemplo: Apellido, teléfono, email

Petición:

GET https://<system_id>.<server_id>.quentn.com/public/api/V1/contact/<contact_mail>?fields=<fields> HTTP/1.1

Respuesta:

[{
  "id": 123, 
  "mail": "johndoe@example.com", 
},
{
  "id": 124, 
  "mail": "johndoe@example.com", 
}]

Se debe tener en cuenta que varios contactos pueden tener la misma dirección de correo electrónico. Por lo tanto, el resultado siempre se devuelve como una matriz, aunque sólo se haya encontrado un contacto.

 

Crear contacto [POST]

Petitión Parámetro Requerido Requisitos Descripción
contact Yes object

El objeto de contactos debe contener un campo de correo válido o una dirección completa que incluya los siguientes campos: nombre, apellido, calle, ciudad y código postal. Aquí encontrarás una lista completa de los campos de contacto disponibles. 
duplicate_check_method No string

Define el método que se utilizará para buscar contactos duplicados con los que fusionar. Los valores posibles son

auto: Se utilizará un algoritmo de probabilidad para buscar duplicados (Predeterminado)

email: Se utilizará la dirección de correo electrónico principal para buscar duplicados

none: No se realizará ninguna comprobación de duplicados (no recomendado)
duplicate_merge_method No string

Define el método que se utilizará para fusionar el contacto si se encuentra un duplicado. Los valores posibles son:

update_add: se añadirán los campos que falten, los campos existentes se sobrescribirán (por defecto)

update: Los campos dados sobrescriben los campos existentes (con valor), los campos que faltan (sin valor) no se añadirán

add : sólo se añadirán los campos que falten
return_fields No array

Define campos de contacto adicionales, que deben ser devueltos en caso de éxito. Esto tiene sentido, por ejemplo, cuando hay duplicados.
request_ip No string

La dirección IPv4 que pertenece al contacto, por ejemplo, de la solicitud que envió un formulario. Este campo debe estar presente cuando se utiliza "flood_limit" o "spam_protection".

Este parámetro debe formar parte del objeto de contacto.
flood_limit No int

Número máximo de contactos que pueden crearse a partir de la misma "request_ip" en una hora. (0 = desactivado)
spam_protection No bool

Cuando se establece, el "request_ip" se comprobará en una base de datos de spammer.

Petición:

POST https://<system_id>.<server_id>.quentn.com/public/api/V1/contact HTTP/1.1

Petición body:

{
   "contact" : {
      "first_name" : "John",
      "family_name" : "Doe",
      "mail" : "johndoe@example.com",	
      "request_ip" : "123.123.123.123",	
   },
   "duplicate_check_method" : "email",
   "duplicate_merge_method" : "update_add",
   "return_fields" : [
      "mail_status","mail","first_name","family_name",
   ],
   "flood_limit" : 5,
   "spam_protection" : true
}

Respuesta:

{
  "id": 123,
}

 

Crear múltiples contactos en una llamada [POST]

Petición_Parámetro Requerido Requisitos Descripción
contacts Yes object

El objeto Contactos debe contener al menos un objeto de contacto con un campo de correo válido.  

Esta es una lista completa de los campos de contacto disponibles. 
duplicate_check_method No string

Define el método que se utilizará para comprobar si hay contactos duplicados con los que fusionar. Los valores posibles son

auto: Se utilizará un algoritmo de probabilidad para buscar duplicados (Predeterminado)

email: Se utilizará la dirección de correo electrónico principal para buscar duplicados

none: No se realizará ninguna comprobación de duplicados (no recomendado)
duplicate_merge_method No string

Define el método que se utilizará para fusionar el contacto si se encuentra un duplicado. Los valores posibles son:

update_add: se añadirán los campos que falten, los campos existentes se sobrescribirán (por defecto)

update: Los campos dados sobrescriben los campos existentes (con valor), los campos que faltan (sin valor) no se añadirán

add: sólo se añadirán los campos que falten
return_fields No array

Define campos de contacto adicionales, que deben ser devueltos en caso de éxito. Esto tiene sentido, por ejemplo, cuando hay duplicados.
request_ip No string

La dirección IPv4 que pertenece al contacto, por ejemplo de la solicitud que envió un formulario. Este campo debe estar presente cuando se utiliza "flood_limit" o "spam_protection".

Este parámetro debe formar parte del objeto de contacto.
flood_limit No int

Número máximo de contactos que pueden crearse a partir de la misma "request_ip" en una hora. (0 = desactivado)
spam_protection No bool

Cuando se establece, el "request_ip" se comprobará en una base de datos de spammer.

Petición:

POST https://<system_id>.<server_id>.quentn.com/public/api/V1/contacts HTTP/1.1

Cuerpo de la petición:

{
   "contacts" : [
      {
          "first_name" : "John",
          "family_name" : "Doe",
          "mail" : "johndoe@example.com",
	  "request_ip" : "123.123.123.123", 
      },
      {
          "first_name" : "James",
          "family_name" : "Doe",
          "mail" : "jamesdoe@example.com",	
          "request_ip" : "123.123.123.123", 
      },
   ],
   "duplicate_check_method" : "email",
   "duplicate_merge_method" : "update_add",
   "return_fields" : [
      "mail_status","mail","first_name","family_name",
   ],
   "flood_limit" : 5,
   "spam_protection" : true
}

Respuesta:

[
  {
     "id": 123,
     "email": "johndoe@example.com",
  },
  {
     "id": 124,
     "email": "jamesdoe@example.com",
  },
]

Ejemplo de respuesta en caso de error de creación de un único contacto:

[
  {
     "id": 123,
     "email": "johndoe@example.com",
  },
  {    
     "email": "jamesdoe@example.com",
     "error": true,
     "message": "The error message"
  },
]

 

Actualizar contacto [PUT]

Petición:

PUT https://<system_id>.<server_id>.quentn.com/public/api/V1/contact/<contact_id> HTTP/1.1

Cuerpo de la petición:

{
  "first_name": "John",
  "family_name": "Doe",
  "mail": "johndoe@example.com",
  "return_fields" : [
     "mail_status","mail","first_name","family_name",
   ]
}

Respuesta:

{
  "success": "true",
}

 

Borrar contacto [DELETE]

Petición:

DELETE https://<system_id>.<server_id>.quentn.com/public/api/V1/contact/<contact_id> HTTP/1.1

Respuesta:

{
  "success": "true",
}

 

API de etiquetas de contacto

Existen varias formas de recuperar y definir las etiquetas de un contacto, por ejemplo, puedes utilizar los métodos CRUD anteriores para definir y recuperar el campo de términos del contacto. Sin embargo, hay situaciones en las que es posible que sólo desee añadir o eliminar una etiqueta sin (re)configurar todo el campo de términos.

 

Obtener términos de contacto[GET]

Petición:

GET https://<system_id>.<server_id>.quentn.com/public/api/V1/contact/<contact_id>/terms HTTP/1.1

Respuesta:

[
  {
    "id" : 12,
    "name" : "ExampleTag",
    "description" : "Example description text"
  },
  {
    "id" : 13,
    "name" : "Sample",
    "description" : "",
  }
]

 

Establecer términos de contacto [POST] (DEPRECATED)

Nota: al utilizar este método POST sobrescribirá todo el campo de términos. Si sólo deseas añadir etiquetas de contacto, utiliza el método PUT. 

Petición:

POST https://<system_id>.<server_id>.quentn.com/public/api/V1/contact/<contact_id>/terms HTTP/1.1

Petición body:

[12,13,65]

Respuesta:

{
  "success": "true",
}

 

Añadir términos de contacto [PUT]

Petición:

PUT https://<system_id>.<server_id>.quentn.com/public/api/V1/contact/<contact_id>/terms HTTP/1.1

Cuerpo de la petición:

[123,555]

Respuesta:

{
  "success": "true",
}

 

Borrar términos de contacto [DELETE]

Petición:

DELETE https://<system_id>.<server_id>.quentn.com/public/api/V1/contact/<contact_id>/terms HTTP/1.1

Cuerpo de la petición:

[123,555]

Respuesta:

{
  "success": "true",
}

 

Contact comments API

Retrieve contact comments [GET]

URI Parameter Required Requirements Description
range No int Defines the range of comments which should be returned. Starts from 0. Default = 0.
limit No int Defines the number of comments which should be returned. Default = 50. Upper limit = 50.
sort No string Defines the order of the results. Results are always ordered by id. Possible values: "asc" and "desc". Default = "asc".

Request:

GET https://<system_id>.<server_id>.quentn.com/public/api/V1/contact/<contact_id>?range=<range>&limit=<limit>&sort=<sort> HTTP/1.1

Response:

{
  "range": 1,
  "limit": 10,
  "sort": "desc",
  "number_comments": 12,
  "number_ranges": 2,
  "comments": [
    {
      "id": 8,
      "contact_id": 93,
      "uid": 2,
      "created": 1627980505,
      "changed": 1627980505,
      "comment": "this is a comment",
    },
    {
      "id": 9,
      "contact_id": 93,
      "uid": 2,
      "created": 1627980614,
      "changed": 1627980728,
      "comment": "this is another comment",
    }
  ]
}

 

Add contact comment [POST]

Request:

POST https://<system_id>.<server_id>.quentn.com/public/api/V1/contact/<contact_id>/comments HTTP/1.1

Request body:

{
  "comment": "this is a comment"
}

Response:

{
  "success": "true",
  "comment_id": 5,
}

 

Update contact comment [PUT]

Request:

PUT https://<system_id>.<server_id>.quentn.com/public/api/V1/contact/<contact_id>/comments HTTP/1.1

Request body:


{
  "id": 5,
  "comment": "this is an updated comment"
}

Response:

{
  "success": "true",
}

 

Delete contact comments [DELETE]

Request:

DELETE https://<system_id>.<server_id>.quentn.com/public/api/V1/contact/<contact_id>/comments HTTP/1.1

Request body:

[123,555]

Response:

{
  "success": "true",
}

 

Campos de contacto disponibles

Nombre del campo Tipo de dato Descripción
title CHAR(1)

Valores posibles:

m : Mr. 
f : Mrs.
title2 CHAR(4)

Valores posibles:

dr : Dr.
prof : Prof.
first_name CHAR(255) NOMBRE
family_name CHAR(255) APELLIDO
company CHAR(255) EMPRESA
job_title CHAR(255) CARGO
mail CHAR(255) DIRECCIÓN EMAIL PRINCIPAL
mail_status integer

Nota: ¡Necesita permisos especiales para que esto tenga efecto!

Valores posibles:

1 = bloqueado

2 = dado de baja

3 = desconocido (por defecto)

4 = opt in único

5 = confirmed (manually)

6 = confirmed (import)

7 = confirmado
mail2 CHAR(255) EMAIL SECUNDARIO
phone_type CHAR(6)

Valores posibles:

trabajo : Trabajo

casa : Casa

móvil : Móvil

otro : otr
phone CHAR(255) Número de teléfono principal
phone2_type CHAR(6)

Valores posibles:

trabajo : Trabajo

casa : Casa

móvil : Móvil

otro : otro
phone2 CHAR(255) Número de teléfono secundario
fax CHAR(255) Número de fax
skype CHAR(255) Nombre de Skype
fb CHAR(255) Facebook
twitter CHAR(255) Twitter (X)
ba_street CHAR(255) Calle (Dirección de Facturación)
ba_street2 CHAR(255) Calle 2 (Dirección de Facturación)
ba_city CHAR(255) Ciudad (Dirección de Facturación
ba_postal_code CHAR(20) Código Postal (Dirección de Facturación)
ba_state CHAR(20) Estado (Dirección de Facturación)
ba_country CHAR(2) País como ISO 3166-1 alpha-2. Ejemplo: DE para Alemania
date_of_birth DATETIME DATETIME Fecha de nacimiento como ISO 8601. Example: 2004-02-12T15:19:21+00:00
terms LIST ld. de los términos de contacto. Ejemplo: [1,2,3 [1,2,3]
created integer Contact's creation date as unix timestamp (Read only)
uid integer User ID of contact's owner
owner mixed When field is read, an object will be returned which contains:
uid: integer (user ID)
mail: string (user's email address)

When field is set, it accepts either integer (uid) or string (mail).

 

Tipos de campos disponibles (campos personalizados)

Nombre del campo Tipo de dato Descripción
text String Compruebe el tamaño máximo de cada campo (de 8 a 255 caracteres)
List selection (single value) String Selección de lista (valor único) Cadena
List selection (multiple values) Array Ejemplo: ["selección_a", "selección_c"]
Float number Float

Utilice siempre el punto (.) como separador decimal.

Número entero Número entero
Integer number Integer  
Datetime mixed

Se espera una marca de tiempo unix (por ejemplo, '1594034942') o una fecha con formato ISO 8601 (por ejemplo, '2007-12-24T18:21Z').
 

Artículos relacionados