CRM Zen

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.

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
  • Sucesso
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.
  • Limite de 120 requisições por minuto excedido. Tente novamente.

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

Obs.: O código de integração do contato deve ser único.


Editar contato

STRING JSON Padrão para edição de contato do tipo Pessoa Física e Pessoa Jurídica:
Ver Modelo

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




Excluir contato

STRING JSON Padrão para exclusão de contato:
Ver Modelo

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

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)
IdAntigo String 50 Código de Integração atual (Obrigatório)
IdNovo String 50 Código de Integração novo (Obrigatório)