Esse documento tem como objetivo descrever as APIs disponíveis no produto CRM.
Para testar os endpoints disponibilizamos uma documentação utilizando a ferramenta swagger, no seguinte link:
http://crm-dev.viasoftcloud.com.br/api/swagger-ui/index.html# (Ainda não disponível).
Primeiramente, é necessário gerar um token de acesso através do endpoint “oauth/token”, conforme exemplo a seguir.
Essa requisição deve retornar a seguinte resposta:
O token de acesso tem duração de duas horas, e deve ser utilizado para realizar as demais requisições. Para isso, deve-se clicar no botão “Authorize”, na parte superior da página, colar o token gerado e clicar novamente em “Authorize”.
Feito isso, o usuário estará autenticado para realizar as demais requisições
Caso o usuário possua acesso à diversas empresas, é possível também especificar em qual deseja se autenticar. Para isso, basta informar o campo “idClient” no corpo da requisição, informando o código da empresa, conforme exemplo:
Para saber o código da empresa, pode-se utilizar o endpoint empresas-do-usuario. Conforme exemplo a seguir:
A resposta irá retornar todas as empresas que o usuário possui acesso:
Com isso o usuário poderá fazer as demais requisições da API.
Principais requisições:
/metadados (GET) → Essa requisição tem como objetivo mostrar quais são os campos da entidade e suas principais caracaterísticas. Onde são definidos o nome do campo, seu tipo, tamanho máximo, e se ele é obrigatório ou não. Além disso, ela também mostra quais são os campos filtráveis e os campos ordenáveis para a entidade.
Abaixo temos um exemplo de resposta para uma reuisição para o caminho “/metadados”.
{ "nomeClasse": "br.com.viasoft.cadastroscrm.features.moeda.entity.Moeda", "campos": [ { "nome": "id", "tipoCampo": "NUMERICO", "requerido": true }, { "nome": "simbolo", "tipoCampo": "TEXTO", "tamanhoMaximo": 3, "requerido": true }, { "nome": "descricao", "tipoCampo": "TEXTO", "tamanhoMaximo": 20, "requerido": true }, { "nome": "codigo_externo", "tipoCampo": "TEXTO", "tamanhoMaximo": 100, "requerido": false } ], "filtros": [ { "rotulo": "simbolo", "opcoesComparacao": [ "TODOS_TIPO_STRING" ] }, { "rotulo": "Descrição da Moeda", "opcoesComparacao": [ "TODOS_TIPO_STRING" ] } ], "ordenacoes": [ { "rotulo": "descricao" } ] }
A descrição da opção de comparação TODOS_TIPO_STRING
remete ao fato que esse campo pode ser filtrado por todas as opções
COMECA_COM, CONTEM, IGUAL
/pesquisar (POST) → Essa requisição tem como objetivo trazer os registros de forma paginada, ordenados e filtrados conforme necessidade do usuário. Abaixo temos um exemplo de como deve ser o corpo da requisição enviada.
{ "pagina": 1, "quantidadeRegistros": 10, "ordenacao": [ { "campo": "simbolo", "ordenacao": "ASC" } ], "filtros": [ { "campo": "descricao", "comparacao": "IGUAL", "valor": "Francos Franceses" } ] }
Deste modo o sistema irá retornar os 10 primeiros registros, ordenados por símbolo de maneira ascendente e com descrição igual a “Francos Franceses”.
Abaixo temos um exemplo de retorno da requisição.
{ "pagina": 1, "registros": [ { "id": 3, "simbolo": "FR$", "descricao": "Francos Franceses" } ], "total_registros": 1 }