Communicate Partner Series (IPPN)

Communicate document series to partners through the IPPN (Integrated Platform for Public Notification) system.

Operation

IPPNCommunicatePartnerSeries

Overview

The IPPN (Integrated Platform for Public Notification) allows businesses to communicate document series information to their business partners. This is particularly useful for:

• Sharing invoice series information with customers
• Notifying partners of new document series
• Maintaining compliance with Portuguese e-invoicing requirements

Request

<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope
  xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
  xmlns:mag="http://magnifinance.com/api/v2.1"
  xmlns:auth="http://magnifinance.com/auth">
  <soapenv:Header>
    <auth:Credentials>
      <auth:ClientId>your_client_id</auth:ClientId>
      <auth:ClientSecret>your_client_secret</auth:ClientSecret>
    </auth:Credentials>
  </soapenv:Header>
  <soapenv:Body>
    <mag:IPPNCommunicatePartnerSeries>
      <mag:Request>
        <mag:PartnerTaxId>123456789</mag:PartnerTaxId>
        <mag:Series>
          <mag:SeriesCode>FT</mag:SeriesCode>
          <mag:SeriesYear>2024</mag:SeriesYear>
          <mag:StartNumber>1</mag:StartNumber>
          <mag:EndNumber>9999</mag:EndNumber>
        </mag:Series>
        <mag:ValidFrom>2024-01-01</mag:ValidFrom>
        <mag:ValidUntil>2024-12-31</mag:ValidUntil>
        <mag:NotifyPartner>true</mag:NotifyPartner>
      </mag:Request>
    </mag:IPPNCommunicatePartnerSeries>
  </soapenv:Body>
</soapenv:Envelope>

Parameters

Parameter	Type	Required	Description
PartnerTaxId	string	Yes	Partner's tax identification number (NIF)
Series.SeriesCode	string	Yes	Document series code (e.g., FT, FS, FR)
Series.SeriesYear	integer	Yes	Year of the document series
Series.StartNumber	integer	Yes	Starting number of the series
Series.EndNumber	integer	Yes	Ending number of the series
ValidFrom	date	Yes	Start date of series validity
ValidUntil	date	No	End date of series validity
NotifyPartner	boolean	No	Send notification to partner (default: true)

Response

<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
  <soapenv:Body>
    <mag:IPPNCommunicatePartnerSeriesResponse xmlns:mag="http://magnifinance.com/api/v2.1">
      <mag:Result>
        <mag:Success>true</mag:Success>
        <mag:CommunicationId>comm_789012</mag:CommunicationId>
        <mag:Status>Communicated</mag:Status>
        <mag:CommunicatedAt>2024-01-15T10:30:00Z</mag:CommunicatedAt>
        <mag:PartnerNotified>true</mag:PartnerNotified>
        <mag:IPPNReference>IPPN-2024-001234</mag:IPPNReference>
      </mag:Result>
    </mag:IPPNCommunicatePartnerSeriesResponse>
  </soapenv:Body>
</soapenv:Envelope>

Response Fields

Field	Type	Description
CommunicationId	string	Unique identifier for this communication
Status	string	Communication status
CommunicatedAt	datetime	Timestamp of communication
PartnerNotified	boolean	Whether the partner was notified
IPPNReference	string	IPPN system reference number

Error Response

<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
  <soapenv:Body>
    <soapenv:Fault>
      <faultcode>soapenv:Client</faultcode>
      <faultstring>Invalid partner tax ID</faultstring>
      <detail>
        <mag:Error xmlns:mag="http://magnifinance.com/api/v2.1">
          <mag:Code>INVALID_PARTNER_NIF</mag:Code>
          <mag:Message>The partner tax ID is not valid or not registered</mag:Message>
        </mag:Error>
      </detail>
    </soapenv:Fault>
  </soapenv:Body>
</soapenv:Envelope>

Error Codes

Code	Description
INVALID_PARTNER_NIF	Partner tax ID is invalid or not registered
SERIES_ALREADY_COMMUNICATED	This series has already been communicated to the partner
INVALID_DATE_RANGE	ValidFrom is after ValidUntil
IPPN_SERVICE_UNAVAILABLE	IPPN service is temporarily unavailable
SERIES_OVERLAP	Series range overlaps with existing communicated series

Example (C#)

using System.ServiceModel;

var binding = new BasicHttpsBinding();
var endpoint = new EndpointAddress("https://api.magnifinance.com/soap/v2.1/TaxCommunication");
var client = new TaxCommunicationClient(binding, endpoint);

var request = new IPPNCommunicatePartnerSeriesRequest
{
    PartnerTaxId = "123456789",
    Series = new DocumentSeries
    {
        SeriesCode = "FT",
        SeriesYear = 2024,
        StartNumber = 1,
        EndNumber = 9999
    },
    ValidFrom = new DateTime(2024, 1, 1),
    ValidUntil = new DateTime(2024, 12, 31),
    NotifyPartner = true
};

var result = await client.IPPNCommunicatePartnerSeriesAsync(credentials, request);

if (result.Success)
{
    Console.WriteLine($"Communication ID: {result.CommunicationId}");
    Console.WriteLine($"IPPN Reference: {result.IPPNReference}");
    Console.WriteLine($"Partner Notified: {result.PartnerNotified}");
}

Notes

• The partner must be registered in the IPPN system for notification to work
• Series communication is required for certain types of business relationships in Portugal
• The IPPNReference can be used for tracking and audit purposes
• Communications are logged and can be retrieved later for compliance reporting