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.
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
Header
| Parameter | Required | Value |
|---|---|---|
| required | string(50) The email of your IPPN account's main user. Example: ippn-api@yourcompany.pt | |
| Token | required | Your IPPN account's token, provided by our commercial team. |
These parameters are HTTP headers.
Body
| Parameter | Required | Description |
|---|---|---|
| CompanyTaxId | required | string(20) The partner's tax id (NIF), for a company or an individual. Example: "599138645" |
| CompanyLegalName | required | string(50) The partner's legal name, or the person's name for an individual. Example: "Magni EShop Partner, Lda." |
| CompanyAddress | required | string(200) The partner's address. Example: "Av. Sidónio Pais, n.º 2" |
| CompanyPostCode | required | string(50) The partner's postal code, in the Portuguese format 0000-000. Example: "1050-214" |
| CompanyCity | required | string(50) The partner's city. Example: "Lisboa" |
| CompanyCountry | optional | string(2) The partner's country as an ISO 3166-1 alpha-2 code. Must be "PT", which is also the default. |
| UserName | required | string(75) Name of the contact person at the partner. Example: "João Cardoso" |
| UserEmail | required | string(75) Email of the contact person. A new partner receives its MagniFinance invitation at this address. Example: "joao.cardoso@partner.pt" |
| UserPhone | required | string(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.
| Parameter | Description |
|---|---|
| RequestId | Unique Id for the request to have a way to identify the request |
| Type | string Description to inform if the request was a success or error. Example value: "Success" |
| ErrorValue | MagniEnum |
| - Value | int Identifies the error with a number. To identify the types of errors in more detail, click here. Example value: "2" |
| - Name | string Identifies the error with a token. Example value: "ValidationError" |
| ErrorHumanReadable | string Text that explains the error found. |
| ValidationErrors | List of ValidationError |
| - Type | string Identifies the error with a token. Example value: "InvalidValue" |
| - Field | string Name of the field in which validation failed. Example value: "CompanyCountry" |
| - ElementNumber | int Which element failed when the field repeats; 0 otherwise. Example value: 0 |
| - Detail | string Detailed error explanation. |
| IsSuccess | boolean Whether the request succeeded or not. Example value: "true" |
| IsError | boolean Whether the request failed or not. Example value: "false" |
Errors you may get
| Error | Meaning |
|---|---|
ValidationError | A required field is missing or invalid; see ValidationErrors. A country other than PT comes back as InvalidValue on CompanyCountry. |
CompanyWithTaxIdAlreadyExists | There's already an open request for this tax id in your IPPN account. |
ClientOwnerAlreadyAssociatedWithPartnership | The partner's owner is already a user of an IPPN partnership. |
AuthenticationError / PartnershipNotFound | The 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.