|
|
Dígitro Neo Interact CTI Computer Telephony Integration |
O acesso à API do Neo Interact sempre será feito pela Internet via HTTPS a partir da URL correspondente ao domínio contratado. Esta URL será do tipo:
https://<domínio-do-cliente>.saas.digitro.cloud/neo/cti/<versão-da-api>/<resource>/<endpoint>
Onde:
<domínio-do-cliente>: É o domínio utilizado pelo cliente para acesso ao serviços da Dígitro na nuvem. Este domínio é definido na criação do domínio do cliente na nuvem de serviços SAAS Dígitro.
<versão-da-api>: É a versão do protocolo utilizado. Ex: v1.0.0
<resource>: Corresponde ao recurso acessado pelo comando REST. O recurso agrupa os endpoints (comandos) por categoria.
<endpoint>: Estes endoints representam os comandos enviados ao Neo Interact CTI e estão descritos detalhadamente na documentação da API do Neo Interact.
Exemplos:
Ex (1): https://digitro.saas.digitro.cloud/neo/cti/v1.0.0/sse/open_channel
Ex (2): https://digitro.saas.digitro.cloud/neo/cti/v1.0.0/system/get_agents_list
Todas as requisições HTTPS/REST devem conter uma chave de acesso denominada API-KEY. Esta chave de acesso tem como objetivo garantir o acesso seguro ao serviço de contact-center do domínio do cliente. Apenas o portador da API-KEY pode acessar os recursos disponíveis pela API.
A API-KEY deve ser criada pelo próprio cliente, através da aplicação Key Manager da suíte de serviços SAAS Dígitro. Uma vez criada, esta chave deverá ser baixada pelo cliente e inserida nas requisições REST no cabeçalho HTTP 'X-API-KEY'.
Exemplo:
curl -X 'GET' \
'https://digitro.saas.digitro.cloud/neo/cti/v1.0.0/system/get_services_list' \
-H 'X-API-KEY: 1f9cdebf-387c-4dc5-a0cd-ac873132ba90'
Mais de uma API-KEY pode ser criada pelo cliente para usos diversos como desenvolvimento, testes e/ou produção. As chaves não expiram, mas podem ser revogadas caso seja desejado ou necessário.
O acesso à aplicação Key Manager pode ser feito diretamente pela plataforma SaaS Dígitro em https://<domínio-cliente>.saas.digitro.cloud/keymanager. Para acessar esta aplicação será necessário se autenticar com um usuário válido cadastrado neste domínio e com permissão de acesso para tal operação.
https://<dominio-do-cliente>.saas.digitro.cloud/keymanager
ATENÇÃO: É de responsabilidade única e exclusiva do cliente a gestão, custódia, distribuição e utilização de suas chaves (API-KEYs) de forma segura, não devendo ser compartilhadas, sob risco de ter o controle de suas operações de contact-center comprometidos por um acesso falho ou mal intencionado. A Dígitro não se responsabiliza pelo prejuízos decorrentes do não cumprimento destas recomendações.
Obtenha a URL de seu domínio na plataforma SaaS Dígitro e verifique se ela está ao alcance de sua rede fazendo:
$ ping <domínio-do-cliente>.saas.digitro.cloud
O domínio não irá responder ao comando ping, no entanto caso ele exista, a URL será convertida em endereço IP via DNS, da seguinte forma:
PING <domínio-do-cliente>.saas.digitro.cloud (1.2.3.4) 56(84) bytes of data.
Se a resposta for:
ping: <domínio-do-cliente>.saas.digitro.cloud: Nome ou serviço desconhecido
Possivelmente a URL/domínio ainda não existe, não foi anunciado aos servidores DNS ou a URL pode estar errada. Verifique estes problemas antes de prosseguir.
Crie uma chave de acesso (API-KEY) como descrito acima
Com essas informações faça um teste de conexão. Abaixo são sugeridos duas formas, via shell script ou node.js (javascript):
Em shell script: Abra um terminal e execute o comando abaixo, substituindo os campos <URL> e a <API-KEY> pelos seus valores reais obtidos nos passos anteriores.
$ curl -I -X GET https://<URL>.saas.digitro.cloud/neo/cti/v1.0.0/hello-neo-cti -H X-API-KEY:<API_KEY>
A resposta deste comando é do tipo:
HTTP/1.1 200 OK
Server: nginx
Date: Thu, 12 Sep 2024 18:40:31 GMT
Connection: close
Content-Security-Policy: default-src 'self';base-uri 'self';font-src 'self' https: data:;form-action 'self';frame-ancestors 'self';img-src 'self' data:;object-src 'none';script-src 'self';script-src-attr 'none';style-src 'self' https: 'unsafe-inline';upgrade-insecure-requests
Cross-Origin-Opener-Policy: same-origin
Cross-Origin-Resource-Policy: same-origin
Origin-Agent-Cluster: ?1
Referrer-Policy: no-referrer
Strict-Transport-Security: max-age=15552000; includeSubDomains
X-Content-Type-Options: nosniff
X-DNS-Prefetch-Control: off
X-Download-Options: noopen
X-Frame-Options: SAMEORIGIN
X-Permitted-Cross-Domain-Policies: none
X-XSS-Protection: 0
Caso a primeira linha retorne:
"HTTP/1.1 200 OK": a execução foi bem sucedida e você enviou seu primerio comando ao CTI do Neo Interact !
"HTTP/1.1 403 Forbidden": a API-KEY enviada é inválida, certifique-se que ela esteja correta e/ou faz parte das chaves válidas do seu domínio.
Caso o envio do comando não tenha sido respondido, verifique:
Se a URL do domínio está correta;
Se não há bloqueio por firewall na sua máquina ou rede;
Em node.js (javascript)
const fetch = require('node-fetch')
const apiKey = '1f9cdebf-387c-4dc5-a0cd-ac873132ba90'
const ctiVersion = 'v1.0.0'
const domain = 'cliente.saas'
const ctiUrl = `https://${domain}.digitro.cloud/neo/cti/${ctiVersion}/hello-neo-cti`
const headers = {
'Content-Type': 'application/json',
'X-API-KEY': apiKey,
}
fetch(`${ctiUrl}`, { method: 'GET', headers }).then((response) => { console.log(response.status) })
Caso a saída seja:
"200": a execução foi bem sucedida e você enviou seu primerio comando ao CTI do Neo Interact !
"403": a API-KEY enviada é inválida, certifique-se que ela esteja correta e/ou faz parte das chaves válidas do seu domínio.
Outras mensagens de erro: Avalie o erro e prossiga com a correção.
Uma vez que se tenha obtido sucesso nesta primeira interação com o Neo Interact os demais acessos via comandos HTTP/REST seguem o mesmo princípio. Vale lembrar que os comandos baseados no método GET não tem corpo na requisicão, enquanto que os demais (POST, PUT, DELETE, PATCH) podem ter corpo na requisição. O NeoInteract CTI utiliza o padrão JSON (Javascript Object Notation) como formato para os dados transportados no corpo das requisições e respostas.
Você pode acessar os comandos REST da API CTI do Neo Interact online em Documentação da API do Neo Interact.