REST API

SOAP API

API 2.1

AddPartner

The AddPartner method allows you to register a new company/partner into your IPPN account. Using this method, it is possible to get access for invoicing on behalf of them.

POST https://bo.magnifinance.com/api/v1.1/partner

Sample Body


                             {
                             "CompanyTaxId": "",
                             "UserName": "",
                             "UserEmail": "", 
                             "CompanyLegalName": "",
                             "CompanyAddress": "",
                             "CompanyCity": "",
                             "CompanyPostCode": "",
                             "CompanyCountry": "",
                             "UserPhone": ""
                             }

Request

Header

Parameter	Required	value
Email	required	string(50) The email address of the owner of the IPPN service with specific permissions to use IPPN services. Example: api@example.com
Token	required	The token for the IPPN account is specific to your IPPN service and is provided by our commercial team.

*These parameters must be an HTTP headers within the request.

Body

PartnerInformation

Parameter	Required	Description
CompanyTaxId	optional	string(20) Partner organization’s tax id. Example value: "513495886"
UserName	optional	string(75) Name of the contact person in the partner organization. Example value: "João Cardoso"
UserEmail	optional	string(75) Name of the contact person in the partner organization. Example value: "tech-success@magnifinance.com"
UserPhone	optional	string(50) Phone number of the contact person in the partner organization. Example value: "999555111"
CompanyLegalName	optional	string(50) Partner organization’s legal name. Example value: "Magni EShop Partner"
CompanyAddress	optional	string(200) Partner organization’s address. Example value: "Av. Sidónio Pais"
CompanyCity	optional	string(50) Partner organization’s city. Example value: "Lisboa"
CompanyPostCode	optional	string(50) Partner organization’s post code. Example value: "1050-214"
CompanyCountry	optional	string(2) Partner organization’s country code. (To consult the code list for each country, access the link: ISO 3166-1 alpha-2 Example value: "pt"

Response

Type

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	string Identifies the error with a number. To identify the types of errors in more detail, click here. Example value: "38"
Name	string Identifies the error with a token. Example value: "PartnershipNotFound"

ErrorHumanReadable

string Text that explains the error found. Example value: "ValidationError"

ValidationErrors

List of ValidationError

Type	string Identifies the error with a token. Example value: "DocumentIsADuplicate"
Field	string Name of the field in which validation failed. Example value: "DocumentDetailExternalId"
ElementNumber	int Identifies index of the field in which validation failed. Example value: "67204"
Detail	string Detailed error explanation. Example value: "Duplicate Document"

IsSuccess

boolean Whether the request succeeded or not. Example value: "true"

IsError

boolean Whether the request failed or not. Example value: "false"

Request Sample

Below you can check some examples of the REST request in some technologies.

cURL


                                 curl --location --request POST 'https://bo.magnifinance.com/api/v1.1/partner' \
                                 --header 'Content-Type: application/json' \
                                 --header 'Email: XXX@example.com' \
                                 --header 'Token: XXX' \
                                 --data-raw '    {
                                 "CompanyTaxId": "",
                                 "UserName": "",
                                 "UserEmail": "", 
                                 "CompanyLegalName": "",
                                 "CompanyAddress": "",
                                 "CompanyCity": "",
                                 "CompanyPostCode": "",
                                 "CompanyCountry": "",
                                 "UserPhone": ""
                                 }'

Javascript (fetch)


                                 var myHeaders = new Headers();
                                 myHeaders.append("Email", "XXX@example.com");
                                 myHeaders.append("Token", "XXX");
                                 myHeaders.append("Content-Type", "application/json");
                                 var raw = "   \r\n    \"CompanyTaxId\": \"\",\r\n    \"UserName\": \"\",\r\n    \"UserEmail\": \"",\r\n    \"CompanyLegalName\": \"\",\r\n    \"CompanyAddress\": \"Address\",\r\n    \"CompanyCity\": \"City\",\r\n    \"CompanyPostCode\": \"\",\r\n    \"CompanyCountry\": \"PT\",\r\n    \"UserPhone\": \"133886751\"\r\n}";

                                 var requestOptions = {
                                 method: 'POST',
                                 headers: myHeaders,
                                 body: raw,
                                 redirect: 'follow'
                                 };

                                 fetch("https://bo.magnifinance.com/api/v1.1/partner", requestOptions)
                                 .then(response => response.text())
                                 .then(result => console.log(result))
                                 .catch(error => console.log('error', error));

NodeJs (axios)


                                 var axios = require('axios');
                                 var data = '    {
                                 "CompanyTaxId": "",
                                 "UserName": "",
                                 "UserEmail": "", 
                                 "CompanyLegalName": "",
                                 "CompanyAddress": "",
                                 "CompanyCity": "",
                                 "CompanyPostCode": "",
                                 "CompanyCountry": "",
                                 "UserPhone": ""
                                 }';

                                 var config = {
                                 method: 'post',
                                 maxBodyLength: Infinity,
                                 url: 'https://bo.magnifinance.com/api/v1.1/partner',
                                 headers: {
                                 'Email': 'XXX@example.com',
                                 'Token': 'XXX',
                                 'Content-Type': 'application/json'
                                 },
                                 data : data
                                 };

                                 axios(config)
                                 .then(function (response) {
                                 console.log(JSON.stringify(response.data));
                                 })
                                 .catch(function (error) {
                                 console.log(error);
                                 });

Important informations

When adding a partner, there are two possible scenarios:
- Adding a company as a partner that has no registration in our platform. If the company is not registered on our platform, when submitting an AddPartner request our process will automatically register and associate this company with your IPPN account.
- Adding a company already registered as MagniFinance client in our platform. If a company is registered on the MagniFinance platform they will receive an email and only after their approval, the partnership will be completed, and the tokens become available. You can consult the request status whenever you want in the Interface Web Config -> IPPN -> PARTNERSHIP MANAGEMENT
- - The first state of this request is: access requested
  - After approval by the company, the status will change to: access granted.
  - When the access is granted, you can query the partner's token to be able to create documents on behalf of them. To get the tokens, you can use the GetPartnerAccessTokens endpoint.