CommunicationList (REST)
Returns the documents that the Tax Communication service communicated, or tried to communicate, to the Tax Authority, with the current status of each one. The list is paged: you choose how many documents come in each page and which page you want.
Endpoint
POST https://bo.magnifinance.com/api/v2.1/taxCommunication/communicationList
Sample Body
{
"ElementsPerPage": 10,
"CurrentPage": 1
}
Request
Header
| Parameter | Required | Value |
|---|---|---|
| required | string(50) The email of an API user of the company. Example: api@yourcompany.pt | |
| Token | required | The subscription token of the company whose communicated documents you want to list. |
| Content-Type | required | application/json |
*Email and Token must be HTTP headers within the request.
Body
| Parameter | Required | Description |
|---|---|---|
| ElementsPerPage | optional | int How many documents you want in each page, from 1 to 100. Default: 20. Example value: 10 |
| CurrentPage | optional | int The page you want, starting at 1. Default: 1. Example value: 1 |
| TotalElements | optional | int Not used in the request: the response always returns the real total. Example value: 0 |
Always send a JSON body, even if it's just {} to use the defaults. A request without a body fails with GeneralUnknownError (3).
The request only supports pagination parameters. There are no date, status, or document type filters for this operation. Documents are ordered by CreatedOn, oldest first.
Response
| Parameter | Description |
|---|---|
| RequestId | string Unique Id for the request to have a way to identify the request. |
| Type | int 0 = Success; 1 = Error. Example value: 0 |
| Object | TaxCommunicationOut Only on success. |
| - Parameters | Object The pagination of this page. See Parameters. |
| - TaxCommunication | List of TaxCommunicationBase The documents in this page. See TaxCommunication. |
| ErrorValue | MagniEnum Only on errors. |
| - Value | int Identifies the error with a number. See Error Codes. Example value: 2 |
| - Name | string Identifies the error with a token. Example value: "ValidationError" |
| 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: "TooBig" |
| - Field | string Name of the field in which validation failed. Example value: "ElementsPerPage" |
| - 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 |
Parameters
| Parameter | Description |
|---|---|
| TotalElements | int The total number of documents in the list, across all pages: every document the service communicated or tried to communicate. Example value: 834 |
| ElementsPerPage | int The page size used. Example value: 10 |
| CurrentPage | int The page returned. Example value: 1 |
The object also carries other list fields (Initial, SortByParameter, SortAscending, SearchString, SearchFilters, TotalAmounts, CurrentStartIndex, CurrentEndIndex, TotalPages) that this operation doesn't use; ignore them. In particular, don't rely on TotalPages: work out the number of pages from TotalElements and ElementsPerPage.
TaxCommunication
| Parameter | Description |
|---|---|
| FiscalDocumentId | int The internal Id of the document. Example value: 31824 |
| FiscalDocumentNumber | string The document's sequence number in the series. Example value: "FT FT/47" |
| Date | date The date of the document. Format: YYYY-MM-DDT00:00:00. Example value: "2022-03-20T00:00:00" |
| DocumentSubTypeId | string(1) The document type code, for example "T" for Invoice/Receipt, "I" for Invoice, "C" for Credit Note or "R" for Receipt. See the document types. Example value: "I" |
| DocumentType | string The name of the document type, for example Invoice/Receipt, Invoice, Credit Note or Receipt. It names the same type as DocumentSubTypeId; see the document types. Example value: "Invoice" |
| FiscalDocumentStatusId | string(1) The status of the document as a single letter: "C" for Closed and "A" for Cancelled. Example value: "C" |
| FiscalDocumentStatus | string The name of the document status: Closed or Cancelled. Example value: "Closed" |
| IsPending | boolean true while the document hasn't been communicated yet and is still being retried automatically. It becomes false once the document is communicated, or after 3 failed attempts. See Documents that weren't communicated. Example value: false |
| IsSubmitted | boolean Whether the document was communicated to the Tax Authority successfully. Example value: true |
| LastError | string The last error message returned by the Tax Authority when trying to communicate the document. |
| CreatedOn | date When the document was added to the communication queue, normally right after it was created. Example value: "2020-08-12T14:10:20.94" |
| IsLimitedInfo | boolean true when some details of this document were left out because of the API user's permissions (see below). Example value: false |
| CreatedBy | int The internal Id of the user who created the document. Example value: 1234 |
An API user that can view the company's documents gets every field. Otherwise some details are left out, and the documents they're left out of have IsLimitedInfo set to true:
- A user that can only work with its own documents gets everything for its own documents. For documents created by other users,
FiscalDocumentNumber,DocumentSubTypeId,FiscalDocumentStatusIdandLastErrorare empty, andDate,CreatedOn,DocumentTypeandFiscalDocumentStatusarenull. - A user that can't view documents only gets
FiscalDocumentId,IsPending,IsSubmittedandCreatedBy.
The meaning of IsPending and IsSubmitted together, and how to resubmit a document that failed, is explained in Documents that weren't communicated.
Errors
| ErrorValue | When |
|---|---|
AuthenticationError (1) | The email or token is wrong. |
ValidationError (2) | ElementsPerPage is greater than 100. |
GeneralUnknownError (3) | There's no request body, ElementsPerPage or CurrentPage is lower than 1, or something went wrong on our side. |
SubscriptionExpired (5) | The company's subscription isn't active. |
WithoutPermission (31) | The API user doesn't have permission to list communicated documents. |
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/communicationList' \
--header 'email: api@yourcompany.pt' \
--header 'token: your-subscription-token' \
--header 'Content-Type: application/json' \
--data-raw '{
"ElementsPerPage": 10,
"CurrentPage": 1
}'
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({
"ElementsPerPage": 10,
"CurrentPage": 1
});
var requestOptions = {
method: 'POST',
headers: myHeaders,
body: raw,
redirect: 'follow'
};
fetch("https://bo.magnifinance.com/api/v2.1/taxCommunication/communicationList", 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({
"ElementsPerPage": 10,
"CurrentPage": 1
});
var config = {
method: 'post',
url: 'https://bo.magnifinance.com/api/v2.1/taxCommunication/communicationList',
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/communicationList"
headers = {
"email": "api@yourcompany.pt",
"token": "your-subscription-token"
}
body = {
"ElementsPerPage": 10,
"CurrentPage": 1
}
response = requests.post(url, headers=headers, json=body)
print(response.json())
PHP (cURL)
<?php
$body = json_encode([
"ElementsPerPage" => 10,
"CurrentPage" => 1
]);
$ch = curl_init("https://bo.magnifinance.com/api/v2.1/taxCommunication/communicationList");
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 = @"{
""ElementsPerPage"": 10,
""CurrentPage"": 1
}";
var content = new StringContent(body, Encoding.UTF8, "application/json");
var response = await client.PostAsync("https://bo.magnifinance.com/api/v2.1/taxCommunication/communicationList", 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 = """
{
"ElementsPerPage": 10,
"CurrentPage": 1
}""";
HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://bo.magnifinance.com/api/v2.1/taxCommunication/communicationList"))
.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
{
"RequestId": "2ec7e0ba-ce40-4a4c-a053-df081be53533",
"Object": {
"Parameters": {
"TotalElements": 834,
"ElementsPerPage": 10,
"CurrentPage": 1,
"Initial": true,
"SortByParameter": null,
"SortAscending": true,
"SearchString": "",
"SearchFilters": null,
"TotalAmounts": null,
"CurrentStartIndex": 0,
"CurrentEndIndex": 0,
"TotalPages": 0
},
"TaxCommunication": [
{
"FiscalDocumentId": 31824,
"FiscalDocumentNumber": "FTM FTmu/23",
"Date": "2020-10-16T00:00:00",
"DocumentSubTypeId": "I",
"DocumentType": "Invoice",
"FiscalDocumentStatusId": "C",
"FiscalDocumentStatus": "Closed",
"IsPending": false,
"IsSubmitted": true,
"LastError": null,
"CreatedOn": "2020-08-12T14:10:20.94",
"IsLimitedInfo": false,
"CreatedBy": 1234
},
{
"FiscalDocumentId": 35455,
"FiscalDocumentNumber": "NC TestNC/5",
"Date": "2020-08-20T00:00:00",
"DocumentSubTypeId": "C",
"DocumentType": "Credit Note",
"FiscalDocumentStatusId": "C",
"FiscalDocumentStatus": "Closed",
"IsPending": true,
"IsSubmitted": false,
"LastError": null,
"CreatedOn": "2020-08-24T17:57:09.25",
"IsLimitedInfo": false,
"CreatedBy": 1234
}
]
},
"Type": 0,
"ErrorValue": null,
"ErrorHumanReadable": null,
"ValidationErrors": null,
"IsSuccess": true,
"IsError": false
}
Error
{
"RequestId": "5165e271-97ec-4425-aa33-f7c32c7c6f3d",
"Object": null,
"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.