Pular para o conteúdo principal

Visão Geral da API SharpSpring

Fernanda Matias
Atualizado

A nossa API da permite que seu aplicativo se conecte ao CRM da SharpSpring. Este artigo fornece uma visão geral da API.

 

Usuários com acesso:

  • Administradores

 

Funcionalidades e Limitações de Uso

A implementação atual da nossa API envolve diversas características, tais como:

  • Criação e atualização de leads, incluindo aqueles com campos personalizados;

  • Integração automática com o engine de Automação, através de eventos de alteração em campos do lead;

  • Criação, atualização e recuperação de campanhas, contas e oportunidades.

Observação: ao usar a API para atualizar o campo de um lead, o valor sempre irá substituir o valor já existente, nunca será adicionado como informação complementar.

Por padrão, cada parceiro(a) SharpSpring possui 50.000 requisições diárias de API, com o máximo de 500 queries por requisição. Na média, usuários podem adicionar cerca de 1 milhão de contatos por dia. As requisições, no entanto, podem ser limitadas em termos de taxa (nos momentos de excesso de tráfego) e por volume de informações do lead. Importante ressaltar que o montante de requisições de API pode mudar no futuro.

 

 

Criando Chaves de API

Para acessar a API SharpSpring, você deve gerar tanto um ID de conta quanto uma chave de API. Nossa API atualmente não suporta sessões, portanto, as chaves devem ser fornecidas durante cada requisição.

  1. Na barra principal da SharpSpring, clique em Configurações de Usuário > Configurações.

  2. No painel à esquerda, sob API SharpSpring, clique em Configurações API.

  3. Acesse as chaves de API em ID da conta e Chave secreta.

  4. Clique em Gerar novas chaves API, para novas chaves.

Observação: a SharpSpring oferece Serviços Profissionais para auxiliar em questões envolvendo a API.

 

 

Acessando as Referências da API

Para acessar o código de exemplo, os métodos, o schema e os códigos de erros, você deve fazer o seguinte:

  1. Na barra principal da SharpSpring, clique em Configurações de Usuário > Configurações.

  2. No painel à esquerda, sob API SharpSpring, clique em Referência API.

  3. Clique na aba the Example Code para ver exemplos de código.

  4. Clique na aba Methods para informações sobre os métodos.

  5. Clique na aba Schema para informações sobre o schema.

  6. Clique na aba Error Codes para uma lista dos códigos de erro.

Observação: você precisa estar logado para ver o conteúdo dos links acima. Caso você ainda não tenha acesso à SharpSpring, clique aqui.

 

 

Usando a API da SharpSpring

Ao usar a API da SharpSpring para atualizar o valor de um campo, este valor sempre vai sobrescrever o valor já existente. Em outras palavras, o valor nunca será acrescentado ao campo - mas substituído.
Quando você cria um campo personalizado, a SharpSpring gera um nome de sistema que você deve utilizar na API. Nesse sentido, mesmo se o nome do campo é alterado no futuro, o nome de sistema dele não vai mudar. Isso acontece para que a conexão da API não seja perdida, em caso de alteração do nome do campo.

Exemplo: um campo personalizado chamado Cor Favorita, para o sistema possui o nome Favorite_Color_5a0dd86e6e290. Se o campo personalizado. Caso o campo personalizado seja alterado para Nome do animal de estimação, o nome no sistema ainda será Favorite_Color_5a0dd86e6e290 na API. Uma dica, nessa situação é melhor criar um novo campo para evitar confusão.

 

 

Formato de Requisição e Resposta

Assim que as chaves forem geradas, você pode começar a criar o mecanismo para recuperar dados da e postar dados na SharpSpring. Todas as requisições são feitas usando um método HTTP POST codificado em JSON. A SharpSpring usa um padrão bastante semelhante ao JSON-RPC para manipular requisições.

 

Requisições da API

As requisições devem ser feitas para a seguinte URL: https://api.sharpspring.com/pubapi/v1/

Argumentos de fuso horário passados para este endpoint serão tratados no fuso horário configurado no Perfil da Empresa.

Argumentos de fuso horário passados para este endpoint serão tratados no fuso horário UTC.

 

Autenticação da API

Os parâmetros de autenticação deve ser adicionados à URL como query strings:
accountID={account-id-here}&secretKey={secret-key-here}

Cada requisição deve conter os seguintes campos:

  • Method: nome do método API sendo chamado;

  • Params: hash do parâmetro a ser passado para o métodos;

  • ID: ID de requisição fornecido pelo usuário, para correlacionar requisições.

 

Respostas da API

Cada resposta da API contém os seguintes campos:

  • Result: valor retornado pelo método chamado, geralmente uma lista de objetos e erros a nível de objeto;

  • Error: erro a nível de API retornado pela API;

  • ID: ID de requisição fornecido pelo usuário, para correlacionar requisições.

Abaixo, um exemplo de uso do método getLead para recuperar um lead único a partir de seu ID:

"Request Data:"
 
{
  "method":"getLead",
  "params":{
    "id":"<a lead id>"
  },

  "id":"<your request ID>",
}
 
"Response Data:"
 
{
  "result":{
    "lead":[
      {
        "id":"<id>",
        "companyName":"<company name>",
        "title":"<title>",
        "firstName":"<first name>",
        "lastName":"<last name>",
        "street":"<street>",
        "city":"<city>",
        "country":"<country>",
        "state":"<state>",
        "zipcode":"<zip code>",
        "emailAddress":"<email>",
        "website":"<website>",
        "phoneNumber":"<phone number>",
        "mobilePhoneNumber":"<mobile phone number>",
        "faxNumber":"<fax number>",
        "description":"<description>",
        "leadScore":"<lead score>",
        "industry":"<industry>",
        "active":"<is active>",
        "isUnsubscribed":"<is unsubscribed>",
        "leadStatus":"<lead status>"
      }
    ]
  },
  "error":null,
  "id":"<your request ID>"
} 

 

 

Erros na API

Quando uma requisição inválida é feita para a API, um objeto de erro será retornado - como no exemplo abaixo:

{
  "result":null,
  "error":{
    "code":205,
    "message":"Invalid parameters",
    "data":{
      "params":[
        {
          "param":"id",
          "message":"Expected data of type integer",
          "validFormat":{
            "type":"int",
            "length":11,
            "required":false
          }
        }
      ]
    }
  },
  "id":"<request ID>"
}

 

 

Erros no Objeto

Quando um objeto de formato inválido é passado como parte de uma lista - tal como numa query de create ou update -, um erro a nível de objeto será retornado no array resultante. Neste caso, não serão retornados erros de API.

Abaixo, um exemplo de erro a nível de objeto:

{
  "result":{
    "creates":[
      {
        "success":"false",
        "error":{
          "code":301,
          "message":"Entry already exists",
          "data":[]
        }
      }
    ]
  },
  "error":null,
  "id":"<request ID>"
}

 

 

Erros 502 e Expect:100-Continue

Se você receber um erro 502 ao rodar uma chamada, verifique se o Expect:100-continue está ativado no header. A SharpSpring usa o serviço GCE do Google e, quando o header Expect:100-continue está ativado, as chamadas de API com mais de 1.024 caracteres (incluindo a chave secreta e demais dados) resultam em erro 502. Tal opção está ativada por default nas linguagens .NET e .PHP.

 

Desativando Expect:100-Continue em .NET

Para desativar o Expect:100-continue in .NET, você deve rodas as seguintes linhas antes da chamada da API:

System.Net.ServicePointManager.Expect100Continue: false;
rqst.ServicePoint.Expect100Continue = false;

 

Desativando Expect:100-Continue em .PHP

Para desativar o Expect:100-continue em Curl, no .PHP, adicione a opção Expect (sem valor) na seção HTTPHEADER.

A última linha do exemplo a seguir mostra como desativar o Expect:100-continue no .PHP com este método:

curl_setopt($ch, CURLOPT_HTTPHEADER, array( 
    'Content-Type: application/json',
    'Content-Length: ' . strlen($data),
    'Expect: '
));

Artigos relacionados

Comentários

0 comentário

Artigo fechado para comentários.