API V2 Tracksale

A nova versão da API de integração da Tracksale foi criada com o objetivo de que as informações pudessem ter uma autenticação para serem acessadas. Dentre as diferenças entre a versão 1.0 e a 2.0, temos:
  • Agora um TOKEN é gerado através da nossa plataforma, ou de uma requisição. Desta forma, automatizamos todo o processo e também homologamos o acesso a informações.
  • A API 2.0 integra as funções da versão 1.0 da API live e API RESTful em uma só API com métodos diversos.
  • A nova API trabalha com modelo RESTful com JSON.

Nessa documentaçao você encontrará também exemplos de códigos nas linguagem a sua escolha, que podem ser alterados a qualquer momento no botão a direita.

A utilização da API demanda o uso de uma chave que chamamos de TOKEN, o mesmo será responsável por autenticar o acesso ao sistema.

  1. Para isso faça o login na Tracksale com uma conta de administrador.
  2. Acesse o menu Apps no canto superior direito junto ao nome do usuário.


  3. Clique em instalar no app

    "API V2".
  4. Clicando em NOVO TOKEN.

  5. Um novo token será gerado.

  6. Um novo TOKEN será gerado e adicionado a lista, novas adições não inutilizam os anteriores.

Toda a comunicação da API é feita a partir da URL base api.tracksale.co/v2.

Usaremos o TOKEN que adquirimos no header (sem a necessidade de conversão para base64), para autenticarmos o acesso. Da seguinte forma:

  • Key Authorization
  • Value bearer TOKEN

Onde:

  • Authorization é a palavra Authorization
  • bearer é a palavra bearer e TOKEN é o TOKEN adquirido aqui

Listar Campanhas



Para listar as campanhas utilizaremos a seguinte configuração


  • O método usado será : GET
  • A URL usada será : api.tracksale.co/v2/campaign

Esse método é responsável por listar todas as campanhas, seus códigos e alguns detalhes, como por exemplo as perguntas usadas.

É possível que se retorne apenas uma campanha específica, isso é possivel usando

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

Onde Campaign_code é o código da campanha que você deseja obter informações.

Para pegar o código de uma campanha específica, deve-se primeiro listar todas as campanhas e pegar o atributo "code" do retorno.



Exemplo de retorno:

{
            "name":"Customers_name",
            "code" : Campaign_code,
            "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"
                }
            ]

}

                                        

Exemplos de código : Listar campanhas

Tipo cURL

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

Disparos



Os disparos podem ser realizados de duas formas diferentes

Disparo agendado:

  • O método usado será : POST
  • A URL usada será : api.tracksale.co/v2/campaign/Campaign_code/dispatch

    Onde Campaign_code é o código da campanha para qual você deseja disparar.

A existência da variável schedule_time é opcional.

Assim, temos duas opções

  • Inserir a variável "schedule_time":

  • Dessa forma você você pode usar "schedule_time" para definir o momento onde o disparo deve ser efetuado, determinado no formato "Unix Timestamp" em segundos .
    O body ficará da seguinte forma

    O Exemplo a seguir mostra a inserção com todas as variáveis, mas existe casos em que as variáveis indentification, phone e email podem ser omitidas.

    Ex: Caso a campanha seja via SMS, não é necessário eviar o email, mas ele ainda pode ser enviado. Nas campanhas via email a variável phone não precisa ser enviada, mas caso seja necessário, existe a possibilidade de enviá-la.

    O envio de ambas variáveis é indicado caso use fluxo de campanhas.

    O envio de identification é recomendado caso deseje identificar o cliente pelo mesmo parâmetro da sua 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 tipo application/json

  • Não inserir a variável "schedule_time" :

  • Essa maneira deve ser usada caso sua intenção seja reunir vários disparos a uma campanha, para efetuá-los de uma só vez posteriormente. Dessa forma, será retornado um código do lote disparos, esse código deve ser usado no Disparo de lotes.


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

    Do tipo application/json

    Todos os disparos subsequentes a mesma campanha retornarão o mesmo lote de disparos até que você realize o disparo deste lote.





Parâmetros

Atributos Tipos Obrigatório Descrição
name String Não Nome do cliente
email String Sim (para disparos via email) Email do cliente
phone String Sim (para disparos via SMS) Telefone do cliente
tags Array Não Nome da tag
tags Tipo Obrigatório Descrição
name String Sim Nome da tag
value String Sim Valor da Tag



Exemplo de retorno:

Sem 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
    }
}
 


Com 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
    }
}

                            

É possível também retornar um array com os customers que não foram inseridos, seja por que eram duplicados ou por que se encontravam inválidos.

Para isso, deve-se passar o parâmetro getNotInserted com o valor 1. Assim retornaremos da seguinte forma.

{
    "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"
                }
    ],
}

                            

Tipo 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:

O disparo deste lote deve ser efetuado usando as seguintes configurações

  • O Método usado será: POST

  • A URL usada será: api.tracksale.co/v2/campaign/Campaign_code/dispatch/Codigo_lote


O body deve ser preenchido com o tempo que o disparo deve ser realizado em segundos, no formato timestamp. Use 0 para um disparo instantâneo
Como no exemplo:

{
    "time": Timestamp_in_seconds
}


Nome Tipo Obrigatório Descrição
time Integer Sim Tempo que o disparo será realizado, em segundos no formato timestamp


Exemplo de retorno:

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

                            

Exemplos de código : Disparo de lotes

Tipo 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
}'

Inserir Respostas

Fornecemos também um método de inserção de respostas. Esse método pode ser utilizado com os seguintes parâmetros.
  • O método será:POST
  • A URL a ser usada deve ser: api.tracksale.co/v2/answer
  • O body deve ser preenchido com o lote de respostas usando o seguinte padrão
{
    "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 Tipo Obrigatório Descrição
campaign_code String Sim Chave da campanha alvo. Obtida pelo método Listar campanhas
answers Array Sim Lista de respostas

answers Tipo Obrigatório Descrição
name String Sim Nome do cliente
email String Sim, se o disparo foi realizado por email Email do cliente
phone String Sim, se o disparo foi realizado por telefone Telefone do cliente
score Integer Sim Score do cliente (entre 0 a 10)
justification String Não Comentário do cliente
create_time Integer Não Data/hora da resposta no padrão timestamp (em segundos)
tags Array Não Tags para adicionar informações ao cliente

tags Tipo Obrigatório Descrição
name String Sim Nome da tag
value String Sim Valor da Tag


Exemplo de retorno:

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

    }
}

                            

Exemplos de código : Inserir respostas

Tipo 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 é nosso método para geração de relatórios, é responsável por mostrar detalhes de todas suas campanhas ou de uma campanha.

Toda a comunicação da API é feita a partir da URL base api.tracksale.co/v2/report/DETALHES.

Onde DETALHES deverá ser substituído pelos detalhes que você deseja obter através da requisição

O método a ser usado será o GET

    O header deve ser preenchido com os parametros onde
  • Key Authorization
  • Value bearer TOKEN

Comentários

O método a ser usado deve ser :GET

A URL a ser usada deve ser :api.tracksale.co/v2/report/answer

Método responsável por retornar os comentários dos clientes.


Parâmetros

Parâmetro Tipo Padrão Obrigatório Descrição
start Date Por padrão mostraremos resultados 30 dias anteriores a data que está realizando a requisição
(Ex: se você está fazendo essa requisição no dia 31/01/2017 e não incluir o intervalo inicial e final que você deseja fazer sua pesquisa, o período retornado será de 01/01/2017 a 31/01/2017)
Não Data inicial no formato aaaa-mm-dd
end Date Por padrão mostraremos resultados 30 dias anteriores a data que está realizando a requisição
(Ex: se você está fazendo essa requisição no dia 31/01/2017 e não incluir o intervalo inicial e final que você deseja fazer sua pesquisa, o período retornado será de 01/01/2017 a 31/01/2017)
Não Data final no formato aaaa-mm-dd
limit Integer Por padrão mostrará 10 comentários por requisição. Não Total de comentários a serem retornados. Utilize -1 para retornar todos.
tags Boolean Por padrão é falso, ou seja, nenhuma tag será mostrada. Não Retorna as tags referentes às respostas
justifReturn String Por padrão mostraremos o formato "level" Não

Formato de retorno das justificativas.


"array" -

Retorna todas em um único array.


"level" -

Retorna formato JSON com subníveis de justificativas agrupadas.

codes String Por padrão mostrará os comentários de todas as campanhas Não Usado para mostrar os comentários de uma campanha específica, ou os comentários de todas as campanhas. Pode-se também mostrar os comentários de mais de uma campanha por vez, para isso utilize a vírgula como separador (Ex: codes=52,51,50 mostrará os comentários das campanhas cujo Campaign_code é 50, 51 e 52)


Exemplo 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

O método a ser usado deve ser : GET

A URL a ser usada deve ser:api.tracksale.co/v2/report/dispatch

Método responsável por retornar os disparos e seus dados, como clientes inseridos , a hora que foi realizado, seu status e os clientes que foram inseridos no mesmo.

[
    {
        "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 Tipo Padrão Obrigatório Descrição
start Date Por padrão mostraremos resultados 30 dias anteriores a data que está realizando a requisição
(Ex: se você está fazendo essa requisição no dia 31/01/2017 e não incluir o intervalo inicial e final que você deseja fazer sua pesquisa, o período retornado será de 01/01/2017 a 31/01/2017)
Não Data inicial no formato aaaa-mm-dd
end Date Por padrão mostraremos resultados 30 dias anteriores a data que está realizando a requisição
(Ex: se você está fazendo essa requisição no dia 31/01/2017 e não incluir o intervalo inicial e final que você deseja fazer sua pesquisa, o período retornado será de 01/01/2017 a 31/01/2017)
Não Data final no formato aaaa-mm-dd
codes String Por padrão mostrará os comentários de todas as campanhas Não Usado para mostrar os comentários de uma campanha específica, ou os comentários de todas as campanhas. Pode-se também mostrar os comentários de mais de uma campanha por vez, para isso utilize a vírgula como separador. (Ex: codes=52,51,50 mostrará os comentários das campanhas cujo Campaign_code é 50, 51 e 52)


NPS

O método a ser usado deve ser : GET

A URL a ser usada deve ser:api.tracksale.co/v2/report/nps

Método responsável por retornar o numero de disparos, os numeros de detratores, promotores e neutros e suas respectivas porcentagens e também o valor do nps.

Parâmetros

Parâmetro Tipo Padrão Obrigatório Descrição
start Date Por padrão mostraremos resultados 30 dias anteriores a data que está realizando a requisição
(Ex: se você está fazendo essa requisição no dia 31/01/2017 e não incluir o intervalo inicial e final que você deseja fazer sua pesquisa, o período retornado será de 01/01/2017 a 31/01/2017)
Não Data inicial no formato aaaa-mm-dd
end Date Por padrão mostraremos resultados 30 dias anteriores a data que está realizando a requisição
(Ex: se você está fazendo essa requisição no dia 31/01/2017 e não incluir o intervalo inicial e final que você deseja fazer sua pesquisa, o período retornado será de 01/01/2017 a 31/01/2017)
Não Data final no formato aaaa-mm-dd
compare Boolean Por padráo é false Não Retorna os dados do NPS referente ao período anterior do filtro de data.
codes String Por padrão mostrará os comentários de todas as campanhas Não Usado para mostrar os comentários de uma campanha específica, ou os comentários de todas as campanhas. Pode-se também mostrar os comentários de mais de uma campanha por vez, para isso utilize a vírgula como separador (Ex: codes=52,51,50 mostrará os comentários das campanhas cujo Campaign_code é 50, 51 e 52)


Exemplo 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,
    }
}

                            

Categorias

O método a ser usado deve ser :GET

A URL a ser usada deve ser: api.tracksale.co/v2/report/category

Método responsável por retornar as categorias das campanhas de acordo com o NPS.

Parâmetros

Parâmetro Tipo Padrão Obrigatório Descrição
start Date Por padrão mostraremos resultados 30 dias anteriores a data que está realizando a requisição
(Ex: se você está fazendo essa requisição no dia 31/01/2017 e não incluir o intervalo inicial e final que você deseja fazer sua pesquisa, o período retornado será de 01/01/2017 a 31/01/2017)
Não Data inicial no formato aaaa-mm-dd
end Date Por padrão mostraremos resultados 30 dias anteriores a data que está realizando a requisição
(Ex: se você está fazendo essa requisição no dia 31/01/2017 e não incluir o intervalo inicial e final que você deseja fazer sua pesquisa, o período retornado será de 01/01/2017 a 31/01/2017)
Não Data final no formato aaaa-mm-dd
codes String Por padrão mostrará os comentários de todas as campanhas Não Usado para mostrar os comentários de uma campanha específica, ou os comentários de todas as campanhas. Pode-se também mostrar os comentários de mais de uma campanha por vez, para isso utilize a vírgula como separador. (Ex: codes=52,51,50 mostrará os comentários das campanhas cujo Campaign_code é 50, 51 e 52)


Exemplo de retorno:

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

    }
]

                            

Obter status das campanhas

O método a ser usado deve ser :GET

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

Método responsável por retornar os status das campanhas.



Parâmetros

Parâmetro Tipo Padrão Obrigatório Descrição
start Date Por padrão mostraremos resultados 30 dias anteriores a data que está realizando a requisição
(Ex: se você está fazendo essa requisição no dia 31/01/2017 e não incluir o intervalo inicial e final que você deseja fazer sua pesquisa, o período retornado será de 01/01/2017 a 31/01/2017)
Não Data inicial no formato aaaa-mm-dd
end Date Por padrão mostraremos resultados 30 dias anteriores a data que está realizando a requisição
(Ex: se você está fazendo essa requisição no dia 31/01/2017 e não incluir o intervalo inicial e final que você deseja fazer sua pesquisa, o período retornado será de 01/01/2017 a 31/01/2017)
Não Data final no formato aaaa-mm-dd
codes String Por padrão mostrará os comentários de todas as campanhas Não Usado para mostrar os comentários de uma campanha específica, ou os comentários de todas as campanhas. Pode-se também mostrar os comentários de mais de uma campanha por vez, para isso utilize a vírgula como separador. (Ex: codes=52,51,50 mostrará os comentários das campanhas cujo Campaign_code é 50, 51 e 52)


Exemplo de retorno:

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

                            

Exemplos de código : Reports /DETALHES

Tipo 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'