/
APIs gerais

APIs gerais

 

Índice

Gerenciador de Webservice 

ACESSO: Módulo Integradores → Menu Gerenciador de Webservices   

image-20250620-165217.png

No Gerenciador de webservice teremos três painéis 

  • Configuração de perfis de webservices

  • Atividades de webservice dos últimos 90 dias

  • Atividades de webservice com erro dos últimos 90 dias

  • Operadores com autorização específica dos serviços de autenticação de usuários.

  • Atividade de validações de usuários. (90 dias)

Configuração de perfis de webservices

Estes perfis irão compor regras para a utilização dos webservices do Sistema MK

No painel de configurações haverão ferramentas para o cadastro e edição de perfis de webservice. 

image-20250620-165253.png

Para criar um novo perfil clique no botão 'Inserir Novo Perfil'

No primeiro passo do assistente temos os seguintes dados:

  • Código - Código auto numerável atribuído pelo banco de dados (bloqueado para edição)

  • Ativo(SIM/NÃO) - Define se a regra está ativa

  • Data/Hora - Data e hora da criação do perfil (bloqueado para edição)

  • Operador - Operador que criou o perfil (bloqueado para edição)

  • Tempo de Expiração - Tempo em minutos de expiração do token de autenticação.

  • Invalidar(SIM/NÃO) - 

    • Marcando Sim neste campo, o token será invalidado a partir da sua utilização ou 

    • Caso contrário vai respeitar o tempo em minutos informado para ser considerado inválido.

  • Contra-senha - 

    • Contra-senha requisitada para a autenticação gerar o token de callback. 

    • O sistema irá sugerir uma contra-senha

    • A contra senha deve ter no mínimo 8 dígitos entre números e caracteres.

  • Descrição identificativa do perfil - Informe a descrição que irá identificar o perfil cadastrado em seu sistema.


Atenção

A liberação deste perfil é de sua inteira responsabilidade, assim como o consumo dos serviços a ele atrelados

Clique no botão 'Próximo' para seguir para o passo seguinte

Neste segundo passo, o operador poderá restringir a utilização dos webservices para determinados endereços de IPs.  

Clique no botão 'Adicionar IP à relação'

Para cada IP Address o operador deverá informar: 

  • IP Address - Número de IP autorizado.

  • Descrição/Observação - Descrições e observações identificativas que autorizaram este IP

Marque a opção "Tem certeza que deseja gravar este registro?" para confirmar e em seguida clique no botão 'Finalizar' para efetivar o cadastro do IP ao perfil.

Marque a opção 'Limitar consumo de serviços a lista de IPs' para obrigar a inserção de IPs ao perfil e para seja feita a restrição de acesso ao webservices. 

Clique no botão 'Próximo' para seguir para o passo seguinte

Nesse terceiro passo o operador poderá restringir a utilização dos Webservices por usuário do sistema.

Passe para o quadro direito os usuário que terão permissão. 

Atenção

A verificação do usuário na autenticação será feita sobre o token do seu cadastro

Clique no botão 'Próximo' para seguir para passo seguinte

Por fim, no último passo serão definidos os webservices autorizados para o perfil. 

Passe para o quadro direito os webservices que farão parte do perfil; 

Marque a opção "Tem certeza que deseja gravar este registro?" para confirmar a operação e clique no botão 'Finalizar' para efetivar o cadastro do perfil. 

Pronto! O perfil de Webservice foi cadastro. 

Atividades de webservice dos últimos 90 dias

Neste painel serão listadas as consultas de webservices realizadas com sucesso 

image-20250620-165402.png

Selecione o Consumo do Webservice no painel e clique no botão 'Detalhes da atividade' para obter maiores informações 

image-20250620-165432.png

Observe que no painel há outras opções de visualização de colunas. Veja na imagem abaixo

image-20250620-165501.png

Atividades de webservice com erro dos últimos 90 dias

Neste painel serão listadas as consultas de webservices realizadas e que ocorreram erro

image-20250620-165534.png

Selecione o Consumo do Webservice no painel e clique no botão 'Detalhes da atividade' para obter maiores informações 

image-20250620-165554.png

Observe que no painel há outras opções de visualização de colunas. Veja na imagem abaixo

image-20250620-165659.png

Operadores com autorização específica dos serviços de autenticação de usuários.

Neste painel teremos uma nova opção de cadastro. O cadastro irá funcionar de forma semelhante ao cadastro do perfil descrito anteriormente

image-20250620-165725.png

No entanto, na primeira etapa do cadastro, será necessário informar apenas 

  • Data Inicial - Data inicial da validade da regra

  • Data Final- Data final da validade da regra

  • Descrição identificativa do perfil - Informe a descrição que irá identificar o perfil cadastrado em seu sistema

Os próximos passos são iguais ao cadastro de perfil dos serviços gerais 

 

Atenção

A liberação deste perfil é de sua inteira responsabilidade, assim como o consumo dos serviços a ele atrelados

 

Atenção

Para campos que terão informações separadas por 'espaço' utilize aspas simples
É fundamental somente autorizar perfis de webservices em ambiente https por questões de segurança dos seus dados

Atividade de validações de usuários. (90 dias)

Neste painel teremos a listagem de todas as autentificações feitas pela URL WSAutenticacaoOperador (que utiliza o perfil de serviços especifico)

image-20250620-165753.png

AUTENTICAÇÃO

Para autorizações especificas 

Este é o autenticador para serviços específicos dos webservices abertos do MK

URL DE AUTENTICAÇÃO

http://IP:PORTA/mk/WSAutenticacaoOperador.rule?sys=MK0&username=Usuário&password=senhaUsuario

Parâmetros:

  • username - usuário de login do sistema (obrigatório)

  • password - senha do login do sistema (obrigatório)

Saída

Observação

Apenas os usuário definidos no perfil de webservices para serviços específicos que vão consegui realizar esta autenticação

Para autorizações em geral 

Este é o autenticador para serviços gerais dos webservices abertos do MK

URL DE AUTENTICAÇÃO

http://IP:PORTA/mk/WSAutenticacao.rule?sys=MK0&token=tokenDoUsuário&password=contrasenhaPerfil&cd_servico=codigoServico


Parâmetros:

  • token - token do cadastro de usuário 

  • password - senha do perfil do Webservice 

    image-20250620-165856.png

     

  • cd_servico - Código do Serviço de acordo com a tabela abaixo

Código Serviço

Serviço

Código Serviço

Serviço

1

Segunda via de boleto

4

Validar user/senha SAC

6

Consultar documento

7

Consulta de faturas pendentes

8

Contratos por cliente

9

Conexões por cliente

10

Classificações de atendimento

11

Processos de atendimentos

16

Estrutura de endereços

17

Consultar pessoa pelo nome

20

Consulta de fatura por código de barras

21

Linha digitável por fatura via SMS

Exemplo: 

http://IP:PORTA/mk/WSAutenticacao.rule?sys=MK0&token=tokenDoUsuário&password=senhaPerfil&cd_servico=1 

http://IP:PORTA/mk/WSAutenticacao.rule?sys=MK0&token=tokenDoUsuário&password=senhaPerfil&cd_servico=9999

Acima são dois exemplos, onde o cd_servico = 1 quer dizer que somente está pedindo autorização para o serviço 1 (Segunda via de boleto)

Já o serviço com cd_servico =  9999 quer dizer que há autorização para todos os serviços do perfil de autenticação

Saída

Exemplo de uma saída ao chamar o Webservice WSAutenticacao

Atenção

Através da Autenticação será retornado o tokenRetornoAutenticacao, será este token que os demais webservices utilizarão como parâmetro de entrada

Exemplo 01:

Observe que é exibido o tempo de expiração do token de autenticação e o limite de uso. No imagem acima informa que não há limite de uso até a data 23/09/219 e hora 18:23:57 e está autorizado apenas para o serviço 1 (cd_servico=1)

Exemplo 02:

Observe que é exibido o tempo de expiração do token de autenticação e o limite de uso. No imagem acima informa que não há limite de uso até a data 24/09/219 e hora 20:52:08 e está autorizado para todos os serviços do perfil (cd_servico = 9999)

OBTER INFO DO CLIENTE A PARTIR DO DOCUMENTO (CPF/CNPJ)

 

Serviço a ser selecionado dentro de seu perfil de webservice.

image-20250915-204846.png

URL PARA OBTER INFO DO CLIENTE A PARTIR DO DOCUMENTO

IP:PORTA/mk/WSMKConsultaDoc.rule?sys=MK0&token=tokenRetornoAutenticacao&doc=cpf/cnpj

Serviço: Consulta documento

Parâmetros:

  •  

    • token - token de retorno da autenticação (Obrigatório) 

    • doc - CPF ou CNPJ do cliente 

Saída

Exemplo de uma saída ao chamar o Webservice WSMKConsultaDoc

 

OBTER FATURAS PENDENTES DO CLIENTE

 

Serviço a ser selecionado dentro de seu perfil de webservice.

image-20250915-205031.png

 

URL PARA OBTER FATURAS PENDENTES

IP:PORTA/mk/WSMKFaturasPendentes.rule?sys=MK0&token=tokenRetornoAutenticacao&cd_cliente=codigoCliente

Serviço: Consulta de faturas pendentes

Parâmetros:

  •  

    • token - token de retorno da autenticação (Obrigatório)

    • cd_cliente - Código do Cliente (Obtido por WSMKConsultaDoc ou WSMKUserSenhaSAC)

Saída

Exemplo de uma saída ao chamar o Webservice WSMKFaturasPendentes

VALIDAR ACESSO SAC

 

Serviço a ser selecionado dentro de seu perfil de webservice.

image-20250915-205523.png

URL PARA VALIDAR ACESSO AO SAC

IP:PORTA/mk/WSMKUserSenhaSAC.rule?sys=MK0&token=tokenRetornoAutenticacao&user_sac=usuarioSAC&pass_sac=senhaSAC

Serviço: Validar user/senha SAC

Parâmetros:

  •  

    • token - token de retorno da autenticação (Obrigatório)

    • user_sac - Usuário do SAC

    • pass_sac - Senha do SAC

Saída

Exemplo de uma saída ao chamar o Webservice WSMKUserSenhaSAC

SEGUNDA VIA DE COBRANÇA

 

Serviço a ser selecionado dentro de seu perfil de webservice.

image-20250915-205611.png

URL PARA OBTER SEGUNDA VIA DE COBRANÇA

IP:PORTA/mk/WSMKSegundaViaCobranca.rule?sys=MK0&token=tokenRetornoAutenticacao&cd_fatura=codigoFatura

Serviço: Segunda via de boleto

Parâmetros:

  •  

    • token - token de retorno da autenticação (Obrigatório)

    • cd_fatura - Código da fatura (Obtido por WSMKFaturasPendentes)

Saída

Exemplo de uma saída ao chamar o Webservice WSMKSegundaViaCobranca

OBTER CONEXÕES DO CLIENTE

 

Serviço a ser selecionado dentro de seu perfil de webservice.

image-20250915-205735.png

URL PARA OBTER CONEXÕES PENDENTES

IP:PORTA/mk/WSMKConexoesPorCliente.rule?sys=MK0&token=tokenRetornoAutenticacao&cd_cliente=codigoCliente

Serviço: Conexões por cliente

Parâmetros:

  •  

    • token - token de retorno da autenticação (Obrigatório)

    • cd_cliente - Código do Cliente (Obtido por WSMKConsultaDoc ou WSMKUserSenhaSAC)

Saída

Exemplo de uma saída ao chamar o Webservice WSMKConexoesPorCliente

OBTER CONTRATOS DO CLIENTE

URL PARA OBTER CONTRATOS PENDENTES

IP:PORTA/mk/WSMKContratosPorCliente.rule?sys=MK0&token=tokenRetornoAutenticacao&cd_cliente=codigoCliente

Serviço: Contratos por cliente

Parâmetros:

  •  

    • token - token de retorno da autenticação (Obrigatório)

    • cd_cliente - Código do Cliente (Obtido por WSMKConsultaDoc ou WSMKUserSenhaSAC)

Saída

Exemplo de uma saída ao chamar o Webservice WSMKContratosPorCliente

OBTER CLASSIFICACÕES DE ATENDIMENTOS

URL PARA OBTER CLASSIFICAÇÕES DE ATENDIMENTO

IP:PORTA/mk/WSMKListaClassificacoesAte.rule?sys=MK0&token=tokenRetornoAutenticacao

Serviço: Classificações de atendimentos

Parâmetros:

  •  

    • token - token de retorno da autenticação (Obrigatório)

Saída

Exemplo de uma saída ao chamar o Webservice WSMKListaClassificacoesAte

OBTER LISTA DE PROCESSOS

URL PARA OBTER LISTA DE PROCESSO

IP:PORTA/mk/WSMKListaProcessos.rule?sys=MK0&token=tokenRetornoAutenticacao

Serviço: Processos de atendimentos

Parâmetros:

  •  

    • token - token de retorno da autenticação (Obrigatório)

Saída

Exemplo de uma saída ao chamar o Webservice WSMKListaProcessos

ESTRUTURA DE ENDERECOS

URL OBTER A ESTRUTURA DE ENDEREÇOS

IP:PORTA/mk/WSMKListaEstruturaEnderecos.rule?sys=MK0&token=tokenRetornoAutenticacao

Serviço: Estrutura de endereços

Parâmetros: 

  • token= token de retorno da autenticação (Obrigatório)

Saída

Exemplo de uma saída ao chamar o Webservice WSMKListaEstruturaEnderecos

CONSULTAR PESSOA PELO NOME 

CONSULTAR PESSOA PELO NOME

IP:PORTA/mk/WSMKConsultaNome.rule?sys=MK0&token=tokenRetornoAutenticacao&nome=nomeCliente

Serviço: Consulta pessoa pelo nome

Parâmetros: 

  • token -  token de retorno da autenticação (Obrigatório)

  • nome - Nome do cliente (Obrigatório)

Saída

CONSULTAR DE FATURA POR CÓDIGO DE BARRA

 

CONSULTAR PESSOA PELO NOME

IP:PORTA/mk/WSMKConsultaBarras.rule?sys=MK0&token=tokenRetornoAutenticacao&barras=codigoBarra

Serviço: Consulta de fatura por código de barras

Parâmetros: 

  • token -  token de retorno da autenticação (Obrigatório)

  • codigoBarra - Código de barras da fatura (Obrigatório) 

Saída

LINHA DIGITÁVEL POR FATURA VIA SMS

 

CONSULTAR PESSOA PELO NOME

IP:PORTA/mk/WSMKLDViaSMS.rule?sys=MK0&token=tokenRetornoAutenticacao&cd_fatura=codigoDaFatura

Serviço: Linha digitável por fatura via SMS

Parâmetros: 

  • token -  token de retorno da autenticação (Obrigatório)

  • codigoDaFatura - Código da fatura (Obrigatório) 

Saída

LISTAR CLIENTES

 

URL PARA CONSULTA DE CLIENTES

IP:PORTA/mk/WSMKConsultaClientes.rule?sys=MK0&token=tokenretornoautenticacao&doc=&codigo_bairro=&nome_cliente=&data_alteracao_inicio=&cd_cliente_inicio=&cd_cliente_fim=&cd_cliente=&data_alteracao_fim=