API V2 Tracksale

La nueva versión de la API de integración de Tracksale fue creada con el objetivo de que las informaciones pudieran tener una autenticación para acceder. Las diferencias entre la versión 1.0 y la 2.0, tenemos:
  • Ahora un TOKEN es generado a través de nuestra plataforma, o de una requisición. De esta forma, automatizamos todo el proceso y también homologamos el acceso a informaciones.
  • La API 2.0 integra las funciones de la versión 1.0 de la API live y API RESTful en una sola API con diversos métodos.
  • La nueva API trabaja con el modelo RESTful con JSON.

En esta documentación encontrará también ejemplos de códigos en el idioma que usted escoja, que pueden cambiar en cualquier momento en el botón de la derecha.

La utilización de la API demanda el uso de una clave que llamamos TOKEN, el mismo será responsable de permitir el acceso al sistema.

  1. Para ello, iniciar sesión en Tracksale con una cuenta de administrador.
  2. Acceder al menú Apps en la esquina superior derecha junto al nombre del usuario.


  3. Haga clic en instalar en la aplicación

    "API V2".
  4. Cliqueando en NUEVO TOKEN.

  5. Se generará un nuevo token.

  6. Un nuevo TOKEN será generado y agregado a la lista, nuevas adiciones no inutilizan los anteriores.

Toda la comunicación de la API se realiza desde la URL base api.tracksale.co/v2.

Utilizaremos el TOKEN que adquirimos en el header (Sin la necesidad de conversión a base64), para autenticar el acceso. De la siguiente manera:

  • Key Authorization
  • Value bearer TOKEN

Donde:

  • Authorization es la palabra Authorization
  • bearer es la palabra bearer y TOKEN es el TOKEN adquirido aqui

Listar Campañas



Para listar las campañas utilizaremos la siguiente configuración


  • El método utilizado será : GET
  • La URL utilizada será : api.tracksale.co/v2/campaign

Este método es responsable de la lista de URL utilizada en todas las campañas, sus códigos y algunos detalles, como por ejemplo, preguntas usadas.

Es posible que se vuelva sólo una campaña específica, esto es posible usando

  • URL: api.tracksale.co/v2/campaign/Campaign_code

Donde Campaign_code es el código de la campaña que desea obtener información.

Para recoger el código de una campaña específica, primero debe listar todos las campañas y tomar el atributo "code" de la vuelta



Ejemplo de retorno:

{
            "name":"Customers_name",
            "code" : Campaign_code,
            "description" : Campaign_description,
            "detractors" : Detractors_name,
            "passives" : Neutrals_name,
            "promoters" : Promoters_name,
            "dispatches" : Dispatches_number,
            "comments" : Comments,
            "answers" : Answers,
            "main_channel" : "Main_channel",
            "create_time" : "Time_of_creation",
            "questions" : [
                {
                    "type" : "Question_type",
                    "title" : "Question_title",
                    "question" : "Question",
                    "secondary" : "Secondary_question"
                }
            ]

}

                                        

Ejemplos de código : Listar Campañas

Clase cURL

curl -X GET \
  https://api.tracksale.co/v2/campaign \
  -H 'authorization: bearer TOKEN' \
  -H 'cache-control: no-cache'

Disparos



Los disparos se pueden realizar de dos formas diferentes

Disparo programado:

  • El método utilizado será : POST
  • La URL utilizada será : api.tracksale.co/v2/campaign/Campaign_code/dispatch

    Donde Campaign_code es el código de la campaña a la que desea disparar

La existencia de la variable schedule_time es opcional.

Así, tenemos dos opciones

  • Insertar la variable "schedule_time" :

  • De esta forma usted puede utilizar "schedule_time" para definir cuando se realizará el disparo, siendo definido como un formato "Unix Timestamp" en segundos. El body quedará de la siguiente forma

    El ejemplo siguiente muestra la inserción con todas las variables, pero hay casos en los que se pueden omitir las variables indentification, phone y email.

    Ex: Si la campaña es vía SMS, no es necesario eviar el email, pero todavía puede ser enviado. En las campañas vía email la variable phone no necesita ser enviada, pero si es necesario, existe la posibilidad de enviarla.

    El envío de ambas variables se indica si utiliza flujo de campañas.

    Se recomienda el envío de identificación si desea identificar al cliente con el mismo parámetro de su empresa / plataforma

    {
        "customers": [
            {
                "name":"Customers_name",
                "email":"Customers_email",
                "identification": null,
                "phone": "Customers_phone",
                "tags" : [
                    {
                        "name" : "TagExample",
                        "value" : "TagExample"
                    },
                    {
                        "name" : "TagExample",
                        "value" : "TagExample"
                    }
                ]
            }
        ],
        "schedule_time": Timestamp_in_seconds
    }
    
                                            

    Do clase application/json

  • No insertar la variable "schedule_time" :

  • Esta manera debe ser usada si su intención es reunir varios disparos a una campaña, para efectuarlos de una sola vez posteriormente. De esta forma, se devuelve un código del lote de disparos, este código se debe utilizar en Disparo de lotes.


    {
        "customers": [
            {
                "name":"Customers_name",
                "email":"Customers_email",
                "tags" : [
                    {
                        "name" : "TagExample",
                        "value" : "TagExample"
                    },
                    {
                        "name" : "TagExample",
                        "value" : "TagExample"
                    }
                ]
            }
        ],
    }
    
                                            

    Do clase application/json

    Todos los disparos posteriores a la misma campaña devolverán el mismo lote de disparos hasta que realice el disparo de este lote.





Parámetros

Atributos Tipos Obligatorio Descripción
name String No Nombre del cliente
email String Sí (para disparos Vía email) Correo electrónico del cliente
phone String Sí (para disparos Vía SMS) Teléfono del cliente
tags Array No Nombre de la tag
tags Clase Obligatorio Descripción
name String Nombre de la tag
value String Valor de la Tag



Ejemplo de retorno:

Sin schedule_time
{
    "msg":"Customers have been successfully added!",
    "dispatch_code":"Dispatch_code",
    "status": {
        "duplicated":Number_of_duplications,
        "invalid":Number_of_invalids,
        "inserted":Number_of_insertions
    },
    "campaign": {
        "name":Campaign_name,
        "cod":Campaign_code
    }
}
 


Con schedule_time
{
    "msg":"Dispatch executed!",
    "dispatch_code":"Dispatch_code",
    "status": {
        "duplicated":Number_of_duplications,
        "invalid":Number_of_invalids,
        "inserted":Number_of_insertions
    },
    "campaign": {
        "name":Campaign_name,
        "cod":Campaign_code
    }
}

                            

También se puede devolver una matriz con los clientes que no se han insertado, ya sea que se duplican o por qué se encontraban inválidos.

Para ello, se debe pasar el parámetro getNotInserted con el valor 1. Así regresaremos de la siguiente manera.

{
    "msg":"Dispatch executed!",
    "dispatch_code":"Dispatch_code",
    "status": {
        "duplicated":Number_of_duplications,
        "invalid":Number_of_invalids,
        "inserted":Number_of_insertions
    },
    "campaign": {
        "name":Campaign_name,
        "cod":Campaign_code
    }
    "duplicated_customers": [
                {
                    "name":"customer name",
                    "email":"email@email.com"
                }
    ],
    "invalid_customers": [
                {
                    "name":"customer name",
                    "reason":"Invalid or empty main channel"
                }
    ],
}

                            

Clase cURL

curl -X POST \
  https://api.tracksale.co/v2/campaign/campaign_code/dispatch \
  -H 'authorization: bearer TOKEN' \
  -H 'cache-control: no-cache' \
  -H 'content-type: application/json' \
  -d '{
    "customers": [
        {
            "name":"Customers_name",
            "email":"Customers_email",
            "tags" : [
                {
                    "name" : "TagExample",
                    "value" : "TagExample"
                },
                {
                    "name" : "TagExample",
                    "value" : "TagExample"
                }
            ]
        }
    ],
    "schedule_time": Timestamp_in_Seconds
}'


Disparo de lotes:

El disparo de este lote debe efectuarse utilizando las siguientes configuraciones

  • El método utilizado será: POST

  • La URL utilizada será: api.tracksale.co/v2/campaign/Campaign_code/dispatch/Codigo_lote


El cuerpo debe ser llenado con el tiempo que el disparo debe realizarse en segundos, en el formato timestamp. Utilice 0 para un disparo instantáneo
Como en el ejemplo:

{
    "time": Timestamp_in_seconds
}


Nombre Clase Obligatorio Descripción
time Integer El tiempo que se realizará el disparo, en segundos en el formato timestamp


Ejemplo de retorno:

{
    "msg":"Dispatch executed!",
    "customers":"Number_of_customers",
}

                            

Ejemplos de código : Disparo de lotes

Clase cURL

curl -X POST \
  https://api.tracksale.co/v2/campaign/campaign_code/dispatch/Codigo_lote \
  -H 'authorization: bearer TOKEN' \
  -H 'cache-control: no-cache' \
  -H 'content-type: application/json' \
  -d '{
    "time": Timestamp_in_Seconds
}'

Insertar Respuestas

También proporcionamos un método de inserción de respuestas. Este método se puede utilizar con los siguientes Parámetros.
  • El método será:POST
  • La URL que se utilizará debe ser: api.tracksale.co/v2/answer
  • El body debe ser completado con el lote de respuestas usando el siguiente por defecto
{
    "campaign_code": "Campaign_code",
    "answers":[
        {
            "name":"Customers_name",
            "email":"Customers_email",
            "score":Customer_score,
            "justification":""Customers_comment"",
            "create_time":Timestamp_in_seconds,
            "tags" : [
                {
                    "name" : "TagExample",
                    "value" : "TagExample"
                }
            ]
        }
    ]
}

                            
Parámetros

Parámetro Clase Obligatorio Descripción
campaign_code String Clave de la campaña objetivo. Obtenido por el métodoListar campañas
answers Array Lista de respuestas

answers Clase Obligatorio Descripción
name String Nombre del cliente
email String Sí, se o disparo foi realizado por email Correo electrónico del cliente
phone String Sí, se o disparo foi realizado por telefone Teléfono del cliente
score Integer Score del cliente (entre 0 a 10)
justification String No Comentarios del cliente
create_time Integer No Fecha/hora de la respuesta en el defecto timestamp (en segundos)
tags Array No Tag para agregar información al cliente

tags Clase Obligatorio Descripción
name String Nombre de la tag
value String Valor de la Tag


Ejemplo de retorno:

{
    "msg":"Number_of_answers Answer inserted"
    "status": {
        "invalid":Number_of_invalids,
        "inserted":Number_of_insertions,

    }
}

                            

Ejemplos de código : Insertar Respuestas

Clase cURL

curl -X POST \
  https://api.tracksale.co/v2/answer \
  -H 'authorization: bearer TOKEN' \
  -H 'cache-control: no-cache' \
  -H 'content-type: application/json' \
  -d '{
    "campaign_code": "campaign_code",
    "answers":[
        {
            "name":"customers_name",
            "email":"customers_Email",
            "score":Customer_score,
            "justification":"customers_comment",
            "create_time":Timestamp_in_seconds,
            "tags" : [
                {
                    "name" : "TagExample",
                    "value" : "TagExample"
                }
            ]
        }
    ]
}'

Reports es nuestro método para la generación de informes, es responsable de mostrar los detalles de todas sus campañas o de una campaña.

Toda la comunicación de la API se realiza desde la URL base https://api.tracksale.co/v2/report/Detalles.

Donde Detalles deberá ser sustituido por los detalles que usted desea obtener a través de un requerimiento

El método que se utilizará seráGET

    El header se debe rellenar con los parámetros Donde
  • Key Authorization
  • Value bearer TOKEN

Comentarios

El método a ser usado debe ser:GET

La URL a ser usada debe ser:https://api.tracksale.co/v2/report/answer

Método responsable por devolver los comentarios de los clientes.


Parámetros

Parámetro Clase Predeterminado Obligatorio Descripción
start Date Predeterminadamente mostrará los resultados 30 dias anteriores a la fecha que está realizando requerimiento
(Ej: si usted está haciendo ese requerimiento el día 31/01/2017 y no incluir el intervalo inicial y final que usted desea hacer su investigación, el período retornado será de 01/01/2017 a 31/01/2017)
No Fecha inicial de su consulta en el formato aaaa-mm-dd
end Date Predeterminadamente mostrará los resultados 30 dias anteriores a la fecha que está realizando requerimiento
(Ej: si usted está haciendo ese requerimiento el día 31/01/2017 y no incluir el intervalo inicial y final que usted desea hacer su investigación, el período retornado será de 01/01/2017 a 31/01/2017)
No Fecha final de su consulta en el formato aaaa-mm-dd
limit Integer Predeterminadamente mostrará 10 Comentarios por requerimiento. No Total de Comentarios a serem retornados. Utilize -1 para retornar todos.
tags Boolean Predeterminadamente es falso, ou seja, nenhuma tag será mostrada. No Devuelve las tags referentes a las respuestas
justifReturn String Predeterminadamente mostrará en el formato "level" No

Formato de devolución de las justificaciones.


"array" -

Devuelve todos en un único array.


"level" -

Devuelve el formato JSON con subniveles de justificaciones agrupadas.

codes String Predeterminadamente mostrará los comentarios de todas las campañas No Usado para mostrar los comentarios de una campaña específica, o los comentarios de todas las campañas. Se puede mostrar tambien los comentarios de más de una campaña por vez, para esto utilice la coma como separador (Por ejemplo: códigos=52,51,50 mostrará los comentarios de las campañas cuyo Campaign_code es 50, 51 y 52)


Ejemplo de retorno:

[
    {
        "time": 1454340407,
        "type": "Email",
        "name": "Customers_name",
        "email": "Customers_email",
        "identification": null,
        "phone": "Customers_phone",
        "alternative_email": "Customers_email",
        "alternative_phone": "Customers_phone",
        "nps_answer": Score,
        "last_nps_answer": Score,
        "nps_comment": Comment,
        "campaign_name": "Campaign_name",
        "campaign_code": "Campaign_code",
        "id": 6805511,
        "deadline": null,
        "elapsed_time": 17,
        "dispatch_time": null,
        "reminder_time": null,
        "status": "Status",
        "priority": "None",
        "assignee": "Assignee_name",
        "picture": null,
        "tags": [],
        "categories": [],
        "justifications": []
    }
]

                            

Dispatch

El método a utilizar debe ser : GET

La URL que se utilizará debe ser:api.tracksale.co/v2/report/dispatch

Método responsable de devolver los disparos y sus datos, como clientes insertados, la hora que se realizó, su estado y los clientes que se han insertado en el mismo.

[
    {
        "campaign": {
            "name": "Camapaign_name",
            "code": "Campaign_code"
        },
        "dispatch_code": "Code_of_dispatch",
        "status": Status_of_dispatch,
        "create_time": "Campaign_creation_time",
        "customers": [
            {
                "name": "Customers_name",
                "identification": null,
                "email": "Customers_email",
                "phone": "Customers_phone",
                "dispatch_time": "Code_of_dispatch",
                "status": "Status_of_dispatch"
            }
        ]
    }
]

                            
Parámetros

Parámetro Clase Predeterminado Obligatorio Descripción
start Date Predeterminado mostrará los resultados 30 dias anteriores a data que está realizando requerimiento
(Ej: si usted está haciendo ese requerimiento el día 31/01/2017 y no incluir el intervalo inicial y final que usted desea hacer su investigación, el período retornado será de 01/01/2017 a 31/01/2017)
No Fecha inicial de su consulta en el formato aaaa-mm-dd
end Date Predeterminado mostrará los resultados 30 dias anteriores a data que está realizando requerimiento
(Ej: si usted está haciendo ese requerimiento el día 31/01/2017 y no incluir el intervalo inicial y final que usted desea hacer su investigación, el período retornado será de 01/01/2017 a 31/01/2017)
No Fecha final de su consulta en el formato aaaa-mm-dd
codes String Predeterminado mostrará os Comentarios de todos as campanhas No Utilizado para mostrar los comentarios de una campaña específica, o los staus de todos las campañas. Se puede también mostrar los comentarios de más de una campaña a la vez, para ello utilice la coma como separador (Por ejemplo: códigos=52,51,50 mostrará los comentarios de las campañas cuyo Campaign_code es 50, 51 y 52)


NPS

El método a utilizar debe ser : GET

La URL que se utilizará debe ser: https://api.tracksale.co/v2/report/nps

La URL a ser utilizada debe ser:https://api.tracksale.co/v2/report/nps

El método responsable de devolver el número de disparos, los números de detractores, promotores y neutros y sus respectivos porcentajes y también el valor del nps.

Parámetros

Parámetro Clase Predeterminado Obligatorio Descripción
start Date Predeterminado mostrará los resultados 30 dias anteriores a data que está realizando requerimiento
(Ej: si usted está haciendo ese requerimiento el día 31/01/2017 y no incluir el intervalo inicial y final que usted desea hacer su investigación, el período retornado será de 01/01/2017 a 31/01/2017)
No Fecha inicial de su consulta en el formato aaaa-mm-dd
end Date Predeterminado mostrará los resultados 30 dias anteriores a data que está realizando requerimiento
(Ej: si usted está haciendo ese requerimiento el día 31/01/2017 y no incluir el intervalo inicial y final que usted desea hacer su investigación, el período retornado será de 01/01/2017 a 31/01/2017)
No Fecha final de su consulta en el formato aaaa-mm-dd
compare Boolean Por padráo es false No Retorna os dados do NPS referente ao período anterior do filtro de data.
codes String Predeterminadamente mostrará los comentarios de todas las campañas No Usado para mostrar los comentarios de una campaña específica, o los comentarios de todas las campañas. Se puede mostrar tambien los comentarios de más de una campaña por vez, para esto utilice la coma como separador (Por ejemplo: códigos=52,51,50 mostrará los comentarios de las campañas cuyo Campaign_code es 50, 51 y 52)


Ejemplo de retorno:

{
    "dispatches": Number_of_dispatches,
    "promoters": Number_of_promoter,
    "detractors": Number_of_detractors,
    "passives": Number_of_neutrals,
    "detractors_percentage": Percentage_of_detractors,
    "passives_percentage": Percentage_of_neutrals,
    "promoters_percentage": Percentage_of_promoters,
    "nps": Period_NPS,
    "compare": {
        "dispatches": Number_of_dispatches,
        "promoters": Number_of_promoter,
        "detractors": Number_of_detractors,
        "passives": Number_of_neutrals,
        "detractors_percentage": Percentage_of_detractors,
        "passives_percentage": Percentage_of_neutrals,
        "promoters_percentage": Percentage_of_promoters,
        "nps": Period_NPS,
    }
}

                            

Categorías

El método a utilizar debe ser :GET

La URL que se utilizará debe ser: https://api.tracksale.co/v2/report/category

Método responsable de devolver las categorías de las campañas de acuerdo Con el NPS.

Parámetros

Parámetro Clase Predeterminado Obligatorio Descripción
start Date Predeterminado mostrará los resultados 30 dias anteriores a data que está realizando requerimiento
(Ej: si usted está haciendo ese requerimiento el día 31/01/2017 y no incluir el intervalo inicial y final que usted desea hacer su investigación, el período retornado será de 01/01/2017 a 31/01/2017)
No Fecha inicial de su consulta en el formato aaaa-mm-dd
end Date Predeterminado mostrará los resultados 30 dias anteriores a data que está realizando requerimiento
(Ej: si usted está haciendo ese requerimiento el día 31/01/2017 y no incluir el intervalo inicial y final que usted desea hacer su investigación, el período retornado será de 01/01/2017 a 31/01/2017)
No Fecha final de su consulta en el formato aaaa-mm-dd
codes String Predeterminado mostrará os Comentarios de todos as campanhas No Utilizado para mostrar los comentarios de una campaña específica, o los staus de todos las campañas. Se puede también mostrar los comentarios de más de una campaña a la vez, para ello utilice la coma como separador (Por ejemplo: códigos=52,51,50 mostrará los comentarios de las campañas cuyo Campaign_code es 50, 51 y 52)


Ejemplo de retorno:

[
    {
        "id": 6805511,
        "name": "Product",
        "color": "#F8D347",
        "total": 25,
        "nps": Period_NPS,
        "total": total,

    }
]

                            

Obtener estado de las campañas

El método a utilizar debe ser :GET

La URL que se utilizará debe ser: https://api.tracksale.co/v2/report/status

A URL a ser usada debe ser: https://api.tracksale.co/v2/report/status

Método responsable de retornar el estado de las campañas.



Parámetros

Parámetro Clase Predeterminado Obligatorio Descripción
start Date Predeterminado mostrará los resultados 30 dias anteriores a data que está realizando requerimiento
(Ej: si usted está haciendo ese requerimiento el día 31/01/2017 y no incluir el intervalo inicial y final que usted desea hacer su investigación, el período retornado será de 01/01/2017 a 31/01/2017)
No Fecha inicial de su consulta en el formato aaaa-mm-dd
end Date Predeterminado mostrará los resultados 30 dias anteriores a data que está realizando requerimiento
(Ej: si usted está haciendo ese requerimiento el día 31/01/2017 y no incluir el intervalo inicial y final que usted desea hacer su investigación, el período retornado será de 01/01/2017 a 31/01/2017)
No Fecha final de su consulta en el formato aaaa-mm-dd
codes String Predeterminado mostrará os Comentarios de todos as campanhas No Utilizado para mostrar los comentarios de una campaña específica, o los staus de todos las campañas. Se puede también mostrar los comentarios de más de una campaña a la vez, para ello utilice la coma como separador (Por ejemplo: códigos=52,51,50 mostrará los comentarios de las campañas cuyo Campaign_code es 50, 51 y 52)


Ejemplo de retorno:

[
    {
        "id": 76,
        "name": "Pendente Cliente",
        "total": 25,
        "color": "#F8D347"
    }
]

                            

Ejemplos de código : Reports /Detalles

Clase cURL

curl -X GET \
  'https://api.tracksale.co/v2/report/DETALHES?start=DATA_INICIO&end=DATA_FIM' \
  -H 'authorization: bearer TOKEN' \
  -H 'cache-control: no-cache'