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
Authorization: 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
Accept: mime_type

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 cliente API (em nossas bibliotecas é a versão do ambiente da biblioteca, ex. 17 para JAVA, ou 7.4 para PHP),
  • mime_type – Nome do tipo MIME no qual a resposta deve ser retornada, dois tipos são suportados: text/xml e application/json, se a solicitação não contiver o cabeçalho Accept, o XML será retornado por padrão.

Solicitação de autenticação

Os dados de autorização devem ser preparados de acordo com Autenticação HTTP: Autenticação de acesso MAC e este é o método de autenticação recomendado. Também é possível usar o Autenticação HTTP: autenticação básica método, no entanto, por motivos de segurança, use-o somente quando usar o primeiro método não for possível por algum motivo.

Cada consulta ao nosso site deve ser autenticada usando um dos dois métodos disponíveis.

Método 1 – HMAC (recomendado)

Especificação do método de autorização utilizado: Autenticação HTTP: Autenticação de acesso MAC. 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=

Este valor deve ser enviado como valor MAC no cabeçalho com os dados para autorização. Finalmente:

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

Na máquina Linux, o valor MAC necessário pode ser calculado em uma etapa usando este comando:

$ 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

Método 2 - Autenticação Básica

Especificação deste método de autorização usado: Autenticação HTTP: autenticação básica.

Exemplo 1

A string de entrada para a função Base64 é:

str = key_id + ':' + key

Onde:

  • key_id – Identificador de chave API (no caso de um ambiente de teste, test_id corda),
  • key – Chave de API (no caso de um ambiente de teste, string test_key).

Para o ambiente de teste, a string de entrada para a função Base64 será:

str = "test_id:test_key"

Depois de aplicar a função Base64, obtemos:

Base64(str) = dGVzdF9pZDp0ZXN0X2tleQ==

Este valor deve ser enviado como valor Básico no cabeçalho com dados para autorização. Em última análise:

Authorization: Basic dGVzdF9pZDp0ZXN0X2tleQ==

Exemplo 2

O exemplo a seguir mostra uma consulta que pode ser invocada em um ambiente de teste a partir de um navegador da web. Basta copiar e colar na barra de endereços do navegador:

https://test_id:test_key@viesapi.eu/api-test/get/vies/euvat/PL7171642051

Onde:

  • test_id – para autenticar em uma produção ambiente, o parâmetro deve conter um identificador de chave válido usado para autorização,
  • test_key – para autenticar em uma produção ambiente, o parâmetro deve conter um valor válido da chave usada para autorização.

O identificador de chave e a chave são gerados pelo usuário após fazer login em sua conta no viesapi.eu portal (API keys aba). See o documentação página para obter mais informações sobre ID e geração de chaves.

Resposta

Se a solicitação for tratada corretamente, a seguinte resposta será gerada:

Descrição detalhada dos atributos retornados:

  • uid – identificador de consulta exclusivo gerado por viesapi.eu,
  • countryCode – código do país em que a empresa associada ao número de IVA da UE fornecido na consulta está registrada,
  • vatNumber – Número de IVA da UE da empresa verificada fornecida no inquérito,
  • valid – resposta do serviço VIES, informando sobre o atual status de IVA da UE da entidade verificada:
    • true – o número de IVA da UE fornecido no inquérito é válido,
    • false – o número de IVA da UE fornecido no inquérito não é válido,
  • traderName – nome comercial da empresa,
  • traderCompanyType – sempre retornou uma string de caracteres '-',
  • traderAddress – endereço da empresa onde a empresa está registrada,
  • id – identificador de consulta exclusivo gerado pelo sistema VIES
  • date – data de execução da consulta
  • source – fonte de dados, sempre: http://ec.europa.eu

Resposta de erro

Caso ocorra algum erro relacionado ao tratamento da requisição, a seguinte mensagem de erro é retornada:

Erro

Descrição detalhada dos atributos retornados:

  • code – código de erro exclusivo para tratamento automático de erros,
  • description – descrição do erro interceptável por humanos,
  • details – mdescrição detalhada do erro (opcional),