Skip to main content

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.

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.

A partner can be a company or an individual (a sole trader or a self-employed worker). Currently, document generation is only available for Portuguese tax entities, so the partner's country must be Portugal (PT).

AddPartner only records the request; its response has no partner data. 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. This runs a few times per business day, not instantly. 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 (automatically for new accounts, after the partner's approval for existing ones). The partner can also reject it.

The state isn't available through the API: watch it in the web interface. Through the API, Get Partner Access Tokens returns NoPartnerFoundWithTaxId until access is granted. The error is the same whether the request is still pending, was rejected or revoked, or was never made.

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.

There's no API call to revoke a token. To stop a token from working, revoke it in the web interface under Config → IPPN → Partnership Management. The partner can also end the partnership from its own MagniFinance account, which revokes all of your tokens for that partner.

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.

You don't create these series yourself: MagniFinance creates them in the partner's account when the partnership is granted. They're 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. You and the partner can see them in MagniFinance under Config → Séries.

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):

StepDone byCall / place
IPPN enabled, API user + main token receivedMagniFinance—
Partner registeredyouAddPartner
Partnership acceptedpartner (e-mail)Web interface (Partnership Management)
Partner tokens fetched and storedyouGetPartnerAccessTokens
Tax communication activated for the partneryou, partner tokenActivationSet
Partner series communicated to ATyou, partner tokenIPPNCommunicatePartnerSeries
Documents issuedyou, partner tokenFinance API Create Document
Documents fetchedyou, partner tokenFinance API Get Document

Errors use the shared error codes; NoPartnerFoundWithTaxId is the one you will meet when you ask for a partner's tokens before the partnership is granted.