Documentação REST da API VIES
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 umAPI key, valortest_keyno 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/xmleapplication/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 (sempreviesapi.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_idcorda),key– Chave de API (no caso de um ambiente de teste, stringtest_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 VIESdate– data de execução da consultasource– 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:
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),
Códigos de erro
A tabela abaixo lista todos os erros possíveis retornados pelas APIs REST e bibliotecas de programação:
| Código de erro | Mensagem de erro |
| 8 | Formato de solicitação inválido |
| 10 | Caminho de API inválido |
| 11 | Erro de serviço interno |
| 22 | O número de IVA da UE é inválido |
| 23 | Falha ao obter dados do sistema VIES |
| 26 | Este recurso não está disponível no plano selecionado no momento |
| 27 | Esta função não suporta este modo de pesquisa |
| 33 | Não é possível consultar os dados fornecidos no modo de teste |
| 35 | Não é necessária autorização de consulta de acesso |
| 36 | O serviço está temporariamente indisponível devido a trabalho técnico programado |
| 43 | Não foi possível recuperar o número de consultas do usuário para o mês atual |
| 54 | Data ou hora incorreta no computador ou sistema do usuário |
| 55 | Valor de string MAC inválido no cabeçalho com credenciais de consulta |
| 57 | Valor de chave inválido no cabeçalho com credenciais de consulta |
| 58 | O número máximo de consultas simultâneas para este Estado-Membro foi atingido |
| 59 | O pedido no Estado-Membro não responde ou não está disponível |
| 101 | O número IP da conexão não corresponde ao número IP atribuído à chave API |
| 102 | A chave da API está bloqueada |
| 103 | Chave API inválida |
| 104 | O número máximo de consultas disponíveis para o plano selecionado foi atingido |
| 105 | Conta bloqueada ou excluída |
| 106 | Tipo de conta inválido |
| 107 | A conta pré-paga não foi paga |
| 108 | ID de chave de API inválida |
| 201 | Falha ao conectar ao serviço VIES API |
| 202 | A resposta do serviço da API VIES tem formato inválido |
| 203 | Tipo de número inválido |
| 204 | NIP é inválido |
| 205 | O ID de IVA da UE é inválido |
| 206 | A função gerou uma exceção |
| 207 | A data tem um formato inválido |
| 208 | Parâmetro de entrada inválido |