Gerenciamento de Categorias e Subcategorias

Gerenciamento de Categorias

Gerenciamento de Categorias e Subcategorias

Introdução

Esta API faz parte da integração de Notas para gerenciar as categorias e subcategorias que serão utilizadas nas mesmas.

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 decodificação do JSON, JSON Inválido.

Requisição inválida (Ação inválida. Ações aceitas: InserirCat/EditarCat/ExcluirCat/InserirSub/EditarSub/ExcluirSub.).

Dados Inválidos (Avisos).

401 Unauthorized

Descrição do Erro

Token obrigatório.

Token inválido.

Limite de requisições por minuto excedido. Tente novamente.

500 Internal Server Error

Descrição do Erro

Ocorreu um erro interno no servidor. Tente novamente.

Observações

Existem quatro categorias padrão de notas:

1100 - Telefone
2100 - E-mail
3100 - Reunião Interna
4100 - Reunião Externa

Estas categorias não podem ser excluídas e não podem ser editadas. Porém, suas subcategorias podem ser incluídas, editadas e excluídas.

As categorias das notas já existentes no sistema estão disponíveis para total gerenciamento.

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

Obter lista completa de categorias e subcategorias existentes

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

	
 {
        "Acao" : "Listar"
 }

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

	
 {
        "Categorias" : 
       	[
           {
              "IdCategoria" : "",
              "NomeCategoria" : "",
              "Quantidade" : "",
              "Subcategorias" : 
       			[
       				{ "IdSubcategoria" : "", "NomeSubcategoria" : "", "Quantidade" : ""},
       				{ "IdSubcategoria" : "", "NomeSubcategoria" : "", "Quantidade" : ""},
       				{ "IdSubcategoria" : "", "NomeSubcategoria" : "", "Quantidade" : ""},
       				{ "IdSubcategoria" : "", "NomeSubcategoria" : "", "Quantidade" : ""}
       			]
            }
       	]
 }

Obs.: Os itens "Quantidade" mostram a quantidade de notas que estão utilizando a categoria/subcategoria.

Inserir categorias

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

	
 {
        "Acao" : "InserirCat",
        "IdCategoria" : "",
        "NomeCategoria" : ""
 }

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

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

Obs3.: O nome da categoria deve ser único.

Parâmetros (InserirCat)

Parâmetro	Tipo	Tamanho	Descrição
Acao	String	10	Ação desejada (InserirCat) (Obrigatório)
IdCategoria	String	10	Código de integração da Categoria (Obrigatório)
NomeCategoria	String	100	Nome da Categoria (Obrigatório)

Inserir subcategorias (em uma categoria)

STRING JSON Padrão para inclusão de subcategorias em uma categoria:
Ver Modelo

	
 {
        "Acao" : "InserirSub",
        "IdCategoria" : "",
        "Subcategorias" : 
       			[
       				{ "IdSubcategoria" : "", "NomeSubcategoria" : ""},
       				{ "IdSubcategoria" : "", "NomeSubcategoria" : ""},
       				{ "IdSubcategoria" : "", "NomeSubcategoria" : ""},
       				{ "IdSubcategoria" : "", "NomeSubcategoria" : ""}
       			]
 }

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

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

Obs3.: O nome da subcategoria deve ser único por categoria (O mesmo nome pode existir em outra categoria).

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

Obs5.: As subcategorias enviadas serão adicionadas e não será excluída nenhuma já existente.

Parâmetros (InserirSub)

Parâmetro	Tipo	Tamanho	Descrição
Acao	String	10	Ação desejada (InserirSub) (Obrigatório)
IdCategoria	String	10	Código de integração da Categoria (Obrigatório)
Subcategorias->IdSubcategoria	String	10	Código de integração da Subcategoria (Obrigatório)
Subcategorias->NomeSubcategoria	String	100	Nome da Subcategoria (Obrigatório)

Editar categoria

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

 {
        "Acao" : "EditarCat",
        "IdCategoria" : "",
        "NomeCategoria" : ""
 }

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

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

Obs3.: O nome da categoria deve ser único.

Parâmetros (EditarCat)

Parâmetro	Tipo	Tamanho	Descrição
Acao	String	10	Ação desejada (EditarCat) (Obrigatório)
IdCategoria	String	10	Código de integração da Categoria (Obrigatório)
NomeCategoria	String	100	Nome da Categoria (Obrigatório)

Editar subcategoria

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

 {
        "Acao" : "EditarSub",
        "IdCategoria" : "",
        "IdSubcategoria" : "",
        "NomeSubcategoria" : ""
 }

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

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

Obs3.: O nome da subcategoria deve ser único por categoria (O mesmo nome pode existir em outra categoria).

Parâmetros (EditarSub)

Parâmetro	Tipo	Tamanho	Descrição
Acao	String	10	Ação desejada (EditarSub) (Obrigatório)
IdCategoria	String	10	Código de integração da Categoria (Obrigatório)
IdSubcategoria	String	10	Código de integração da Subcategoria (Obrigatório)
NomeSubcategoria	String	100	Nome da Subcategoria (Obrigatório)

Excluir categoria (e suas subcategorias)

STRING JSON Padrão para exclusão de categoria e suas subcategorias:
Ver Modelo

	
{
        "Acao" : "ExcluirCat",
        "IdCategoria" : ""
}

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

Obs2.: Caso exista mais de um registro com o mesmo código de integração de categoria, os mesmos serão excluídos.

Obs3.: Categorias que já estão sendo utilizadas não podem ser excluídas.

Parâmetros (ExcluirCat)

Parâmetro	Tipo	Tamanho	Descrição
Acao	String	10	Ação desejada (ExcluirCat) (Obrigatório)
IdCategoria	String	10	Código de integração da categoria (Obrigatório)

Excluir subcategorias (em uma categoria)

STRING JSON Padrão para exclusão de subcategorias em uma categoria:
Ver Modelo

	
 {
        "Acao" : "ExcluirSub",
        "IdCategoria" : "",
        "Subcategorias" : 
       			[
       				{ "IdSubcategoria" : ""},
       				{ "IdSubcategoria" : ""},
       				{ "IdSubcategoria" : ""},
       				{ "IdSubcategoria" : ""}
       			]
 }

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

Obs2.: Caso exista mais de um registro com o mesmo código de integração de subcategoria, os mesmos serão excluídos.

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

Obs4.: Subcategorias que já estão sendo utilizadas não podem ser excluídas.

Parâmetros (ExcluirSub)

Parâmetro	Tipo	Tamanho	Descrição
Acao	String	10	Ação desejada (ExcluirSub) (Obrigatório)
IdCategoria	String	10	Código de integração da Categoria (Obrigatório)
Subcategorias->IdSubcategoria	String	10	Código de integração da Subcategoria (Obrigatório)