Integração de Contatos (Entrada) Versão 1.0
Introdução
Esta API integra os contatos do sistema do cliente com os contatos do CRM Zen. Quando houver alguma ação no sistema do cliente referente ao contato, ao chamar esta API, os dados são incluídos no CRM Zen.
Obs.: Para envio de contato para a Distribuição de Lead, usar a API Distribuição de Lead. Clique aqui para ver a documentação
Requisições
A
url e o
token são gerados na área de Integração do Zen (No topo do CRM Zen, clique no ícone de engrenagem e depois selecione Integração).
Todas as requisições devem conter o parâmetro
token (na querystring).
Os
dados são uma string JSON válida. Ver modelos mais à frente.
Obs.: Cada requisição recebe uma string JSON com dados de somente um contato.
Obs.: O JSON deve ser encodado em UTF-8
Obs.: O token NÃO deve ser divulgado publicamente em hipótese alguma
Exemplo de requisição com AJAX:
$.ajax({
url:'{URL}?token={TOKEN}',
type: 'POST',
data: JSON.parse({DADOS}),
complete: function(retorno){
//RETORNO (VER MENSAGENS DE RETORNO PADRÃO)
}
})
Exemplo de requisição com PHP:
$ch = curl_init();
$url = "{URL}?token={TOKEN}";
curl_setopt($ch, CURLOPT_URL,$url);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query(json_decode({DADOS})));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$retorno = curl_exec($ch); //VER MENSAGENS DE RETORNO PADRÃO
curl_close($ch);
Respostas
Todas as respostas estarão no formato JSON.
De modo geral, respostas bem sucedidas retornarão código
HTTP 200 OK.
Erros
Na ocorrência de erros, a resposta será da seguinte forma:
{
"Erro" : "Código",
"Mensagem" : "Descrição do erro"
}
Mensagens de retorno
200 OK
400 Bad Request
- JSON obrigatório
- JSON Incompleto
- Erro na estrutura do JSON, JSON Inválido
- Requisição inválida (Ação inválida. Ações aceitas: Inserir/Editar/Excluir/EditarId.)
- Dados Inválidos (Avisos)
- Contatos inválidos (Avisos)
- Contato não encontrado para edição/exclusão
401 Unauthorized
- Token obrigatório
- Token inválido
- Limite de contatos do plano excedido
- Contato não inserido, devido à outra requisição em andamento no sistema. Tente novamente.
429 Too Many Requests
- Você excedeu o número de requisições. Sua última requisição foi em "YYYY-mm-dd H:i:s".
Sua próxima requisição estará disponível em "YYYY-mm-dd H:i:s"
Obs.: O tempo de espera para a próxima requisição é de 2 segundos.
Obs.: Mesmo não usando todos os parâmetros de cada requisição, é importante não remove-los.
Inserir contato
STRING JSON Padrão para inclusão de contato do tipo
Pessoa Física e
Pessoa Jurídica:
Ver Modelo
{
"Acao" : "Inserir",
"VerificaEndereco" : "1",
"Compartilhamento" : "",
"Integracao" : "",
"Nome" : "",
"Sobrenome" : "",
"CPF" : "",
"RG" : "",
"Sexo" : "",
"Nascimento" : "",
"Razao" : "",
"Fantasia" : "",
"CNPJ" : "",
"Tipo" : "",
"Email" :
{
"Email1" : "",
"Email2" : "",
"Email3" : "",
"Email4" : "",
"Email5" : ""
},
"Website" : "",
"Endereco" :
{
"Endereco" : "",
"Numero" : "",
"Complemento" : "",
"Bairro" : "",
"Cidade" : "",
"Estado" : "",
"Cep" : "",
"Pais" : ""
},
"Telefone" :
[
{
"Tipo" : "",
"DDI" : "",
"DDD" : "",
"Telefone" : "",
"Ramal" : ""
},
{
"Tipo" : "",
"DDI" : "",
"DDD" : "",
"Telefone" : "",
"Ramal" : ""
},
{
"Tipo" : "",
"DDI" : "",
"DDD" : "",
"Telefone" : "",
"Ramal" : ""
},
{
"Tipo" : "",
"DDI" : "",
"DDD" : "",
"Telefone" : "",
"Ramal" : ""
},
{
"Tipo" : "",
"DDI" : "",
"DDD" : "",
"Telefone" : "",
"Ramal" : ""
}
],
"Redes" :
{
"Linkedin" : "",
"Twitter" : "",
"Facebook" : "",
"GooglePlus" : ""
},
"Campos" :
[
{"Titulo" : "", "Valor" : ""},
{"Titulo" : "", "Valor" : ""},
{"Titulo" : "", "Valor" : ""},
{"Titulo" : "", "Valor" : ""},
{"Titulo" : "", "Valor" : ""},
{"Titulo" : "", "Valor" : ""},
{"Titulo" : "", "Valor" : ""},
{"Titulo" : "", "Valor" : ""},
{"Titulo" : "", "Valor" : ""},
{"Titulo" : "", "Valor" : ""}
],
"Observacao" : "",
"Tag" : "",
"Automacao" : "",
"TipoAutomacao" : [
{ "Nome" : "", "Codigo" : "" },
{ "Nome" : "", "Codigo" : "" },
{ "Nome" : "", "Codigo" : "" }
]
}
Obs.: O código de integração do contato deve ser único.
Obs.: Se o parâmetro Automacao for 1, o processo de venda será criado automaticamente.
Editar contato
STRING JSON Padrão para edição de contato do tipo
Pessoa Física e
Pessoa Jurídica:
Ver Modelo
{
"Acao" : "Editar",
"VerificaEndereco" : "1",
"Compartilhamento" : "",
"Integracao" : "",
"Nome" : "",
"Sobrenome" : "",
"CPF" : "",
"RG" : "",
"Sexo" : "",
"Nascimento" : "",
"Razao" : "",
"Fantasia" : "",
"CNPJ" : "",
"Tipo" : "",
"Email" :
{
"Email1" : "",
"Email2" : "",
"Email3" : "",
"Email4" : "",
"Email5" : ""
},
"Website" : "",
"Endereco" :
{
"Endereco" : "",
"Numero" : "",
"Complemento" : "",
"Bairro" : "",
"Cidade" : "",
"Estado" : "",
"Cep" : "",
"Pais" : ""
},
"Telefone" :
[
{
"Tipo" : "",
"DDI" : "",
"DDD" : "",
"Telefone" : "",
"Ramal" : ""
},
{
"Tipo" : "",
"DDI" : "",
"DDD" : "",
"Telefone" : "",
"Ramal" : ""
},
{
"Tipo" : "",
"DDI" : "",
"DDD" : "",
"Telefone" : "",
"Ramal" : ""
},
{
"Tipo" : "",
"DDI" : "",
"DDD" : "",
"Telefone" : "",
"Ramal" : ""
},
{
"Tipo" : "",
"DDI" : "",
"DDD" : "",
"Telefone" : "",
"Ramal" : ""
}
],
"Redes" :
{
"Linkedin" : "",
"Twitter" : "",
"Facebook" : "",
"GooglePlus" : ""
},
"Campos" :
[
{"Titulo" : "", "Valor" : ""},
{"Titulo" : "", "Valor" : ""},
{"Titulo" : "", "Valor" : ""},
{"Titulo" : "", "Valor" : ""},
{"Titulo" : "", "Valor" : ""},
{"Titulo" : "", "Valor" : ""},
{"Titulo" : "", "Valor" : ""},
{"Titulo" : "", "Valor" : ""},
{"Titulo" : "", "Valor" : ""},
{"Titulo" : "", "Valor" : ""}
],
"Observacao" : "",
"Tag" : ""
}
Obs.: Caso exista mais de um registro com o mesmo código de integração, os mesmos serão editados.
Recomendações
Diferente do modo onde é criado um cadastro da empresa e dentro dela cadastra-se os colaboradores, no CRM Zen o vínculo de um contato com a empresa é feito via tag. Desta forma cada usuário pode dar a inteligência de busca conforme sua necessidade.
Ex: No contato da empresa e colaborador use a tag com o nome da empresa, desta forma basta buscar pela tag “nome da empresa” para achar a empresa e seus colaboradores.
É recomendado o uso de tags.
Parâmetros (Inserir e Editar)
Parâmetro |
Tipo |
Tamanho |
Descrição |
Acao |
String |
10 |
Ação desejada (Inserir/Editar) (Obrigatório) |
VerificaEndereco |
String |
1 |
0 (Sem validação de endereço do correios) (Padrão: 0)
1 (Com validação de endereço do correios)
|
Compartilhamento |
String |
15.000 |
Emails de usuários que poderão ver o contato. Separados por vírgula.
(150 caracteres cada email)
Caso esteja vazio, o compartilhamento será com todos os usuários do sistema |
Integracao |
String |
50 |
Código de Integração do contato (Obrigatório) |
Nome |
String |
100 |
Apenas para Pessoa Física (Obrigatório para pessoa física) |
Sobrenome |
String |
120 |
Apenas para Pessoa Física |
CPF |
String |
11 |
Apenas para Pessoa Física. Sem pontos, barras ou traços |
RG |
String |
20 |
Apenas para Pessoa Física |
Sexo |
String |
1 |
F (Feminino) /M (Masculino). Apenas para Pessoa Física |
Nascimento |
String |
12 |
dd/mm/aaaa. Apenas para Pessoa Física |
Razao |
String |
120 |
Razão social. Apenas para Pessoa Jurídica (Obrigatório para pessoa jurídica) |
Fantasia |
String |
120 |
Nome fantasia. Apenas para Pessoa Jurídica |
CNPJ |
String |
14 |
Apenas para Pessoa Jurídica. Sem pontos, barras ou traços |
Tipo |
String |
1 |
F (Física) /J (Jurídica) (Obrigatório) |
Emails |
String |
150 |
Emails (Até 5 emails com 150 caracteres cada) |
Website |
String |
180 |
Website |
Endereco |
String |
120 |
Endereço |
Numero |
String |
20 |
Número |
Complemento |
String |
50 |
Complemento |
Bairro |
String |
100 |
Bairro |
Cidade |
String |
100 |
Cidade |
Estado |
String |
80 |
Estado |
CEP |
String |
10 |
CEP |
Pais |
String |
80 |
País |
Telefone-> Tipo |
String |
20 |
Tipo do telefone (Tipos aceitos: Residencial,
Comercial,
Celular,
Residencial Fax,
Fax,
Nextel,
Outros,
Celular Vivo,
Celular Oi,
Celular Tim,
Celular Claro,
Celular Sercontel,
Celular CTBC e
Celular Conecta) |
Telefone-> DDI |
String |
4 |
DDI |
Telefone-> DDD |
String |
4 |
DDD |
Telefone-> Telefone |
String |
24 |
Número do telefone |
Telefone-> Ramal |
String |
20 |
Ramal |
Redes |
String |
120 |
Redes Sociais com 120 caracteres cada |
Campos-> Título |
String |
50 |
Título dos Campos Personalizados com 50 caracteres cada |
Campos-> Valor |
String |
100 |
Valor dos Campos Personalizados com 100 caracteres cada |
Observacao |
String |
500 |
Observação |
Tag |
String |
1000 |
Tags separadas por vírgula e com 50 caracteres cada |
Automacao |
Inteiro |
|
1 (Somente no Inserir) |
TipoAutomacao->Nome |
String |
100 |
Nome do Tipo de Automação (Somente no Inserir) |
TipoAutomacao->Codigo |
String |
50 |
Código do Tipo de Automação (Somente no Inserir) |
Excluir contato
STRING JSON Padrão para exclusão de contato:
Ver Modelo
{
"Acao" : "Excluir",
"Integracao" : "",
"Compromissos_Agendados" : ""
}
Obs.: As tags, notas e negócios pertinentes a esse contato também serão removidos.
Obs.2: Caso exista mais de um registro com o mesmo código de integração, os mesmos serão excluídos.
Parâmetros (Excluir)
Parâmetro |
Tipo |
Tamanho |
Descrição |
Acao |
String |
10 |
Ação desejada (Excluir) (Obrigatório) |
Integracao |
String |
50 |
Código de Integração do contato (Obrigatório) |
Compromissos_Agendados |
String |
1 |
Remover também os compromissos agendados para os negócios
(1 = SIM/ 0 = NÃO) (Obrigatório) |
Editar Código de Integração
STRING JSON Padrão para editar código de integração de contato:
Ver Modelo
{
"Acao" : "EditarId",
"IdAtual" : "000",
"IdNovo" : "001"
}
Obs.: Caso exista mais de um registro com o mesmo código de integração, os mesmos serão editados.
Parâmetros (Editar Código de Integração)
Parâmetro |
Tipo |
Tamanho |
Descrição |
Acao |
String |
10 |
Ação desejada (EditarId) (Obrigatório) |
IdAtual |
String |
50 |
Código de Integração atual (Obrigatório) |
IdNovo |
String |
50 |
Código de Integração novo (Obrigatório) |