Entendendo a API Aberta do Lead Gen & CRM: Visão Geral

Última atualização: 9 de outubro de 2024

A API do Lead Gen & CRM permite que seu aplicativo se conecte à funcionalidade interna de CRM do Lead Gen & CRM. Este artigo fornecerá uma visão geral da API do Lead Gen & CRM.

Conteúdo do Artigo

Informações Adicionais da API
API do Lead Gen & CRM e Limitações de Uso
Gerando Chaves de API
Acessando Referências de API
Usando a API do Lead Gen & CRM
Formato de Requisição e Resposta
Erros de Nível de API
Erros de Nível de Objeto
Erros 502 e Expect:100-Continue

Usuários:

Administradores	✓
Gerentes de Empresa
Gerentes de Marketing
Gerentes de Vendas
Vendedores
Vendedores Jr.

Informações Adicionais da API

Este artigo fornece uma visão geral da API do Lead Gen & CRM. No entanto, dado o tamanho e o escopo da API, as informações estão divididas e contidas em diferentes artigos. Cada artigo foca em uma função específica da API do Lead Gen & CRM. Informações adicionais sobre a API podem ser encontradas nos seguintes artigos:

API do Lead Gen & CRM e Limitações de Uso

A implementação atual da API do Lead Gen & CRM envolve muitos recursos, como:

Criar e atualizar leads, incluindo aqueles com campos personalizados
Integrar automaticamente com o Motor de Automação através de eventos de mudança de campo de lead
Criar, atualizar e recuperar campanhas, contas e oportunidades

Nota: Ao usar a API para atualizar um campo de lead, esse valor sempre substituirá qualquer valor de campo existente e não será adicionado a ele.

Cada parceiro do Lead Gen & CRM atualmente tem direito a 50.000 requisições de API por dia por padrão, com um máximo de 10 consultas por segundo e um limite de 500 consultas por requisição. Em média, os usuários podem adicionar cerca de 1 milhão de contatos por dia. No entanto, as requisições podem ser limitadas em épocas de alto tráfego e pelo volume de informações de lead. Esteja ciente de que a quantidade de requisições de API está sujeita a alterações no futuro.

Gerando Chaves de API

Para acessar a API do Lead Gen & CRM, você deve gerar tanto um ID de conta quanto uma chave de API. A API do Lead Gen & CRM atualmente não suporta sessões, então essas chaves devem ser fornecidas durante cada requisição.

Para acessar a API do Lead Gen & CRM e criar chaves de API, faça o seguinte:

Clique em Configurações na barra lateral esquerda.
Clique em Configurações da API, localizado em API do Lead Gen & CRM no painel esquerdo.
Acesse suas chaves de API do Lead Gen & CRM em ID da Conta e Chave Secreta.
Clique em Gerar Novas Chaves de API para novas chaves de API.

Nota: A Constant Contact oferece Serviços Profissionais para ajudar com problemas da API do Lead Gen & CRM.

Acessando Referências de API

Para acessar código de exemplo, métodos, esquema e códigos de erro, faça o seguinte:

Clique Configurações na barra lateral esquerda.
Clique em Referência da API, localizado em API do Lead Gen & CRM no painel esquerdo.
Selecione qualquer uma das seguintes abas:
- Clique na aba Código de Exemplo para acessar códigos de exemplo.
- Clique na aba Métodos para informações sobre métodos.
- Clique na aba Esquema para informações sobre esquema.
- Clique na aba Códigos de Erro para uma lista de códigos de erro.

Usando a API do Lead Gen & CRM

Usar a API do Lead Gen & CRM para atualizar um valor de campo sempre substituirá qualquer valor de campo existente. A substituição ocorrerá em vez de adicionar, anexar ou modificar o valor de qualquer outra maneira.

Quando você cria um campo personalizado, o Lead Gen & CRM gera um nome de sistema, que é o que você usa na API. No entanto, se o nome do campo for alterado posteriormente, o nome do sistema não mudará. Isso é para evitar quebrar acidentalmente uma conexão da API ao alterar um rótulo.

Por exemplo, se um campo personalizado é chamado Cor Favorita, o nome do sistema pode ser Favorite_Color_5a0dd86e6e290. Se o campo personalizado for alterado para Nome do Pet na interface do usuário, ele ainda será Favorite_Color_5a0dd86e6e290 na API. Nesse ponto, seria melhor criar um novo campo para evitar confusão.

Formato de Requisição e Resposta

Uma vez que suas chaves tenham sido geradas, você pode começar a criar o mecanismo para recuperar e enviar dados para e da aplicação Lead Gen & CRM. Todas as requisições são feitas usando um POST HTTPs codificado em JSON. O Lead Gen & CRM usa um padrão muito semelhante ao JSON-RPC para manipulação de requisições.

Requisições de API

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

	Versão		Descrição
	v1		https://api.sharpspring.com/pubapi/v1/ Os argumentos de fuso horário passados para este endpoint serão tratados com base na configuração de fuso horário selecionada no Perfil da Empresa.
	v1.2		https://api.sharpspring.com/pubapi/v1.2/ Os argumentos de fuso horário passados para este endpoint serão tratados em UTC.

Autenticação da API

Os parâmetros de autenticação devem ser anexados ao URL como strings de consulta:
accountID={id-da-conta-aqui}&secretKey={chave-secreta-aqui}

Cada requisição deve conter os seguintes três campos:

	Campo		Descrição
	Método		O nome do método da API que está sendo chamado.
	Params		Um hash de parâmetros a ser passado para o método.
	ID		Um ID de requisição fornecido pelo usuário para correlacionar requisições.

Respostas da API

Cada resposta da API contém os seguintes três campos:

	Campo		Descrição
	Resultado		O valor de retorno do método chamado. Geralmente uma lista de Objetos e erros de nível de objeto.
	Erro		Um erro de nível de API retornado pela API.
	ID		Um ID de requisição fornecido pelo usuário para correlacionar requisições.

O seguinte é um exemplo de uso do método getLead para recuperar um único lead pelo seu ID:

"Dados da Requisição:"
 
{
  "method":"getLead",
  "params":{
    "id":"<id do lead>"
  },

  "id":"<seu ID de requisição>",
}
 
"Dados da Resposta:"
 
{
  "result":{
    "lead":[
      {
        "id":"<id>",
        "companyName":"<nome da empresa>",
        "title":"<título>",
        "firstName":"<primeiro nome>",
        "lastName":"<último nome>",
        "street":"<rua>",
        "city":"<cidade>",
        "country":"<país>",
        "state":"<estado>",
        "zipcode":"<cep>",
        "emailAddress":"<email>",
        "website":"<website>",
        "phoneNumber":"<telefone>",
        "mobilePhoneNumber":"<telefone celular>",
        "faxNumber":"<telefone fax>",
        "description":"<descrição>",
        "leadScore":"<pontuação do lead>",
        "industry":"<setor>",
        "active":"<está ativo>",
        "isUnsubscribed":"<está desinscrito>",
        "leadStatus":"<status do lead>"
      }
    ]
  },
  "error":null,
  "id":"<seu ID de requisição>"
}

Erros de Nível de API

Quando uma requisição inválida é feita à API, um objeto de erro será retornado.

Um exemplo de objeto de erro de nível de API é o seguinte:

{
  "result":null,
  "error":{
    "code":205,
    "message":"Parâmetros inválidos",
    "data":{
      "params":[
        {
          "param":"id",
          "message":"Dados do tipo inteiro esperados",
          "validFormat":{
            "type":"int",
            "length":11,
            "required":false
          }
        }
      ]
    }
  },
  "id":"<ID da requisição>"
}

Erros de Nível de Objeto

Quando um objeto de formato inválido é passado como parte de uma lista (como em uma consulta de criação ou atualização), um erro de nível de objeto será retornado no array de resultados. Como o erro foi no nível do objeto, nenhum erro de API será retornado.

Um exemplo de objeto de erro de nível de objeto é o seguinte:

{
  "result":{
    "creates":[
      {
        "success":"false",
        "error":{
          "code":301,
          "message":"Entrada já existe",
          "data":[]
        }
      }
    ]
  },
  "error":null,
  "id":"<ID da requisição>"
}

Erros 502 e Expect:100-Continue

Se você encontrar um erro 502 ao executar uma chamada, verifique se Expect:100-continue está habilitado no cabeçalho. O Lead Gen & CRM usa o serviço GCE do Google, e quando o cabeçalho Expect:100-continue está habilitado, chamadas de API com mais de 1.024 caracteres (incluindo a chave secreta e outros dados) resultarão em um erro 502. Esta opção está ativada por padrão no .NET, assim como no .PHP.

Desabilitando Expect:100-Continue para .NET

Para desabilitar Expect:100-continue no .NET, execute as seguintes linhas antes da chamada da API:

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

Desabilitando Expect:100-Continue para .PHP

Para desabilitar Expect:100-continue no Curl dentro do .PHP, adicione a opção Expect sem valor à seção HTTPHEADER.

A última linha do exemplo abaixo mostra como desabilitar Expect:100-continue no .PHP com este método:

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