Jump to table of contents

Manual API REST Atende CRM

Esse manual técnico tem como objetivo ajudar desenvolvedores/programadores na integração com a API Rest Atende CRM. Este manual conta também com exemplos práticos e em português para que a integração seja simples e completa.

O que é a API Atende CRM?

A API Atende CRM é uma integração do tipo REST que permite acesso externo ao sistema Atende CRM para realizar comunicações seguras para geração de cobranças e consultas. A comunicação ocorre através de objetos JSON, que tenham ID e Token válidos.

A REST API pode ter seus recursos acessados e utilizados por qualquer linguagem de programação que tenha recursos Web de comunicação HTTP e manipulação de JSON.

Quais são as operações que a API Atende CRM pode realizar?

Os endpoints correspondem a cada operação permitida, abaixo a relação das operações disponíveis na API:

- POST https://www.atendecrm.com.br/api/v1/lead
- GET  https://www.atendecrm.com.br/api/v1/lead/{CODIGO}						
- GET  https://www.atendecrm.com.br/api/v1/leads

Autenticação

Somente usuários autenticados terão acesso a essa REST API. A Autenticação se dá através de um ID e Token.

Como obter meu ID e Token?

No seu painel de controle da Atende CRM, acesse o menu "Integração", preencha os campos solicitados e ative a sua API. Assim você irá ter acesso ao ID e o Token, com esses dados basta criar sua aplicação comunicando com a API.

Autorização

Para utilizar os recursos da API é necessário enviar em todas as requisições o ID e Token no cabeçalho da requisição HTTP. Os parametros a serem passados são: x-ID:Seu ID e x-Token:Seu Token além disso é necessário enviar o Content-Type neste formato Content-Type: application/json

Abaixo, veja um exemplo de uma comunicação autorizada na linguagem PHP no endpoint GET leads utilizando-se do Curl:


				//Exemplo do GET LEADS
				$url = "https://www.atendecrm.com.br/api/v1/leads";

				$curl = curl_init();
				curl_setopt($curl, CURLOPT_URL, $url);

				$headers = array();
				$headers[] = "x-ID:3566"; // Coloque seu ID aqui
				$headers[] = "x-Token:3481260001..."; // Coloque aqui seu Token
				$headers[] = "Content-Type: application/json";

				curl_setopt($curl, CURLOPT_HTTPHEADER, $headers);
				curl_setopt($curl, CURLOPT_RETURNTRANSFER, TRUE);
				$response = curl_exec($curl);
				$httpcode = curl_getinfo($curl, CURLINFO_HTTP_CODE);  // Código de retorno.

				curl_close($curl);

				$retornoJSON = json_decode($response);
				
				var_dump($retornoJSON);

Veja o exemplo abaixo de Autorização utilizando o Postman:


					GET /api/v1/leads HTTP/1.1
					Host: www.atendecrm.com.br
					x-ID: 9898
					x-Token: 77O585194T334540R429730I7167u50O9460u63a1223O59u9156I51C4171R97j8830T18S84627
					Content-Type: application/json
					Cache-Control: no-cache
					Postman-Token: 0d5cb339-7fa1-bcb8-4796-53026a8b28ed

Leads

As operações em LEADS permitem: Criar lead em uma conta Atende CRM e também consultar dados dos leads na conta autenticada na API.

POST lead (Criar um Lead)

O endpoint usado na api para realizar a operação de criar lead é o POST lead. Veja abaixo um exemplo do código usando o cURL PHP para criação de uma conta virtual. 


		//Exemplo do POST lead
		$url = "https://www.atendecrm.com.br/api/v1/lead"; 

		$json = array
		(
		"seu_codigo"=>"1000",
 		"cliente_nome"=>"Amaral Silva",
		"cliente_doc"=>"07163359858",
		"cliente_email"=>"comercial@empresa.com.br",
		"cliente_telefone"=>"00000000000",
		"campanha"=>"Venda Certa",
		"origem"=>"ERP",
		"operador"=>"JOAO.FRANCISCO",
		"qualificacao"=>"QUER_CONTRATO",
		"valor"=>"2730.00",
		"etapa_funil"=>"MORNO",
		"cadencia"=>"PADRAO",
		"observacoes"=>"Cliente com potencial de conversao."
		);
		$json = json_encode($json); // Converte em formato Json
		 
		$curl = curl_init();
		curl_setopt($curl, CURLOPT_URL, $url);

		$headers = array();
		$headers[] = "x-ID:3566"; // Coloque seu ID aqui
		$headers[] = "x-Token:3481260001..."; // Coloque aqui seu Token
		$headers[] = "Content-Type: application/json";

		curl_setopt($curl, CURLOPT_HTTPHEADER, $headers);
		
		curl_setopt($curl, CURLOPT_POST, 1); // Informando que é POST
		curl_setopt($curl, CURLOPT_POSTFIELDS, $json); // Envio do JSON		
		
		curl_setopt($curl, CURLOPT_RETURNTRANSFER, TRUE);
		$response = curl_exec($curl);
		$httpcode = curl_getinfo($curl, CURLINFO_HTTP_CODE); // Código de retorno.

		curl_close($curl);

		$retornoJSON = json_decode($response);
		
		var_dump($retornoJSON);

Tabela de Especificações dos Campos (POST lead)

Campo Formato Tamanho Obrigatório Descrição
seu_codigo string 100 Não Defina um código seu para o lead. Se não informado, criaremos.
cliente_nome string 100 Sim Nome completo cliente.
cliente_doc string 30 Sim Informe o CPF do cliente ou CNPJ. Formato: Somente números.
cliente_email string 40 Sim Informe o email do cliente.
cliente_telefone string 15 Sim Telefone principal do cliente.
campanha string 50 Não Nome da campanha
origem string 50 Não Nome da origem do lead
operador string 50 Não Nome do operador responsável pelo lead.
qualificacao string 50 Não Noem da qualificação de entrada do lead.
valor string 50 Não Valor envolvido no lead
etapa_funil string 50 Não Nome da etapa de entrada do lead no fúnil.
cadencia string 50 Não Nome da cadência de entrada do lead.
observacoes string 350 Não Observação do lead.

Se tudo ocorreu bem, o lead será processado e retornado o codigo 201 no header e no body todas informações do lead. Abaixo o Payload de retorno no formato json: 


{	
	"codigo":"789991020",	
	"seu_codigo":"1000",
	"cliente_nome":"Amaral Silva",
	"cliente_doc":"07163359858",
	"cliente_email":"comercial@empresa.com.br",
	"cliente_telefone":"00000000000",
	"campanha":"Venda Certa",
	"origem":"ERP",
	"operador":"JOAO.FRANCISCO",
	"qualificacao":"QUER_CONTRATO",
	"valor":"2730.00",
	"etapa_funil":"MORNO",
	"cadencia":"PADRAO",
	"observacoes":"Cliente com potencial de conversao."
}

GET lead/{CODIGO}

O endpoint usado na api para realizar a operação de consultar um lead é o GET lead/{CODIGO}. Veja abaixo um exemplo do código usando o cURL PHP para consultar uma conta. 


		$url = "https://www.atendecrm.com.br/api/v1/lead/100000";

		$curl = curl_init();
		curl_setopt($curl, CURLOPT_URL, $url);

		$headers = array();
		$headers[] = "x-ID:3566"; // Coloque seu ID aqui
		$headers[] = "x-Token:3481260001..."; // Coloque aqui seu Token
		$headers[] = "Content-Type: application/json";

		curl_setopt($curl, CURLOPT_HTTPHEADER, $headers);
		curl_setopt($curl, CURLOPT_RETURNTRANSFER, TRUE);
		$response = curl_exec($curl);
		$httpcode = curl_getinfo($curl, CURLINFO_HTTP_CODE); // Código de retorno.

		curl_close($curl);

		$retornoJSON = json_decode($response);

Se tudo ocorreu bem, será retornado um codigo 200 no header e no body o seguinte Payload no formato json: 


{	
	"codigo":"789991020",	
	"seu_codigo":"1000",
	"cliente_nome":"Amaral Silva",
	"cliente_doc":"07163359858",
	"cliente_email":"comercial@empresa.com.br",
	"cliente_telefone":"00000000000",
	"campanha":"Venda Certa",
	"origem":"ERP",
	"operador":"JOAO.FRANCISCO",
	"qualificacao":"QUER_CONTRATO",
	"valor":"2730.00",
	"etapa_funil":"MORNO",
	"cadencia":"PADRAO",
	"observacoes":"Cliente com potencial de conversao."
}

GET leads

O endpoint usado na api para realizar a operação de consultar vários leads é o GET leads. Veja abaixo um exemplo do código usando o cURL PHP para consultar uma conta. 


		$url = "https://www.atendecrm.com.br/api/v1/leads";

		$curl = curl_init();
		curl_setopt($curl, CURLOPT_URL, $url);

		$headers = array();
		$headers[] = "x-ID:3566"; // Coloque seu ID aqui
		$headers[] = "x-Token:3481260001..."; // Coloque aqui seu Token
		$headers[] = "Content-Type: application/json";

		curl_setopt($curl, CURLOPT_HTTPHEADER, $headers);
		curl_setopt($curl, CURLOPT_RETURNTRANSFER, TRUE);
		$response = curl_exec($curl);
		$httpcode = curl_getinfo($curl, CURLINFO_HTTP_CODE); // Código de retorno.

		curl_close($curl);

		$retornoJSON = json_decode($response);

Se tudo ocorreu bem, será retornado um codigo 200 no header e no body o seguinte Payload no formato json: 


[
	{	
		"codigo":"789991020",	
		"seu_codigo":"1000",
		"cliente_nome":"Amaral Silva",
		"cliente_doc":"07163359858",
		"cliente_email":"comercial@empresa.com.br",
		"cliente_telefone":"00000000000",
		"campanha":"Venda Certa",
		"origem":"ERP",
		"operador":"JOAO.FRANCISCO",
		"qualificacao":"QUER_CONTRATO",
		"valor":"2730.00",
		"etapa_funil":"MORNO",
		"cadencia":"PADRAO",
		"observacoes":"Cliente com potencial de conversao."
	},
	{	
		"codigo":"789991020",	
		"seu_codigo":"1000",
		"cliente_nome":"Amaral Silva",
		"cliente_doc":"07163359858",
		"cliente_email":"comercial@empresa.com.br",
		"cliente_telefone":"00000000000",
		"campanha":"Venda Certa",
		"origem":"ERP",
		"operador":"JOAO.FRANCISCO",
		"qualificacao":"QUER_CONTRATO",
		"valor":"2730.00",
		"etapa_funil":"MORNO",
		"cadencia":"PADRAO",
		"observacoes":"Cliente com potencial de conversao."
	}	
]

CallBack (Movimentação de Lead)

Havendo qualquer alteração da situação de um lead o sistema emitirá um POST de JSON à URL de callback configurada em seu painel de integração, essa URL deverá está preparada para recebê-lo. 


/* Modelo de JSON de callback */

{
   "seu_codigo":"1000",
   "codigo":"789991020",
   "movimento":"funil"
   "data":"2023-04-01 12:12:20"
}

Observe que com o código do lead recebido via callback, você poderá realizar uma consulta via GET lead/{CODIGO} para obter detalhes gerais do lead, ou criar sua fila de consultas.


/* Modelo do arquivo que irá receber POST no seu lado */

$data = json_decode(file_get_contents('php://input'), true);

$seu_codigo = $data['seu_codigo']; // Seu código ou Referência Interna
$codigo = $data['codigo']; // Código interno
$movimento = $data['movimento']; // Indicado onde ocorreu o movimento no sistema
$data = $data['data']; // Indica a data do movimento.

Codigos de Retorno e Descrição das Requisições (HTTP)

Codigo Descrição
495 Requisição não segura - SSL Certificate Error
200 A requisição foi bem sucedida
201 Recurso criado ou alterado com sucesso
400 Alguma informação enviada está incorreta. {Descrição do erro}
401 Problemas na autenticação. Verifique sua api key
403 Acesso a um recurso não permitido
404 Método não existe ou tipo de chamada não aceita neste método
500 Erro interno do sistema. Comunique nossa equipe técnica.
501 A operação não foi concluída. Erro interno, comunique nossa equipe técnica.
407 A origem do acesso não é API. Não autorizado.
406 Token não existe.