HotelDataHub - Contactos

Tabla de contenidos¶

Introducción
Casos de uso
Métodos disponibles
Tabla de parámetros
Ejemplos
Petición (POST-PATCH)
Respuesta (POST-PATCH)
Petición (GET)
Respuesta (GET)

Introducción¶

En este artículo hablamos sobre las peticiones de la API relacionadas con los Contactos.

Crear contacto
Actualizar contacto
Listar y filtrar contactos

Endpoint: https://app.hoteldatahub.io/api/v1/contacts/

Swagger: https://app.hoteldatahub.io/swagger/#/contacts

Casos de uso¶

El endpoint para la gestión de contactos resulta de gran utilidad para incorporar nuevos contactos en Fideltour procedentes de distintas fuentes. Para el caso de contactos ya existentes, permite ampliar la información contenida en su ficha enriqueciendo así la calidad de la base de datos. Múltiples orígenes de datos permiten obtener distinta información que después se centraliza en Fideltour.

Motor de reservas¶

El uso de este endpoint desde un motor de reservas permite recuperar la información de contacto de un huésped que ha realizado una reserva desde la página web del hotel o cadena. De esta forma, y desde incluso antes de la llegada del futuro huésped al hotel, en Fideltour ya obtenemos sus datos de contacto y podemos utilizarlos para comenzar a comunicarnos con el mismo.

PMS¶

La información proveniente de un PMS resulta de gran valor para Fideltour, ya que muchos orígenes de datos centralizan su información en él. También nos permite obtener información de contacto de otros huéspedes, además del propietario de la reserva, con lo que aumentamos el tamaño de nuestra base de datos gracias a esta conexión.

Wi-Fi y otras plataformas¶

En un hotel pueden existir otras plataformas o servicios en la nube que recopilen información sobre sus usuarios, y la puedan enviar a Fideltour para enriquecer la base de datos y mejorar las campañas de marketing y comunicaciones informativas sobre los servicios del hotel.

Métodos disponibles¶

Todos los métodos y filtros disponibles para trabajar con contactos se pueden consultar aquí. En este artículo nos centramos en los siguientes:

GET: Consulta de datos de uno o varios contactos
POST: Creación de un nuevo contacto
PATCH: Actualización de los datos de un contacto ya existente

Tabla de parámetros¶

Campo	Tipo	Obl.	Descripción
`email`	String	Sí	Email del contacto, campo único, usado como identificador del contacto.
`name`	String	No	Nombre del contacto
`surname`	String	No	Apellidos del contacto
`phone1`	String	No	Teléfono del contacto
`birthday`	Date YYYY-MM-DD	No	Fecha de nacimiento
`gender`	Integer	No	Género: • 0 = no especificado (default) • 1 = hombre • 2 = mujer • 3 = no binario • 4 = género fluido • 5 = prefiere no decirlo
`address`	String	No	Dirección
`post_code`	String	No	Código postal
`zone`	String	No	Dos opciones: • Identificador de la zona ya creada. • Nombre de la zona. El sistema la crea si no existe ninguna con ese nombre
`town`	String	No	Dos opciones: • Identificador de la ciudad ya creada. • Nombre de la ciudad. El sistema la crea si no existe ninguna con ese nombre
`province`	String	No	Dos opciones: • Identificador de la provincia ya creada. • Nombre de la provincia. El sistema la crea si no existe ninguna con ese nombre
`country`	String	No	ISO 3166-1 alpha-2
`language`	String	No	ISO 639-1 Code
`identification_document_type`	Numérico	No	Tipo de documento de identidad. • 0 = Otros • 1 = DNI • 2 = NIE • 3 = Pasaporte
`identification_number`	String	No	Número de documento de identidad.
`business_name`	String	No	Nombre de la empresa
`work_place`	String	No	Cargo empresarial
`business_address`	String	No	Dirección de la empresa
`fiscal_address`	String	No	Dirección fiscal
`notes`	String	No	Notas
`custom_tags`	Listado de Strings	No	Dos opciones: • Identificador de la etiqueta ya creada. • Nombre de la etiqueta. El sistema la crea si no existe ninguna con ese nombre
`source`	Integer	Sí (POST) No (PATCH)	Origen del contacto. • 0 = PMS • 1 = Wifi Login • 2 = Facebook • 3 = Web / Booking Engine • 4 = Otro • 5 = Importación • 6 = Formulario Newsletter • 7 = Formulario de contacto • 8 = Guest Portal • 9 = Pre-Checkin • 10 = Chatbot • 11 = Concierge • 12 = Call Center • 13 = Landing Form • 14 = Intranet • 15 = PMS Otros • 16 = PMS Restaurante • 17 = PMS SPA • 18 = BE Otros • 19 = BE Restaurante • 20 = BE SPA • 21 = API • 22 = Zapier / Make • 23 = SDK / App Hotel • 24 = CRM Corporativo • 25 = Web Hotel • 26 = Web Espacios • 27 = Web Restaurante
`custom_fields`	Objeto	No	Diccionario clave-valor con campos personalizados del contacto. Las claves son los identificadores de los campos definidos en Fideltour. Ejemplo: `{"cf_vip": true, "cf_deeplink": "https://..."}`
`external_object_id`	String	No	Identificador del contacto en el sistema externo (PMS, BE, etc.). Se usa como criterio de búsqueda alternativo al email para localizar y deduplicar contactos en Fideltour.
`subscribed`	Booleano	No	Indica si el contacto está suscrito a recibir mailing. • True = Está suscrito • False = No está suscrito (por defecto)

Ejemplos¶

A continuación mostramos algunos ejemplos de creación, actualización y visualización de contactos.

Petición (POST-PATCH)¶

En el siguiente ejemplo se muestra una petición para dar de alta (POST) o actualizar (PATCH) el contacto pablo@hdh.com.

PROTOCOLO: HTTP/1.1 MÉTODO: POST/PATCH HOST/ENDPOINT: https://app.hoteldatahub.io/api/v1/contacts/ HEADERS:

Content-type: application/json
Authorization: Token xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

BODY:

{
    "email": "pablo@hdh.com",
    "birthday": "1976-04-18",
    "phone1": "651442233",
    "gender": 2,
    "address": "Calle los olivos",
    "province": "Madrid",
    "town": "Madrid",
    "zone": "Sol",
    "post_code": "28013",
    "language": "es",
    "country": "ES",
    "name": "Pablo",
    "surname": "Mir",
    "identification_document_type": 1,
    "identification_number": "01234567Z",
    "source": 1,
    "notes": "Muy exigente",
    "work_place": "Palma",
    "business_name": "Customia",
    "business_address": "Calle de las soluciones industriales 25",
    "fiscal_address": "Calle de las soluciones industriales 25",
    "custom_tags": ["Cliente VIP", "Turista"],
    "custom_fields": {"cf_vip": true},
    "subscribed": false
}

Nota: los valores Booleanos true y false, también se pueden enviar como Integers 1 y 0.

Respuesta (POST-PATCH)¶

En caso de una respuesta 200 o 201, el json que se recibe tiene la siguiente estructura:

{
   "id": 9999999,
   "business_name": "Customia",
   "work_place": "Palma",
   "business_address": "Calle de las soluciones industriales 25",
   "fiscal_address": "Calle de las soluciones industriales 25",
   "language": "es",
   "country": "ES",
   "created_at": "2022-01-01T12:12:12.654321",
   "level_name": "",
   "loyalty_card_number": null,
   "name": "Pablo",
   "surname": "Mir",
   "email": "pablo@hdh.com",
   "email_status": 0,
   "phone1": "651442233",
   "gender": 2,
   "identification_document_type": 1,
   "identification_number": "01234567Z",
   "birthday": "1976-04-18",
   "address": "Calle los olivos",
   "post_code": "28013",
   "source": 1,
   "notes": "Muy exigente",
   "photo": null,
   "subscribed": false,
   "unsubscribe_reason": null,
   "date_subscribed": "2022-01-01T12:12:12.654321",
   "modification_date_subscribed": null,
   "is_active": true,
   "points": 0,
   "value": 0,
   "review": null,
   "total_bookings": 0,
   "level_points": 0,
   "loyalty_custom_tag_timestamp": null,
   "is_profile_completed": false,
   "last_level_review": null,
   "kicked_out_loyalty": null,
   "province": 1,
   "town": 2,
   "zone": 3,
   "level": null,
   "custom_tags": [4, 5],
   "custom_fields": {"cf_vip": true},
   "hotels": []
}

Petición (GET)¶

El método GET permite lo siguiente:

Listar los contactos en base a unos filtros aplicados, que se pueden consultar en: Ver en swagger
Obtener los datos de un contacto pasando su ID por parámetro de URL: https://app.hoteldatahub.io/api/v1/contacts/{id}/

Nota: Al obtener un contacto por ID (/contacts/{id}/), la respuesta incluye el campo extra custom_tags_names con los nombres de las etiquetas correspondientes a los IDs de custom_tags.

Solicitar los custom_fields de un contacto¶

El listado de contactos (GET /api/v1/contacts/) admite dos parámetros de query string para pedir los campos personalizados:

Parámetro	Descripción
`?fields=custom_fields`	Devuelve todos los campos personalizados activos del contacto.
`?custom_fields=clave1,clave2`	Devuelve solo los campos personalizados indicados por clave, separados por comas. No es necesario combinarlo con `?fields=custom_fields`.

Ejemplo:

GET https://app.hoteldatahub.io/api/v1/contacts/?email__iexact=pablo@hdh.com&custom_fields=cf_vip,cf_deeplink

PROTOCOLO: HTTP/1.1 MÉTODO: GET HOST/ENDPOINT: https://app.hoteldatahub.io/api/v1/contacts/?email__iexact=pablo@hdh.com HEADERS:

Authorization: Token xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

BODY: En este caso al ser un método de tipo GET no incluimos datos en el cuerpo de la petición, ya que se incluyen en la url.

Respuesta (GET)¶

{
   "count": 1,
   "next": null,
   "previous": null,
   "results": [
       {
           "id": 7778735,
           "business_name": null,
           "work_place": "Palma",
           "business_address": null,
           "fiscal_address": "Calle de las soluciones industriales 25",
           "language": "ES",
           "country": "ES",
           "created_at": "2022-12-21T16:40:20.681955",
           "level_name": "",
           "loyalty_card_number": null,
           "name": "Pablo",
           "surname": "Mir",
           "email": "pablo@hdh.com",
           "email_status": 0,
           "phone1": "651442233",
           "gender": 2,
           "identification_document_type": 1,
           "identification_number": "01234567Z",
           "birthday": "1976-04-18",
           "address": "Calle los olivos",
           "post_code": "07006",
           "source": 1,
           "notes": "Muy exigente",
           "photo": null,
           "subscribed": false,
           "unsubscribe_reason": null,
           "date_subscribed": "2022-12-21T16:40:20.681955",
           "modification_date_subscribed": null,
           "is_active": true,
           "points": 0,
           "value": 0,
           "review": null,
           "total_bookings": 0,
           "level_points": 0,
           "loyalty_custom_tag_timestamp": null,
           "is_profile_completed": false,
           "last_level_review": null,
           "kicked_out_loyalty": null,
           "province": 1,
           "town": 2,
           "zone": 3,
           "level": null,
           "custom_tags": [4, 5],
           "custom_tags_names": ["Cliente VIP", "Turista"],
           "custom_fields": {"cf_vip": true},
           "hotels": []
       }
   ]
}