Documentação da API REST

Introdução

A API fornecida por nós usa o protocolo HTTP padrão. Todas as funções da API usam o método HTTP GET. Cada chamada de função requer autorização de consulta. Os dados para autorização de consulta são enviados no cabeçalho HTTP.

Serviço de produção

É necessário o registo de uma entidade que pretenda utilizar a funcionalidade do sistema viesapi.eu. Para fazer isso, acesse o Cadastro página e preencha o formulário apropriado. O pré-requisito para usar o sistema viesapi.eu é a aceitação do Termos de serviço. Preenchendo corretamente o formulário e clicando no botão Registro botão criará uma conta no sistema viesapi.eu e sua ativação automática.

Ao fazer login pela primeira vez, um identificador é gerado automaticamente junto com a chave correspondente. O identificador é público e não requer proteção, enquanto a chave é privada e não deve ser disponibilizada a terceiros.

Endereço do serviço de produção: https://viesapi.eu/api

Serviço de teste

A funcionalidade completa de todas as bibliotecas compartilhadas pode ser verificada usando o Teste a API VIES. Usando a API de teste, é possível conferir todas as funções oferecidas nos planos pagos sem a necessidade de criar uma conta.

Endereço do serviço de teste: https://viesapi.eu/api-test

Definição da interface da API

Uma definição detalhada da API está disponível em um formato compatível com OpenAPI e pode ser baixada como um arquivo YAML aqui.

API também está disponível como uma interface de cliente IU do Swagger.

Execução da consulta

Um exemplo de como fazer uma consulta ao site de teste:

GET /api-test/get/vies/euvat/PL7171642051 HTTP/1.1
Host: viesapi.eu:443
Autorização: MAC id="api_key_id", ts="unix_timestamp", nonce="random_str", mac="b64_calculated_mac_value"
User-Agent: VIESAPIClient/client_version platform_name/platform_version

Onde:

  • api_key_id – Identificador de chave de API (no ambiente de produção, o valor do identificador gerado durante o registro, no ambiente de teste, o valor de test_id),
  • unix_timestamp – a hora atual na forma de um número de segundos a partir do chamado época do unix,
  • random_str – string aleatória, diferente para cada consulta (mín. 8 caracteres, máx. 16 caracteres),
  • b64_calculated_mac_value – HMAC calculado (usando um API key, valor test_key no ambiente de teste),
  • client_version – versão do cliente (em nossas bibliotecas é a versão da nossa biblioteca API, por exemplo, 1.2.3),
  • platform_name – o nome da plataforma cliente da API (em nossas bibliotecas é o nome da linguagem da biblioteca, por exemplo, JAVA, PHP, .NET, Python),
  • platform_version – Versão da plataforma do cliente API (em nossas bibliotecas é a versão do ambiente da biblioteca, por exemplo, 17 para JAVA ou 7.4 para PHP).

Todas as respostas retornadas pelo site estão em formato XML.

Solicitação de autenticação

Especificação do método de autorização utilizado: Autenticação HTTP: Autenticação de acesso MAC. Cada consulta ao nosso site deve ser autenticada usando este método. A autorização consiste em calcular o HMAC SHA256 a partir de uma string devidamente preparada e enviar o resultado no cabeçalho HTTP.

Exemplo

A string de entrada para a função HMAC é:
ts + '\n' + nonce + '\n' + method + '\n' + path + '\n' + host + '\n' + port + '\n\n'

Onde:

  • ts – a hora atual na forma de um número de segundos a partir do chamado época do unix, você deve sempre fornecer o tempo de execução da consulta atual (tolerância do servidor +/- 10 min em relação ao tempo atual),
  • nonce – string aleatória, diferente para cada consulta (mín. 8 caracteres, máx. 16 caracteres),
  • method – nome do método HTTP (sempre GET),
  • path – URL caminho da consulta a ser executada,
  • host – Nome do servidor VIES API (sempre viesapi.eu),
  • port – Número da porta do servidor VIES API (sempre 443),
  • ’\n’ – caractere de nova linha (código ASCII 10, 0x0A).

Para a consulta do número de IVA PL7171642051 enviada ao serviço de teste em 25/11/2019 00:00:00 UTC, a string de entrada para a função HMAC ficará assim:
str = "1574640000\ndt831hs59s\nGET\n/api-test/get/vies/euvat/PL7171642051\nviesapi.eu\n443\n\n"

O arquivo de string de entrada para este exemplo pode ser baixado aqui.

A partir da string preparada, calculamos o HMAC SHA256, como a senha do HMAC, damos o API key, ou seja, no caso da API de teste, o valor de test_key:

HMAC_SHA256(str, "test_key") = 7776a12b958233ce60dd0f16b8d141e80472a1ee3b1e1fb136d7abe34cb59306

A função HMAC SHA256 retorna 32 bytes binários (mostrado acima como um hex string para facilitar a leitura). Baixar arquivo com valor binário aqui.

O valor binário do HMAC calculado deve ser codificado com o algoritmo Base64, obtemos:

d3ahK5WCM85g3Q8WuNFB6ARyoe47Hh+xNter40y1kwY=

This value should be sent as MAC value in the header with data for authorization. Finally:

Authorization: MAC id="test_id", ts="1574640000", nonce="dt831hs59s", mac="d3ahK5WCM85g3Q8WuNFB6ARyoe47Hh+xNter40y1kwY="

On Linux machine required MAC value can be calculated in one step using this command:

$ echo -e -n "1574640000\ndt831hs59s\nGET\n/api-test/get/vies/euvat/PL7171642051\nviesapi.eu\n443\n\n" | openssl dgst -sha256 -hmac "test_key" -binary | openssl enc -base64