Guided Tour: Partner Services

This is a step-by-step guide to using Partner Services for setting up new customers, changing their configuration and deactivating them, typically from a partner's multi-tenant application.

📘

Partner Services are for partners and ERP vendors who set up and manage their customers' subscriptions (participants) through the API.

Partner Services are typically built into the partner's own multi-tenant application, so that its users can start and manage their own subscription. All routes are under /api/v1/partners. In Sandbox the base URL is https://mapi-sandbox.unimaze.com, with Swagger UI at /swagger/.

Use the Accept-Language HTTP header if you want error messages to be shown to your users in a supported language.

Authentication

Authenticate every request with a Bearer token:

Authorization: Bearer {token}

The token is issued by Unimaze when you are onboarded as a partner. Treat it as a credential: anyone holding it can manage your customers. Basic authentication is retained for existing integrations only. New integrations should use Bearer.

Key concepts

  • Manager. Your partner credential. It can only act on the companies it manages.
  • Party. A managed company, identified by its ISO identifier, {identifierType}:{identifier}, for example 0196:xxxxxxyyyy.
  • Billing package. What the customer is charged for. Set up for your login together with Unimaze.
  • Configuration template. What the company can do: delivery protocols, receiving capabilities and customer settings. Often a partner has a single template, and several when customers have different requirements, for example some receive billing documents and others orders. Set up for your login together with Unimaze.
  • Contacts. Who is notified for the company, each with a role (see Contact roles).

Billing packages and configuration templates differ from partner to partner. The list calls below return the ones your login can use.

Setting up a new subscription

  1. Fetch the billing packages you can assign:
    • GET /partners/billing-packages
      Each package has a keyName, a name and a description. Note the keyName of the one to use.
  2. Fetch the configuration templates you can assign:
    • GET /partners/configuration-templates
      Each template has a keyName and a description of what it enables. Note the keyName of the one to use.
  3. Create the subscription:
    • POST /partners/parties
      Provide the following in the request body:
FieldRequiredDescription
isoIdentifierYesThe customer's ISO identifier, {identifierType}:{identifier}.
nameYesThe customer's legal name, up to 250 characters.
billingPackageKeyNameYesA keyName from step 1.
configurationTemplateKeyNameYesA keyName from step 2.
contactsYesAt least one contact for notifications, covering each role the template's receiving capabilities need. Name up to 30 characters, email up to 50.
userNameYesThe username of the participant's login, 5 to 25 characters.
encodedPasswordYesThe password of the login, Base64 encoded. Send it only over a secure link.
managerNoNormally your own support name, for example Partner Inc. (Support). Up to 30 characters.
managerEmailNoNormally your own support email address. Up to 50 characters.
{
  "isoIdentifier": "0196:xxxxxxyyyy",
  "name": "Example Corp",
  "manager": "Partner Inc. (Support)",
  "managerEmail": "[email protected]",
  "billingPackageKeyName": "{keyName from step 1}",
  "configurationTemplateKeyName": "{keyName from step 2}",
  "contacts": [
    {
      "roleKey": "CustomerAccounting",
      "name": "Example AP Team",
      "email": "[email protected]"
    }
  ],
  "userName": "examplecorp",
  "encodedPassword": "{the password, Base64 encoded}"
}
  1. Read the response:
    • 201 Created: the subscription is created.
    • 202 Accepted: the customer may already exist and be managed by a different partner. See Customer already managed by another partner.
    • 422: an error, with a localized message. This is also the answer when the participant already exists under another partner, see below. When the template receives invoices and no CustomerAccounting contact is given, the message is "Customer accounting contact must be specified".
  2. Use the login you created (userName and the password) to send and receive documents as the participant.
📘

Creating a subscription does not register the participant on any network. A participant that must receive documents has to be registered for receiving separately.

Customer already managed by another partner

If the participant already exists and is managed by a different partner, the call is either rejected with 422 and the message "This party already exists managed by ...", or answered with 202 Accepted.

On 202 Accepted, Unimaze emails the customer so that they can resolve the issue. Check the progress with:

  • GET /partners/parties/{isoIdentifier}

The status MigrationPending means the ownership conflict is still pending. The statuses Active, ActiveSending and NotActive mean it has been resolved.

Contact roles

roleKeyUsed for
CustomerAccountingReceiving invoices. Required for templates that do so.
SupplierSellerReceiving orders.
SupplierAccountingCurrently unused.
BuyerCustomerCurrently unused.

Checking and changing a subscription

  1. Check the status of a participant:
    • GET /partners/parties/{isoIdentifier}
      This returns identifier, name and status:
StatusMeaning
ActiveSubscription is active and fully configured
ActiveSendingActive and able to send messages
MigrationPendingOwnership conflict pending resolution
NotActiveAccount exists but is inactive
  1. List the participants you manage, page by page:
    • GET /partners/parties?Offset={n}&Limit={n}
      The participants are returned in value, each with isoIdentifier and name.
  2. Rename a participant:
    • PUT /partners/parties/{isoIdentifier}
      Send { "name": "New legal name" } as the body.
  3. Change the billing package or the configuration template:
    • PUT /partners/parties/{isoIdentifier}/billing-packages/{keyName}
      The billing package is replaced immediately.
    • PUT /partners/parties/{isoIdentifier}/configuration-templates/{keyName}
      This adds the transactions of the new template. It does not remove those of earlier templates. For a clean slate, deactivate the participant and create it again.
  4. To see what a participant can receive, use GET /parties/{id}/transactions, see Get party receiving transactions. Note that this route is not under /partners.

Deactivating a subscription

Deactivate a participant using:

  • DELETE /partners/parties/{isoIdentifier}
    This returns 204 No Content. The account is deactivated, its identifiers are removed and the deregistration of its registered endpoints is queued. It is not instantly reversible, so confirm with the customer first.

Response codes

CodeMeaningWhere
200 OKThe request succeeded.Get and update calls
201 CreatedThe subscription was created.POST /partners/parties
202 AcceptedAccepted but pending, see the ownership conflict above.POST /partners/parties
204 No ContentDone, no body returned.DELETE /partners/parties/{isoIdentifier}
403 ForbiddenYou are not authorized to manage this participant.Calls on a participant
404 Not FoundThe participant or resource was not found.Calls on a participant
409 ConflictThe resource already exists.Create calls
422A validation error, with a localized message.POST /partners/parties, update calls

Did this page help you?