Endpoint: https://api.login.fxdata.com.br/api/authenticate
Método: POST
{
"username": "name_user",
"password": "senha"
}
curl -X POST \
https://api.login.fxdata.com.br/api/authenticate \
-H 'content-type: application/json' \
-d '{
"username": "USER",
"password": "SENHA"
}'
{
"success": true,
"token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ2ZXJzaW9uIjoyLCJsZWdhY3lUb2tlbiI6IkZYYjAxYzViYzE2MjBmMWQwZGU5NDQyODVkNTQ2ODBlNTM5ODYyN2IxMmYwMjM1YWRmYTQ1YzNlYTgzOWUxYzIzMyIsImNsaWVudElkIjoiTDM2OE4xMiIsImlzQWRtaW4iOmZhbHNlLCJwcm9maWxlSWQiOm51bGx9.",
"user": {
"admin": false,
"clients": [
{
"analyst": false,
"id": "ID cliente do tipo string",
"kind": "store",
"logo": "url_logo",
"manager": false,
"master": true,
"name": "Fake Cliente"
}
],
"company": {
"analyst": false,
"id": "ID cliente do tipo string",
"kind": "store",
"logo": "url_logo",
"manager": false,
"master": true,
"name": "Fake Company"
},
"email": "Fake.Fake@fake.com".br,
"id": null,
"legacyToken": "FXb01c5bc1620f1d0de944285d54680e5398627b12f0235adfa45c3ea8",
"name": "Fake Name",
"username": "Fake.Fake"
}
}
Endpoint: https://api.login.fxdata.com.br/api/establishments
Método: GET
Header: Authorization: Token recebido ao solicitar a autenticação Autenticação , este token deve ser passado no Request Header em todas as requisições, caso contrário receberá a resposta abaixo.Token recebido ao solicitar a autenticação Autenticação , este token deve ser passado no Request Header em todas as requisições, caso contrário receberá a resposta abaixo.
curl -X GET \
https://api.login.fxdata.com.br/api/establishments \
-H 'authorization: Token eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJsZWdhY3lDbGllbnRJZCI6MzQ0LCJjbGllbnRJZCI6bnVsbCwidG9rZW4iOiJGWDYyM2M1YmY5NjBhNDNjMjU4MjQ5ZGVkOWU0OTc1N2U2YTVhMDdkZTkwMTczOTE2NTc3MDcwNzJhMGUyZGUyZTYifQ.wlu8-flZPQJQIsk5TwvMpqpS0tb-iYu7ATXbuB'
{
"establishments": [
{
"brand": "ID Marca",
"brandName": "Nome da Marca",
"city": "São Paulo",
"company": "ID cliente do tipo string",
"companyName": "Nome do Cliente",
"establishment": "ID estabelecimento do tipo string",
"establishmentName": "Nome do Estabelecimento",
"externalNumber": "Identificação externa do tipo String",
"hasVitrine": false,
"kind": null,
"state": 25,
"stateName": "São Paulo"
},
],
"success": true
}
→ conversion: caso o estabelecimento tenha integração de cupom com a FX, este campo irá trazer a conversão entre a quantidade de cupons versus entrantes na estabelecimento.
→ entrace_flow: esta métrica retorna os dados dos entrantes no estabelecimento.
→ vitrine_flow: esta métrica retorna os dados dos passantes em frente ao estabelecimento.
→ company: é o ID do cliente cadastrado na base FX. O ID recebido da key: company ao consultar o estabelecimento Autenticação deve ser utilizado aqui.
→ filter: são os ID’s retornados ao consultar o estabelecimento Autenticação da key: establishments. Esses ID’s correspondem a cada estabelecimento cadastrado e ativo na base FX, e devem ser utilizados aqui.
→ purchase: esta métrica retorna os cupons (venda realizada no dia) enviados para a FX.
→ attractiveness: esta métrica retorna o percentual sobre o cálculo realizado entre: Vitrine_Flow / Entrace_Flow. Este indicador diz respeito aos entrantes versus os passantes em frente ao estabelecimento.
→ permanence: esta métrica retorna qual foi o tempo médio que os clientes ficaram dentro do estabelecimento (devices com Wi-Fi habilitado). É retornado o número inteiro que corresponde aos minutos (60 = 1 hora | 120 = 2 horas).
→ unique_visitor: esta métrica retorna o número total de Mac Addresses (devices com Wi-Fi habilitado) dos entrantes no estabelecimento.
→ frequency: esta métrica retorna quantas vezes o mesmo Mac Address (device com Wi-Fi habilitado) voltou ao estabelecimento.
→ by_establishment: caso seja passado o parâmetro true serão retornados os seguintes dados do estabelecimento:
→ by_device: caso seja passado o parâmetro true serão retornados os dados do device:
→ period: é o período de consulta de dados, sendo a data e hora inicial em: FROM e data e hora final em: TO - formato aceito YYYY-MM-DD H:M:S.
→ granularity: ao consultar determinado período, é possível definir como deseja que ele seja retornado. Este campo suporta: Hour, Day, Week, Month e Year.
→ externalNumber: A função especial deste campo é possibilitar o cliente informar qual é o identificador que ele deseja passar para seu(s) estabelecimento(s), facilitando depois sua identificação ao consumir os dados da API da FX. Por padrão será retornado o CNPJ do estabelecimento, mas caso queira alterar para outro identificador, faça sua solicitação em: dev@fxdata.com.br (assunto: External Number e no corpo do e-mail não se esqueça de se identificar e dizer de qual cliente você pertence). Este campo é retornado nos endpoints:
Endpoint: https://api.login.fxdata.com.br/api/data
Método: POST
Authorization: Token recebido ao solicitar a autenticação, este token deve ser passado no Request Header em todas as requisições, caso contrário receberá a resposta abaixo:
{
"message": "Unauthorized",
"success": false
}
{
"company": "ID cliente do tipo string",
"filter": [
"ID(s) estabelecimento(s) do tipo string"
],
"queries": [
{
"alias": "entrace_flow",
"metric": "entrace_flow",
"by_establishment": true,
"by_device": false,
"period": {
"from": "2018-06-09 00:00:00",
"to": "2018-06-09 23:59:59"
},
"granularity": "day"
}
]
}
{
"data": {
"entrace_flow": {
"data": [
{
"city": "São Paulo",
"companyName": "Nome Cliente",
"data": [
{
"key": "2018-06-09T00:00:00",
"value": 200
}
],
"establishmentName": "Nome do Estabelecimento",
"externalNumber": "Identificação externa do tipo String",
"id": "ID estabelecimento do tipo string",
"isMall": false,
"stateName": "São Paulo"
}
],
"metric": "entrace_flow",
"period": {
"from": "2018-06-09T00:00:00",
"to": "2018-06-09T23:59:59"
}
}
},
"success": true
}
{
"company": "ID cliente do tipo string",
"filter": [
"ID(s) estabelecimento(s) do tipo string"
],
"queries": [
{
"alias": "vitrine_flow",
"metric": "vitrine_flow",
"by_establishment": true,
"by_device": false,
"period": {
"from": "2018-06-09 00:00:00",
"to": "2018-06-09 23:59:59"
},
"granularity": "day"
}
]
}
{
"data": {
"entrace_flow": {
"data": [
{
"city": "São Paulo",
"companyName": "Nome Cliente",
"data": [
{
"key": "2018-06-09T00:00:00",
"value": 200
}
],
"establishmentName": "Nome do Estabelecimento",
"externalNumber": "Identificação externa do tipo String",
"id": "ID estabelecimento do tipo string",
"isMall": false,
"stateName": "São Paulo"
}
],
"metric": "entrace_flow",
"period": {
"from": "2018-06-09T00:00:00",
"to": "2018-06-09T23:59:59"
}
}
},
"success": true
}
{
"company": "ID cliente do tipo string",
"filter": [
"ID(s) estabelecimento(s) do tipo string"
],
"queries": [
{
"alias": "attractiveness",
"metric": "attractiveness",
"by_establishment": true,
"by_device": false,
"period": {
"from": "2018-06-09 00:00:00",
"to": "2018-06-09 23:59:59"
},
"granularity": "day"
}
]
}
{
"data": {
"vitrine_flow": {
"data": [
{
"city": "São Paulo",
"companyName": "Nome Cliente",
"data": [
{
"key": "2018-06-09T00:00:00",
"value": 3016
}
],
"establishmentName": "Nome do Estabelecimento",
"externalNumber": "Identificação externa do tipo String",
"id": "ID estabelecimento do tipo string",
"isMall": false,
"stateName": "São Paulo"
}
],
"metric": "vitrine_flow",
"period": {
"from": "2018-06-09T00:00:00",
"to": "2018-06-09T23:59:59"
}
}
},
"success": true
}
{
"company": "ID cliente do tipo string",
"filter": [
"ID(s) estabelecimento(s) do tipo string"
],
"queries": [
{
"alias": "conversion",
"metric": "conversion",
"by_establishment": true,
"by_device": false,
"period": {
"from": "2018-06-09 00:00:00",
"to": "2018-06-09 23:59:59"
},
"granularity": "day"
}
]
}
{
"data": {
"conversion": {
"data": [
{
"city": "São Paulo",
"companyName": "Nome Cliente",
"data": [
{
"calendar": {
"week": 22,
"weekday": 6
},
"key": "2018-06-09T00:00:00",
"value": 0.145
}
],
"establishmentName": "Nome do Estabelecimento",
"externalNumber": "Identificação externa do tipo String",
"id": "ID estabelecimento do tipo string",
"isMall": false,
"stateName": "São Paulo"
}
],
"metric": "conversion",
"period": {
"from": "2018-06-09T00:00:00",
"to": "2018-06-09T23:59:59"
}
}
},
"success": true
}
{
"company": ID cliente do tipo string,
"filter": [
"ID(s) estabelecimento(s) do tipo string"
],
"queries": [
{
"alias": "purchase",
"metric": "purchase",
"by_establishment": true,
"by_device": false,
"period": {
"from": "2018-06-09 00:00:00",
"to": "2018-06-09 23:59:59"
},
"granularity": "day"
}
]
}
{
"data": {
"purchase": {
"data": [
{
"city": "São Paulo",
"companyName": "Nome Cliente",
"data": [
{
"calendar": {
"week": 22,
"weekday": 6
},
"key": "2018-06-09T00:00:00",
"value": 29
}
],
"establishmentName": "Nome do Estabelecimento",
"externalNumber": "Identificação externa do tipo String",
"id": "ID estabelecimento do tipo string",
"isMall": false,
"stateName": "São Paulo"
}
],
"metric": "purchase",
"period": {
"from": "2018-06-09T00:00:00",
"to": "2018-06-09T23:59:59"
}
}
},
"success": true
}
{
"company": "ID cliente do tipo string",
"filter": [
"ID(s) estabelecimento(s) do tipo string"
],
"queries": [
{
"alias": "unique_visitor",
"metric": "unique_visitor",
"by_establishment": true,
"by_device": false,
"period": {
"from": "2018-06-09 00:00:00",
"to": "2018-06-09 23:59:59"
},
"granularity": "day"
}
]
}
{
"data": {
"unique_visitor": {
"data": [
{
"city": "São Paulo",
"companyName": "Nome Empresa",
"data": [
{
"calendar": {
"week": 22,
"weekday": 6
},
"key": "2018-06-09T00:00:00",
"value": 160
}
],
"establishmentName": "Nome do Estabelecimento",
"externalNumber": "Identificação externa do tipo String",
"id": "ID estabelecimento do tipo string",
"isMall": false,
"stateName": "São Paulo"
}
],
"metric": "unique_visitor",
"period": {
"from": "2018-06-09T00:00:00",
"to": "2018-06-09T23:59:59"
}
}
},
"success": true
}
{
"company": "ID cliente do tipo string",
"filter": [
"ID(s) estabelecimento(s) do tipo string"
],
"queries": [
{
"alias": "permanence",
"metric": "permanence",
"by_establishment": true,
"period": {
"from": "2018-06-09 00:00:00",
"to": "2018-06-09 23:59:59"
},
"granularity": "day"
}
]
}
{
"data": {
"permanence": {
"data": [
{
"city": "São Paulo",
"companyName": "Nome Cliente",
"data": [
{
"calendar": {
"week": 22,
"weekday": 6
},
"key": "2018-06-09T00:00:00",
"value": 26
}
],
"establishmentName": "Nome do Estabelecimento",
"externalNumber": "Identificação externa do tipo String",
"id": "ID estabelecimento do tipo string",
"isMall": false,
"stateName": "São Paulo"
}
],
"metric": "permanence",
"period": {
"from": "2018-06-09T00:00:00",
"to": "2018-06-09T23:59:59"
}
}
},
"success": true
}
Granularidade aceitável nesse indicador é: Week, Month e Year.
{
"company": "ID cliente do tipo string",
"filter": [
"ID(s) estabelecimento(s) do tipo string"
],
"queries": [
{
"alias": "frequency",
"metric": "frequency",
"by_establishment": true,
"by_device": false,
"period": {
"from": "2018-06-09 00:00:00",
"to": "2018-06-09 23:59:59"
},
"granularity": "week"
}
]
}
{
"data": {
"frequency": {
"data": [
{
"city": "São Paulo",
"companyName": "Nome Cliente",
"data": [
{
"calendar": {
"week": 22,
"weekday": 6
},
"key": "2018-06-09T00:00:00",
"value": []
}
],
"establishmentName": "Nome do Estabelecimento",
"externalNumber": "Identificação externa do tipo String",
"id": "ID estabelecimento do tipo string",
"isMall": false,
"stateName": "São Paulo"
}
],
"metric": "frequency",
"period": {
"from": "2018-06-09T00:00:00",
"to": "2018-06-09T23:59:59"
}
}
},
"success": true
}
→ usuário: é o mesmo login utilizado para fazer a autenticação , tanto em nosso Dashboard, quanto na API.
→ senha: é a mesma senha utilizada para fazer a autenticação , tanto em nosso Dashboard, quanto na API.
→ cnpj: corresponde ao CNPJ do estabelecimento no qual deseja inserir os dados de cupom. Caso seja informado um CNPJ não cadastrado em nossa base ou um CNPJ sem permissão pelo seu usuário, retornará uma mensagem de erro. O CNPJ precisa ser informado sem máscara, apenas com números. Exemplo: 88888888888888.
→ CupomRequests: aqui deve ser informado a lista de cupons contendo as informações abaixo:
♦ datahora: há duas opções de informar a data e hora nesse campo:
Por hora: caso queira visualizar a conversão no Dashboard e na API por hora, dia, semana, mês e ano, informe nesta formatação: yyyy-MM-DD H:M (2018-06-14 10:00).
Por dia: caso queira visualizar a conversão no Dashboard e na API apenas por dia, semana, mês e ano, informe nesta formatação: yyyy-MM-DD H:M (2018-06-14 00:00). Informando apenas o dia e mantendo zerados “Hora” e "Minuto”
♦ valor: corresponde ao valor da venda. Caso não queira informar qual foi o valor da venda, basta informar o valor como: 0.0.
♦ quantidade: corresponde ao total de cupons, ou seja, a quantidade de vendas realizadas no estabelecimento. Este dado é utilizado para gerar o indicador de conversão no Dashboard e API.
{
"usuario": "USER",
"senha": "SENHA",
"cnpj": "CNPJ",
"CupomRequests": [
{
"datahora": "2018-06-05 10:00",
"valor": 0.0,
"quantidade": 4
},
{
"datahora": "2018-06-05 11:00",
"valor": 0.0,
"quantidade": 4
},
{
"datahora": "2018-06-05 12:00",
"valor": 0.0,
"quantidade": 8
},
{
"datahora": "2018-06-05 13:00",
"valor": 0.0,
"quantidade": 10
}
]
}
{
"usuario": "USER",
"senha": "SENHA",
"cnpj": "CNPJ",
"CupomRequests": [
{
"datahora": "2018-06-05 00:00",
"valor": 0.0,
"quantidade": 4
},
{
"datahora": "2018-06-06 00:00",
"valor": 0.0,
"quantidade": 4
},
{
"datahora": "2018-06-07 00:00",
"valor": 0.0,
"quantidade": 8
},
{
"datahora": "2018-06-08 00:00",
"valor": 0.0,
"quantidade": 10
}
]
}
{
"sucesso": "True",
"mensagem": "Inserido com sucesso!"
}
Obs: Após os dados serem inseridos, a consolidação leva cerca de 5 a 10 minutos (dependendo do tráfego de dados recebidos pela API) para ficar disponível no Dashboard e na própria API.
Obs 2: Os dados de cupom inseridos ficarão disponíveis no indicador “conversão” do dashboard, somente se houver dados de entrantes (fluxo), pois o cálculo depende dos entrantes - conforme explicado no item 2, indicador: conversion.
Obs 3: Caso seja enviado os cupons novamente para o mesmo dia ou hora, a API vai considerar o último dado enviado, e será considerado ele na inserção em nosso banco de dados.
Exemplo Dia:
{
"datahora": "2018-06-07 00:00",
"valor": 0.0,
"quantidade": 10
},
{
"datahora": "2018-06-07 00:00",
"valor": 0.0,
"quantidade": 25
}
Repare que no JSON acima, o dia 07/06 repetiu duas vezes com quantidade diferente, neste caso a API irá considerar o último que entrou na fila de processamento, que pode ter sido o de quantidade 10 ou de quantidade 25. Em hipótese nenhuma será somado esses valores ou duplica-los.
Exemplo Hora:
{
"datahora": "2018-06-07 10:00",
"valor": 0.0,
"quantidade": 10
},
{
"datahora": "2018-06-07 10:00",
"valor": 0.0,
"quantidade": 25
}
Repare que no JSON acima, o dia 07/06 repetiu duas vezes com quantidade diferente para o mesmo horário. Neste caso a API irá considerar o último horário que entrou na fila de processamento, que pode ter sido o de quantidade 10 ou de quantidade 25. Em hipótese nenhuma será somado esses valores ou duplica-los.