Skip to main content

AddPartner

Adds a partner to your IPPN account, so that you can invoice on its behalf.

A partner can be a company or an individual: sole traders (empresários em nome individual) and self-employed workers (trabalhadores independentes, category B) can be partners too. For an individual, send their NIF in CompanyTaxId and their name in CompanyLegalName.

Portuguese partners only

Currently, document generation is only available for Portuguese tax entities. CompanyCountry must be PT (it's the default when you leave it out); any other country is rejected.

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

Sample Body​

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:inv="http://MagniAPI/Invoicing/">
<soapenv:Header/>
<soapenv:Body>
<inv:AddPartner>
<inv:Authentication>
<inv:Email>ippn-api@yourcompany.pt</inv:Email>
<inv:Token>your-ippn-token</inv:Token>
</inv:Authentication>
<inv:PartnerInformation>
<inv:UserName>João Cardoso</inv:UserName>
<inv:UserEmail>joao.cardoso@partner.pt</inv:UserEmail>
<inv:UserPhone>912345678</inv:UserPhone>
<inv:CompanyTaxId>992281008</inv:CompanyTaxId>
<inv:CompanyLegalName>Magni EShop Partner, Lda.</inv:CompanyLegalName>
<inv:CompanyAddress>Av. Sidónio Pais, n.º 2</inv:CompanyAddress>
<inv:CompanyCity>Lisboa</inv:CompanyCity>
<inv:CompanyPostCode>1050-214</inv:CompanyPostCode>
<inv:CompanyCountry>PT</inv:CompanyCountry>
</inv:PartnerInformation>
</inv:AddPartner>
</soapenv:Body>
</soapenv:Envelope>

Request​

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

Body​

Authentication​

ParameterRequiredDescription
Emailrequiredstring(50) The email of your IPPN API user.
Tokenrequiredstring(50) Your IPPN account's token.

PartnerInformation​

ParameterRequiredDescription
UserNamerequiredstring(75) Name of the contact person at the partner. Example: "João Cardoso"
UserEmailrequiredstring(75) Email of the contact person. A new partner receives its MagniFinance invitation at this address. Example: "joao.cardoso@partner.pt"
UserPhonerequiredstring(50) Phone number of the contact person. Example: "912345678"
CompanyTaxIdrequiredstring(20) The partner's tax id (NIF), for a company or an individual. Example: "992281008"
CompanyLegalNamerequiredstring(50) The partner's legal name, or the person's name for an individual. Example: "Magni EShop Partner, Lda."
CompanyAddressrequiredstring(200) The partner's address. Example: "Av. Sidónio Pais, n.º 2"
CompanyCityrequiredstring(50) The partner's city. Example: "Lisboa"
CompanyPostCoderequiredstring(50) The partner's postal code, in the Portuguese format 0000-000. Example: "1050-214"
CompanyCountryoptionalstring(2) The partner's country as an ISO 3166-1 alpha-2 code. Must be "PT", which is also the default.

The WSDL marks every field as optional (minOccurs="0"), but the service rejects the request with a ValidationError when a required field is missing.

Response​

The result is in <ResponseAddPartner>. It has no Object, because AddPartner only records the request: check Type (Success or Error), and on errors ErrorValue and ValidationErrors. See Response Format for these fields.

ErrorMeaning
ValidationErrorA required field is missing or invalid; see ValidationErrors. A country other than PT comes back as InvalidValue on CompanyCountry.
CompanyWithTaxIdAlreadyExistsThere's already an open request for this tax id in your IPPN account.
ClientOwnerAlreadyAssociatedWithPartnershipThe partner's owner is already a user of an IPPN partnership.
AuthenticationError / PartnershipNotFoundThe email and token aren't your IPPN account's main user and token.

Request Sample​

Save the Sample Body as request.xml, then:

cURL​

curl https://bo.magnifinance.com/MagniAPI/Invoicing.asmx \
--header 'Content-Type: text/xml; charset=utf-8' \
--header 'SOAPAction: "http://MagniAPI/Invoicing/AddPartner"' \
--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/Invoicing.asmx', {
method: 'POST',
headers: {
'Content-Type': 'text/xml; charset=utf-8',
SOAPAction: '"http://MagniAPI/Invoicing/AddPartner"',
},
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/Invoicing.asmx', body, {
headers: {
'Content-Type': 'text/xml; charset=utf-8',
SOAPAction: '"http://MagniAPI/Invoicing/AddPartner"',
},
})
.then((response) => console.log(response.data))
.catch((error) => console.error(error));

Important Information​

What happens next depends on whether the company already uses MagniFinance.

The partner isn't registered in MagniFinance​

MagniFinance creates its account and links it to your IPPN account automatically. This runs a few times per business day, not instantly. The contact person then receives an email to set a password.

The partner is already a MagniFinance client​

It receives an email and must approve the partnership. Until then you can't get its tokens. You can follow the request in the web interface (Config → IPPN → Partnership Management):

  • While waiting, the request is in the state access requested.
  • Once the partner approves it, the state changes to access granted. It can also reject it.
  • From then on, get the partner's tokens with GetPartnerAccessTokens and use them to create documents on its behalf.

The state isn't available through the API. Until access is granted, GetPartnerAccessTokens returns NoPartnerFoundWithTaxId.

The partner's series​

When access is granted, MagniFinance creates the partner's document series automatically, 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. They're listed in MagniFinance under Config → Séries. Communicate them to the Tax Authority with Communicate Partner Series before issuing documents.