Integração de Calendário (Entrada)

Calendário (Entrada)

Integração de Calendário (Entrada) Versão 1.0

Introdução

Esta API integra os eventos do sistema do cliente com os eventos do CRM Zen. Quando houver alguma ação no sistema do cliente referente aos eventos, 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).

Evento não encontrado 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 removê-los.

Obter lista completa de status

STRING JSON Padrão para fazer a requisição da lista de status:
Ver Modelo

	
 {
        "Acao" : "Listar",
        "Tipo" : "Status"
 }

STRING JSON Padrão de resposta com a lista de status:
Ver Modelo

	
 {
        "Status" : 
       	[
           {
              "Nome" : "",
              "Codigo" : ""
            },
           {
              "Nome" : "",
              "Codigo" : ""
            }
       	]
 }

Obter lista completa de categorias

STRING JSON Padrão para fazer a requisição da lista de categorias:
Ver Modelo

	
 {
        "Acao" : "Listar",
        "Tipo" : "Categorias"
 }

STRING JSON Padrão de resposta com a lista de categorias:
Ver Modelo

	
 {
        "Categorias" : 
       	[
           {
              "Nome" : "",
              "Codigo" : ""
            },
           {
              "Nome" : "",
              "Codigo" : ""
            }
       	]
 }

Obter lista completa de salas

STRING JSON Padrão para fazer a requisição da lista de salas:
Ver Modelo

	
 {
        "Acao" : "Listar",
        "Tipo" : "Salas"
 }

STRING JSON Padrão de resposta com a lista de salas:
Ver Modelo

	
 {
        "Salas" : 
       	[
           {
              "Nome" : "",
              "Codigo" : ""
            },
           {
              "Nome" : "",
              "Codigo" : ""
            }
       	]
 }

Inserir evento

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

 {
        "Acao" : "Inserir",
        "Compartilhamento" : "",
        "Integracao" : "",
        "Titulo" : "",
        "Data_Inicial" : "",
        "Data_Final" : "",
        "Aniversario" : "",
        "Hora_Inicial" : "",
        "Hora_Final" : "",
        "Lembrete" : {
                       "Quantidade":"",
                       "Tipo":"",
                       "Aviso_Sonoro":""
                     },
        "Local" : "",
        "Sala" : {
                   "Nome" : "",
                   "Codigo" : ""
                 },
        "Categoria" : [
                        { "Nome" : "", "Codigo" : "" },
                        { "Nome" : "", "Codigo" : "" },
                        { "Nome" : "", "Codigo" : "" }
                      ],
        "Status" : {
                     "Nome" : "",
                     "Codigo" : ""
                   },
        "Recorrencia" : {
                         "Repetir" : "",
                         "Ate" : ""
                        },
        "Contatos_Associados" : [
                                 { "Integracao" : "" },
                                 { "Integracao" : "" }
                                ],
        "Observacao" : "",
        "Tag" : "",
        "Notas_Vinculadas" : [
                               { "Integracao" : "" },
                               { "Integracao" : "" }
                             ]
 }

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

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

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

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

Obs5.: O nó Notas Vinculadas pode conter até 50 itens

Obs6.: Caso a sala, status e/ou categoria não exista, será criada. Use a requisição de listagem para verificar.

Obs7.: Uma nota só pode ser vinculada à um evento.

Editar evento

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

 {
        "Acao" : "Editar",
        "Compartilhamento" : "",
        "Integracao" : "",
        "Titulo" : "",
        "Data_Inicial" : "",
        "Data_Final" : "",
        "Aniversario" : "",
        "Hora_Inicial" : "",
        "Hora_Final" : "",
        "Lembrete" : {
                       "Quantidade":"",
                       "Tipo":"",
                       "Aviso_Sonoro":""
                     },
        "Local" : "",
        "Sala" : {
                   "Nome" : "",
                   "Codigo" : ""
                 },
        "Categoria" : [
                        { "Nome" : "", "Codigo" : "" },
                        { "Nome" : "", "Codigo" : "" },
                        { "Nome" : "", "Codigo" : "" }
                      ],
        "Status" : {
                     "Nome" : "",
                     "Codigo" : ""
                   },
        "Recorrencia" : {
                         "Repetir" : "",
                         "Ate" : ""
                        },
        "Contatos_Associados" : [
                                 { "Integracao" : "" },
                                 { "Integracao" : "" }
                                ],
        "Observacao" : "",
        "Tag" : "",
        "Notas_Vinculadas" : [
                               { "Integracao" : "" },
                               { "Integracao" : "" }
                             ]
 }

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

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

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

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

Obs5.: O nó Notas Vinculadas pode conter até 50 itens

Obs6.: Caso a sala, status e/ou categoria não exista, será criada. Use a requisição de listagem para verificar.

Obs7.: Uma nota só pode ser vinculada à um evento.

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 o evento. 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 evento (Obrigatório)
Titulo	String	100	Título do evento (Obrigatório)
Data_Inicial	String	10	Data inicial do evento (Se vazio, será gravado como a data de envio)
Data_Final	String	10	Data final do evento (Se vazio, será gravado como a data de envio)
Aniversario	String	1	0 (Não é aniverário) (Padrão: 0) 1 (É aniversário)
Hora_Inicial	String	8	Hora inicial do evento (Padrão: 8:00)
Hora_Final	String	8	Hora final do evento (Padrão: 30 minutos a mais da Hora Inicial)
Lembrete->Quantidade	Inteiro		Exemplo: 15 (15 dias)
Lembrete->Tipo	String	7	Tipos aceitos: minutos, horas, dias, semanas
Lembrete->Aviso_Sonoro	String	1	1 = Criar aviso sonoro no desktop para todos os usuários que podem ver o evento 0 = Não criar aviso sonoro
Local	String	256	Local do evento
Sala->Nome	String	50	Nome da sala
Sala->Codigo	String	50	Código da sala
Categoria->Nome	String	100	Nome da Categoria
Categoria->Codigo	String	50	Código da Categoria
Status->Nome	String	70	Status do evento
Status->Codigo	String	50	Código do Status
Recorrencia->Repetir	String	12	Tipos aceitos: nunca, diariamente, semanalmente, mensalmente, anualmente. (Padrão: nunca)
Recorrencia->Ate	String	10	Data final da recorrência
Contatos_Associados->Integracao	String	50	Códigos de integração dos contatos associados ao evento
Observacao	String	1000	Observação
Tag	String	1000	Tags separadas por vírgula e com 50 caracteres cada
Notas_Vinculadas->Integracao	String	50	Códigos de integração das notas associadas ao evento

Excluir evento

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

	
{
        "Acao" : "Excluir",
        "Integracao" : "",
}

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

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 evento (Obrigatório)