CRM Zen

Integração de Notas (Entrada) Versão 1.0


Introdução

Esta API integra as notas dos contatos do sistema do cliente com as notas dos contatos do CRM Zen. Quando houver alguma ação no sistema do cliente referente às notas dos contatos, 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.: 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

Obs.: Caso ocorra alguma falha na requisição mantenha uma fila e tente novamente.

Na ocorrência de erros, a resposta será da seguinte forma: 

	
    {
    	"Erro" : "Código",
        "Mensagem" : "Descrição do erro"
     }


Mensagens de retorno

200 OK
Descrição do Erro
Sucesso.

400 Bad Request
Descrição do Erro
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.).
Dados Inválidos (Avisos).
Nota não encontrada para edição/exclusão

401 Unauthorized
Descrição do Erro
Token obrigatório.
Token inválido.

429 Too Many Requests
Descrição do Erro
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 5 segundos.

500 Internal Server Error
Descrição do Erro
Ocorreu um erro interno no servidor. Tente novamente.


Obs.: Mesmo não usando todos os parâmetros de cada requisição, é importante não remove-los.

Inserir nota

STRING JSON Padrão para inclusão de nota:
Ver Modelo


Obs.: Cada requisição recebe uma string JSON com dados de somente uma nota de um contato.

Obs2.: O código de integração da nota deve ser único.

Obs3.: O nó Categorias pode conter até 50 itens

Obs4.: O nó Subcategorias pode conter até 30 itens


Editar nota

STRING JSON Padrão para edição de nota:
Ver Modelo


Obs.: Cada requisição recebe uma string JSON com dados de somente uma nota de um contato.

Obs2.: Caso exista mais de um registro com o mesmo código de integração de nota, os mesmos serão editados.

Obs3.: As categorias e subcategorias existentes serão substituídas pelas enviadas na edição.

Obs4.: O nó Categorias pode conter até 50 itens

Obs5.: O nó Subcategorias pode conter até 30 itens


Parâmetros (Inserir e Editar)

Parâmetro Tipo Tamanho Descrição
Acao String 10 Ação desejada (Inserir/Editar) (Obrigatório)
Compartilhamento String 15.000 Emails de usuários que poderão ver a nota do 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)
IdNota String 10 Código de integração da nota (Obrigatório)
Texto String 5.000 Texto da nota (Obrigatório)
Data String 10

Data de criação da nota (na ação Inserir) (Se vazio, será gravado como a data de envio)
Data de edição da nota (na ação Editar) (Se vazio, será gravado como a data de envio)
Horario String 8

Horário de criação da nota (na ação Inserir) (Se vazio, será gravado como o horário de envio)
Horário de edição da nota (na ação Editar) (Se vazio, será gravado como o horário de envio)
Categorias->IdCategoria* String 10 Código de integração da categoria (Obrigatório pelo menos um)
Subcategorias->IdSubcategoria* String 10 Código de integração da subcategoria

* Veja na aba Gerenciamento de Categorias como gerenciar Categorias e Subcategorias


Excluir nota

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


Obs.: Cada requisição recebe uma string JSON com dados de somente uma nota de um contato.

Obs2.: 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)
IdNota String 10 Código de integração da nota (Obrigatório)