Envio de dados de Pessoas

O envio é realizado a partir de um CSV ou JSON. O arquivo deve conter no máximo 1GB de tamanho, caso ultrapasse o limite o arquivo deve ser divido em partes contendo 1GB cada.

Os campos a serem enviados devem seguir o padrão PascalCase nas duas estrutura (CSV e JSON).

Requisição

Deve incluir em seu cabeçalho, a chave de acesso e o tipo de conteúdo que será enviado, que pode ser application/json para arquivos no formato .json e application/csv para arquivos no formato .csv.

O envio do arquivo deve ser realizado através de streaming. Se estiver utilizando um programa para fazer a requisição (Insomnia/Postman), é recomendado utilizar o formato Binary no corpo da requisição para o envio do arquivo.

Exemplo de solicitação utilizando cURL:

curl --request POST \
  --url 'https://{base_url}/DataInserterProfiles/api/profile' \
  --header 'Content-Type: application/json' \
  --header 'apiKey: {apiKey}' \

curl --request POST \
  --url 'https://{base_url}/DataInserterProfiles/api/profile' \
  --header 'Content-Type: application/csv' \
  --header 'apiKey: {apiKey}' \

🚧
Requisições realizadas pela documentação não irão retornar sucesso, pois a plataforma não suporta o formato Streaming

Query parameters

Campo	Tipo	Descrição	Obrigatório
FirstName	String	Primeiro nome da pessoa	Sim*
LastName	String	Sobrenome da pessoa	Sim*
CPF	String	CPF da pessoa	Sim*
Email	String	Email da pessoa	Sim*
Phone	String	Telefone celular da pessoa	Sim*
ExternalId	String	Algum identificador da pessoa usado internamente (Ex: id no banco de dados)	Não
FacebookId	String	Facebook id da pessoa	Não
AccessToken	String	-	Não
Token	String	Identificador único do Web Push associado a um PushProfile (para clientes que usam web push)	Não
SmartLinkId	String	-	Não
CookieId	String	Identificador único do Cookie do Btg, que guarda informações de acesso da sessão do usuario	Não
CustomAttributes	Map<String, CustomAttributes>	Atributos customizáveis que deseja enviar sobre as pessoas	Não

Valores obrigatórios da API

Antes de iniciar o uso da API, solicite ao seu account a configuração dos campos chaves da mesma. Hoje, você pode escolher entre três campos chave:

Email
CPF
Phone

Os campos chave são usados para atribuir os eventos a mesma pessoa, ou seja, se você usa o email como chave, todo evento que tiver o email da mesma pessoa será atribuído àquela mesma pessoa.

Você tem várias opções de configuração. Você pode escolher apenas um dos campos como chave, ou escolher os 3 campos como chave e definir uma ordem de prioridade. Por exemplo, você pode definir que o email é seu campo chave principal e cpf é um campo chave com segunda prioridade. Imagine o cenário que recebemos um dado com o email "igor@gmail.com” e cpf '11123208424”, primeiro o sistema vai buscar por uma pessoa com email “igor@gmail.com”, caso não encontre, vai realizar a mesma busca mas agora usando o cpf.

Caso você não configure as chaves, iremos usar o padrão que faz a união das pessoas por Email OU cpf OU phone e consequentemente você precisa enviar um desses campos como obrigatório.

Exemplo do arquivo na configuração padrão

Exemplo com os 3 campos enviados (email, cpf e phone)

[
  {
    "FirstName": "Melissa",
    "LastName": "Araújo",
    "CPF": "24631414090",
    "Email": "melissaaraujo@example.com.br",
    "Phone": "8529741289",
    "ExternalId": "External123",
    "FacebookId": "Facebook123",
    "AccessToken": "AccessToken123",
    "Token": "Token123",
    "SmartLinkId": "Smartlink123",
    "CookieId": "Cookie123",  
  }
]

FirstName;LastName;CPF;Email;Phone;ExternalId;FacebookId;AccessToken;Token;SmartLinkId;CookieId;CorFavorita:String;TemCachorro:Boolean;Altura:Float;TamanhoSapato:Integer;Aniversario:Datetime
Melissa;Araújo;24631414090;melissaaraujo;8529741289;External123;Facebook123;AccessToken123;Token123;Smartlink123;Cookie123;Vermelho;false;2.0;30;2023-11-26T14:35:44.433Z

Exemplo com apenas 1 dos campos enviado (CPF)

[
  {
    "FirstName": "Melissa",
    "LastName": "Araújo",
    "CPF": "24631414090",
    "ExternalId": "External123",
    "FacebookId": "Facebook123",
    "AccessToken": "AccessToken123",
    "Token": "Token123",
    "SmartLinkId": "Smartlink123",
    "CookieId": "Cookie123",  
  }
]

FirstName;LastName;CPF;Email;Phone;ExternalId;FacebookId;AccessToken;Token;SmartLinkId;CookieId;CorFavorita:String;TemCachorro:Boolean;Altura:Float;TamanhoSapato:Integer;Aniversario:Datetime
Melissa;Araújo;24631414090;melissaaraujo;8529741289;External123;Facebook123;AccessToken123;Token123;Smartlink123;Cookie123;Vermelho;false;2.0;30;2023-11-26T14:35:44.433Z

Caso você configure as chaves, a sua chave será obrigatório no envio dos dados. Logo, se o email é sua chave com maior prioridade, ele se torna obrigatório no envio do dado.

Você também deve enviar o FirstName OU LastName. Não é obrigatório o envio dos dois

CustomAttributes

Type  : String
Value : Object

Ao enviar CustomAttributes, é importante incluir o nome, tipo e valor do atributo. Você tem a flexibilidade de escolher qualquer nome para o atributo, mas o tipo deve ser selecionado a partir das opções: String, Integer, Float, Boolean ou Datetime. Certifique-se de que o valor fornecido esteja em conformidade com a tipo especificada no campo Type. Para o CSV o cabeçalho segue a estrutura: [NomeDoAtributo]:[TipoDoAtributo]

💡
Atributo do tipo Float deve conter uma casa decimal, para que seja identificado como um valor flutuante. A casa decimal é representada pelo ponto e não por vírgula

💡
Atributo do tipo DateTime deve estar no yyyy-MM-dd

Exemplo de envio com custom Attributes

[
  {
    "FirstName": "Melissa",
    "LastName": "Araújo",
    "CPF": "24631414090",
    "Email": "melissaaraujo@example.com.br",
    "Phone": "8529741289",
    "ExternalId": "External123",
    "FacebookId": "Facebook123",
    "AccessToken": "AccessToken123",
    "Token": "Token123",
    "SmartLinkId": "Smartlink123",
    "CookieId": "Cookie123",
    "customAttributes": {
      "CorFavorita": {
        "Type": "string",
        "Value": "Vermelho"
      },
      "TemCachorro": {
        "Type": "boolean",
        "Value": false
      },
      "Altura": {
        "Type": "float",
        "Value": 2.0
      },
      "TamanhoSapato": {
        "Type": "integer",
        "Value": 30
      },
      "Aniversario": {
        "Type": "datetime",
        "Value": "2023-11-26"
      }
    }
  }
]

FirstName;LastName;CPF;Email;Phone;ExternalId;FacebookId;AccessToken;Token;SmartLinkId;CookieId;CorFavorita:String;TemCachorro:Boolean;Altura:Float;TamanhoSapato:Integer;Aniversario:Datetime
Melissa;Araújo;24631414090;melissaaraujo;8529741289;External123;Facebook123;AccessToken123;Token123;Smartlink123;Cookie123;Vermelho;false;2.0;30;2023-11-26

Requisição

Retorno da requisição

Após o envio do arquivo ser realizado com sucesso a API ira retornar no response o fileId que pode ser utilizado para acompanhar o estado de processamento do arquivo.

Exemplos do retorno

{
	"success": true,
	"response": {
		"status": true,
		"message": "Arquivo salvo como: Profile-79bb7d1a-55b2-4d37-a128-8cbf052679a8.json, Id do arquivo: 79bb7d1a-55b2-4d37-a128-8cbf052679a8",
		"nameFile": "Profile-79bb7d1a-55b2-4d37-a128-8cbf052679a8.json",
		"path": "customerId=c4feffd5-5f05-45f8-acde-c6604766ff3e/fileId=79bb7d1a-55b2-4d37-a128-8cbf052679a8/Profile-79bb7d1a-55b2-4d37-a128-8cbf052679a8.json",
		"fileId": "79bb7d1a-55b2-4d37-a128-8cbf052679a8"
	}
}

Boas práticas de uso

É muito importante a configuração das chaves da API
Os campos obrigatórios devem ser preenchidos. Não enviar os campos chaves com valores como “None” ou “Desconhecido” ou “null”
É comum que para cenários de loja física os vendedores preencham alguns campos com valores aleatórios, caso o cliente não queria informar, como “Phone”: “9999999999” ou “CPF”:”12312312312”, ou “email”:”loja@gmail.com”. É importante evitar enviar os dados desse jeito
É importante que os customAttributes sejam sempre enviados com mesmo nome (eles são case sensitive, ou seja se enviar “idade”:10 e depois “IDADE”:10, serão criados dois campos distintos)
Não enviar valores com indicador de moeda, mandar só os números (Ex: Não enviar R$10 e sim 10). Assim, conseguirá filtrar o dado como número em audiências

Exemplos dos arquivos CSV e JSON

[
  {
    "FirstName": "Melissa",
    "LastName": "Araújo",
    "CPF": "24631414090",
    "Email": "melissaaraujo@example.com.br",
    "Phone": "8529741289",
    "ExternalId": "External123",
    "FacebookId": "Facebook123",
    "AccessToken": "AccessToken123",
    "Token": "Token123",
    "SmartLinkId": "Smartlink123",
    "CookieId": "Cookie123",
    "customAttributes": {
      "CorFavorita": {
        "Type": "string",
        "Value": "Vermelho"
      },
      "TemCachorro": {
        "Type": "boolean",
        "Value": false
      },
      "Altura": {
        "Type": "float",
        "Value": 2.0
      },
      "TamanhoSapato": {
        "Type": "integer",
        "Value": 30
      },
      "Aniversario": {
        "Type": "datetime",
        "Value": "2023-11-26"
      }
    }
  }
]

FirstName;LastName;CPF;Email;Phone;ExternalId;FacebookId;AccessToken;Token;SmartLinkId;CookieId;CorFavorita:String;TemCachorro:Boolean;Altura:Float;TamanhoSapato:Integer;Aniversario:Datetime
Melissa;Araújo;24631414090;melissaaraujo;8529741289;External123;Facebook123;AccessToken123;Token123;Smartlink123;Cookie123;Vermelho;false;2.0;30;2023-11-26