Autenticação

A autenticação para todos os serviços dessa API utilizará o protocolo HMAC. Objetivo: permitir de forma segura a comunicação entre o Cliente e o Servidor.

Nonce

O número nonce deve ser composto pelo timestamp (Unix Timestamp sem microssegundos).

HMAC

O protocolo HMAC prevê comunicação para mensagens imunes a ataques de replay.

O Servidor define o algoritmo de hash H()a ser utilizado para cálculo do HMAC. Recomendamos SHA256 ou superior.

Cliente e Servidor devem utilizar a mesma chave key para o cálculo do HMAC.

A key utilizada será fornecida pela Soluti durante a etapa de integração.

O HMAC é calculado da seguinte forma:

$$hmac=H(H(hkey)∣∣H(hkey∣∣ds))$$

H() : Algoritmo de hash (sha256) hkey : Chave utilizada para o cálculo || : Concatenação de strings ds : Assinatura dos dados

A chave hkey é definida da seguinte forma:

$$hkey=nonce║key$$

A chave ds é definida da seguinte forma:

$$ds=(method∣∣uri∣∣m)$$

ds : Assinatura dos dados method: Método a ser utilizado(POST) uri : <base_url>/videoconferencia-api/<route> m : Mensagem em formato JSON sendo a chave o nome do parâmetro a ser enviado

A base_url é o link de acesso ao Sistema da AR.

Exemplo: https://arsolutihom.acsoluti.com.br

A route é o serviço no qual você irá fazer a requisição. Exemplo: importar-pedido

Exemplo de m para o serviço importar-pedido:

Exemplo de m em formato JSON

{
    "pedido": "12345"
}

Exemplo de comunicação Hmac

Cálculo do HMAC em PHP

$base_url = "https://arsolutihom.acsoluti.com.br";
$uri = "{$base_url}/videoconferencia-api/importar-pedido";
$method = 'POST';
$hmacVersion = 1;
$clientId = 0;

$mensagem = array(
    "pedido" => "12345"
);

$m = json_encode($mensagem);

$ds = $method . $uri . $m;

$key = "CHAVESECRETAAPI";
$nonce = time();
$hkey = $nonce . $key;
$hmac = hash('sha256', hash('sha256', $hkey) . hash('sha256', $hkey . $ds));

Header

Preparando o conteúdo a ser enviado no Header da requisição.

$headers = [
    'Content-type' => 'application/json',
    'HMAC-Authentication' => $hmacVersion . ':' . $clientId . ':' . $nonce . ':' . $hmac
];

O valor da variável $hmacVersion corresponde a versão do HMAC utilizada.

Atualmente estamos na versão 1.

O valor da variável $clientId corresponde ao ID do Cliente de Integração.

Por padrão será 0.

Definição