EFAPI Desktop Application User Guide
Introduction
The EFAPI application (Online Delivery of Customs Files) allows the automatic or interactive transfer of files through a user-friendly and economic channel (Internet).
Available operations include sending and retrieving files securely, listing and deleting responses regarding file submissions.
Users interact with the system using:
- An option available in EFAPIINTER that allows the "manual" sending and capturing of files;
- A client application that works through a command line on the user's machine and allows the sending and capturing of files automatically.
This guide aims to provide the basic elements of the EFAPI application in order to facilitate its use by economic operators regarding the electronic transfer of data within the scope of Export, Import and Transit.
Characterisation of the EFAPI Application
Users
The application is available to users with the following profiles:
- DAV (SFA user);
- DUE (STADA Export user);
- DUI (STADA Import user);
- TRS (Transit user).
To obtain one of these profiles, i.e. if you do not yet have the desired profile, you must ask GUE (link in "Useful Links" section) to assign you the desired profile.
Restrictions
The functionalities of the EFAPI application can only be accessed and used by users with one of the profiles indicated above.
Each user will only be able to carry out send, retrieve, list and delete operations on their own files. Below we indicate a table with the types of documents that can be sent, received and removed according to the profile of the operator.
| Profile | Vehicle Customs Declaration | Electronic Transit Declaration | Electronic Export Declaration | Exit Summary Declaration | Single Administrative Document (DUI2) | Unique Import Document (DUI) |
|---|---|---|---|---|---|---|
| DAV | X | |||||
| DUE | X | X | ||||
| DUI | X | X | ||||
| TRS | X |
Functionalities ensured
The application is designed to ensure the following:
- File transfer between the user's machine and EFAPI, either automatically or interactively ("manually");
- Files sent and their replies can be deleted at the user's option (automatically via command line or interactively via browser);
- Only properly authenticated users can use this service;
- Users can only perform operations on their own files;
- Files sent and their replies will be saved on the file system until they are deleted;
- The responses that are sent to the recycling board will be subject to periodic cleaning;
- All communications will be carried out over a secure channel (in this case HTTP over SSL) guaranteeing the confidentiality and integrity of the messages exchanged.
Available environments
EFAPI Internet provides two environments via the Portal Aduaneiro through these addresses:
Both environments allow the use of EFAPI, with the quality/testing environment aimed at verifying the application before going into production.
EFAPI Client Application
Minimum Requirements
- Internet connection;
Installation
After making sure that the operator's machine has the minimum requirements to use the application, it is necessary to obtain the archive with the application in order to install and run it. The following steps should be performed:
- After accessing the application download page, you should choose the archive that corresponds to the operating system of your computer. In this example, we have chosen the zip archive for the Windows operating system. After selecting the desired archive, the download will start. After the download has finished, you should go to your computer's download folder and extract its contents to your preferred location.
- After downloading the archive, we recomend validating the SHA-512 hash. To guarantee that the obtained file is from a trustful source, the user will have to generate a SHA-512 hash with the archive that he just obtained and compare it with the hash that is available in the download page. For that, the user will have to execute one of the following commands based on the operating system that he is using:
| Operating System | Command |
|---|---|
| Windows | certutil -hashfile "archive_path" SHA512 type "archive_name.sha512" |
| Mac / Linux | sha512sum -t "archive_path" |
After executing the command, the user should compare the character sequence produced by the command with the sha512 file obtained via the download page and see if they match. If they match, the user can proceed to the next steps.
- After extracting the archive, a folder named efapi-"version" should have been generated and should have the following files:
Regarding the path on where to place the folder created from the zip/tar.gz extracted, we suggest placing it in a path like, for example, C:\EFAPI (example for Windows) and avoid placing in the usual folders such as Program Files and Program Files(x86) that need administrator priveleges when trying to create folders/files (e.g. logs), which might cause problems in the aplication's overall functionality.
Configuration
After installation, the operator normally performs tests in Quality to get familiar with the use of the program and test that everything is working correctly. For the operator to be able to test in Quality it is necessary to perform the following steps:
- Access the folder where the application was installed;
- Open the "config.properties" file with Notepad/Notepad++;
- Place a '#' before the "server.url" property to comment out the Production endpoint (line 5);
- Remove the '#' that is placed before the property "server.url" to uncomment the Quality endpoint (line 8);
- Save the changes to the file;
- Close Notepad.
After performing the tests in Quality, if the operator wants to perform operations in the Production environment he will have to comment the Quality endpoint and uncomment the Production one and save the changes in the "config.properties" file.
Using the EFAPI Client Application
The use of the command line allows manual intervention by the user, however, its main objective and greatest advantage is to enable its invocation from a user application in order to automate the operations of sending and receiving files.
File upload
| Context | The entity wants to send a DU file using the command line |
|---|---|
| Primary actor | Entity |
| Preconditions | The primary actor exists in the Portal de Finanças and has the required profile |
| Guarantees | The application guarantees, under all circumstances, the creation of the secure channel and authentication before the system |
| Expected frequency | Frequently |
| Restrictions and limitations |
|
| Start event | The user accesses the command line |
Example of command
With a command prompt open (make sure it is in the path where the EFAPI application was extracted), execute the command "efapi (./efapi.sh for linux and mac versions) -n NIF_test -p password_test -c enviar -d local_path_of_folder_where_the_file_is_located -f file_name -t file_type -a" (the 'a' is an optional flag in case the user wants to remove local file after the upload has been performed).
If the response code returned is 0, the operation was successful.
If the test user is a subuser (userID different than 0) it is necessary to indicate the -u flag after the nif (-n). If the -u flag is omitted, the user ID is by default 0. So an example command with the user ID set would be: efapi -n NIF_test -u user_id_test -p password_test -c enviar -d path_location_of_file_to_be_sent -f file_name -t file_type.
File download
| Context | The operator wants to receive all responses to the files he sent using the command line |
|---|---|
| Primary actor | User |
| Preconditions | The primary actor is registered in the Portal de Finanças and has the necessary profile for the type of file he wants to receive. |
| Guarantees | The application guarantees, in all circumstances, the creation of the secure channel and authentication before the system |
| Expected frequency | Frequently |
| Restrictions and limitations |
|
| Start event | The user accesses the command line |
Example of command
With the command line open via the application's shortcut or .cmd file, run the command "efapi (./efapi.sh for linux and mac versions) -n NIF_test -p password_test -c receber -d path_of_local_directory_to_save_files_coming_from_server -t file_type -a" (the 'a' is an optional flag in case the user wants to remove the files from the server after receiving them).
If the response code returned is 0, the operation was successful. If there were files on the server side associated to the NIF, the user should receive them in the folder where he indicated in the command. However, even though it returns the response with the code 0, the user may not receive any files because there is not one present on the server that is associated with the NIF and sub-user id given in the command.
If the test user is a subuser (userID different than 0) it is necessary to indicate the -u flag after the nif (-n). If the -u flag is omitted, the user ID is by default 0. So an example command with the user ID set would be: efapi -n NIF_test -u user_id_test -p password_test -c receber -d path_of_local_directory_to_save_from_server -t file_type -a (optional).
Error codes
| Code | Error Message |
|---|---|
| -1 | Unknown error |
| 0 | Successfully performed operation |
| 1 | Local file does not exist |
| 2 | File already exists in the local directory |
| 3 | File already exists on the server |
| 4 | File size too large |
| 5 | Invalid arguments in the given command |
| 6 | Error when uploading the file |
| 7 | Error when downloading the file/s |
| 8 | Error when trying to delete local file |
| 9 | Error when trying to delete file on the server |
| 10 | Unauthenticated user |
| 11 | User does not have the necessary profiles to perform operations on this type of file |
| 12 | Invalid type of operation |
| 13 | Type of file indicated is invalid |
| 14 | Error when trying to save local file. Check if you have disk space or permissions to save the file in the specified directory |
| 15 | Error when trying to save file on the server. There may be low disk space on the server |
| 16 | Communications Error. Check that you do not have to set the proxy values in the "config.properties" file of the Application |
| 17 | Remote filesystem unavailable or invalid path |
| 18 | File name contains invalid characters or has too many characters |
| 19 | The given directory is invalid |
| 20 | Invalid Java Virtual Machine |
| 21 | User temporarily blocked due to several failed login attempts. Try again later. |