Usando a API

Bem-vindo à API do Communications Mining. Nós nos esforçamos para tornar a API previsível, fácil de usar e indolor para integrar. Se achar que podemos fazer algo para melhorá-lo, ou se encontrar algum bug ou comportamento inesperado, entre em contato com o suporte e entraremos em contato com você o mais rápido possível.

Você pode ver todos os endpoints disponíveis na Referência da API. Há também um Tutorial de API.

Ponto de Extremidade da API

Todas as solicitações de API são enviadas para o Communications Mining como objetos JSON para o ponto de extremidade do seu tenant sobre HTTPS.

Tenants integrados via UiPath:

https://cloud.uipath.com/<my_uipath_organisation>/<my_uipath_tenant>/reinfer_/api/...

Tenants integrados por meio do Communications Mining:

https://<mydomain>.reinfer.io/api/...

Importante:

Ambientes de desenvolvimento e produção

No Communications Mining, os dados e fluxos de trabalho de desenvolvimento e produção podem ser separados, tendo tenants separados ou colocando-os em projetos separados no mesmo tenant. Em cada caso, o acesso aos dados é permitido separadamente (para que os desenvolvedores possam ter acesso de administrador aos dados de desenvolvimento, enquanto controles mais restritos podem ser colocados na produção). Se estiver usando tenants separados, o endpoint da API é diferente para cada um dos dados de desenvolvimento e produção; se estiver usando projetos separados no mesmo tenant, o ponto de extremidade desse único tenant será usado para ambos.

Autenticação

Todas as solicitações de API exigem autenticação para identificar o usuário que faz a solicitação. A autenticação é fornecida por meio de um token de acesso. O token de acesso do desenvolvedor pode ser obtido na página Gerenciar conta.

Observação:

Você pode ter apenas um token de API ativo por vez. Gerar um novo token invalidará o anterior.

Você precisa incluir o seguinte cabeçalho HTTP para cada chamada de API que fizer, onde $REINFER_TOKEN é seu token da API do Communications Mining.

Authorization: Bearer $REINFER_TOKEN

Os exemplos do bash na Referência da API pressupõem que você salvou seu token em uma variável de ambiente. Os exemplos de Python e Nó na Referência da API pressupõem que o token foi armazenado em uma variável local REINFER_TOKEN por meio da solução de configuração escolhida.

• Bash

  curl -X GET 'https://<my_api_endpoint>/api/...' \
      -H "Authorization: Bearer $REINFER_TOKEN"

• Nó

  const request = require("request");
  
  request.get(
    {
      url: "https://<my_api_endpoint>/api/...",
      headers: {
        Authorization: "Bearer " + process.env.REINFER_TOKEN,
      },
    },
    function (error, response, json) {
      // digest response
      console.log(JSON.stringify(json, null, 2));
    }
  );

• Python

  import json
  import os
  
  import requests
  
  response = requests.get(
      "https://<my_api_endpoint>/api/...",
      headers={"Authorization": "Bearer " + os.environ["REINFER_TOKEN"]},
  )
  
  print(json.dumps(response.json(), indent=2, sort_keys=True))

• Resposta

  {
    "status": "ok"
  }

Permissões

Cada ponto de extremidade da API lista as permissões necessárias na Referência da API. Você pode visualizar as permissões que tem acessando sua página Gerenciar conta. A página mostra os Projetos aos quais você tem acesso e as Permissões que você tem em cada projeto.

Erros

Usamos códigos de resposta HTTP convencional para indicar sucesso ou falha de uma solicitação de API. Em geral, códigos no intervalo 2xx indicam sucesso, códigos no intervalo 4xx indicam um erro que resultou da solicitação fornecida e códigos no intervalo 5xx indicam um problema com a plataforma Communications Mining.

Solicitações desse erro também retornarão um corpo com um valor status de error ao invés de ok, e uma mensagem de erro descrevendo o erro.

• Bash

  curl -X GET 'https://<my_api_endpoint>/api/v1/nonexistent_page' \
      -H "Authorization: Bearer $REINFER_TOKEN"

• Nó

  const request = require("request");
  
  request.get(
    {
      url: "https://<my_api_endpoint>/api/v1/nonexistent_page",
      headers: {
        Authorization: "Bearer " + process.env.REINFER_TOKEN,
      },
    },
    function (error, response, json) {
      // digest response
      console.log(JSON.stringify(json, null, 2));
    }
  );

• Python

  import json
  import os
  
  import requests
  
  response = requests.get(
      "https://<my_api_endpoint>/api/v1/nonexistent_page",
      headers={"Authorization": "Bearer " + os.environ["REINFER_TOKEN"]},
  )
  
  print(json.dumps(response.json(), indent=2, sort_keys=True))

• Resposta

  {
    "message": "404 Not Found",
    "status": "error"
  }

Observe que sua solicitação pode falhar devido a problemas em sua rede antes de chegar ao Communications Mining. Nesses casos, a resposta que você receberá será diferente da resposta de erro do Communications Mining descrita acima.

Tempo de Desempenho

Usamos o cabeçalho HTTP Server- Time para comunicar o tempo necessário para que as solicitações à nossa API sejam processadas. Incluímos uma única métrica, total, que você pode usar para medir quanto tempo nossa plataforma levou para processar sua solicitação sem a latência da solicitação da rede.

Um exemplo do cabeçalho como será visto em uma resposta:

Server-Timing: total;dur=37.7

Os valores Server-Timing são sempre em milissegundos, portanto, neste caso, a solicitação da API com este valor de cabeçalho levou 37,7 milissegundos para ser processada em nossa plataforma.