Activation Set (REST)
Turns the Tax Communication service on or off for your company. While it's on, your fiscal documents are communicated to the Tax Authority (AT) automatically after they are created.
To turn it on you need a Tax Authority user and password with the appropriate permissions ('WFA - Comunicacao de dados de faturas' and/or 'WDT - Comunicacao de dados de documentos de transporte'), created on the Portal das Financas website.
When you turn the service on, the credentials are checked against the Tax Authority right away, and the response tells you whether the service is active.
Endpoint
POST https://bo.magnifinance.com/api/v2.1/taxCommunication/activationSet
Sample Body
{
"Username": "your-at-username",
"Password": "your-at-password",
"IsActive": true
}
Request
Header
| Parameter | Required | Value |
|---|---|---|
| required | string(50) The email of an API user with permission to configure this service for the company. Example: api@yourcompany.pt | |
| Token | required | The subscription token of the company for which you are turning the service on or off. |
| Content-Type | required | application/json |
*Email and Token must be HTTP headers within the request.
Body
| Parameter | Required | Description |
|---|---|---|
| Username | required when IsActive is true | string(250) The Tax Authority (AT) user with the appropriate permission (WFA / WDT). You can create it on the AT website under 'Servicos tributarios / Outros servicos / Gestao de utilizadores': create a user and give it the permissions 'WFA - Comunicacao de dados de faturas' and/or 'WDT - Comunicacao de dados de documentos de transporte'. Example value: "your-at-username" |
| Password | required when IsActive is true | string (min = 6 and max = 50) The password of that Tax Authority user. Example value: "your-at-password" |
| IsActive | required | boolean true saves the user and password and turns the service on if the Tax Authority accepts them. false removes the saved Tax Authority user and turns the service off; Username and Password are ignored. If you leave it out, it's treated as false. Example value: true |
The AT credentials are checked in real time against the Portal das Financas. Invalid credentials deactivate the communication. If the Tax Authority rejects them (wrong password, or the user doesn't have the WFA/WDT permissions), this isn't an error: the request succeeds (Type is 0), the service is switched off, and Object.IsActive is false. Always read Object.IsActive, not only Type.
To create the required AT user, go to Portal das Financas and navigate to Servicos tributarios > Outros servicos > Gestao de utilizadores. Create a new user and assign the permissions WFA - Comunicacao de dados de faturas and/or WDT - Comunicacao de dados de documentos de transporte.
Response
| Parameter | Description |
|---|---|
| RequestId | string Unique Id for the request to have a way to identify the request. It can be null on some responses of this operation. |
| Type | int 0 = Success; 1 = Error. Example value: 0 |
| Object | Activation Only when you sent IsActive: true and the request succeeded. When you turn the service off, the response has no Object. |
| - IsActive | boolean Whether the Tax Communication service is now active. false when the Tax Authority rejected the credentials. Example value: true |
| - Username | string Always null in this response. |
| - Password | string Always null in this response. |
| ErrorValue | MagniEnum Only on errors. |
| - Value | int Identifies the error with a number. See Error Codes. Example value: 1 |
| - Name | string Identifies the error with a token. Example value: "AuthenticationError" |
| ErrorHumanReadable | string Text that explains the error found. |
| ValidationErrors | List of ValidationError Only when ErrorValue is ValidationError. |
| - Type | string Identifies the error with a token. Example value: "EmptyField" |
| - Field | string Name of the field in which validation failed: ATUser (the Username) or ATPassword (the Password). Example value: "ATPassword" |
| - ElementNumber | int 0 for this operation. |
| - Detail | string Detailed error explanation. |
| IsError | boolean Whether the request failed or not. Example value: false |
| IsSuccess | boolean Whether the request succeeded or not. Example value: true |
Errors
| ErrorValue | When |
|---|---|
AuthenticationError (1) | The email or token is wrong. |
ValidationError (2) | IsActive is true and Username or Password is missing, Username is longer than 250 characters, or Password is shorter than 6 or longer than 50 characters. |
GeneralUnknownError (3) | Something went wrong on our side, for example while contacting the Tax Authority. Try again later. |
SubscriptionExpired (5) | The company's subscription isn't active. |
WithoutPermission (31) | The API user doesn't have permission to configure Tax Communication. |
If the Email or Token header is missing, the API answers HTTP 401 Unauthorized with no body.
Request Samples
Below you can check some examples of the REST request in some technologies.
cURL
curl --location --request POST 'https://bo.magnifinance.com/api/v2.1/taxCommunication/activationSet' \
--header 'email: api@yourcompany.pt' \
--header 'token: your-subscription-token' \
--header 'Content-Type: application/json' \
--data-raw '{
"Username": "your-at-username",
"Password": "your-at-password",
"IsActive": true
}'
JavaScript (fetch)
var myHeaders = new Headers();
myHeaders.append("email", "api@yourcompany.pt");
myHeaders.append("token", "your-subscription-token");
myHeaders.append("Content-Type", "application/json");
var raw = JSON.stringify({
"Username": "your-at-username",
"Password": "your-at-password",
"IsActive": true
});
var requestOptions = {
method: 'POST',
headers: myHeaders,
body: raw,
redirect: 'follow'
};
fetch("https://bo.magnifinance.com/api/v2.1/taxCommunication/activationSet", requestOptions)
.then(response => response.text())
.then(result => console.log(result))
.catch(error => console.log('error', error));
Node.js (axios)
var axios = require('axios');
var data = JSON.stringify({
"Username": "your-at-username",
"Password": "your-at-password",
"IsActive": true
});
var config = {
method: 'post',
url: 'https://bo.magnifinance.com/api/v2.1/taxCommunication/activationSet',
headers: {
'email': 'api@yourcompany.pt',
'token': 'your-subscription-token',
'Content-Type': 'application/json'
},
data: data
};
axios(config)
.then(function (response) {
console.log(JSON.stringify(response.data));
})
.catch(function (error) {
console.log(error);
});
Python (requests)
import requests
url = "https://bo.magnifinance.com/api/v2.1/taxCommunication/activationSet"
headers = {
"email": "api@yourcompany.pt",
"token": "your-subscription-token"
}
body = {
"Username": "your-at-username",
"Password": "your-at-password",
"IsActive": True
}
response = requests.post(url, headers=headers, json=body)
print(response.json())
PHP (cURL)
<?php
$body = json_encode([
"Username" => "your-at-username",
"Password" => "your-at-password",
"IsActive" => true
]);
$ch = curl_init("https://bo.magnifinance.com/api/v2.1/taxCommunication/activationSet");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $body);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
"email: api@yourcompany.pt",
"token: your-subscription-token",
"Content-Type: application/json"
]);
$response = curl_exec($ch);
curl_close($ch);
echo $response;
?>
C# (HttpClient)
using System.Net.Http;
using System.Text;
var client = new HttpClient();
client.DefaultRequestHeaders.Add("email", "api@yourcompany.pt");
client.DefaultRequestHeaders.Add("token", "your-subscription-token");
var body = @"{
""Username"": ""your-at-username"",
""Password"": ""your-at-password"",
""IsActive"": true
}";
var content = new StringContent(body, Encoding.UTF8, "application/json");
var response = await client.PostAsync("https://bo.magnifinance.com/api/v2.1/taxCommunication/activationSet", content);
Console.WriteLine(await response.Content.ReadAsStringAsync());
Java (HttpClient)
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
String body = """
{
"Username": "your-at-username",
"Password": "your-at-password",
"IsActive": true
}""";
HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://bo.magnifinance.com/api/v2.1/taxCommunication/activationSet"))
.header("email", "api@yourcompany.pt")
.header("token", "your-subscription-token")
.header("Content-Type", "application/json")
.POST(HttpRequest.BodyPublishers.ofString(body))
.build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
Example Response
Success (service turned on)
{
"RequestId": null,
"Object": {
"Username": null,
"Password": null,
"IsActive": true
},
"Type": 0,
"ErrorValue": null,
"ErrorHumanReadable": null,
"ValidationErrors": null,
"IsSuccess": true,
"IsError": false
}
Success (service turned off)
{
"RequestId": "08d52dd7-cfba-4542-abeb-935504ccdbaa",
"Type": 0,
"ErrorValue": null,
"ErrorHumanReadable": null,
"ValidationErrors": null,
"IsSuccess": true,
"IsError": false
}
Error
{
"RequestId": "5165e271-97ec-4425-aa33-f7c32c7c6f3d",
"Type": 1,
"ErrorValue": {
"Value": 1,
"Name": "AuthenticationError"
},
"ErrorHumanReadable": null,
"ValidationErrors": null,
"IsSuccess": false,
"IsError": true
}
For a complete list of error codes and their meanings, see the Error Codes page.