Communicate Partner Series

The "IPPN Communicate Partner Series" API method enables IPPN users to communicate to the Portugal Tax Authority (AT) all the series of a partner that will be used for invoicing on their behalf. This can be done either by the IPPN user configuring the AT credentials of the partners if they have this data, or by the partner doing so after the company has been registered by the IPPN user.

The series communication process is legally mandatory in Portugal. By using this endpoint, you do not need to wait for the partner to communicate their series manually. This can help streamline the invoicing process and ensure compliance with legal requirements.

POST https://bo.magnifinance.com/MagniAPI/TaxCommunication.asmx

Sample Body

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:tax="http://MagniAPI/TaxCommunication/">
  <soapenv:Header/>
  <soapenv:Body>
    <tax:IPPNCommunicatePartnerSeries>
      <tax:authentication>
        <tax:Email>XXX@example.com</tax:Email>
        <tax:Token>XXX</tax:Token>
      </tax:authentication>
    </tax:IPPNCommunicatePartnerSeries>
  </soapenv:Body>
</soapenv:Envelope>

Request

Header

Parameter	Required	Value
Content-Type	required	text/xml

Body

Authentication

Parameter	Required	Description
Email	required	string(50) The API user with specific IPPN permission to communicate series in behalf of your partner. Example: api@example.com
Token	required	string(50) The token of a partner that you want to communicate their IPPN series.

info

The request body only requires authentication. No additional parameters are needed. The method will automatically communicate all document series for the partner identified by the provided token.

Response

Parameter	Description
Type	string Description to inform if the request was a success or error. Example value: "Success"
Object	Array of IPPNCommunicateSeriesOut

IPPNCommunicateSeriesOut

Parameter	Description
SeriesName	string The name of the series that the method tried to communicate to AT. Example value: "FT2023"
FiscalDocumentSubTypeId	string(1) A letter that indicates the type of the document. See table below. Example value: "T"
Status	string The status of the communication to AT. Indicates if the series was successfully communicated or not. Example value: "Communicated"

Document Sub-Types

Code	Description
T	Invoice/Receipt (Fatura/Recibo)
I	Invoice (Fatura)
S	Simplified Invoice (Fatura Simplificada)
C	Credit Note (Nota de Credito)
D	Debit Note (Nota de Debito)
B	Budget (Orcamento)
Z	Purchase Order (Encomenda)
W	Transport Guide (Guia de Transporte)
Y	Delivery Note (Guia de Entrega)
P	Pro-forma

Error Fields

Parameter	Description
ErrorValue	MagniEnum
Value	string Identifies the error with a number. To identify the types of errors in more detail, click here. Example value: "29"
Name	string Identifies the error with a token. Example value: "ATInvalidCredencials"

Request Sample

Below you can check some examples of the SOAP request in some technologies.

cURL

curl --location --request POST 'https://bo.magnifinance.com/MagniAPI/TaxCommunication.asmx' \
--header 'Content-Type: application/soap+xml; charset=utf-8' \
--data-raw '<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:tax="http://MagniAPI/TaxCommunication/">
  <soapenv:Header/>
  <soapenv:Body>
    <tax:IPPNCommunicatePartnerSeries>
      <tax:authentication>
        <tax:Email>XXX@example.com</tax:Email>
        <tax:Token>XXX</tax:Token>
      </tax:authentication>
    </tax:IPPNCommunicatePartnerSeries>
  </soapenv:Body>
</soapenv:Envelope>'

JavaScript (fetch)

var myHeaders = new Headers();
myHeaders.append("Content-Type", "application/soap+xml; charset=utf-8");

var raw = `<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:tax="http://MagniAPI/TaxCommunication/">
  <soapenv:Header/>
  <soapenv:Body>
    <tax:IPPNCommunicatePartnerSeries>
      <tax:authentication>
        <tax:Email>XXX@example.com</tax:Email>
        <tax:Token>XXX</tax:Token>
      </tax:authentication>
    </tax:IPPNCommunicatePartnerSeries>
  </soapenv:Body>
</soapenv:Envelope>`;

var requestOptions = {
  method: 'POST',
  headers: myHeaders,
  body: raw,
  redirect: 'follow'
};

fetch("https://bo.magnifinance.com/MagniAPI/TaxCommunication.asmx", 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 = `<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:tax="http://MagniAPI/TaxCommunication/">
  <soapenv:Header/>
  <soapenv:Body>
    <tax:IPPNCommunicatePartnerSeries>
      <tax:authentication>
        <tax:Email>XXX@example.com</tax:Email>
        <tax:Token>XXX</tax:Token>
      </tax:authentication>
    </tax:IPPNCommunicatePartnerSeries>
  </soapenv:Body>
</soapenv:Envelope>`;

var config = {
  method: 'post',
  url: 'https://bo.magnifinance.com/MagniAPI/TaxCommunication.asmx',
  headers: {
    'Content-Type': 'application/soap+xml; charset=utf-8'
  },
  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/MagniAPI/TaxCommunication.asmx"
headers = {
    "Content-Type": "application/soap+xml; charset=utf-8"
}
body = """<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:tax="http://MagniAPI/TaxCommunication/">
  <soapenv:Header/>
  <soapenv:Body>
    <tax:IPPNCommunicatePartnerSeries>
      <tax:authentication>
        <tax:Email>XXX@example.com</tax:Email>
        <tax:Token>XXX</tax:Token>
      </tax:authentication>
    </tax:IPPNCommunicatePartnerSeries>
  </soapenv:Body>
</soapenv:Envelope>"""

response = requests.post(url, headers=headers, data=body)
print(response.text)

PHP (cURL)

<?php
$url = "https://bo.magnifinance.com/MagniAPI/TaxCommunication.asmx";
$headers = [
    "Content-Type: application/soap+xml; charset=utf-8"
];
$body = '<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:tax="http://MagniAPI/TaxCommunication/">
  <soapenv:Header/>
  <soapenv:Body>
    <tax:IPPNCommunicatePartnerSeries>
      <tax:authentication>
        <tax:Email>XXX@example.com</tax:Email>
        <tax:Token>XXX</tax:Token>
      </tax:authentication>
    </tax:IPPNCommunicatePartnerSeries>
  </soapenv:Body>
</soapenv:Envelope>';

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $body);

$response = curl_exec($ch);
curl_close($ch);

echo $response;
?>

C# (HttpClient)

using System.Net.Http;
using System.Text;

var client = new HttpClient();

var body = @"<soapenv:Envelope xmlns:soapenv=""http://schemas.xmlsoap.org/soap/envelope/"" xmlns:tax=""http://MagniAPI/TaxCommunication/"">
  <soapenv:Header/>
  <soapenv:Body>
    <tax:IPPNCommunicatePartnerSeries>
      <tax:authentication>
        <tax:Email>XXX@example.com</tax:Email>
        <tax:Token>XXX</tax:Token>
      </tax:authentication>
    </tax:IPPNCommunicatePartnerSeries>
  </soapenv:Body>
</soapenv:Envelope>";

var content = new StringContent(body, Encoding.UTF8, "application/soap+xml");

var response = await client.PostAsync(
    "https://bo.magnifinance.com/MagniAPI/TaxCommunication.asmx",
    content
);

var result = await response.Content.ReadAsStringAsync();
Console.WriteLine(result);

Java (HttpClient)

import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.net.URI;

HttpClient client = HttpClient.newHttpClient();

String body = """
    <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:tax="http://MagniAPI/TaxCommunication/">
      <soapenv:Header/>
      <soapenv:Body>
        <tax:IPPNCommunicatePartnerSeries>
          <tax:authentication>
            <tax:Email>XXX@example.com</tax:Email>
            <tax:Token>XXX</tax:Token>
          </tax:authentication>
        </tax:IPPNCommunicatePartnerSeries>
      </soapenv:Body>
    </soapenv:Envelope>""";

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://bo.magnifinance.com/MagniAPI/TaxCommunication.asmx"))
    .header("Content-Type", "application/soap+xml; charset=utf-8")
    .POST(HttpRequest.BodyPublishers.ofString(body))
    .build();

HttpResponse<String> response = client.send(request,
    HttpResponse.BodyHandlers.ofString());

System.out.println(response.body());

Example Response

Success

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <soap:Body>
    <IPPNCommunicatePartnerSeriesResponse xmlns="http://MagniAPI/TaxCommunication/">
      <ResponseIPPNCommunicatePartnerSeries>
        <Type>Success</Type>
        <Object>
          <IPPNCommunicateSeriesOut>
            <SeriesName>MAGNITESTING</SeriesName>
            <FiscalDocumentSubTypeId>T</FiscalDocumentSubTypeId>
            <Status>Communicated</Status>
          </IPPNCommunicateSeriesOut>
          <IPPNCommunicateSeriesOut>
            <SeriesName>MAGNITESTINGNC</SeriesName>
            <FiscalDocumentSubTypeId>C</FiscalDocumentSubTypeId>
            <Status>Communicated</Status>
          </IPPNCommunicateSeriesOut>
          <IPPNCommunicateSeriesOut>
            <SeriesName>MAGNITESTINGM</SeriesName>
            <FiscalDocumentSubTypeId>T</FiscalDocumentSubTypeId>
            <Status>Communicated</Status>
          </IPPNCommunicateSeriesOut>
          <IPPNCommunicateSeriesOut>
            <SeriesName>MAGNITESTINGNCM</SeriesName>
            <FiscalDocumentSubTypeId>C</FiscalDocumentSubTypeId>
            <Status>Communicated</Status>
          </IPPNCommunicateSeriesOut>
        </Object>
      </ResponseIPPNCommunicatePartnerSeries>
    </IPPNCommunicatePartnerSeriesResponse>
  </soap:Body>
</soap:Envelope>

Error

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <soap:Body>
    <IPPNCommunicatePartnerSeriesResponse xmlns="http://MagniAPI/TaxCommunication/">
      <ResponseIPPNCommunicatePartnerSeries>
        <Type>Error</Type>
        <ErrorValue>
          <Value>29</Value>
          <Name>ATInvalidCredencials</Name>
        </ErrorValue>
      </ResponseIPPNCommunicatePartnerSeries>
    </IPPNCommunicatePartnerSeriesResponse>
  </soap:Body>
</soap:Envelope>

Important

• This method communicates all partner series to AT in a single call. There is no way to select individual series.
• Partners can either have their AT credentials configured by the IPPN user, or configure them independently after registration.
• To identify error codes in more detail, see the Error Codes page.