Skip to main content

AddPartner

Adds a partner to your IPPN account, so that you can issue documents 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/api/v1.1/partner

Sample Body​

{
"CompanyTaxId": "599138645",
"CompanyLegalName": "Magni EShop Partner, Lda.",
"CompanyAddress": "Av. Sidónio Pais, n.º 2",
"CompanyPostCode": "1050-214",
"CompanyCity": "Lisboa",
"CompanyCountry": "PT",
"UserName": "João Cardoso",
"UserEmail": "joao.cardoso@partner.pt",
"UserPhone": "912345678"
}

Request​

ParameterRequiredValue
Emailrequiredstring(50) The email of your IPPN account's main user. Example: ippn-api@yourcompany.pt
TokenrequiredYour IPPN account's token, provided by our commercial team.
note

These parameters are HTTP headers.

Body​

ParameterRequiredDescription
CompanyTaxIdrequiredstring(20) The partner's tax id (NIF), for a company or an individual. Example: "599138645"
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"
CompanyPostCoderequiredstring(50) The partner's postal code, in the Portuguese format 0000-000. Example: "1050-214"
CompanyCityrequiredstring(50) The partner's city. Example: "Lisboa"
CompanyCountryoptionalstring(2) The partner's country as an ISO 3166-1 alpha-2 code. Must be "PT", which is also the default.
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"

Response​

The response has no Object: AddPartner only records the request. Check Type, and on errors ErrorValue and ValidationErrors.

ParameterDescription
RequestIdUnique Id for the request to have a way to identify the request
Typestring Description to inform if the request was a success or error. Example value: "Success"
ErrorValueMagniEnum
- Valueint Identifies the error with a number. To identify the types of errors in more detail, click here. Example value: "2"
- Namestring Identifies the error with a token. Example value: "ValidationError"
ErrorHumanReadablestring Text that explains the error found.
ValidationErrorsList of ValidationError
- Typestring Identifies the error with a token. Example value: "InvalidValue"
- Fieldstring Name of the field in which validation failed. Example value: "CompanyCountry"
- ElementNumberint Which element failed when the field repeats; 0 otherwise. Example value: 0
- Detailstring Detailed error explanation.
IsSuccessboolean Whether the request succeeded or not. Example value: "true"
IsErrorboolean Whether the request failed or not. Example value: "false"

Errors you may get​

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​

cURL​

curl https://bo.magnifinance.com/api/v1.1/partner \
--header 'Content-Type: application/json' \
--header 'Email: ippn-api@yourcompany.pt' \
--header 'Token: your-ippn-token' \
--data-binary @partner.json

partner.json is the Sample Body.

JavaScript (fetch)​

const partner = {
CompanyTaxId: '599138645',
CompanyLegalName: 'Magni EShop Partner, Lda.',
CompanyAddress: 'Av. Sidónio Pais, n.º 2',
CompanyPostCode: '1050-214',
CompanyCity: 'Lisboa',
CompanyCountry: 'PT',
UserName: 'João Cardoso',
UserEmail: 'joao.cardoso@partner.pt',
UserPhone: '912345678',
};

fetch('https://bo.magnifinance.com/api/v1.1/partner', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
Email: 'ippn-api@yourcompany.pt',
Token: 'your-ippn-token',
},
body: JSON.stringify(partner),
})
.then((response) => response.json())
.then((result) => console.log(result))
.catch((error) => console.error(error));

Node.js (axios)​

const axios = require('axios');

const partner = {
CompanyTaxId: '599138645',
CompanyLegalName: 'Magni EShop Partner, Lda.',
CompanyAddress: 'Av. Sidónio Pais, n.º 2',
CompanyPostCode: '1050-214',
CompanyCity: 'Lisboa',
CompanyCountry: 'PT',
UserName: 'João Cardoso',
UserEmail: 'joao.cardoso@partner.pt',
UserPhone: '912345678',
};

axios
.post('https://bo.magnifinance.com/api/v1.1/partner', partner, {
headers: {
Email: 'ippn-api@yourcompany.pt',
Token: 'your-ippn-token',
},
})
.then((response) => console.log(response.data))
.catch((error) => console.error(error));

Python (requests)​

import requests

partner = {
"CompanyTaxId": "599138645",
"CompanyLegalName": "Magni EShop Partner, Lda.",
"CompanyAddress": "Av. Sidónio Pais, n.º 2",
"CompanyPostCode": "1050-214",
"CompanyCity": "Lisboa",
"CompanyCountry": "PT",
"UserName": "João Cardoso",
"UserEmail": "joao.cardoso@partner.pt",
"UserPhone": "912345678",
}

response = requests.post(
"https://bo.magnifinance.com/api/v1.1/partner",
headers={"Email": "ippn-api@yourcompany.pt", "Token": "your-ippn-token"},
json=partner,
)
print(response.json())

PHP (cURL)​

<?php
$partner = [
"CompanyTaxId" => "599138645",
"CompanyLegalName" => "Magni EShop Partner, Lda.",
"CompanyAddress" => "Av. Sidónio Pais, n.º 2",
"CompanyPostCode" => "1050-214",
"CompanyCity" => "Lisboa",
"CompanyCountry" => "PT",
"UserName" => "João Cardoso",
"UserEmail" => "joao.cardoso@partner.pt",
"UserPhone" => "912345678"
];

$ch = curl_init("https://bo.magnifinance.com/api/v1.1/partner");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
"Email: ippn-api@yourcompany.pt",
"Token: your-ippn-token",
"Content-Type: application/json"
]);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($partner));
$response = curl_exec($ch);
curl_close($ch);
echo $response;
?>

C# (HttpClient)​

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

var client = new HttpClient();
client.DefaultRequestHeaders.Add("Email", "ippn-api@yourcompany.pt");
client.DefaultRequestHeaders.Add("Token", "your-ippn-token");

var partner = new
{
CompanyTaxId = "599138645",
CompanyLegalName = "Magni EShop Partner, Lda.",
CompanyAddress = "Av. Sidónio Pais, n.º 2",
CompanyPostCode = "1050-214",
CompanyCity = "Lisboa",
CompanyCountry = "PT",
UserName = "João Cardoso",
UserEmail = "joao.cardoso@partner.pt",
UserPhone = "912345678"
};

var content = new StringContent(JsonSerializer.Serialize(partner), Encoding.UTF8, "application/json");
var response = await client.PostAsync("https://bo.magnifinance.com/api/v1.1/partner", 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 partner = """
{
"CompanyTaxId": "599138645",
"CompanyLegalName": "Magni EShop Partner, Lda.",
"CompanyAddress": "Av. Sidónio Pais, n.º 2",
"CompanyPostCode": "1050-214",
"CompanyCity": "Lisboa",
"CompanyCountry": "PT",
"UserName": "João Cardoso",
"UserEmail": "joao.cardoso@partner.pt",
"UserPhone": "912345678"
}
""";

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://bo.magnifinance.com/api/v1.1/partner"))
.header("Email", "ippn-api@yourcompany.pt")
.header("Token", "your-ippn-token")
.header("Content-Type", "application/json")
.POST(HttpRequest.BodyPublishers.ofString(partner))
.build();

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

Important Information​

What happens next depends on whether the partner 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, and can use the account to consult the documents issued in the partner's name and export SAF-T files.

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 issue 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.