Manual Referencia API

Webhook para notificar clientes suscritos a la tarjeta de lealtad

En tu tarjeta de lealtad puedes agregar un webhook en el cual se notificará cuando un cliente se registre.

Este lo puedes configurar en el apartado de medición de tu tarjeta de lealtad ubicado en Tarjetas de lealtad

Webhook para notificar clientes suscritos a la tarjeta de lealtad

Respuesta:

{
    "type" => "registered_user",
    "agenda" => "Nombre de la agenda",
    "contact_name" => "Nombre del contacto",
    "contact_email" => "",
    "contact_number" => "Número del contento",
    "contact_birth" => "",
    "contact_city" => "",
    "contact_state" => "",
    "contact_cp" => "",
    "custom_field_1" => "",
    "custom_field_2" => "",
    "contact_response" => "",
    "date" => "2023-12-08 11:06:42"
}

Webhook ventas completadas

Con este webhook podrás recibir información acerca de todos las ventas exitosas que tengas con tu tarjeta de lealtad, esto se logra agregando la URL de tu webhook en el apartado de Medición de la tarjeta.

Importante

Para que funcione correctamente el Webhook debe de validar que su URL se encuentre en funcionamiento, esto lo puede comprobar con la opción Probar

Webhook ventas completadas

Respuesta:

{
    "event_name": "Purchase",
    "data": {
        loyaltyCard: "Loyalty card 'Nombre_Cupon'",
        currency: "MXN/USD", 
        value: 1000
    },
    "date": "2023-12-08 11:06:42"
}

Agregar Javascript

Si deseas ejecutar algún código Javascript personalizado en tu tarjeta de lealtad podrás hacerlo agregándolo en el apartado de medición de tu tarjeta.

Agregar Javascript

Obtener usuarios

Puedes obtener los cajeros y gerentes que has creado, con el fin de poder asignarles las transacciones que realices cuando uses la API. Obtendrás el valor usertool_id que es requerido para algunos otros métodos.

Encabezados

Atributo	Descripción	Tipo de Dato
apikey	`Obligatorio` Clave API generada en la sección de integraciones dentro del panel.	`Text`

              curl -X POST "/toolusers/get" -H "apikey: your_apikey" -d ""

                
        $params = array();
        $headers = array(
          "apikey: your_apikey"
        );
        curl_setopt_array($ch = curl_init(), array(
          CURLOPT_URL => "/toolusers/get",
          CURLOPT_SSL_VERIFYPEER => 0,
          CURLOPT_HEADER => 0,
          CURLOPT_HTTPHEADER => $headers,
          CURLOPT_POST => 1,
          CURLOPT_POSTFIELDS => http_build_query($params),
          CURLOPT_RETURNTRANSFER => 1
        ));
        $response = curl_exec($ch);
        curl_close($ch);
            
        echo json_encode($response);

                
        require 'net/http'
        require 'uri'
        
        uri = URI.parse("/toolusers/get")
        headers = {
          "apikey": your_apikey
        }
        request = Net::HTTP::Post.new(uri, headers)
        request.set_form_data()
        req_options = {
          use_ssl: uri.scheme == "https",
        }
        response = Net::HTTP.start(uri.hostname, uri.port, req_options) do |http|
          http.request(request)
        end
        
        puts response.body

                
        var request = (HttpWebRequest)WebRequest.Create("/toolusers/get");
        var postData = "";
        var data = Encoding.ASCII.GetBytes(postData);
        Console.WriteLine(postData.ToString());
        request.Method = "POST";
        request.Headers["apikey"] = your_apikey;
        request.ContentType = "application/x-www-form-urlencoded";
        request.ContentLength = data.Length;
        using (var stream = request.GetRequestStream())
        {
          stream.Write(data, 0, data.Length);
        }
        var response = (HttpWebResponse)request.GetResponse();
        var responseString = new StreamReader(response.GetResponseStream()).ReadToEnd();
        
        Console.WriteLine(responseString);

                
        var request = require('request');
        
        var targetURL = '/toolusers/get'
        var response = request.post(
          {
            url: targetURL,
            headers: {
              "apikey": your_apikey
            },
            form: {
              
            }
          }, (err, res, body) => {
            if(err == null){
              console.log(body);
            }
          }
        );

                
        import requests
        
        targetURL = "/toolusers/get"
        headers = {
          'apikey':your_apikey
        }
        data = {}
        r = requests.post(url = targetURL, data = data, headers = headers)
        
        print(r.text)

                
No available

                
No available

                
No available

Respuesta:

        {
            "success": true,
            "result": [
                {
                    "usertool_id": usertool_id,
                    "usertool_name": usertool_name,
                    "usertool_number": usertool_number,
                    "usertool_branch": usertool_branch,
                    "usertool_type": usertool_type,
                    "usertool_status": usertool_status
                }
            ],
            "code": "tool_users_01"
        }

Obtener tarjetas

Puedes obtener las tarjetas de lealtad que has creado con tu usuario, con el fin de poder utilizar la API, ya que el loyalty_key es un valor necesario para tus peticiones.

Encabezados

Atributo	Descripción	Tipo de Dato
apikey	`Obligatorio` Clave API generada en la sección de integraciones dentro del panel.	`Text`

              curl -X POST "/loyalty/get" -H "apikey: your_apikey" -d ""

                
        $params = array();
        $headers = array(
          "apikey: your_apikey"
        );
        curl_setopt_array($ch = curl_init(), array(
          CURLOPT_URL => "/loyalty/get",
          CURLOPT_SSL_VERIFYPEER => 0,
          CURLOPT_HEADER => 0,
          CURLOPT_HTTPHEADER => $headers,
          CURLOPT_POST => 1,
          CURLOPT_POSTFIELDS => http_build_query($params),
          CURLOPT_RETURNTRANSFER => 1
        ));
        $response = curl_exec($ch);
        curl_close($ch);
            
        echo json_encode($response);

                
        require 'net/http'
        require 'uri'
        
        uri = URI.parse("/loyalty/get")
        headers = {
          "apikey": your_apikey
        }
        request = Net::HTTP::Post.new(uri, headers)
        request.set_form_data()
        req_options = {
          use_ssl: uri.scheme == "https",
        }
        response = Net::HTTP.start(uri.hostname, uri.port, req_options) do |http|
          http.request(request)
        end
        
        puts response.body

                
        var request = (HttpWebRequest)WebRequest.Create("/loyalty/get");
        var postData = "";
        var data = Encoding.ASCII.GetBytes(postData);
        Console.WriteLine(postData.ToString());
        request.Method = "POST";
        request.Headers["apikey"] = your_apikey;
        request.ContentType = "application/x-www-form-urlencoded";
        request.ContentLength = data.Length;
        using (var stream = request.GetRequestStream())
        {
          stream.Write(data, 0, data.Length);
        }
        var response = (HttpWebResponse)request.GetResponse();
        var responseString = new StreamReader(response.GetResponseStream()).ReadToEnd();
        
        Console.WriteLine(responseString);

                
        var request = require('request');
        
        var targetURL = '/loyalty/get'
        var response = request.post(
          {
            url: targetURL,
            headers: {
              "apikey": your_apikey
            },
            form: {}
          }, (err, res, body) => {
            if(err == null){
              console.log(body);
            }
          }
        );

                
        import requests
        
        targetURL = "/loyalty/get"
        headers = {
          'apikey':your_apikey
        }
        data = {}
        r = requests.post(url = targetURL, data = data, headers = headers)
        
        print(r.text)

                
No available

                
No available

                
No available

Respuesta:

        {
          "success": true,
          "result": [
            {
                "loyalty_name": your_loyalty_name,
                "loyalty_key": your_loyalty_key,
                "loyalty_app_client": your_loyalty_app_client,
                "loyalty_app_redeem": your_loyalty_app_redeem
            }
          ],
          "status": 200,
          "code": "loyalty_get_01"
        }

Crear contacto

Este método te permitirá dar de alta usuarios para que puedan usar tu tarjeta de lealtad, al completarse el alta, el cliente recibirá un mensaje SMS o WhatsApp que contiene el link para ingresar a su nueva cuenta.

Encabezados

Atributo	Descripción	Tipo de Dato
apikey	`Obligatorio` Clave API generada en la sección de integraciones dentro del panel.	`Text`

Atributos

Atributo	Descripción	Tipo de Dato
loyalty_key	`Obligatorio` Llave de la tarjeta de lealtad.	`Text`
phone	`Obligatorio` Número a 10 digitos del cliente a registrar `4771234567`	`Text`
customer_name	`Obligatorio` Nombre del cliente	`Text`
usertool_id	`Obligatorio` Id del cajero o gerente que realiza la transacción. (Se obtiene con el método: Obtener usuarios)	`Number`
customer_birthdate	`Opcional` Fecha de cumpleaños del cliente, en caso que la tarjeta lo necesite. `YYYY-MM-DD HH-MM-DD`	`Text`

Errores

Código	Mensaje
auth_01	Usuario no autorizado
loyalty_contact_add_02	Llave la tarjeta de lealtad indefinido.
loyalty_contact_add_03	Teléfono indefinido.
loyalty_contact_add_04	Teléfono con formato incorrecto.
loyalty_contact_add_05	Nombre indefinido.
loyalty_contact_add_06	Usuario indefinido.
loyalty_contact_add_08	Contacto deshabilitado.
loyalty_contact_add_09	El teléfono es de casa o fijo.
loyalty_contact_add_10	Fecha de cumpleaños indefinida o con formato incorrecto.
loyalty_contact_add_07, loyalty_contact_add_11, loyalty_contact_add_12, loyalty_contact_add_13	Error al crear el registro del contacto.
loyalty_contact_add_14	Ya existe el contacto.
loyalty_contact_add_15	Lada no soportada
err_toolusers_01	El usuario no pertenece al propietario de la API Key.
loyalty_02, loyalty_03	No existe la tarjeta de lealtad o está deshabilitada.
marketing_tools_welcome_message_02	Error al obtener el WhatsApp.
marketing_tools_welcome_message_03	Error al enviar el mensaje.

              curl -X POST "/loyalty/contact/add" -H "apikey: your_apikey" -d "loyalty_key=your_loyalty_key&phone=client_phone_number&customer_name=client_name&usertool_id=cashier_id"

                
        $params = array(
          "loyalty_key" => your_loyalty_key,
          "phone" => client_phone_number,
          "customer_name" => client_name,
          "usertool_id" => cashier_id
        );
        $headers = array(
          "apikey: your_apikey"
        );
        curl_setopt_array($ch = curl_init(), array(
          CURLOPT_URL => "/loyalty/contact/add",
          CURLOPT_SSL_VERIFYPEER => 0,
          CURLOPT_HEADER => 0,
          CURLOPT_HTTPHEADER => $headers,
          CURLOPT_POST => 1,
          CURLOPT_POSTFIELDS => http_build_query($params),
          CURLOPT_RETURNTRANSFER => 1
        ));
        $response = curl_exec($ch);
        curl_close($ch);
            
        echo json_encode($response);

                
        require 'net/http'
        require 'uri'
        
        uri = URI.parse("/loyalty/contact/add")
        headers = {
          "apikey": your_apikey
        }
        request = Net::HTTP::Post.new(uri, headers)
        request.set_form_data(
          "loyalty_key" => your_loyalty_key,
          "phone" => client_phone_number,
          "customer_name" => client_name,
          "usertool_id" => cashier_id
        )
        req_options = {
          use_ssl: uri.scheme == "https",
        }
        response = Net::HTTP.start(uri.hostname, uri.port, req_options) do |http|
          http.request(request)
        end
        
        puts response.body

                
        var request = (HttpWebRequest)WebRequest.Create("/loyalty/contact/add");
        var postData = "loyalty_key=your_loyalty_key&";
        postData += "phone=client_phone_number&";
        postData += "customer_name=client_name&";
        postData += "usertool_id=cashier_id";
        var data = Encoding.ASCII.GetBytes(postData);
        Console.WriteLine(postData.ToString());
        request.Method = "POST";
        request.Headers["apikey"] = your_apikey;
        request.ContentType = "application/x-www-form-urlencoded";
        request.ContentLength = data.Length;
        using (var stream = request.GetRequestStream())
        {
          stream.Write(data, 0, data.Length);
        }
        var response = (HttpWebResponse)request.GetResponse();
        var responseString = new StreamReader(response.GetResponseStream()).ReadToEnd();
        
        Console.WriteLine(responseString);

                
        var request = require('request');
        
        var targetURL = '/loyalty/contact/add'
        var response = request.post(
          {
            url: targetURL,
            headers: {
              "apikey": your_apikey
            },
            form: {
              "loyalty_key": your_loyalty_key,
              "phone": client_phone_number,
              "customer_name": client_name,
              "usertool_id": cashier_id
            }
          }, (err, res, body) => {
            if(err == null){
              console.log(body);
            }
          }
        );

                
        import requests
        
        targetURL = "/loyalty/contact/add"
        headers = {
          'apikey':your_apikey
        }
        data = {
          'loyalty_key':your_loyalty_key,
          'phone':client_phone_number,
          'customer_name':client_name,
          'usertool_id':cashier_id
        }
        r = requests.post(url = targetURL, data = data, headers = headers)
        
        print(r.text)

                
No available

                
No available

                
No available

Respuesta:

        {
          "success": true,
          "message": "Contacto creado correctamente.",
          "status": 200,
          "code": "loyalty_contact_add_01"
        }

Obtener contactos

Este método te permite obtener un listado de los contactos registrados en tu tarjeta de lealtad y sus datos. También podrás solicitar los datos de un contacto específico.

Encabezados

Atributo	Descripción	Tipo de Dato
apikey	`Obligatorio` Clave API generada en la sección de integraciones dentro del panel.	`Text`

Atributos

Atributo	Descripción	Tipo de Dato
loyalty_key	`Obligatorio` Llave de la tarjeta de lealtad.	`Text`
phone	`Opcional` Número a 10 digitos del cliente a consultar `4771234567`	`Text`

Errores

Código	Mensaje
auth_01	Usuario no autorizado
loyalty_contact_get_02	Llave de la tarjeta indefinida.
loyalty_contact_get_03	Teléfono con formato incorrecto.
loyalty_contact_get_04	La tarjeta de lealtad no existe.
loyalty_contact_get_05	El contacto no se encuentra registrado en la tarjeta.

              curl -X POST "/loyalty/contact/get" -H "apikey: your_apikey" -d "loyalty_key=your_loyalty_key"

                
        $params = array(
          "loyalty_key" => your_loyalty_key
        );
        $headers = array(
          "apikey: your_apikey"
        );
        curl_setopt_array($ch = curl_init(), array(
          CURLOPT_URL => "/loyalty/contact/get",
          CURLOPT_SSL_VERIFYPEER => 0,
          CURLOPT_HEADER => 0,
          CURLOPT_HTTPHEADER => $headers,
          CURLOPT_POST => 1,
          CURLOPT_POSTFIELDS => http_build_query($params),
          CURLOPT_RETURNTRANSFER => 1
        ));
        $response = curl_exec($ch);
        curl_close($ch);
            
        echo json_encode($response);

                
        require 'net/http'
        require 'uri'
        
        uri = URI.parse("/loyalty/contact/get")
        headers = {
          "apikey": your_apikey
        }
        request = Net::HTTP::Post.new(uri, headers)
        request.set_form_data(
          "loyalty_key" => your_loyalty_key
        )
        req_options = {
          use_ssl: uri.scheme == "https",
        }
        response = Net::HTTP.start(uri.hostname, uri.port, req_options) do |http|
          http.request(request)
        end
        
        puts response.body

                
        var request = (HttpWebRequest)WebRequest.Create("/loyalty/contact/get");
        var postData = "loyalty_key=your_loyalty_key";
        var data = Encoding.ASCII.GetBytes(postData);
        Console.WriteLine(postData.ToString());
        request.Method = "POST";
        request.Headers["apikey"] = your_apikey;
        request.ContentType = "application/x-www-form-urlencoded";
        request.ContentLength = data.Length;
        using (var stream = request.GetRequestStream())
        {
          stream.Write(data, 0, data.Length);
        }
        var response = (HttpWebResponse)request.GetResponse();
        var responseString = new StreamReader(response.GetResponseStream()).ReadToEnd();
        
        Console.WriteLine(responseString);

                
        var request = require('request');
        
        var targetURL = '/loyalty/contact/get'
        var response = request.post(
          {
            url: targetURL,
            headers: {
              "apikey": your_apikey
            },
            form: {
              "loyalty_key": your_loyalty_key
            }
          }, (err, res, body) => {
            if(err == null){
              console.log(body);
            }
          }
        );

                
        import requests
        
        targetURL = "/loyalty/contact/get"
        headers = {
          'apikey':your_apikey
        }
        data = {
          'loyalty_key':your_loyalty_key
        }
        r = requests.post(url = targetURL, data = data, headers = headers)
        
        print(r.text)

                
No available

                
No available

                
No available

Respuesta:

        {
            "success": true,
            "result": [
                {
                    "contact_name": contact_name,
                    "contact_phone": contact_phone,
                    "contact_birthdate": contact_birthdate,
                    "contact_total_loyalty_completes": contact_total_loyalty_completes,
                    "contact_current_redeem": contact_current_redeem
                }
            ]
            "status": 200,
            "code": "loyalty_contact_get_01"
        }
        
        O en caso de buscar un contacto en específico
        
        {
            "success": true,
            "result": {
                "contact_name": contact_name,
                "contact_phone": contact_phone,
                "contact_birthdate": contact_birthdate,
                "contact_total_loyalty_completes": contact_total_loyalty_completes,
                "contact_current_redeem": contact_current_redeem
            }
            "status": 200,
            "code": "loyalty_contact_get_01"
        }

Crear venta

Puedes generar una nueva venta a tu cliente. Ingresarás el monto total de compra y el ticket, dependiendo si estos campos los configuraste en tu tarjeta de lealtad.

Encabezados

Atributo	Descripción	Tipo de Dato
apikey	`Obligatorio` Clave API generada en la sección de integraciones dentro del panel.	`Text`

Atributos

Atributo	Descripción	Tipo de Dato
loyalty_key	`Obligatorio` Llave de la tarjeta de lealtad.	`Text`
phone	`Obligatorio` Número a 10 digitos del cliente a consultar `4771234567`	`Text`
usertool_id	`Obligatorio` Id del cajero o gerente que realiza la transacción. (Se obtiene con el método: Obtener usuarios)	`Number`
transaction_amount	`Opcional` Monto de la venta, en caso de configurarlo en la tarjeta este dato no es necesario, pero si no se ingresa se tomará el valor por default configurado.	`Number`
ticket	`Opcional` En caso de que la tarjeta de lealtad tenga configurado el ticket, este valor es obligatorio.	`Text`

Errores

Código	Mensaje
auth_01	Usuario no autorizado
loyalty_sale_03	Llave de la tarjeta indefinida.
loyalty_sale_04	Teléfono indefinido.
loyalty_sale_05	Teléfono con formato incorrecto.
loyalty_sale_06	Id del usuario indefinido.
loyalty_sale_07	El contacto no existe.
loyalty_sale_08	El contacto no se encuentra registrado en la tarjeta de lealtad.
loyalty_sale_09	Ticket indefinido.
loyalty_sale_10	Monto de la transacción indefinida o debe de ser mayor a 0.
loyalty_sale_11	El contacto está en tu blacklist.
loyalty_sale_12, loyalty_sale_14, loyalty_sale_18, loyalty_sale_19	Error al generar la venta.
loyalty_sale_13	El usuario llegó al límite de canjes por día.
loyalty_sale_15, loyalty_sale_16	Saldo insuficiente
loyalty_sale_17	Error al obtener la información de tu WhatsApp.
loyalty_sale_20	Error al enviar el mensaje de canje.
loyalty_sale_21	El usuario de la herramienta no pertenece al usuario de la apikey.
loyalty_sale_22	El usuario de la herramienta no tiene permisos sobre el monedero.
loyalty_02, loyalty_03	No existe la tarjeta de lealtad o está deshabilitada.

              curl -X POST "/loyalty/sale" -H "apikey: your_apikey" -d "loyalty_key=your_loyalty_key&phone=client_phone_number&transaction_amount=1000&usertool_id=cashier_id"

                
        $params = array(
          "loyalty_key" => your_loyalty_key,
          "phone" => client_phone_number,
          "transaction_amount" => 1000,
          "usertool_id" => cashier_id
        );
        $headers = array(
          "apikey: your_apikey"
        );
        curl_setopt_array($ch = curl_init(), array(
          CURLOPT_URL => "/loyalty/sale",
          CURLOPT_SSL_VERIFYPEER => 0,
          CURLOPT_HEADER => 0,
          CURLOPT_HTTPHEADER => $headers,
          CURLOPT_POST => 1,
          CURLOPT_POSTFIELDS => http_build_query($params),
          CURLOPT_RETURNTRANSFER => 1
        ));
        $response = curl_exec($ch);
        curl_close($ch);
            
        echo json_encode($response);

                
        require 'net/http'
        require 'uri'
        
        uri = URI.parse("/loyalty/sale")
        headers = {
          "apikey": your_apikey
        }
        request = Net::HTTP::Post.new(uri, headers)
        request.set_form_data(
          "loyalty_key" => your_loyalty_key,
          "phone" => client_phone_number,
          "transaction_amount" => 1000,
          "usertool_id" => cashier_id
        )
        req_options = {
          use_ssl: uri.scheme == "https",
        }
        response = Net::HTTP.start(uri.hostname, uri.port, req_options) do |http|
          http.request(request)
        end
        
        puts response.body

                
        var request = (HttpWebRequest)WebRequest.Create("/loyalty/sale");
        var postData = "loyalty_key=your_loyalty_key&";
        postData += "phone=client_phone_number&";
        postData += "transaction_amount=1000&";
        postData += "usertool_id=cashier_id";
        var data = Encoding.ASCII.GetBytes(postData);
        Console.WriteLine(postData.ToString());
        request.Method = "POST";
        request.Headers["apikey"] = your_apikey;
        request.ContentType = "application/x-www-form-urlencoded";
        request.ContentLength = data.Length;
        using (var stream = request.GetRequestStream())
        {
          stream.Write(data, 0, data.Length);
        }
        var response = (HttpWebResponse)request.GetResponse();
        var responseString = new StreamReader(response.GetResponseStream()).ReadToEnd();
        
        Console.WriteLine(responseString);

                
        var request = require('request');
        
        var targetURL = '/loyalty/sale'
        var response = request.post(
          {
            url: targetURL,
            headers: {
              "apikey": your_apikey
            },
            form: {
              "loyalty_key": your_loyalty_key,
              "phone": client_phone_number,
              "transaction_amount": 1000,
              "usertool_id": cashier_id
            }
          }, (err, res, body) => {
            if(err == null){
              console.log(body);
            }
          }
        );

                
        import requests
        
        targetURL = "/loyalty/sale"
        headers = {
          'apikey':your_apikey
        }
        data = {
          'loyalty_key':your_loyalty_key,
          'phone': client_phone_number,
          'transaction_amount': 1000,
          'usertool_id': cashier_id
        }
        r = requests.post(url = targetURL, data = data, headers = headers)
        
        print(r.text)

                
No available

                
No available

                
No available

Respuesta:

        {
            "success": true,
            "message": "Venta creada correctamente.",
            "code": "loyalty_sale_01",
            "status": 200
        }
        
        O en caso que el cliente completó la tarjeta
        
        {
            "success": true,
            "message": "El usuario ya ha completado la tarjeta.",
            "code": "loyalty_sale_02",
            "status": 200
        }