Getting Started with IPPN
This page walks through what has to happen before your platform can issue documents on a partner's behalf, in the order it happens. Each step names the API call (or the manual action) that performs it.
The model in one paragraph
Your company holds an IPPN account with an API user and a main token. Each partner is a company in your network — registered on MagniFinance by you, under its own tax identity. Once a partnership is accepted, the partner has a partner token. Documents are created with the partner's token and the IPPN user's e-mail, so every invoice is issued under the partner's fiscal identity, communicated to the Tax Authority (AT) under the partner's series, and visible to the partner in their own MagniFinance account.
Step by step
1. IPPN is enabled on your account
IPPN is not on by default. Contact MagniFinance to enable it on your subscription; you receive the API user e-mail and the main token used in every request. A 30-day trial period is available to run the whole flow before going to production.
2. Register the partner
Call Add Partner (or its SOAP counterpart) with the partner's tax ID and legal name. Validate the tax ID first with TaxId Validation if it comes from user input.
Two situations follow, and they are different:
- The company is not on MagniFinance yet. MagniFinance creates the account, associates it with your IPPN network and e-mails the partner to set a password. The partner uses that account to consult the documents issued in its name and to export SAF-T files.
- The company already uses MagniFinance. The partner receives an e-mail asking for permission. Nothing is issued until they accept.
Partners can also be added and managed by hand in the web interface at bo.magnifinance.com/Partnership/Invoicing (Config → IPPN → Partnership Management).
3. Wait for the partnership to be granted
The request starts as access requested and becomes access granted when the partner accepts (immediately for new accounts, after the partner's approval for existing ones). Query the state with Client Get, or watch it in the web interface.
4. Fetch the partner's tokens
Once access is granted, Get Partner Access Tokens returns the partner's token(s). Store them: they are what you send instead of your own token from now on.
5. Activate tax communication for the partner
Before any document is issued, the partner's account must be able to talk to the Portuguese Tax Authority (AT). Activation Set — called with the partner's token and the partner's AT credentials — validates them live against the Portal das Finanças and switches the service on (IsActive: true). Tax communication is off by default and must be enabled for your IPPN account by MagniFinance first.
6. Communicate the partner's series to the Tax Authority
Portuguese law requires document series to be communicated to AT before use. Communicate Partner Series, again with the partner's token, does this for each series the partner will issue under.
7. Issue documents on the partner's behalf
Use the Finance API exactly as for your own documents, with the partner's token:
- Create Document — invoices/receipts (
T) and credit notes (C) are enabled by default for IPPN; other document types are disabled to protect the partner's tax compliance and can be enabled on request.
Every document issued this way is visible to the partner in their MagniFinance account.
8. Fetch documents
Get Document returns the document and its PDF — with the partner's token, the partner's documents.
Checklist
The sequence, as MagniFinance runs it for every new IPPN partner (Convert Leads IPPN › Kick-off):
| Step | Done by | Call / place |
|---|---|---|
| IPPN enabled, API user + main token received | MagniFinance | — |
| Partner registered | you | AddPartner |
| Partnership accepted | partner (e-mail) | ClientGet to check |
| Partner tokens fetched and stored | you | GetPartnerAccessTokens |
| Tax communication activated for the partner | you, partner token | ActivationSet |
| Partner series communicated to AT | you, partner token | IPPNCommunicatePartnerSeries |
| Documents issued | you, partner token | Finance API Create Document |
| Documents fetched | you, partner token | Finance API Get Document |
Errors use the shared error codes; PartnershipNotFound (38) is the one you will meet when a token is used before the partnership is granted.