Documentação

Documento que descreve comportamento e usabilidade da API do SnapProperty.

Método de Autenticação Oauth:

Para autenticação no Salesforce é necessário utilizar o método de autenticação Oauth 2.0.

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=" }

Métodos de negócio

DescreveObjeto

Descrição: Método responsável por descrever a estrutura/modelagem de um objeto,

para obter os campos disponíveis em cada objeto da integração com o SnapProperty.

Neste método será possível a discrição de um objeto, utilizando o método Rest Get.

Tipo de parâmetro: Nome de API do Objeto.

Tipo: Síncrono

Máximo de registros por requisição: 1

Assinatura

URL

Descrição

Padrão

https://<instância do cliente>/<versão>/<Nome do objeto>/describe

<instância do cliente> : nome de instância da org salesforce que o cliente utiliza.

<versão> : versão da org salesforce que o cliente utiliza.

<Nome do objeto> : Nome de API do objeto no Salesforce.

Exemplo: Método
Get

Exemplo: URL
https://snap-property.salesforce.com/v43.0/sobjects/snap_brok__Imovel__c/describe

Exemplo: Requisição Header
Content-Type	application/json
Authorization	OAuth 00Do0000000Kygx!ARUAQNIkRvLZ.uTwqA._wGu.5But

Exemplo: Requisição body JSON	Observações
	Método Get não possui body

Exemplo: Resposta - Sucesso	Observações
{ "actionOverrides" : [ { "formFactor" : "LARGE", "isAvailableInTouch" : false, "name" : "Edit", "pageId" : "0Ab0B0000008RT7SAM", "url" : null }, { "formFactor" : "SMALL", "isAvailableInTouch" : false, "name" : "Edit", "pageId" : "0Ab0B0000008RT7SAM", "url" : null }, ...	Exemplo de resultado parcial.

Exemplo: Resposta - Falha	Observações
[ { "errorCode" : "NOT_FOUND", "message" : "The requested resource does not exist" } ]

Referências de implementação	Descrição
https://developer.salesforce.com/docs/atlas.en-us.api_rest.meta/api_rest/resources_sobject_describe.htm	Descrição de sObjects

IncluirConta

Descrição: Método responsável por incluir um registro de Conta (Pessoa jurídica ou Física), para ocasiões de

inserções de contas em sistemas externos com a necessidade de equalização dentro do SnapProperty.

Neste método será possível a inserção de uma ou mais contas, utilizando o método Rest Post.

No body da requisição todos os campos obrigatórios, e todos aqueles que se deseja popular na criação do registro.

Tipo de parâmetro: Lista de contas ( mesmo que seja apenas uma conta a ser inclusa).

Tipo: Síncrono

Máximo de registros por requisição: 200

Assinatura

URL

Descrição

Padrão

https://<instância do cliente>/<versão>/composite/sobjects

<instância do cliente> : nome de instância da org salesforce que o cliente utiliza.

<versão> : versão da org salesforce que o cliente utiliza.

Exemplo: Método
Post

Exemplo: URL
https://snap-property.salesforce.com/v43.0/apexrest/composite/sobjects

Exemplo: Requisição Header
Content-Type	application/json
Authorization	OAuth 00Do0000000Kygx!ARUAQNIkRvLZ.uTwqA._wGu.5But

Exemplo: Requisição body JSON	Observações
{ "allOrNone" : false, "records" : [{ "attributes" : {"type" : "Account"}, "LastName" : "Aline", "FirstName" : "Pereira", "RecordType" : {"Name": "Cliente pessoa física"}, "snap_finan__Id_externo__c": "Conta1" }, { "attributes" : {"type" : "Account"}, "LastName" : "Estevão", "FirstName" : "Fernandes", "RecordType" : {"Name": "Cliente pessoa física"}, "snap_finan__Id_externo__c": "Conta2" }] }	Opções de RecordType: Administradora Cliente pessoa física Construtora Empresa Fornecedor Seguradora Cliente pessoa física allOrNone: caso verdadeiro(true), cancela toda a transação se um registro apresentar erro.

Exemplo: Resposta - Sucesso	Observações
[ { "id": "0010B000022lk6AQAQ", "success": true, "errors": [] }, { "id": "0010B000022lk6BQAQ", "success": true, "errors": [] } ]

Exemplo: Resposta - Falha	Observações
[ { "id": "0010B000022lk77QAA", "success": true, "errors": [] }, { "success": false, "errors": [ { "statusCode": "DUPLICATE_VALUE", "message": "duplicate value found: snap_finan__Id_externo__c duplica o valor no registro com ID: 0010B000022lk6A", "fields": [] } ] } ]

Referências de implementação	Descrição
https://developer.salesforce.com/docs/atlas.en-us.api_rest.meta/api_rest/resources_composite_sobjects_collections_create.htm	Criação de múltiplos registros. Rest API Salesforce

AtualizarConta

Descrição: Método responsável por atualizar um registro de Conta (Pessoa jurídica ou Física), para ocasiões de alterações

cadastrais em sistemas externos, com a necessidade de equalização dentro do SnapProperty.

Neste método será possível a atualização de uma conta, utilizando o método Rest Post. No body da requisição

apenas os campos que se deseja atualizar.

Tipo de parâmetro: Lista de contas (mesmo que seja apenas uma conta a ser atualizada).

Tipo: Síncrono

Máximo de registros por requisição: 200

Assinatura

URL

Descrição

Id externo

https://<instância do cliente>/services/data/<versão>/composite

Informe o "Id externo" da conta ou "Id" no local apropriado do body da requisição.

<instância do cliente> : nome de instância da org salesforce que o cliente utiliza.

<versão> : versão da instância salelsforce que o cliente utiliza.

Exemplo: Método
Post

Exemplo: URL
https://snap-property.salesforce.com/services/data/v44.0/composite

Exemplo: Requisição Header
Content-Type	application/json
Authorization	OAuth 00Do0000000Kygx!ARUAQNIkRvLZ.uTwqA._wGu.5But

Exemplo: Requisição body JSON

Observações

{
"compositeRequest" : [
{
"method" : "PATCH",
"url" : "/services/data/v41.0/sobjects/Account/snap_finan__Id_externo__c/Louco1",
"body" : { "Website" : "Jack.com.br" },
"referenceId" : "1"
}, {
"method" : "PATCH",
"url" : "/services/data/v41.0/sobjects/Account/snap_finan__Id_externo__c/Louco2",
"body" : { "Website" : "Jack.com.br"},
"referenceId" : "2"
}
]
}

Obrigatório informar:
- method [com método patch]
- url [contendo o campo que será a base da atualização ("Id externo" ou "Id")]
- referenceId [sequencial para saber resultado de cada registro no retorno]
- body [contendo os campos a se atualizar]

Exemplo: Resposta - Sucesso

Observações

{

"compositeResponse" : [ {

"body" : null,

"httpHeaders" : { },

"httpStatusCode" : 204,

"referenceId" : "1"

}, {

"body" : null,

"httpHeaders" : { },

"httpStatusCode" : 204,

"referenceId" : "2" } ]

}

Status 204: "Sucesso sem necessidade de ação"

Exemplo: Resposta - Falha

Observações

{ "compositeResponse" : [ {

"body" : [ {

"message" : "'a' is not a valid salesforce ID",

"errorCode" : "FIELD_INTEGRITY_EXCEPTION"

} ],

"httpHeaders" : { },

"httpStatusCode" : 400,

"referenceId" : "1"

}, {

"body" : [ {

"message" : "Campos obrigatórios ausentes: [Name]",

"errorCode" : "REQUIRED_FIELD_MISSING",

"fields" : [ "Name" ]

} ],

"httpHeaders" : { },

"httpStatusCode" : 400,

"referenceId" : "2"

} ]

}

Id informado incorreto

Referências de implementação	Descrição
https://developer.salesforce.com/docs/atlas.en-us.api_rest.meta/api_rest/resources_composite_composite.htm	Utilização do composite. Rest API Salesforce.

AtualizarImovel

Descrição: Método responsável por atualizar um registro de Imóvel, para ocasiões de alterações

cadastrais em sistemas externos, com a necessidade de equalização dentro do SnapProperty.

Neste método será possível a atualização de um imóvel, utilizando o método Rest Post. No body da requisição

apenas os campos que se deseja atualizar.

Tipo de parâmetro: Lista de imóveis (mesmo que seja apenas um imóvel a ser atualizado).

Tipo: Síncrono

Máximo de registros por requisição: 200

Assinatura

URL

Descrição

Id externo

https://<instância do cliente>/services/data/<versão>/composite

Informe o "Id externo" do imóvel ou "Id" no local apropriado do body da requisição.

<instância do cliente> : nome de instância da org salesforce que o cliente utiliza.

<versão> : versão da instância salelsforce que o cliente utiliza.

Exemplo: Método
Post

Exemplo: URL
https://snap-property.salesforce.com/services/data/v44.0/composite

Exemplo: Requisição Header
Content-Type	application/json
Authorization	Bearer 00Do0000000Kygx!ARUAQNIkRvLZ.uTwqA._wGu.5But

Exemplo: Requisição body JSON

Observações

{
"compositeRequest" : [
{
"method" : "PATCH",
"url" : "/services/data/v41.0/sobjects/snap_brok__Imovel__c/snap_brok__ID_externo__c/CR12345",
"body" : {

"snap_brok__Valor_IPTU__c" : "850.77",

"snap_brok__Valor_Condominio__c" : "700"

},
"referenceId" : "1"
}, {
"method" : "PATCH",
"url" : "/services/data/v41.0/sobjects/snap_brok__Imovel__c/snap_brok__ID_externo__c/CR99999",
"body" : {

"snap_brok__Valor_IPTU__c" : "650.55",

"snap_brok__Valor_Condominio__c" : ""

},
"referenceId" : "2"
}
]
}

Obrigatório informar:
- method [com método patch]
- url [contendo o campo que será a base da atualização ("Id externo" ou "Id")]
- referenceId [sequencial para saber resultado de cada registro no retorno
- body [contendo os campos a se atualizar]

Exemplo: Resposta - Sucesso	Observações
{ "compositeResponse": [ { "body": null, "httpHeaders": {}, "httpStatusCode": 204, "referenceId": "1" }, { "body": null, "httpHeaders": {}, "httpStatusCode": 204, "referenceId": "2" } ] }	Status 204: "Sucesso sem necessidade de ação"

Exemplo: Resposta - Falha

Observações

{
    "compositeResponse": [
        {
            "body": [
                {
                    "message": "Campos obrigatórios ausentes: [snap_brok__Logradouro__c, snap_brok__Tipo_uso_3__c, snap_brok__Tipo_imovel_2__c]",
                    "errorCode": "REQUIRED_FIELD_MISSING",
                    "fields": [
                        "snap_brok__Logradouro__c",
                        "snap_brok__Tipo_uso_3__c",
                        "snap_brok__Tipo_imovel_2__c"
                    ]
                }
            ],
            "httpHeaders": {},
            "httpStatusCode": 400,
            "referenceId": "1"
        },
        {
            "body": null,
            "httpHeaders": {},
            "httpStatusCode": 204,
            "referenceId": "2"
        }
    ]
}

Um dos IDs estando incorreto: retornará erro de preenchimento para inserção, para aquele referenceId específico.

Referências de implementação	Descrição
https://developer.salesforce.com/docs/atlas.en-us.api_rest.meta/api_rest/resources_composite_composite.htm	Utilização do composite. Rest API Salesforce.