Skip to main content

Communicate Partner Series

Communicates a partner's document series to the Portuguese Tax Authority (AT), so that you can issue documents in them on the partner's behalf. Portuguese law requires every series to be communicated before it's used. With this operation you don't have to wait for the partner to do it.

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

PostmanTry it in Postman

This operation is the last request of both IPPN Postman collections, REST and SOAP, with the envelope already set and the partner's token taken from the Get Partner Access Tokens request before it. How to use them.

Before you call it​

  • Tax communication must be active for the partner. Call Activation Set with the partner's token and its AT credentials first, or let the partner configure them in its own account. Without them the call returns ATInvalidCredencials.
  • You don't create the series. MagniFinance creates them in the partner's account when the partnership is granted. They're named after your partnership's code: <CODE> for invoice-receipts and <CODE>NC for credit notes. Partnerships set up for self-billing also get <CODE>AF and <CODE>NCAF. You and the partner can see them in MagniFinance under Config → Séries.

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>ippn-api@yourcompany.pt</tax:Email>
<tax:Token>partner-token</tax:Token>
</tax:authentication>
</tax:IPPNCommunicatePartnerSeries>
</soapenv:Body>
</soapenv:Envelope>

Request​

ParameterRequiredValue
Content-Typerequiredtext/xml; charset=utf-8
SOAPActionoptional"http://MagniAPI/TaxCommunication/IPPNCommunicatePartnerSeries"

The envelope above is SOAP 1.1, so send it as text/xml. Sending it as application/soap+xml returns HTTP 415. See SOAP version and headers.

Body​

authentication​

ParameterRequiredDescription
Emailrequiredstring(50) The email of your IPPN API user. Example: ippn-api@yourcompany.pt
Tokenrequiredstring(50) The partner's token, from GetPartnerAccessTokens. The series communicated are that partner's.

There are no other parameters: the call communicates all of the partner's series. You can't pick individual ones.

Response​

The result is in <ResponseIPPNCommunicatePartnerSeries>; see Response Format for the fields every response has. Object has one IPPNCommunicateSeriesOut per series:

ParameterDescription
SeriesNamestring The series' name. Example: "MAGNITESTING"
FiscalDocumentSubTypeIdstring(1) The document type of the series: T for invoice-receipts, C for credit notes.
Statusstring Communicated (the series is registered at AT, now or before), CommunicationError (AT rejected it) or CreationError (the series couldn't be created in the partner's account).

Calling it again is safe: series already registered at AT come back as Communicated and aren't sent again.

Request Sample​

Save the Sample Body as request.xml, then:

cURL​

curl https://bo.magnifinance.com/MagniAPI/TaxCommunication.asmx \
--header 'Content-Type: text/xml; charset=utf-8' \
--header 'SOAPAction: "http://MagniAPI/TaxCommunication/IPPNCommunicatePartnerSeries"' \
--data-binary @request.xml

JavaScript (Node.js 18+)​

const fs = require('fs');

const body = fs.readFileSync('request.xml', 'utf8');

fetch('https://bo.magnifinance.com/MagniAPI/TaxCommunication.asmx', {
method: 'POST',
headers: {
'Content-Type': 'text/xml; charset=utf-8',
SOAPAction: '"http://MagniAPI/TaxCommunication/IPPNCommunicatePartnerSeries"',
},
body,
})
.then((response) => response.text())
.then((xml) => console.log(xml))
.catch((error) => console.error(error));

Node.js (axios)​

const fs = require('fs');
const axios = require('axios');

const body = fs.readFileSync('request.xml', 'utf8');

axios
.post('https://bo.magnifinance.com/MagniAPI/TaxCommunication.asmx', body, {
headers: {
'Content-Type': 'text/xml; charset=utf-8',
SOAPAction: '"http://MagniAPI/TaxCommunication/IPPNCommunicatePartnerSeries"',
},
})
.then((response) => console.log(response.data))
.catch((error) => console.error(error));

Example Response​

Success​

<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>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>
</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>

ATInvalidCredencials means the partner's tax communication isn't active or its AT credentials are wrong. See Error Codes for the others.