Guia de Utilização da Aplicação Desktop EFAPI
Introdução
A aplicação EFAPI (Entrega de Ficheiros Aduaneiros Por Internet) permite a transferência, automática ou interativa, de ficheiros através dum canal de utilização, fácil e económico (Internet).
As operações disponíveis incluem o envio e obtenção segura de ficheiros, listagem e eliminação das respostas referentes ao envio de ficheiros.
Os utilizadores interagem com o sistema utilizando:
- Uma opção disponível no EFAPIINTER que permite o envio e a captura "manual" de ficheiros;
- Uma aplicação cliente que funciona através de uma linha de comandos na máquina do utilizador e que permite o envio e a captura dos ficheiros automaticamente.
Este guia pretende fornecer os elementos básicos sobre a aplicação EFAPI de forma a facilitar a sua utilização pelos operadores económicos relativamente à transferência eletrónica de dados no âmbito da Exportação, Importação e Trânsito.
Caraterização da Aplicação EFAPI
Utilizadores
A aplicação está disponível aos utilizadores com os seguintes perfis:
- DAV (utilizador SFA);
- DUE (utilizador STADA Exportação);
- DUI (utilizador STADA Importação);
- TRS (utilizador Trânsito).
Para obter um destes perfis, isto é, se ainda não tiver o perfil desejado, deverá solicitar ao GUE (link na secção "Links Úteis") a atribuição do perfil desejado.
Restrições
As funcionalidades da aplicação EFAPI só poderão ser acedidas e usadas pelos utilizadores com um dos perfis indicados acima.
Cada utilizador apenas poderá efetuar operações de enviar, obter, listar e apagar sobre ficheiros próprios. Abaixo indicamos uma tabela com os tipos de documentos que podem ser enviados, recebidos e removidos de acordo com o perfil do operador.
| Perfil | Declaração Aduaneira de Veículos | Declaração Eletrónica de Trânsito | Declaração Eletrónica de Exportação | Declaração Sumária de Saída | Documento Administrativo Único (DUI2) | Documento Único de Importação (DUI) |
|---|---|---|---|---|---|---|
| DAV | X | |||||
| DUE | X | X | ||||
| DUI | X | X | ||||
| TRS | X |
Funcionalidades asseguradas
A aplicação foi concebida de forma a assegurar o seguinte:
- Transferência de ficheiros entre a máquina do utilizador e o EFAPI, via automática ou interativa ("manual");
- Os ficheiros enviados e as respetivas respostas podem ser apagados mediante opção do utilizador (automaticamente através da linha de comando ou interactivamente, via browser);
- Apenas os utilizadores devidamente autenticados podem utilizar este serviço;
- Os utilizadores só conseguem fazer operações sobre os seus próprios ficheiros;
- Os ficheiros enviados e as respetivas respostas serão guardados no sistema de ficheiros até que sejam apagados;
- As respostas que são enviadas para a diretoria de reciclagem serão objeto de limpeza periódica;
- Todas as comunicações serão efetuadas sobre um canal seguro (neste caso HTTP sobre SSL) garantindo a confidencialidade e integridade das mensagens trocadas.
Ambientes disponibilizados
O EFAPI Internet disponibiliza dois ambientes via Portal Aduaneiro através destes endereços:
Ambos os ambientes permitem usar o EFAPI, estando o de qualidade/testes vocacionado para verificação da aplicação antes de passar a produção.
Aplicação Cliente EFAPI
Requisitos Mínimos
- Ligação à Internet;
Instalação
Após certificação de que a máquina do operador tem os requisitos mínimos para instalar e executar a aplicação, é necessário obter o arquivo com a aplicação. Deverão ser feitos os seguintes passos:
- Após aceder à página de download da aplicação, deverá escolher o arquivo que corresponda ao sistema operativo do seu computador. Neste exemplo foi escolhido o arquivo zip para o sistema operativo Windows. Após selecionar o arquivo desejado, a transferência do arquivo irá iniciar. Depois de a transferência ter sido concluída deverá ir à pasta de downloads do seu computador e extrair os conteúdos do arquivo para o local que deseja.
- Após transferir o arquivo, recomendamos que valide o hash SHA-512. Ou seja, para garantir que o ficheiro foi obtido de uma fonte filedigna, o utilizador terá de gerar um hash SHA-512 com o arquivo que acabou de transferir e comparar com o hash que está disponível na página de download. Para isso, terá de executar um dos seguintes comandos com base no Sistema Operativo que o utilizador está a usar:
| Sistema Operativo | Comando |
|---|---|
| Windows | certutil -hashfile "caminho_do_ficheiro" SHA512 type "nome_do_ficheiro.sha512" |
| Mac / Linux | sha512sum -t "caminho_do_ficheiro" |
Após executar o comando, o utilizador deverá comparar a sequência de caracteres produzida pelo comando com a do ficheiro sha512 obtido na página de download e ver se coincidem. Se coincidirem, o utilizador pode prosseguir para os próximos passos.
- Após a extração do arquivo, deverá ter gerado uma pasta com o nome efapi-"versão" e deverá ter os seguintes ficheiros:
Em relação ao path onde colocar a pasta resultante da extração do zip/tar.gz, sugerimos colocar num path como por exemplo C:\EFAPI (exemplo para Windows) e evitar colocar nas pastas habituais como Program Files e Program Files(x86) que precisam de permissões de administrador quando tentamos criar pastas/ficheiros(por exemplo logs), o que poderá provocar problemas no funcionamento geral da aplicação.
Configuração
Após a instalação, o habitual é o operador realizar testes em Qualidade para se habituar à utilização do programa e testar se está tudo a funcionar corretamente. Para o operador poder testar em Qualidade é necessário realizar os seguintes passos:
- Aceder à pasta onde a aplicação foi instalada;
- Abrir o ficheiro "config.properties" com Notepad/Notepad++;
- Colocar um '#' antes da propriedade "server.url" para comentar o endpoint de Produção (linha 5);
- Remover o '#' que está colocado antes da propriedade "server.url" para descomentar o endpoint de qualidade (linha 8);
- Guardar as alterações do ficheiro;
- Fechar o Notepad.
Após realizar os testes em Qualidade, se o operador pretende efetuar operações no ambiente de Produção terá de comentar o endpoint de Qualidade e descomentar o de Produção e guardar as alterações no ficheiro "config.properties" da aplicação.
Utilização da Aplicação Cliente EFAPI
A utilização da linha de comando permite a intervenção manual por parte do utilizador porém, o seu objetivo principal e maior vantagem é possibilitar a sua invocação a partir duma aplicação do utilizador de forma a automatizar as operações de envio e receção de ficheiros.
Envio de ficheiro
| Contexto | A entidade pretende enviar um ficheiro DU utilizando a linha de comandos |
|---|---|
| Actor primário | Entidade |
| Pré-condições | O ator primário existe no Portal das Finanças e tem o perfil necessário |
| Garantias | A aplicação garante, em qualquer circunstância, a criação do canal seguro e a autenticação perante o sistema |
| Frequência prevista | Frequente |
| Restrições e limitações |
|
| Evento de início | O utilizador acede à linha de comandos |
Exemplo de comando
Com uma linha de comandos aberta (certificar que está na diretoria onde a aplicação EFAPI foi extraída), executar o comando "efapi (./efapi.sh para versões mac e linux) -n NIF_teste -p palavra_passe_teste -c enviar -d caminho_local_da_pasta_onde_o_ficheiro_está_localizado -f nome_de_ficheiro -t tipo_de_ficheiro -a" (o 'a' é uma flag opcional no caso de o utilizador querer remover o ficheiro local após ter sido efetuado o upload do mesmo).
Se o código de resposta devolvido for 0, a operação foi bem sucedida.
Se o user é um sub-utilizador (userID diferente de 0) é necessário indicar a flag -u a seguir ao nif. Se a flag -u for omitida, o user ID é por defeito 0. Portanto, um comando exemplo com o user ID definido seria: efapi -n NIF_teste -u user_id_teste -p palavra_passe_teste -c enviar -d caminho_local_do_ficheiro_a_ser_enviado -f nome_de_ficheiro -t tipo_de_ficheiro.
Receção de ficheiros
| Contexto | O operador pretende receber todas as respostas aos ficheiros que enviou utilizando a linha de comandos |
|---|---|
| Actor primário | Utilizador |
| Pré-condições | O ator primário está registado no Portal das Finanças e tem o perfil necessário para o tipo de ficheiro que pretende receber |
| Garantias | A aplicação garante, em qualquer circunstância, a criação do canal seguro e a autenticação perante o sistema |
| Frequência prevista | Frequente |
| Restrições e limitações |
|
| Evento de início | O utilizador acede à linha de comandos |
Exemplo de comando
Com a linha de comandos aberta via atalho ou ficheiro .cmd da aplicação, executar o comando "efapi (./efapi.sh para versões mac e linux) -n NIF_teste -p palavra_passe_teste -c receber -d caminho_de_diretoria_local_a_ser_guardado_os_ficheiros_vindos_do_servidor -t tipo_de_ficheiro -a" (o 'a' é uma flag opcional no caso de o utilizador querer remover os ficheiros do servidor após receber os mesmos).
Se o código de resposta devolvido for 0, a operação foi bem sucedida. Se havia ficheiros do lado do servidor associados ao NIF, o utilizador deverá recebê-los na pasta onde indicou no comando. No entanto, apesar de devolver resposta com código 0, o utilizador poderá não receber ficheiros por não haver ficheiros no servidor associados ao NIF e id de sub-utilizador indicados no comando.
Se o user é um sub-utilizador (userID diferente de 0) é necessário indicar a flag -u a seguir ao nif. Se a flag -u for omitida, o user ID é por defeito 0. Portanto, um comando exemplo com o user ID definido seria: efapi -n NIF_teste -u user_id_teste -p palavra_passe_teste -c receber -d caminho_de_diretoria_local_a_ser_guardado_os_ficheiros_vindos_do_servidor -t tipo_de_ficheiro -a (opcional).
Códigos de erro
| Código | Mensagem de Erro |
|---|---|
| -1 | Erro desconhecido |
| 0 | Operação efetuada com sucesso |
| 1 | Ficheiro local não existe |
| 2 | Ficheiro já existe na diretoria local |
| 3 | Ficheiro já existe no servidor |
| 4 | Tamanho de ficheiro demasiado grande |
| 5 | Argumentos inválidos no comando indicado |
| 6 | Erro no upload do ficheiro |
| 7 | Erro no download do/s ficheiro/s |
| 8 | Erro ao tentar apagar ficheiro local |
| 9 | Erro ao tentar apagar ficheiro no servidor |
| 10 | Utilizador não autenticado |
| 11 | Utilizador não tem os perfis necessários para efetuar operações neste tipo de ficheiro |
| 12 | Tipo de operação inválida |
| 13 | Tipo de ficheiro indicado inválido |
| 14 | Erro ao tentar gravar ficheiro local. Verifique se tem espaço no disco ou se tem permissões para gravar o ficheiro no diretoria indicada |
| 15 | Erro ao tentar gravar ficheiro no servidor. Poderá haver pouco espaço no disco do servidor |
| 16 | Erro de Comunicações. Verifique se não terá que definir os valores de proxy no ficheiro "config.properties" da Aplicação |
| 17 | Sistema de ficheiros remoto indisponível ou path inválido |
| 18 | Nome do ficheiro contém caracteres inválidos ou tem demasiados carateres |
| 19 | Diretoria indicada é inválida |
| 20 | Java Virtual Machine inválida |
| 21 | Utilizador temporariamente bloqueado devido a demasiadas tentativas de login falhadas. Tente novamente mais tarde. |