Documentação da API REST

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 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 de um navegador da web. Basta copiar e colar na barra de endereço 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.

getVIESData resposta

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

vies api - getVIESDataParsed

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 (formato original),
  • traderAddressComponent – detalhes do endereço do agrupamento de componentes – atributo opcional, nunca será retornado nesta função.
  • id – identificador de consulta único gerado pelo sistema VIES (Número de Consulta),
  • date – data de execução da consulta
  • source – fonte de dados, sempre: http://ec.europa.eu

obterVIESDataParsed resposta

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

vies api - getVIESDataParsed

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 (formato original),
  • traderAddressComponent – detalhes do endereço do agrupamento de componentes
    • country – nome do país do comerciante na sua língua nacional
    • postalCode – código postal do endereço do comerciante
    • city – cidade do endereço do comerciante
    • street - rua do endereço do comerciante
    • streetNumber – número da rua do endereço do comerciante
    • houseNumber – número da casa do endereço do comerciante
  • id – identificador de consulta único gerado pelo sistema VIES (Número de Consulta),
  • date – data de execução da consulta,
  • source – fonte de dados, sempre: http://ec.europa.eu

Isenção de responsabilidade importante!

A função de análise usa algoritmos de IA externos e APIs para extrair automaticamente atributos como: cidade, código postal, rua com número da rua (número do prédio) e número da casa, portanto não podemos garantir sua operação correta 100%.

obterVIESDataAsync resposta

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

Resposta getVIESDataAsync da API VIES

Descrição detalhada dos atributos retornados:

  • token – token de lote (guid) gerado por viesapi.eu, deve ser usado para chamar a função getVIESDataAsync (após 2-3 minutos) para obter resultados.

obterVIESDataAsyncResult resposta

Se a solicitação for tratada corretamente, a seguinte resposta deverá ser gerada, contendo uma lista de objetos com dados retornados pelo VIES:

vies api getVIESDataAsyncResults

Descrição detalhada dos atributos retornados:

  • numbers – uma matriz de objetos com resultados retornados pelo VIES correspondentes aos números de IVA da UE enviados na solicitação de chamada da função getVIESDataAsync
    • 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 (formato original),
    • id – identificador de consulta único gerado pelo sistema VIES (Número de Consulta),
    • date – data de execução da consulta
    • source – fonte de dados, sempre: http://ec.europa.eu
  • errors – matriz de objetos com erros retornados pelo VIES para dados de número de IVA da UE enviados na solicitação de chamada de função getVIESDataAsync
    • 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,
    • error – detalhes do erro retornado para este número de IVA da UE específico
    • 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:

Resposta de erro da API REST do Vies

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
62 O lote ainda está sendo processado, tente novamente mais tarde
63 O número máximo de solicitações de lote foi atingido. Por favor, reenvie sua solicitação mais tarde.
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
209 Limite de tamanho de lote excedido [2-99]