Saltar al contenido principal

API REST v1: Contactos Manejo y búsqueda de contactos con la API de DataCrush.

Team DataCrush

[Tiempo de lectura del articulo: 10:32 minutos]

Los parámetros correspondiente a la autenticación deben ser enviados como campos de query string ya sea por el método GET o por POST.

La API REST de DataCrush permite administrar contactos desde cualquier aplicación de terceros, la misma ofrece las siguientes funciones:

Detalles del método
HTTP method:    POST
Respuesta:    JSON
Requiere autorización:    SI
URL:    https://api.datacrush.la/contact/insert


Códigos de error.

Código Descripción
100 Acceso denegado
101 Se superó el límite de llamadas a la API. (100 llamadas por minuto)
200 Error en validación de campos
201 El campo es obligatorio
202 No cumple con el mínimo de caracteres
203 No cumple con el máximo de caracteres
204 El tipo de campo es incorrecto
205 El contenido es inválido, no concuerda con los valores aceptados por el campo
206 El campo o propiedad no existe
207 El valor ya existe
208 El campo o propiedad no puede ser modificado
209 El valor no puede ser vacío
300 Error del sistema, fallo al insertar el contacto
301 Error del sistema, fallo al actualizar el contacto
302 Error del sistema, fallo al eliminar el contacto
303 Contact key inválida

 

1. Creación de un contacto.

Creación de un contacto en DataCrush con un HTTP POST a la API de Contactos.

El contacto será creado inmediatamente en tu base de contactos y se le asignará un KEY de identificación que podrá ser utilizado para buscar el contacto utilizando esta misma API.

Parámetros requeridos Descripción
portal_id El Portal ID es un número que identifica tu portal. (*)
api_key El API KEY es una llave que valida tu acceso a la API, es una cadena aleatoria de 50 caracteres. (*)
email La dirección de correo electrónico del contacto a crear es obligatoria

(*) Solicita a soporte tus credenciales de acceso.

Parámetros opcionales Descripción
{Nombre de propiedad} Cualquier propiedad existente en DataCrush, debe utilizarse el nombre de la etiqueta tal cual se puede ver en las propiedades de los contactos

Respuesta exitosa:

Si la respuesta es exitosa, se devolverá el contact_key asociado al nuevo contacto.

Este contact_key puede ser utilizado para identificar al contacto en futuras consultas a la API.

Ejemplo: 

{"result":"success","contact_key":"WhCmx1Bm0IZ4Kf5CAWwl36oJZkNTrPoo6AsFa32kM1oahp9RqG"}

Respuesta con error:

En caso de existir un error en la creación del contacto, se devolverá un JSON con el código de error y un detalle de propiedades con error

Ejemplo:

{
"result":"fail"
,"error": {"code":200,"message":"Validation error"}
,"error_list":[
	{"label":"email","field":"email","value":"","error":{"code":209,"message":"The value of this field can not be empty"}},
	{"label":"phone","field":"phone","value":"a","error":{"code":204,"message":"The type of field is not correct"}},	
	]
}

Ejemplo de alta de contacto en PHP: 

<?php

$url = https://api.datacrush.la/contact/insert;

$postData	= array(
	"portal_id" => yourportalID,
	"api_key" => "yourapikey",
	"email" => "valid@email.com",
	"first_name" => "Firstname",
	"last_name" => "Lastname"
);

$ch = curl_init();

curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_POSTFIELDS, $postData);

$data = json_decode(curl_exec($ch));

$info = curl_getinfo($ch);

if($info['http_code'] != 200) {


} else {

	if( $data->result == "success") {
		$contact_key = $data->contact_key;
	} else {
		$errors = $data->error_list;
	}

}

curl_close($ch);

?>

2. Actualización de un contacto.

Actualiza cualquier propiedad de un contacto existente en tu base de contactos de DataCrush con un HTTP POST.

Se debe utilizar el contact key asociado a ese contacto para poder actualizarlo, en caso de no saberlo se puede realizar primero una búsqueda para obtenerlo

Parámetros requeridos Descripción
portal_id El Portal ID es un número que identifica tu portal. (*)
api_key El API KEY es una llave que valida tu acceso a la API, es una cadena aleatoria de 50 caracteres. (*)
contact_key El contact_key asociado al contacto que se desea actualizar, para obtenerlo se puede realizar una búsqueda

(*) Solicita a soporte tus credenciales de acceso.

Parámetros opcionales Descripción
{Nombre de propiedad} Cualquier propiedad existente en DataCrush, debe utilizarse el nombre de la etiqueta tal cual se puede ver en las propiedades de los contactos

Respuesta exitosa:

Si la respuesta es exitosa, se devolverá success

Ejemplo: 

{"result":"success"}

Respuesta con error:

En caso de existir un error en la actualización del contacto, se devolverá un JSON con el código de error y un detalle de propiedades con error

Ejemplo:

{
"result":"fail"
,"error": {"code":200,"message":"Validation error"}
,"error_list":[
	{"label":"email","field":"email","value":"","error":{"code":209,"message":"The value of this field can not be empty"}},
	{"label":"phone","field":"phone","value":"a","error":{"code":204,"message":"The type of field is not correct"}},	
	]
}
 

Ejemplo de actualización de contacto en PHP: 

<?php

$url = https://api.datacrush.la/contact/update;

$postData	= array(
	"portal_id" => yourportalID,
	"api_key" => "yourapikey",
	"phone" => "54115551234",
	"contact_key" => "somecontactkey"
);

$ch = curl_init();

curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_POSTFIELDS, $postData);

$data = json_decode(curl_exec($ch));

$info = curl_getinfo($ch);

if($info['http_code'] != 200) {

	echo("error");
  
} else {

	if( $data->result == "success") {
		echo("Ok");
		
	} else {
		$errors = $data->error_list;
	}
	print_r($errors);

}

curl_close($ch);


?>

3. Eliminación de un contacto.

Elimina un contacto existente en tu base de contactos de DataCrush con un HTTP POST.

Se debe utilizar el contact key asociado a ese contacto para poder eliminarlo, en caso de no saberlo se puede realizar primero una búsqueda para obtenerlo

‼️ ATENCIÓN: Un contacto eliminado no podrá ser recuperado.
 
Parámetros requeridos Descripción
portal_id El Portal ID es un número que identifica tu porta. (*)
api_key El API KEY es una llave que valida tu acceso a la API, es una cadena aleatoria de 50 caracteres. (*)
contact_key El contact_key asociado al contacto que se desea eliminar, para obtenerlo se puede realizar una búsqueda

(*) Solicita a soporte tus credenciales de acceso.

Respuesta exitosa:

Si la respuesta es exitosa, se devolverá success

Ejemplo:

{"result":"success"}

 Respuesta con error:

En caso de existir un error en la ejecución, se devolverá un JSON con el código de error.

Ejemplo:

{
"result":"fail"
,"error": {"code":200,"message":"Validation error"}
,"error_list":[]
}

Ejemplo de eliminación de contacto en PHP:

<?php

$url = https://api.datacrush.la/contact/delete;

$postData	= array(
	"portal_id" => yourportalID,
	"api_key" => "yourapikey",
	"contact_key" => "somecontactkey"
);

$ch = curl_init();

curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_POSTFIELDS, $postData);

$data = json_decode(curl_exec($ch));

$info = curl_getinfo($ch);

if($info['http_code'] != 200) {

	echo("error");
  
} else {

	if( $data->result == "success") {
		echo("Ok");
		
	} else {
		$errors = $data->error_list;
	}
	print_r($errors);

}

curl_close($ch);


?>

 4. Búsqueda de un contacto.

Busca un contacto existente en tu base de contactos de DataCrush con un HTTP POST.

La búsqueda puede realizarse por una o varias propiedades. Estas propiedades deben ser sólo las habilitadas para búsqueda

‼️ Nota: la búsqueda siempre devolverá un máximo de 100 contactos.
 
Parámetros requeridos Descripción
portal_id El Portal ID es un número que identifica tu portal. (*)
api_key El API KEY es una llave que valida tu acceso a la API, es una cadena aleatoria de 50 caracteres. (*)
{Nombre de propiedad} Es obligatorio pasar una propiedad existente habilitada para búsqueda para realizar la búsqueda, debe utilizarse el nombre de la etiqueta tal cual se puede ver en las propiedades de los contactos

(*) Solicita a soporte tus credenciales de acceso.

Parámetros opcionales Descripción
{Nombre de propiedad} Cualquier propiedad existente en DataCrush habilitada para búsqueda, debe utilizarse el nombre de la etiqueta tal cual se puede ver en las propiedades de los contactos

Respuesta exitosa:

Si la respuesta es exitosa, se devolverá success y el listado de contactos con sus propiedades

Ejemplo:

{"result":"success","rows":[ list of fields and values]}

Respuesta con error:

En caso de existir un error en la ejecución, se devolverá un JSON con el código de error.

Ejemplo: 

{
"result":"fail"
,"error": {"code":200,"message":"Validation error"}
,"error_list":[]
}

 Propiedades habilitadas para búsqueda.

  • company
  • company_size
  • email
  • first_name
  • industry
  • instragram
  • job_title
  • klout
  • last_name
  • latitude
  • lifecycle
  • longitude
  • mobile
  • owner
  • phone
  • photo
  • revenue
  • score
  • sex
  • skype
  • twitter
  • website 

Ejemplo de actualización de contacto en PHP:

<?php

$url = https://api.datacrush.la/contact/search;


$postData	= array(
	"portal_id" => yourportalID,
	"api_key" => "yourapikey",
	"contact_key" => "somecontactkey"
);

$ch = curl_init();

curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_POSTFIELDS, $postData);

$data = json_decode(curl_exec($ch));

$info = curl_getinfo($ch);

if($info['http_code'] != 200) {

	echo("error");
  
} else {

	if( $data->result == "success") {

		print_r($data->rows);
		
	} else {
		$errors = $data->error_list;
	}
	print_r($errors);

}

curl_close($ch);

?>

5. Listar contactos de una lista.

Lista todos los contactos pertenecientes a una lista.

Parámetros requeridos Descripción
portal_id El Portal ID es un número que identifica tu portal. (*)
api_key El API KEY es una llave que valida tu acceso a la API, es una cadena aleatoria de 50 caracteres. (*)
id ID de la lista. (Este campo es obligatorio si no se especifica el campo name)
name Nombre de la lista. (Este campo es obligatorio si no se especifica el campo id)

(*) Solicita a soporte tus credenciales de acceso.

Respuesta exitosa:

Si la respuesta es exitosa, se devolverá success

Ejemplo: 

{"result":"success","rows":[ list of fields and values]}

Respuesta con error:

En caso de existir un error en la solicitud, se devolverá un JSON con el código de error y un detalle de propiedades con error

Ejemplo: 

{
"result":"fail"
,"error": {"code":510,"message":"Invalid list"}
}

Ejemplo solicitud de listado de contactos en PHP:

<?php

$url = https://api.datacrush.la/contact/update;

$postData	= array(
	"portal_id" => yourportalID,
	"api_key" => "yourapikey",
	"id" => "123",
	"name" => ""
);

$ch = curl_init();

curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_POSTFIELDS, $postData);

$data = json_decode(curl_exec($ch));

$info = curl_getinfo($ch);

if($info['http_code'] != 200) {

	echo("error");
  
} else {

	if( $data->result == "success") {

		print_r($data);
		
	} else {
		$code 	 = $data->error->code;		
		$message = $data->error->message;				
		$errors  = $data->error_list;
	}

}

curl_close($ch);


?>

6. Importación de contactos.

Importa los contactos de forma masiva que se encuentran dentro de un archivo .CSV.

Nota: El archivo puede encontrarse comprimido (zip).
Parámetros requeridos Descripción
portal_id El Portal ID es un número que identifica tu portal. (*)
api_key El API KEY es una llave que valida tu acceso a la API, es una cadena aleatoria de 50 caracteres. (*)
file Se debe enviar el archivo .csv (o .zip) que será importado
list_name Nombre de la lista estática que se va a crear y asociar los contactos. (Este parámetro debe ser obligatorio si no se especificó el parámetro list_id)
list_id ID de una lista estática existente en la que se asociaron los contactos. (Este parámetro debe ser obligatorio si no se especificó el parámetro list_name)

(*) Solicita a soporte tus credenciales de acceso.

Respuesta exitosa:

Si la respuesta es exitosa, se devolverá success y los IDs correspondientes

Ejemplo:

			{"result":"success",
			 "file_id": [ ID interno de procesamiento del archivo],
			 "list_Id": [ID de la lista que fue creada]
		     }

 Respuesta con error:

En caso de existir un error en el envío de la solicitud de importación, se devolverá un JSON con el código de error.

Ejemplo:

		{
		"result":"fail"
		,"error": {"code":200,"message":"Validation error"}
		,"error_list":[]
		}

 Ejemplo de importación de contactos en PHP:

	<?php

	$url = https://api.datacrush.la/contact/search;


	$file 	= realpath('./prueba.zip');
	$cfile     = new CURLFile($file, 'text/csv','prueba.zip');

	$postData	= array(
		"portal_id" => yourportalID,
		"api_key" => "yourapikey",
		'file' 		=> $cfile,
		'list_name' => "Grupo A",
		"list_id"	=> ""
	);

	$ch = curl_init();

	curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
	curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
	curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
	curl_setopt($ch, CURLOPT_URL, $url);
	curl_setopt($ch, CURLOPT_POSTFIELDS, $postData);

	$data = json_decode(curl_exec($ch));

	$info = curl_getinfo($ch);

	if($info['http_code'] != 200) {

		echo("error");
  
	} else {

		if( $data->result == "success") {

			print_r($data);
		
		} else {
			$code 	 = $data->error->code;		
			$message = $data->error->message;				
			$errors  = $data->error_list;
		}

	}

	curl_close($ch);

	?>

7. Ingreso de eventos.

Ingresar eventos asociados a un contacto

Parámetros requeridos Descripción
portal_id El Portal ID es un número que identifica tu portal. (*)
api_key El API KEY es una llave que valida tu acceso a la API, es una cadena aleatoria de 50 caracteres. (*)
event Código de evento creado en Datacrush
email Dirección de correo electrónico del contacto.
value Información adicional sobre el evento (por ejemplo número de pedido)
revenue Monto asociado al evento (por ejemplo el monto del pedido)
data Información adicional asociada al evento en formato JSON

(*) Solicita a soporte tus credenciales de acceso.

Respuesta exitosa:

Si la respuesta es exitosa, se devolverá success

Ejemplo: 

			{"result":"success"}

 Respuesta con error:

En caso de existir un error en el envío de la solicitud de importación, se devolverá un JSON con el código de error.

Ejemplo: 

		{
		"result":"fail"
		,"error": {"code":200,"message":"Validation error"}
		,"error_list":[]
		}

 Ejemplo de ingreso de eventos en PHP:

	<?php

	$url = https://api.datacrush.la/contact/search;

	$postData	= array(
		"portal_id" => yourportalID,
		"api_key" => "yourapikey",
		'event' 		=> "XXJSZXZNAJSHQQWA",
		'vakue' => "Pedido Nro 123",
		"revenue"	=> "9.99",
		"data"	=> '{"code":"abc","date":"11/02/1976"}'
	);

	$ch = curl_init();

	curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
	curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
	curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
	curl_setopt($ch, CURLOPT_URL, $url);
	curl_setopt($ch, CURLOPT_POSTFIELDS, $postData);

	$data = json_decode(curl_exec($ch));

	$info = curl_getinfo($ch);

	if($info['http_code'] != 200) {

		echo("error");
  
	} else {

		if( $data->result == "success") {

			print_r($data);
		
		} else {
			$code 	 = $data->error->code;		
			$message = $data->error->message;				
			$errors  = $data->error_list;
		}

	}

	curl_close($ch);

	?>

 8. Cambio de email de contacto.

Cambiar el valor de la propiedad email. El nuevo valor de email no debe existir en la plataforma.

Parámetros requeridos Descripción
portal_id El Portal ID es un número que identifica tu portal. (*)
api_key El API KEY es una llave que valida tu acceso a la API, es una cadena aleatoria de 50 caracteres. (*)
event Código de evento creado en Datacrush.
email Dirección de correo electrónico del contacto.
new_email Nueva dirección de email.

 (*) Solicita a soporte tus credenciales de acceso.

Respuesta exitosa:

Si la respuesta es exitosa, se devolverá success

Ejemplo: 

			{"result":"success"}

 Respuesta con error:

En caso de existir un error en el envío de la solicitud de importación, se devolverá un JSON con el código de error.

Ejemplo: 

		{
		"result":"fail"
		,"error": {"code":200,"message":"Validation error"}
		,"error_list":[]
		}

 Ejemplo de cambio de email en PHP: 

	<?php

	$url = https://api.datacrush.la/contact/search;

	$postData	= array(
		"portal_id" => yourportalID,
		"api_key" => "yourapikey",
		'email' 		=> "actual@dominio.com",
		'new_email' => "nuevo@dominio.com",
	);

	$ch = curl_init();

	curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
	curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
	curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
	curl_setopt($ch, CURLOPT_URL, $url);
	curl_setopt($ch, CURLOPT_POSTFIELDS, $postData);

	$data = json_decode(curl_exec($ch));

	$info = curl_getinfo($ch);

	if($info['http_code'] != 200) {

		echo("error");
  
	} else {

		if( $data->result == "success") {

			print_r($data);
		
		} else {
			$code 	 = $data->error->code;		
			$message = $data->error->message;				
			$errors  = $data->error_list;
		}

	}

	curl_close($ch);

	?>
 

Relacionada con

Artículos relacionados

Comentarios

0 comentarios

Inicie sesión para dejar un comentario.