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
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>NCfor credit notes. Partnerships set up for self-billing also get<CODE>AFand<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
Header
| Parameter | Required | Value |
|---|---|---|
| Content-Type | required | text/xml; charset=utf-8 |
| SOAPAction | optional | "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
| Parameter | Required | Description |
|---|---|---|
| required | string(50) The email of your IPPN API user. Example: ippn-api@yourcompany.pt | |
| Token | required | string(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:
| Parameter | Description |
|---|---|
| SeriesName | string The series' name. Example: "MAGNITESTING" |
| FiscalDocumentSubTypeId | string(1) The document type of the series: T for invoice-receipts, C for credit notes. |
| Status | string 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.