N|Solid (opens new window)

# Api - Estruturas

# Introdução

O Snep nesta nova versão começará a possuir em seu core uma estrutura de API's e nesta página será feita toda documentação das mesmas. Neste espaço deverá conter todas as API's criadas assim como seu parâmetros de entradas e suas respectivas respostas.

O SNEP oferece API's para que o cliente possa acessar algumas funcionalidades da central permitindo a integração com sistemas de ERP, CRM e outros. Essa API é constituída de uma aplicação desenvolvida em php rodando no caminho /snep/modules/default/api/.

Todas as comunicações das centrais SNEP com aplicações de terceiros e, em alguns casos, internas, são feitas usando o mesmo padrão de comunicação. Este padrão se baseia nos Protocolos HTTP e JSON.

# Como Usar

Para fazer uso dos serviços basta fazer uma requisição http para o servidor requisitando o arquivo "http://servidor/snep/modules/default/api/?service=nome_do_serviço &parâmetros" passando os parâmetros pedidos pelas ações.

Exemplo:

http://servidor_snep/snep/modules/default/api/?service=CallsReport&start_date=2015-01-01&start_hour=00:00
1

O parâmetro service é case sensitive, portanto "CallsReport" e "callsreport" são diferentes e NÃO representam a mesma ação.

Será sempre devolvido um parâmetro "status" que terá o valor "error" caso algum problema tenha ocorrido.

Exemplo:

{
  "status":"error",
  "cause":"Nenhum resultado encontrado"
}
1
2
3
4

Caso o status seja "ok", o comando foi executado com sucesso.

Exemplo:

{ 
  "status": "ok", 
  "data": [{
    "codigo": "9",
    "src": "1000",
    "dst": "1001",
    "disposition": "ANSWERED",
    "calldate": "2015-04-07 10:23:12"
  }],
}
1
2
3
4
5
6
7
8
9
10

# APIs

Abaixo segue manual de utilização das APIs do Snep.

# Relatório Chamadas do Período

O serviço do relatório de chamadas do período prevê os dados das chamadas conforme os parâmetros enviados na requisição.

# Parâmetros

Nome Valor Obrigatório Observação
report_type analytic ou synthetic SIM Tipo de relatório. Analítico: Detalhado. Sintético: Totalizações
start_date aaaa-mm-dd SIM Data inicial da consulta. Exemplo: start_date=2015-01-30
start_hour hh:mm SIM Hora inicial da consulta. Exemplo: start_hour=00:00
end_date aaaa-mm-dd SIM Data final da consulta. Exemplo: end_date=2015-02-10
end_hour hh:mm SIM Hora final da consulta. Exemplo: end_hour=23:59
limit INT,INT NÃO Retorna dados por página.Obrigatório uso quando há grande volume de dados. Exemplo: limit=40,20 trará 20 registros a partir do id 40, ou seja, ligações do id 40 ao 60.
groupsrc nome do grupo NÃO Nome do grupo de ramal para origem. A consulta será feita somente com os ramais deste grupo
groupdst nome do grupo NÃO Nome do grupo de ramal para destino. A consulta será feita somente com os ramais deste grupo
src ramais NÃO Número a ser consultado como origem. Exemplo src=1001. OBS: Quando ramal, poderá colocar mais de um separando-os por virgula. Depende do valor order_src para efetuar a consulta
order_src equal ou contain NÃO * Exatamente igual ou contém no valor. Quando especificado o valor em src este parâmetro é obrigatoriamente exigido. Por exemplo: Ao colocar o valor src=1000 e o valor order_src=equal, então a consulta buscará somente chamadas com a origem 1000. Caso coloque order_src=contain então a consulta será feita com like '%1000%'
dst equal NÃO Número a ser consultado como destino. Exemplo src=1001. OBS: Quando ramal, poderá colocar mais de um separando-os por virgula. Depende do valor order_src para efetuar a consulta
order_dst equal ou contain NÃO * Exatamente igual ou contém no valor. Quando especificado o valor em dst este parâmetro é obrigatoriamente exigido. Por exemplo: Ao colocar o valor dst=1000 e o valor order_dst=equal, então a consulta buscará somente chamadas com o destino 1000. Caso coloque order_dst=contain então a consulta será feita com like '%1000%'
status_answered true NÃO Seleciona chamadas com status de atendidas
status_noanswer true NÃO Seleciona chamadas com status de não atendidas
status_busy true NÃO Seleciona chamadas com status de ocupadas
status_failed true NÃO Seleciona chamadas com status de falhadas
time_call_init inteiro NÃO Tempo mínimo das chamadas em segundos. O valor deve ser inteiro.
time_call_end inteiro NÃO Tempo máximo das chamadas em segundos. O valor deve ser inteiro.
cost_center id do centro de custo NÃO Identificação do centro de custo. Caso possua mais de um, deve-se separar por underline. Exemplo: cost_center=1_1.2
locale true NÃO Localização da chamada. Caso habilitada consulta será mais lenta
clausule bound ou notbound NÃO Verifica permissão de visualização dos dados. bound -> Visualiza somente as chamadas dos ramais informados em clausulepeer notbound -> Não visualizar chamadas dos ramais informados em clausulepeer. OBS: Sempre que utilizado este parâmetro, deve ser informado o parâmetro clausulepeer
clausulepeer ramal NÃO * Informar ramais separados por underline. Exemplo: clausulepeer=1000_1001. OBS: Sempre que utilizado este parâmetro, deve ser informado o parâmetro clausule
exceptions string NÃO Informar exceções especiais. Por exemplo: Contexto de URA como 'suporte'. Caso exista mais de um separa-los por underline(_).
replace true NÃO Troca o número de origem ou destino pelo nome do contato ou ramal caso exista.

# Exemplo de Requisição

http://servidor_snep/snep/modules/default/api/?service=CallsReport&start_date=2015-01-01&start_hour=00:00&end_date=2015-01-01&end_hour=23:59&status_answered=true&status_busy=true&time_call_init=10&cost_center=1_2_3.1
1

# Respostas da Requisição

O retorno da requisição será em formato json. Caso a consulta traga algum dado será informado da seguinte maneira:

Exemplo retorno do tipo analítico:

{ 
  "status": "ok", 
  "data": [{
    "codigo": "9",
    "tipo": "O",
    "nome": "Internas",
    "key_dia": "07/04/2015",
    "dia": "07/04/2015 10:23:12",
    "src": "1000",
    "dst": "1001",
    "disposition": "ANSWERED",
    "duration": "120",
    "billsec": "110",
    "accountcode": "9",
    "userfield": "1428412992_20150407_1023_1000_1001",
    "dcontext": "default",
    "amaflags": "3",
    "uniqueid": "1428412992.1",
    "calldate": "2015-04-07 10:23:12",
    "dstchannel": "SIP/1001-00000002"
  }],
  "quantity": 2, 
  "totals":{
    "ANSWERED": 2,
    "NOANSWER": 1,
    "BUSY": 2,
    "FAILED": 0,
    "TOTALS": 5
  }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
  • data -> Dados da chamada
  • quantity -> Quantidade de chamadas encontradas
  • totals -> Quantidade de chamadas por status

Exemplo retorno do tipo sintético:

{
  "status": "ok",
  "quantity": 12165, 
  "totals": { 
    "ANSWERED": 6549, 
    "NOANSWER": 5156, 
    "BUSY": 336, 
    "FAILED": 124, 
    "TOTALS": 12165
  },
  "ccustos": { 
    "1": 2003,
    "2": 3476,
    "9": 68,
    "1.01": 173
  },
  "type": { 
    "S": 9685,
    "E": 2412,
    "O": 68
  },
  "calldate": { 
    "05/04/2015": {
      "ANSWERED": 9,
      "TOTALS": 9
    },
    "06/04/2015":{
      "ANSWERED": 6536,
      "TOTALS": 12152,
      "NOANSWER": 5155,
      "FAILED": 123,
      "BUSY": 335
    }
  }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
  • quantity -> Quantidade de chamadas atendidas
  • totals -> Quantidade de chamadas por status
  • ccustos -> Quantidade de chamadas por centros de custos (Código e quantidade)
  • type -> Quantidade de chamadas por tipo. (S= saída, E= entrada, O= outros)
  • calldate -> Quantidade de chamadas por status separadas por dia

Exemplo retorno nenhum dado encontrado:

Em caso de nenhum dado encontrado o resultado virá da seguinte forma:

{
  "status":"fail",
  "message":"No entries found."
}
1
2
3
4

# Relatório Serviços Utilizados

O serviço do relatório de serviços utilizados prevê os dados dos serviços conforme os parâmetros enviados na requisição.

# Parâmetros

Nome Valor Obrigatório Observação
start_date aaaa-mm-dd SIM Data inicial da consulta. Exemplo: start_date=2015-01-30
start_hour hh:mm SIM Hora inicial da consulta. Exemplo: start_hour=00:00
end_date aaaa-mm-dd SIM Data final da consulta. Exemplo: end_date=2015-02-10
end_hour hh:mm SIM Hora final da consulta. Exemplo: end_hour=23:59
group_select nome do grupo NÃO Nome do grupo de ramal para consulta. A consulta será feita somente com os ramais deste grupo
exten_select ramais NÃO Número do ramal a ser consultado como origem. Exemplo exten_select=1001. OBS: Quando existir mais de um ramal, deverá separa-los por virgula. Ex: exten_select=1000,1001
SIGAME true NÃO Seleciona os serviços do tipo SIGAME
DND true NÃO Seleciona os serviços do tipo DND
clausule bound ou notbound NÃO Verifica permissão de visualização dos dados. bound -> Visualiza somente as chamadas dos ramais informados em clausulepeer notbound -> Não visualizar chamadas dos ramais informados em clausulepeer. OBS: Sempre que utilizado este parâmetro, deve ser informado o parâmetro clausulepeer
clausulepeer ramal NÃO * Informar ramais separados por underline. Exemplo: clausulepeer=1000_1001. OBS: Sempre que utilizado este parâmetro, deve ser informado o parâmetro clausule

# Exemplo de Requisição

http://servidor_snep/snep/modules/default/api/?service=ServicesReport&start_date=2015-04-01&end_date=2015-04-30&start_hour=10:09:00&end_hour=10:09:59&clausule=nobound&clausulepeer=1000&SIGAME=1&DND=1&exten_select=1000,1001
1

# Respostas da Requisição

O retorno da requisição será em formato json. Caso a consulta traga algum dado será informado da seguinte maneira:

Exemplo retorno:

{
  "status":"ok",
  "totals":[{
    "date":"2015-04-23 14:51:51",
    "peer":"1001",
    "service":"SIGAME",
    "state":"0",
    "status":"Sigame desativado"
  }]
}
1
2
3
4
5
6
7
8
9
10

Exemplo retorno nenhum dado encontrado:

Em caso de nenhum dado encontrado o resultado virá da seguinte forma:

{
  "status":"empty",
  "message":"No entries found."
}
1
2
3
4

# Relatório de Ranking de Ligações

O serviço do relatório de ranking de ligações prevê uma lista detalhada dos números que mais efetuam/recebem chamadas conforme os parâmetros enviados na requisição.

# Parâmetros

Nome Valor Obrigatório Observação
start_date aaaa-mm-dd SIM Data inicial da consulta. Exemplo: start_date=2015-01-30
start_hour hh:mm SIM Hora inicial da consulta. Exemplo: start_hour=00:00
end_date aaaa-mm-dd SIM Data final da consulta. Exemplo: end_date=2015-02-10
end_hour hh:mm SIM Hora final da consulta. Exemplo: end_hour=23:59
showsource 1 a 20 SIM Top 'n' do ranking.
showdestiny 1 a 20 SIM Quantidade de números de destino a serem analisados para cada chamador
type num ou time SIM Ordenar por quantidade ou tempo das chamadas
clausule bound ou notbound NÃO Verifica permissão de visualização dos dados. bound -> Visualiza somente as chamadas dos ramais informados em clausulepeer notbound -> Não visualizar chamadas dos ramais informados em clausulepeer. OBS: Sempre que utilizado este parâmetro, deve ser informado o parâmetro clausulepeer
clausulepeer ramal NÃO * Informar ramais separados por underline. Exemplo: clausulepeer=1000_1001. OBS: Sempre que utilizado este parâmetro, deve ser informado o parâmetro clausule
replace true NÃO Troca o número de origem ou destino pelo nome do contato ou ramal caso exista.

# Exemplo de Requisição

http://servidor_snep/snep/modules/default/api/?service=RankingReport&start_date=2015-04-07&end_date=2015-04-14&start_hour=09:04:00&end_hour=09:04:59&type=num&showsource=5&showdestiny=10
1

# Respostas da Requisição

O retorno da requisição será em formato json. Caso a consulta traga algum dado será informado da seguinte maneira:

Exemplo retorno:

{
  "status":"ok",
  "quantity":{
    "1000":{
      "553144899446139":{
        "QA":5,
        "QN":0,
        "QT":5,
        "TA":"00:00:24",
        "TN":"00:00:00",
        "TT":"00:00:24"
      },
      "1002":{
        "QA":2,
        "QN":1,
        "QT":3,
        "TA":"00:00:22",
        "TN":"00:00:00",
        "TT":"00:00:25"
      }
    }
  },
 "type":"num",
 "totals":{
   "1000":8
  }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
  • QA -> Quantidade de chamadas Atendidas
  • QN -> Quantidade de chamadas Não Atendidas
  • QT -> Quantidade total de chamadas
  • TA -> Tempo de chamadas Atendidas
  • TN -> Tempo de chamadas Não Atendidas
  • TT -> Tempo total de chamadas
  • Totals -> Total de todas as chamadas do mesmo chamador

Exemplo retorno nenhum dado encontrado:

Em caso de nenhum dado encontrado o resultado virá da seguinte forma:

{
  "status":"empty",
  "message":"No entries found."
}
1
2
3
4

# Contatos

O serviço de contatos busca o dado conforme os parâmetros enviados na requisição.

# Parâmetros

Nome Valor Obrigatório Observação
phone Número NÃO Número do contato. Exemplo: phone=48999446611
name Nome NÃO Nome do contato. Exemplo: name=Joao Silva

OBS: A API recebe os dois parâmetros ou individualmente.

# Exemplo de Requisição

http://servidor_snep/snep/modules/default/api/?service=Contacts&phone=48999446600
1

# Respostas da Requisição

O retorno da requisição será em formato json. Caso a consulta traga algum dado será informado da seguinte maneira:

Exemplo retorno:

{
 "status":"ok",
 "contact":{
    id: "1", 
    contact_id: "1", 
    phone: "48999446600", 
    name: "Joao Silva", 
    address: "Rua B", 
    id_state: "SC", 
    id_city: "49198", 
    cep: "88160000", 
    group: "1", 
    created: "2016-08-23 09:39:17", 
    updated: "2017-02-14 11:21:16"
  }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
  • phone -> Número de telefone
  • name -> Nome do contato
  • address -> Endereço do contato
  • id_state -> Estado do contato
  • id_city -> Código da cidade do contato

Exemplo retorno nenhum dado encontrado:

Em caso de nenhum dado encontrado o resultado virá da seguinte forma:

{
  "status":"empty",
  "message":"No entries found."
}
1
2
3
4