A API do SMV foi desenvolvida visando a possibilidade de automação de integrações com o sistema SMV 3.0 da V2 Consulting, e poderá ser utilizada por todo cliente do serviço, mediante autenticação.
Sua utilização é através de chamada simples com padrão de dados JSON, via GET de URL, podendo dessa maneira ser utilizada por um grande número de plataformas.
A autenticação na API gera um token único e personalizado, que poderá ser utilizado por até 5 minutos. Após esse tempo o token será automaticamente inutilizando, havendo a necessidade de nova autenticação.
Você pode testar a API através da versão de tela, acessando o link abaixo. Ela deixa mais clara a forma como os parâmetros são enviados e recebidos, e também pode ser um bom auxílio no entendimento desse fluxo.
http://api.smvv2.com.br/callapisample.html
Estrutura de Chamada
A estrutura da chamada, como dito anteriormente, é realizada através de url com padrão de dados JSON, conforme esquema abaixo:
Os parâmetros utilizados dependerão do método da API desejado, informado através de “apikey”.
{ login: xxxxxxxx@xxxxxx.xxx.xx
, password: *********
, apikey: <chave hexa>
, start_date: aaaa-mm-dd
, end_date: aaaa-mm-dd
, clie_id: <-1,n>
, cnta_id: <-1,n>
, serv_id: <-1,n>
, date_mode: <0,1>
, exp_mode: <-1,0,1>
, user_id: <SMV ID>
, token: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
, format: <json|xml>
}
Estrutura de Resposta
Todas as respostas serão enviadas em formado XML ou JSON.
No caso do XML, a primeira tag sendo sempre <error>, informativa do sucesso ou insucesso da chamada. Seguindo-se a ela, a tag <records> trará os dados relativos à chamada
<xml>
<error code='0' msg='ok' />
<records></records>
</xml>
De forma análoga, as mensagens JSON também informarão o código de retorno de erro ou sucesso, seguido da informação solicitada:
{
"returnNumber": "0",
… dados json…
}
Códigos e Mensagens de Retorno
| CÓDIGO | MENSAGEM | DESCRIÇÃO |
| 0 | Ok | A chamada ocorreu com sucesso |
| -100 | Login não informado. Impossível autenticar | Não foi informado o login de usuário para a API de autenticação |
| -101 | Senha não informada. Impossível autenticar | Não foi informada a senha do usuário para a API de autenticação |
| -1 | Falha de autenticação. Usuário inexistente | Não foi encontrado no SMV o usuário informado |
| -2 | Falha de autenticação. Usuário bloqueado | O usuário informado encontra-se bloqueado no SMV |
| -3 | Falha de autenticação. Usuário expirado | O usuário informado encontra-se expirado no SMV |
| -4 | Falha de autenticação. Usuário inativo | O usuário informado encontra-se inativo no SMV |
| -5 | Senha incorreta. Restam n tentativas | Senha informada está incorreta. O sistema bloqueia o usuário após 3 tentativas |
| -8 | ID SMV inválido ou não informado | Não foi informado corretamente o ID SMV na chamada da API |
| -9 | Token inválido ou não informado | Não foi informado o Token na chamada da API ou o mesmo não é mais válido |
| -11 | ID Cliente inválido ou não informado | Não foi informado corretamente o ID Cliente na chamada da API |
| -12 | ID Conta inválido ou não informado | Não foi informado corretamente o ID Conta na chamada da API |
| -13 | ID Serviço inválido ou não informado | Não foi informado corretamente o ID Serviço na chamada da API |
| -14 | Data Inicial não informada | Não foi informada a Data Inicial na chamada da API |
| -15 | Data Final não informada | Não foi informada a Data Final na chamada da API |
| -16 | Data Final deve ser maior ou igual à Data Inicial | Foi informada uma Data Final menor do que a Data Inicial na chamada da API |
| -17 | Modo de Data não informado ou inválido | Não foi informado o Modo de Data (0-Data Monitoria ou 1-Data da Ligação) na chamada da API |
| -18 | Modo Experiência não informado ou inválido | Não foi informado o Modo Experiência (0-Agentes fora do Período de Experiência, 1-Agentes dentro do período de experiência ou -1 Ambos) na chamada da API |
| -19 | Período inválido. Tente diminuir o período de datas. | Foi informado um período de datas superior a 31 dias na chamada da API |
Métodos
Os métodos são informados através do parâmetro apikey, e determinam quais parâmetros devem ser obrigatórios na chamada. Cada método possui uma chave correspondente, que deve ser informada no campo apikey Abaixo, apresentamos cada método e seus parâmetros.
Chamadas
As chamadas são realizadas através de URL, com protocolo seguro SSL, conforme exemplo abaixo:
xmlhttp.open("GET", ‘https://api.smvv2.com.br/api.asp?’ + <string_json_parametros>, true)
xmlhttp.setRequestHeader("Content-Type", "application/json")
Autenticação
É o primeiro método a ser chamado. É através dele que o sistema identifica se o usuário está apto a utilizar a API, e o retorno dele fornece duas informações indispensáveis a todas as outras chamadas, o ID SMV e o TOKEN.
O ID SMV é seu ID de usuário dentro do SMV, e o TOKEN é o responsável por informar à API que trata-se de uma chamada previamente autorizada. O TOKEN tem validade de 5 minutos, depois dos quais, será necessária uma nova chamada de autenticação para o recebimento de um novo TOKEN.
CHAVE: 0B1269239389EC54E4750E30D35B5B33CCFCFE819FADF7F8112F5715F467EC84
PARÂMETROS: {login, password, apikey}
EXEMPLO:
Chamada
{
login: teste@meudominio.com.br,
password: Senha@123,
apikey: 0B1269239389EC54E4750E30D35B5B33CCFCFE819FADF7F8112F5715F467EC84
}
Retorno
<xml>
<error code='0' msg='ok'/>
<records>
<auth token='80E2848E74CA7F7FCDD27FDFA800807E624802D076201BCDAA5CE890AD8F8795'
smv_id='12345'>
</records>
</xml>
Clientes
Através desta chamada, serão obtidos os Cliente aos quais o usuário autenticado possui acesso, com os respectivos ID CLIENTE (clie_id) de cada um, que serão utilizados em chamadas subsequentes.
CHAVE: 936181F75549D56EAF4DEE9B6BF6DC7BDD30F88A014D947FD02EE9C67829A1B4
PARÂMETROS: {smv_id, token, apikey}
EXEMPLO:
Chamada
{
smv_id:12345,
token= 80E2848E74CA7F7FCDD27FDFA800807E624802D076201BCDAA5CE890AD8F8795,
apikey: 936181F75549D56EAF4DEE9B6BF6DC7BDD30F88A014D947FD02EE9C67829A1B4
}
Retorno
<xml>
<error code='0' msg='ok' />
<records>
<row clie_id="1234" clie_nome="Cliente 1"/>
<row clie_id="2341" clie_nome="Cliente 2"/>
<row clie_id="3412" clie_nome="Cliente 3"/>
<row clie_id="4123" clie_nome="Cliente 4"/>
</records>
</xml>
Contas
Através desta chamada, serão obtidas as Contas às quais o usuário autenticado possui acesso, com os respectivos ID CONTA (cnta_id) de cada uma, que serão utilizados em chamadas subsequentes. As contas devolvidas dependerão do parâmetro ID CLIENTE informado. Se o ID CLIENTE informado for -1, as contas de todos os clientes aos quais o usuário possuir acesso serão apresentadas.
CHAVE: EBB71E7A75C4039AE0EF3F3B9B6DD789B9D7BBD26C29C739B575EDBAA3E6AAB6
PARÂMETROS: { smv_id, token, <id_clie | -1>, apikey}
Chamada
{
smv_id:12345,
token= 80E2848E74CA7F7FCDD27FDFA800807E624802D076201BCDAA5CE890AD8F8795,
clie_id=-1,
apikey: EBB71E7A75C4039AE0EF3F3B9B6DD789B9D7BBD26C29C739B575EDBAA3E6AAB6
}
Retorno:
<xml>
<error code='0' msg='ok' />
<records>
<row clie_id="1234" cnta_id="1111" cnta_nome="Conta 1"/>
<row clie_id="1234" cnta_id="2222" cnta_nome="Conta 2"/>
<row clie_id="2341" cnta_id="3333" cnta_nome="Conta 3"/>
<row clie_id="2341" cnta_id="4444" cnta_nome="Conta 4"/>
<row clie_id="3412" cnta_id="5555" cnta_nome="Conta 5"/>
<row clie_id="4123" cnta_id="6666" cnta_nome="Conta 6"/>
</records>
</xml>
Serviços
Através desta chamada, serão obtidos os Serviços aos quais o usuário autenticado possui acesso, com os respectivos ID SERVICO (serv_id) de cada um, que serão utilizados em chamadas subsequentes. Os serviços devolvidos dependerão do parâmetro ID CONTA e ID CLIENTE informado. Se o ID CONTA informado for -1, os serviços de todas as contas do cliente informado (ou de todos os clientes se ID CLIENTE for -1) aos quais o usuário possuir acesso serão apresentados.
CHAVE: A673F93EF115771004D754C3C1F92A8A9EDA916F2FF169A4E1DFEF9AFC9B4CDB
PARÂMETROS: {smv_id, token, <clie_id |-1>, <cnta_id | -1>, apikey}
Chamada
{
smv_id:12345,
token= 80E2848E74CA7F7FCDD27FDFA800807E624802D076201BCDAA5CE890AD8F8795,
clie_id=-1,
cnta_id=-1,
apikey: A673F93EF115771004D754C3C1F92A8A9EDA916F2FF169A4E1DFEF9AFC9B4CDB
}
Retorno
<xml>
<error code='0' msg='ok' />
<records>
<row clie_id="1234" cnta_id="1111" serv_id="199999" serv_nome="Serviço 1"/>
<row clie_id="1234" cnta_id="1111" serv_id="299999" serv_nome="Serviço 2"/>
<row clie_id="1234" cnta_id="2222" serv_id="399999" serv_nome="Serviço 3"/>
<row clie_id="1234" cnta_id="2222" serv_id="499999" serv_nome="Serviço 4"/>
<row clie_id="2341" cnta_id="3333" serv_id="599999" serv_nome="Serviço 5"/>
<row clie_id="2341" cnta_id="4444" serv_id="699999" serv_nome="Serviço 6"/>
</records>
</xml>
Relatório de Monitorias
Esta chamada retorna os mesmos dados que são obtidos dentro do sistema SMV através do Relatório de Monitorias.
CHAVE: F814379368FC97F2DBEE05B58080B747513006C01A940B036B1828A9A3EAF82A
PARÂMETROS: {smv_id, token, <clie_id | -1>, <cnta_id | -1>, <serv_id | -1>, start_date, end_date, date_mode, exp_mode}
Chamada
{
smv_id:12345,
token= 80E2848E74CA7F7FCDD27FDFA800807E624802D076201BCDAA5CE890AD8F8795,
clie_id=-1,
cnta_id=-1,
serv_id=-1,
start_date=2020-10-01,
end_date=2020-10-31,
date_mode=0,
exp_mode=-1
apikey: F814379368FC97F2DBEE05B58080B747513006C01A940B036B1828A9A3EAF82A
}
Retorno
<xml>
<error code='0' msg='ok' />
<records>
<row Data="26/08/2020 18:02:37" DataLigacao="26/08/2020 10:00:00"
Conta="Conta Teste - V2" Servico="Serviço X - V2" Equipe="Sup Final"
Monitor="Danilo da Silva Lima" Experiencia="NÃO" Colaborador="Agente Final1"
Questionario="Teste - Formulário Normal." TMA="00:00" ArqMonitoria="x"
Final="100.00" Padrão="100.00" Padrão2="100.00" NCG="0.00" ID="7971341"
Quantidade="1" UserID="15846" formulario="715"/>
<row Data="26/08/2020 17:57:18" DataLigacao="26/08/2020 10:00:00"
Conta="Conta Teste - V2" Servico="Serviço X - V2" Equipe="Sup Final"
Monitor="Danilo da Silva Lima" Experiencia="NÃO" Colaborador="Agente Final1"
Questionario="Teste - Formulário Normal." TMA="00:30" ArqMonitoria="teste"
Final="100.00" Padrão="100.00" Padrão2="100.00" NCG="0.00" ID="7971337"
Quantidade="1" UserID="15846" formulario="715"/>
<row Data="26/08/2020 14:59:15" DataLigacao="26/08/2020 10:00:00"
Conta="Conta Teste - V2" Servico="Serviço X - V2" Equipe="Sup Final"
Monitor="Danilo da Silva Lima" Experiencia="NÃO" Colaborador="Agente Final1"
Questionario="Teste - Formulário Normal." TMA="01:00" ArqMonitoria="x"
Final="100.00" Padrão="100.00" Padrão2="100.00" NCG="0.00" ID="7970946"
Quantidade="1" UserID="15846" formulario="715"/>
</records>
</xml>
Extração de Base (Parte 1, 2 e 3)
Esta chamada retorna os mesmos dados que são obtidos dentro do sistema SMV através da Extração de Base, e cada “workbook” do Excel é contemplado em uma das 3 partes da chamada.
CHAVES:
Parte 1 - Monitorias - 8AC3423419845502FA26CA94F62732AB7A612BD0B1CA90F2C944CD9A419A99D9
Parte 2 - Questões - 92AD318C763D3C4A8A5F80467F0230073ADE9FC13A8753213B631EA1B624D110
Parte 3 - Subquestões - AAE63F32D39656A17877F0D92E9FB0F1797D0904BF9963ECC19B56C905A1990B
PARÂMETROS: {smv_id, token, <clie_id | -1>, <cnta_id | -1>, <serv_id | -1>, start_date, end_date, date_mode}
Chamada
{
smv_id:12345,
token=80E2848E74CA7F7FCDD27FDFA800807E624802D076201BCDAA5CE890AD8F8795,
clie_id=-1,
cnta_id=-1,
serv_id=-1,
start_date=2020-10-01,
end_date=2020-10-31,
date_mode=0,
exp_mode=-1
apikey: 8AC3423419845502FA26CA94F62732AB7A612BD0B1CA90F2C944CD9A419A99D9
}
Retorno
<xml>
<error code='0' msg='ok' />
<records>
<row IDMonitoria="8077852" Formulário="Teste - Formulário Normal." Cliente="V2 - Cliente Teste" Conta="Conta Teste - V2" Servico="Serviço X - V2" Equipe="Sup Final" Agente="Danilo da Silva Lima" Per.Exp.="Não" DataMonit.="2021-01-04T18:05:29.037" DataLigacao="2021-01-04T10:00:00" TMA="01:30" ArquivoMonitoria="x" CPF="x" NomeContato="x" Canal="A" TipoContato="Ativo" Processo="Alteração Dados Bancários" Produto="Abastecimento." ClassAlter1="A" ClassAlter2="Ativo" ClassAlter3="A" ManifestCliente="-" DescManifest="" Nota10="NÃO" DescNota10="" ResumoMonitoria="x" PontosDesenvolver="" PontosPositivos="" Monitor="Danilo da Silva Lima" NotaFinal="100.0" QtdErrosGraves="0.0" NotaFinalSemErrosGraves="100.0"/>
<row IDMonitoria="8082311" Formulário="Teste - Formulário Normal." Cliente="V2 - Cliente Teste" Conta="Conta Teste - V2" Servico="Serviço X - V2" Equipe="Sup Final" Agente="Danilo da Silva Lima" Per.Exp.="Não" DataMonit.="2021-01-11T11:40:06.607" DataLigacao="2021-01-11T10:00:00" TMA="01:30" ArquivoMonitoria="x" CPF="x" NomeContato="x" Canal="A" TipoContato="Ativo" Processo="Alteração Dados Bancários" Produto="Abastecimento." ClassAlter1="A" ClassAlter2="Ativo" ClassAlter3="A" ManifestCliente="-" DescManifest="" Nota10="NÃO" DescNota10="" ResumoMonitoria="x" PontosDesenvolver="" PontosPositivos="" Monitor="Danilo da Silva Lima" NotaFinal="100.0" QtdErrosGraves="0.0" NotaFinalSemErrosGraves="100.0"/>
<row IDMonitoria="8082293" Formulário="Teste - Formulário Normal." Cliente="V2 - Cliente Teste" Conta="Conta Teste - V2" Servico="Serviço X - V2" Equipe="Sup Final" Agente="Agente Final1" Per.Exp.="Não" DataMonit.="2021-01-11T11:33:52.807" DataLigacao="2021-01-11T10:00:00" TMA="01:30" ArquivoMonitoria="x" CPF="x" NomeContato="x" Canal="A" TipoContato="Ativo" Processo="Alteração Dados Bancários" Produto="Abastecimento." ClassAlter1="A" ClassAlter2="Ativo" ClassAlter3="A" ManifestCliente="-" DescManifest="" Nota10="NÃO" DescNota10="" ResumoMonitoria="x" PontosDesenvolver="" PontosPositivos="" Monitor="Danilo da Silva Lima" NotaFinal="100.0" QtdErrosGraves="0.0" NotaFinalSemErrosGraves="100.0"/>
</records>
</xml>
Relatório de Contestação
Esta chamada retorna os mesmos dados que são obtidos dentro do sistema SMV através do relatório de Contestação.
CHAVES: A8FFE8ADDFAF56265EDF778F53C522AACC78AB37E79E5DA0BD3E2EA9671E0D8B
PARÂMETROS: {smv_id, token, <clie_id | -1>, <cnta_id | -1>, <serv_id | -1>, start_date, end_date, date_mode}
Chamada
{
smv_id:12345,
token=80E2848E74CA7F7FCDD27FDFA800807E624802D076201BCDAA5CE890AD8F8795,
clie_id=-1,
cnta_id=-1,
serv_id=-1,
start_date=2020-10-01,
end_date=2020-10-31,
date_mode=0,
exp_mode=-1
apikey: A8FFE8ADDFAF56265EDF778F53C522AACC78AB37E79E5DA0BD3E2EA9671E0D8B
}
Retorno
<xml>
<error code='0' msg='ok' />
<records>
<row CriadaEm="Feb 8 2021 10:51AM" CriadoPor="Danilo da Silva Lima" DataMonit="Dec 1 2020 10:37AM"
UltimoEvento="Feb 8 2021 10:51AM" Status="Criação. Aguardando Resposta da Monitoria"
Resultado="Não Pertinente" EncerradoPro="-" Servico="SAC" Equipe="Carla Santos" Agente="João"
Monitor="Danilo da Silva Lima" moni_id="8051867" />
</records>
</xml>
Relatório de Feedback
Esta chamada retorna os mesmos dados que são obtidos dentro do sistema SMV através do relatório de Feedback.
CHAVES: DDEF92E8AF8E7409BA735F654FD1746616F945E333DB7D346997C794DD1084DD
PARÂMETROS: {smv_id, token, <clie_id | -1>, <cnta_id | -1>, <serv_id | -1>, start_date, end_date, date_mode}
Chamada
{
smv_id:12345,
token=80E2848E74CA7F7FCDD27FDFA800807E624802D076201BCDAA5CE890AD8F8795,
clie_id=-1,
cnta_id=-1,
serv_id=-1,
start_date=2020-10-01,
end_date=2020-10-31,
date_mode=0,
exp_mode=-1
apikey: DDEF92E8AF8E7409BA735F654FD1746616F945E333DB7D346997C794DD1084DD
}
Retorno
<xml>
<error code='0' msg='ok' />
<records>
<row Monitoria="8051867" Cliente="V2 - Cliente Teste" Conta="Central de Atendimento" Servico="SAC"
Equipe="Carla Santos" Agente="João" Monitor="Danilo da Silva Lima" DataLigacao="Dec 1 2020 10:00AM"
DataMonitoria="Dec 1 2020 10:37AM" NotaFinal="100.00" NCG="Não" Pontualidade="-" AtrasoHrs="0.00"
Status="Aguardando Agente" EmContestacao="Sim" Observacao="" DataLimiteFB="Dec 4 2020 10:37AM" />
<row Monitoria="8051878" Cliente="V2 - Cliente Teste" Conta="Central de Atendimento" Servico="SAC"
Equipe="Carla Santos" Agente="José" Monitor="Danilo da Silva Lima" DataLigacao="Dec 1 2020 10:00AM"
DataMonitoria="Dec 1 2020 10:40AM" NotaFinal="50.00" NCG="Não" Pontualidade="-" AtrasoHrs="0.00"
Status="Aguardando Agente" EmContestacao="Não" Observacao="" DataLimiteFB="Dec 4 2020 10:40AM" />
<row Monitoria="8051941" Cliente="V2 - Cliente Teste" Conta="Central de Atendimento" Servico="SAC"
Equipe="Carla Santos" Agente="Leticia" Monitor="Danilo da Silva Lima" DataLigacao="Dec 1 2020 10:00AM"
DataMonitoria="Dec 1 2020 11:12AM" NotaFinal="100.00" NCG="Não" Pontualidade="-" AtrasoHrs="0.00"
Status="Cancelado" EmContestacao="Não" MotivoNaoFB="Desligado" Observacao="svsdnvsdln lsdn l"
DataLimiteFB="Dec 4 2020 11:12AM" />
</records>
</xml>
Descarte de Monitoria
Esta chamada retorna os mesmos dados que são obtidos dentro do sistema SMV através do relatório de Descarte de Monitoria.
CHAVES: 50368E0D5461B858FB484B66AF8C5D2F0434B3760DC4CE782D680689F8FFFD3B
PARÂMETROS: {smv_id, token, <clie_id | -1>, <cnta_id | -1>, <serv_id | -1>, start_date, end_date, date_mode}
Chamada
{
smv_id:12345,
token=80E2848E74CA7F7FCDD27FDFA800807E624802D076201BCDAA5CE890AD8F8795,
clie_id=-1,
cnta_id=-1,
serv_id=-1,
start_date=2020-10-01,
end_date=2020-10-31,
date_mode=0,
exp_mode=-1
apikey: 50368E0D5461B858FB484B66AF8C5D2F0434B3760DC4CE782D680689F8FFFD3B
}
Retorno
<xml>
<error code='0' msg='ok' />
<records>
<row Cliente="V2 - Cliente Teste" Conta="Central de Atendimento" Servico="Retenção" Supervisor="André Silva"
Monitor="Ana Carla Britto" Agente="Agente Teste" Data="21/12/2021" TMA="05:00" TMP="02:00"
Motivo="Conteúdo não avaliável" />
</records>
</xml>
Agentes Não Localizados
Esta chamada retorna os mesmos dados que são obtidos dentro do sistema SMV através do relatório de Agentes Não Localizados.
CHAVES: D5F44EDAFF30A0AD10BA9EB3FE989D96F0C3F34EE3FF32EC18D78A5A749FB7A6
PARÂMETROS: {smv_id, token, <clie_id | -1>, <cnta_id | -1>, <serv_id | -1>, start_date, end_date, date_mode}
Chamada
{
smv_id:12345,
token=80E2848E74CA7F7FCDD27FDFA800807E624802D076201BCDAA5CE890AD8F8795,
clie_id=-1,
cnta_id=-1,
serv_id=-1,
start_date=2020-10-01,
end_date=2020-10-31,
date_mode=0,
exp_mode=-1
apikey: D5F44EDAFF30A0AD10BA9EB3FE989D96F0C3F34EE3FF32EC18D78A5A749FB7A6
}
Retorno
<xml>
<error code='0' msg='ok' />
<records>
<row Cliente="V2 - Cliente Teste" Conta="Central de Atendimento" Servico="SAC" Supervisor="Carla Santos"
Monitor="Danilo da Silva Lima" Agente="José" Data="30/12/2020" tmp="01:00" observacao="xxxxxx" />
</records>
</xml>