Este artigo descreve os passos necessários para um sistema externo enviar um registro de indicação para o SnapProperty.

Regras de negócio

Indicação de cliente

O registro para indicação de um cliente é dividido em três partes:

Indicador (pessoa que indica o cliente)
Indicado (cliente indicado)
Detalhes (detalhes da indicação)

Indicador

Campo	Tipo	Obrigatório	Observação
Nome	String	Sim	Primeiro nome do indicador. Ex.: João
Sobrenome	String	Sim	Sobrenome do indicador. Ex.: Souza
Email	String	Sim	Endereço de email do indicador. Ex.: joao.souza@gmail.com. O sistema valida o endereço de email.
Celular	String	Sim	Telefone celular do indicador. Ex.: +55(11) 99422-3020
CPF	String	Sim	CPF do indicador. Ex.: 150.117.518-17

Indicado

Campo	Tipo	Obrigatório	Observação
Nome	String	Sim	Primeiro nome do indicado. Ex.: Maria
Sobrenome	String	Sim	Sobrenome do indicado. Ex.: Menezes
Email	String	Sim	Endereço de email do indicado. Ex.: maria.menezes@gmail.com. O sistema valida o endereço de email.
Celular	String	Sim	Telefone celular do indicado. Ex.: +55(11) 99425-8320
CPF	String	Não	CPF do indicado. Ex.: 170.187.518-17

Detalhes

Campo	Tipo	Obrigatório	Observação
Tipo de negócio	String	Sim	Indica o tipo de negócio para o qual o cliente foi indicado. As opções são: Locação ou Captação.
Origem	String	Sim	Indica o parceiro que originou a indicação. As opções são: Buzzlead.
Campanha	String	Não	Código para identificação da campanha que originou a indicação, informado pelo administrador da organização.

Nota sobre campanha

A indicação pode ser associada a uma campanha de marketing. Os usuários da organização que precisam acessar o módulo "Campanhas" devem ter uma licença do "Sales Cloud".

Fluxo para integração

API para integração

O SnapProperty disponibiliza uma API para receber indicações de clientes de sistemas externos.

Requisitos para integração

Para realizar a integração de um sistema externo, o administrador da organização deve concluir as seguintes atividades:

Criar uma "Aplicação conectada" para o sistema externo que pretende enviar indicações.
Criar um usuário para autenticar o sistema externo.

Token de acesso

Antes de enviar uma requisição de cadastro para uma nova indicação, o sistema externo deve solicitar um token de acesso.

Para mais informações, consulte o link abaixo:

https://developer.salesforce.com/docs/atlas.en-us.218.0.api_rest.meta/api_rest/intro_understanding_username_password_oauth_flow.htm

Requisição

Para enviar uma indicação, o sistema externo deve receber um token de segurança que é utilizado para autenticar as requisições para a API do SnapProperty.

Parâmetro	Tipo	Descrição
Endpoint	String	Endereço para enviar uma requisição para token de acesso. Utilizar sempre https://login.salesforce.com/services/oauth2/token/
Verbo	String	Utilizar sempre POST
grant_type	String	Identifica o tipo de requisição. Deve utilizar sempre "password".
client_id	String	Código para identificação da aplicação no Salesforce, informado pelo administrador da organização.
client_secret	String	Chave secreta da aplicação, informado pelo administrador da organização.
username	String	Nome do usuário para autenticação, cadastrado pelo administradora da organização.
password	String	Senha utilizada pelo usuário para autenticação concatenada com a chave de segurança enviada por email pelo Salesforce.

Retorno de uma requisição bem sucedida

Parâmetro	Tipo	Descrição
access_token	String	Chave de acesso para as demais requisições para a API.
instance_url	String	Este valor será utilizado nas demais requisições para a API.
id	String
token_type	String
issued_at	String
signature	String

Exemplo de requisição com sucesso

	Exemplo
Requisição	https://login.salesforce.com/services/oauth2/token ?grand_type=password &client_id=3MVG9QDx8IX8nP5SIyDa4YCKZ5fWQe4zJBToiPFMmU94sSExkYBBr3gNZnzXXUS316 &client_secret=065345560BF35CD3F101EAB2B9F1838B402D4903 &username=sistema@dominio.com.br &password=senha23409284203942
Retorno	{ "access_token": "00DU0000000KkSx!ARQAQCV4Ss4lCPejtaWcCz3W.26oOVeAbvxaAU4BndfDvDk5CoRKSWUubdF7XjNulocbDRlPU81DjNT0.kiFhIr.Kbz", "instance_url": "https://snap-broker-dev-ed.my.salesforce.com", "id": "https://login.salesforce.com/id/00DU0000000KkSxMAK/005U0000000NVceIAG", "token_type": "Bearer", "issued_at": "1556731033567", "signature": "15dl4dW8LSkp+r1FHbj/Y/3mD/AiRrKB0HNee4IGa+A=" }

Cadastrar uma nova indicação

Requisição

Para cadastrar uma nova indicação, o sistema externo deve enviar uma requisição para a API do SnapProperty, com os seguintes parâmetros:

Parâmetro

Tipo

Obrigatório

Descrição

endpoint

String

O endereço da requisição é formado por duas partes concatenadas: "URL da instância" + "Nome do recurso".

A "URL da instância" é o valor retornado no parâmetro "instance_url" da requisição para o token de acesso.

O "Nome do recurso" é "/services/apexrest/snap_brok/indicacao/v1"

Exemplo: https://snap-broker-dev-ed.my.salesforce.com /services/apexrest/snap_brok/indicacao/v1

verbo

POST

indicacao

Indicacao

Sim

Estrutura de dados com a representação da indicacao

Indicacao

Parâmetro	Tipo	Obrigatório	Descrição
tipo	String	Sim	Identifica o tipo de indicação. As opções são: Locação ou Captação.
origem	String	Sim	Identifica a origem da indicação. As opções são: Buzzlead
campanha	String	Não	ID da campanha cadastrada no Salesforce. Ex.: 7014P000001m432QAA
divulgador	String	Não	E-mail do divulgador da indicação.
indicador	Pessoa	Sim	Identifica a pessoa que indicou o cliente.
indicado	Pessoa	Sim	Identifica o cliente que foi indicado.

Pessoa

Parâmetro	Tipo	Descrição
nome	String	Primeiro nome da pessoa. Ex.: Roberto
sobrenome	String	Sobrenome da pessoa. Ex.: Souza
email	String	Endereço de email da pessoa. Ex.: roberto.souza@gmail.com
cpf	String	Código da pessoa no cadastro da receita federal. Incluir apenas números. Ex.: 14811751817.
celular	String	Número do telefone celular da pessoa. Incluir o DDD e deixar sem máscara. Ex.: 11994258349.

Retorno

Parâmetro

Tipo

Descrição

mensagem

String

A indicação INDICA-999999999 foi cadastrada com sucesso.

Se ocorrer algum erro, indica a mensagem do erro.

indicacao

Indicacao__c

Estrutura de dados com as informações da indicação cadastrada.

erro

Boolean

Retorno verdadeiro quando ocorreu um erro ou falso quando a indicação foi cadastrada com sucesso.

Exemplo de requisição com sucesso

Exemplo

Requisição

{ "indicacao": {
"tipo": "Locação",
"origem": "Buzzlead",
"campanha": "asdfasdf",

"divulgador":"teste@teste.com"
"indicador": {
"nome": "Fabio",
"sobrenome": "Zarvos",
"email": "fabiozarvos@gmail.com",
"cpf": "14811751817",
"celular": "11994258349"},
"indicado": {
"nome": "Roberto",
"sobrenome": "Souza",
"email": "roberto.souza@gmail.com",
"celular": "1199323244"}}
}

Retorno

{
"mensagem": "A indicação INDICA-00000008 foi cadastrada com sucesso",
"indicacao": {
"attributes": {
"type": "snap_brok__Indicacao__c",
"url": "/services/data/v45.0/sobjects/snap_brok__Indicacao__c/a5T4P000000HuSHUA0"
},
"Id": "a5T4P000000HuSHUA0",
"Name": "INDICA-00000008",
"snap_brok__Data_indicacao__c": "2019-05-15",
"snap_brok__Indicado__c": "0010B00001qYZo7QAG",
"snap_brok__Indicador__c": "0010B00001ydepcQAA",
"snap_brok__Origem_indicacao__c": "Buzzlead",
"snap_brok__Tipo_indicacao__c": "Locação",
"snap_brok__Indicado__r": {
"attributes": {
"type": "Account",
"url": "/services/data/v45.0/sobjects/Account/0010B00001qYZo7QAG"
},
"Id": "0010B00001qYZo7QAG",
"Name": "Comgás"
},
"snap_brok__Indicador__r": {
"attributes": {
"type": "Account",
"url": "/services/data/v45.0/sobjects/Account/0010B00001ydepcQAA"
},
"Id": "0010B00001ydepcQAA",
"Name": "Maria Morena",
"PersonEmail": "fabiozarvos@gmail.com"
}
},
"erro": false
}