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.
- To exchange documents as one of these participants, use its own login with Guided Tour: Messaging Services or Guided Tour: Transaction Services.
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 example0196: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
- Fetch the billing packages you can assign:
GET /partners/billing-packages
Each package has akeyName, anameand adescription. Note thekeyNameof the one to use.
- Fetch the configuration templates you can assign:
GET /partners/configuration-templates
Each template has akeyNameand adescriptionof what it enables. Note thekeyNameof the one to use.
- Create the subscription:
POST /partners/parties
Provide the following in the request body:
| Field | Required | Description |
|---|---|---|
isoIdentifier | Yes | The customer's ISO identifier, {identifierType}:{identifier}. |
name | Yes | The customer's legal name, up to 250 characters. |
billingPackageKeyName | Yes | A keyName from step 1. |
configurationTemplateKeyName | Yes | A keyName from step 2. |
contacts | Yes | At least one contact for notifications, covering each role the template's receiving capabilities need. Name up to 30 characters, email up to 50. |
userName | Yes | The username of the participant's login, 5 to 25 characters. |
encodedPassword | Yes | The password of the login, Base64 encoded. Send it only over a secure link. |
manager | No | Normally your own support name, for example Partner Inc. (Support). Up to 30 characters. |
managerEmail | No | Normally 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}"
}- 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 noCustomerAccountingcontact is given, the message is "Customer accounting contact must be specified".
- Use the login you created (
userNameand 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
roleKey | Used for |
|---|---|
CustomerAccounting | Receiving invoices. Required for templates that do so. |
SupplierSeller | Receiving orders. |
SupplierAccounting | Currently unused. |
BuyerCustomer | Currently unused. |
Checking and changing a subscription
- Check the status of a participant:
GET /partners/parties/{isoIdentifier}
This returnsidentifier,nameandstatus:
| Status | Meaning |
|---|---|
Active | Subscription is active and fully configured |
ActiveSending | Active and able to send messages |
MigrationPending | Ownership conflict pending resolution |
NotActive | Account exists but is inactive |
- List the participants you manage, page by page:
GET /partners/parties?Offset={n}&Limit={n}
The participants are returned invalue, each withisoIdentifierandname.
- Rename a participant:
PUT /partners/parties/{isoIdentifier}
Send{ "name": "New legal name" }as the body.
- 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.
- 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 returns204 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
| Code | Meaning | Where |
|---|---|---|
200 OK | The request succeeded. | Get and update calls |
201 Created | The subscription was created. | POST /partners/parties |
202 Accepted | Accepted but pending, see the ownership conflict above. | POST /partners/parties |
204 No Content | Done, no body returned. | DELETE /partners/parties/{isoIdentifier} |
403 Forbidden | You are not authorized to manage this participant. | Calls on a participant |
404 Not Found | The participant or resource was not found. | Calls on a participant |
409 Conflict | The resource already exists. | Create calls |
422 | A validation error, with a localized message. | POST /partners/parties, update calls |
Updated 19 days ago
