Skip to main content

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​

ParameterRequiredValue
Emailrequiredstring(50) The email of an API user of the company. Example: api@yourcompany.pt
TokenrequiredThe subscription token of the company whose communicated documents you want to list.
Content-Typerequiredapplication/json
note

*Email and Token must be HTTP headers within the request.

Body​

ParameterRequiredDescription
ElementsPerPageoptionalint How many documents you want in each page, from 1 to 100. Default: 20. Example value: 10
CurrentPageoptionalint The page you want, starting at 1. Default: 1. Example value: 1
TotalElementsoptionalint Not used in the request: the response always returns the real total. Example value: 0
Send a body

Always send a JSON body, even if it's just {} to use the defaults. A request without a body fails with GeneralUnknownError (3).

note

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​

ParameterDescription
RequestIdstring Unique Id for the request to have a way to identify the request.
Typeint 0 = Success; 1 = Error. Example value: 0
ObjectTaxCommunicationOut Only on success.
- ParametersObject The pagination of this page. See Parameters.
- TaxCommunicationList of TaxCommunicationBase The documents in this page. See TaxCommunication.
ErrorValueMagniEnum Only on errors.
- Valueint Identifies the error with a number. See Error Codes. Example value: 2
- Namestring Identifies the error with a token. Example value: "ValidationError"
ErrorHumanReadablestring Text that explains the error found.
ValidationErrorsList of ValidationError Only when ErrorValue is ValidationError.
- Typestring Identifies the error with a token. Example value: "TooBig"
- Fieldstring Name of the field in which validation failed. Example value: "ElementsPerPage"
- ElementNumberint 0 for this operation.
- Detailstring Detailed error explanation.
IsErrorboolean Whether the request failed or not. Example value: false
IsSuccessboolean Whether the request succeeded or not. Example value: true

Parameters​

ParameterDescription
TotalElementsint The total number of documents in the list, across all pages: every document the service communicated or tried to communicate. Example value: 834
ElementsPerPageint The page size used. Example value: 10
CurrentPageint 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​

ParameterDescription
FiscalDocumentIdint The internal Id of the document. Example value: 31824
FiscalDocumentNumberstring The document's sequence number in the series. Example value: "FT FT/47"
Datedate The date of the document. Format: YYYY-MM-DDT00:00:00. Example value: "2022-03-20T00:00:00"
DocumentSubTypeIdstring(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"
DocumentTypestring 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"
FiscalDocumentStatusIdstring(1) The status of the document as a single letter: "C" for Closed and "A" for Cancelled. Example value: "C"
FiscalDocumentStatusstring The name of the document status: Closed or Cancelled. Example value: "Closed"
IsPendingboolean 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
IsSubmittedboolean Whether the document was communicated to the Tax Authority successfully. Example value: true
LastErrorstring The last error message returned by the Tax Authority when trying to communicate the document.
CreatedOndate When the document was added to the communication queue, normally right after it was created. Example value: "2020-08-12T14:10:20.94"
IsLimitedInfoboolean true when some details of this document were left out because of the API user's permissions (see below). Example value: false
CreatedByint The internal Id of the user who created the document. Example value: 1234
What you see depends on the API user's permissions

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, FiscalDocumentStatusId and LastError are empty, and Date, CreatedOn, DocumentType and FiscalDocumentStatus are null.
  • A user that can't view documents only gets FiscalDocumentId, IsPending, IsSubmitted and CreatedBy.

The meaning of IsPending and IsSubmitted together, and how to resubmit a document that failed, is explained in Documents that weren't communicated.

Errors​

ErrorValueWhen
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
}
note

For a complete list of error codes and their meanings, see the Error Codes page.