Invoice Sales Integration

Our invoice sales process is robust and dynamic solution that will help external sales providers to easily integrate with our Unimicro platform.

How Invoice Sales works

We use Webhooks (event plans) and Approvals to handle invoice sales. Webhooks are asynchronous events trigged when some action done by user. We use webhooks to notify the external sales provider about the request and wait for external sales provider to send offers to our external-offer endpoint. 'Ones' system receives offer, will create approvals which can be used by end user to provide feedback by accepting or rejecting the offer. End user can only accept one offer if there are multiple offers from different sales provider. When user accept an offer other pending offers will be automatically rejected by the system.

If user Accept or Reject an offer it will trigger an event in webhook system to notify to external sales provider about the feedback.

When external sales provider receives an accepted offer notification, they should send the Bank Account Number, Invoice Text, and PaymentID for the invoice to the purchased offer endpoint in Unimicro platform

How to Integrate with Unimicro

External vendors who like to onboard to do invoice sales need to create a product in our developer portal. They need to create a server client to do communication with our endpoints.

Read How to create product in Dev Portal article for more details

User should select Invoice Sale as the product category for the Application you create in dev portal and need to enter values for following properties

As mentioned above table, external sales providers should open 5 endpoints as event listeners for events that triggered when user initiated the invoice sale. When an event occurs Unimicro platform will send a notification to the event listener endpoints so external sales provider can act depend on the event.

There are 5 main events.

1. Request Offer Event
2. Accept Offer Event
3. Reject Offer Event
4. Credit Note Raised Event
5. Product Activation Event

External Sales provider should actively listen to these events and response to those events by calling our Unimicro platform APIs for Invoice Sales

All the event listeners will use a single generic object type with entity property. This entity property will include the object that associated with each event. Object that comes in the entity property will differ depend on the event. You can read more below.

Following properties will be included in the generic object that will be sent by the event listener endpoints

Example :

{
  "EventType": "Update",
  "EntityName": "PurchaseEvent",
  "Entity": 
    {
      "PurchaseEventType": 1020,
      "ProductId": 49,
      "CompanyName": "Testserver selskap",
      "OrganizationNumber": "959415900",
      "Email": "",
      "Platform": "unimicro",
      "ApiBaseUrl": "https://test-api.unimicro.no/",
      "ID": 2931
    },
  "EntityID": 2931,
  "MessageID": "170987-1",
  "SessionID": "bb8f7d6c-c900-4d01-aab0-ed786fcafe9f",
  "TimeStamp": "2021-08-27T07:00:12.51414Z",
  "CompanyKey": "eda508bc-cab4-4697-aeb8-8b5688389fe6",
  "Reason": "/api/elsa/purchases"
}

API needed to communicate with Unimicro

Following 4 APIs can be used by external providers to do Invoice sales though Unimicro

1. Send Offer API

2. Offer Purchased API

3. Credit Note Success API

4. Product Status Update Endpoint

Event listener endpoint Specification

These event listener endpoints should follow bellow rules and specification.

1. All event listener endpoints should be HTTP POST

2. All endpoints should be able call without any Authorization or Authentication.

3. Request Offer event listener endpoint should accept CustomerInvoice object in HTTP request body.

4. AcceptOffer, RejectOffer and CreditNoteRaised event listener endpoints should accept ExternalOffer object in HTTP request body

5. Product Activation event listener endpoint should accept following model in HTTP request body

How user Activate the product

User can activate the product through the marketplace. When a user activated an Invoice Sales product external sales provider will be notified about the activation and product activation status will be set to pending until external sales provider approved the customer. When product is in pending status external sales provider able to use our Unimicro API to get company details and accounting data to validate and verify the customer before onboarding. After external sales provider completed the verification and validation process, they should inform us the feedback through Product Status Update Endpoint. Using this endpoint external vendors can set the product purchase status to Active, Reject or Pending. Only when purchase status set to Active customers can start to sell invoices.

Product Status Update Endpoint

External vendors can use following endpoint to update the status of a purchase

• Method : PUT
• Body : null
• {productId} path parameter needs to replace with correct product Id for the external vendor. This will be available in MyApps section in Dev Portal

✏ : Product Id can be different in production and test environments. Our product admin will be contact you with correct production values one's product is moved to production

Get Company Details

CompnaySettings entity api can provide all details about the company. External sales provider will get access to the company when user activated the product in marketplace.

• Entity : CompanySettings
• Endpoint : api/biz/companysettings
• More Details : Company Settings Swagger

Get Company Accounting Data

Following entity API's can be used to get different accounting related data for the company.

1. Account Receivables

2. Account Payable

3. Customer Invoice Reminders

4. General Ledger

Account Receivables

• Entity : CustomerInvoice
• Endpoint : api/biz/invoices
• More Details : Customer Invoice Swagger

Account Payable

• Entity : SupplierInvoice
• Endpoint : api/biz/supplierinvoices
• More Details : Supplier Invoice Swagger

Customer Invoice Reminders

• Entity : CustomerInvoiceReminder
• Endpoint : api/biz/invoicereminders
• More Details : Customer Invoice Reminder Swagger

General Ledger

• Entity : JournalEntry
• Endpoint : api/biz/journalentries
• More Details : Journal Entry Swagger
• Entity : JournalEntryLine
• Endpoint : api/biz/journalentrylines
• More Details : Journal Entry Line Swagger
• Entity : Account
• Endpoint : api/biz/accounts
• More Details : Account Swagger

Start to Sell Invoice

For a successful invoice sale there are 3 steps to be followed by user and external sales provider

• Request for Offer
  • User will request for an Offer.
  • External Sales Provider will receive an offer request.
  • External Sales Provider will send an Offer.
• Accept/Reject Offer
  • User Accept or Reject the Offer
  • External Sales Provider receive the feedback.
• Complete the Offer (Only for Accepted Scenarios)
  • External Sales Provider send the Bank Account Number, Invoice Text, and Payment ID (KID)
  • Notify user and update the Invoice to Sold status.

Request Offer

This is the initial step for the invoice sales. User will request for an invoice sale for a draft invoice. It will update the invoice status to WaitingForOffer. This will trigger an event in webhook system which has the responsibility of notifying the external sales provider about the request. If user has multiple invoice sales providers activated, then all providers will get the request simultaneously.

Webhook system will send a HTTP POST request to the request offer event listener endpoint to notify about the request. Request will contain the invoice object that offer has been requested. By looking at the invoice and other factors external sales providers can decide to send a Valid Offer or Rejected offer. It is recommended to always send a valid or rejected offer back to the customer. External sales providers can use Comment property to provide reject reason when sending a rejecting offer. Then external sales providers can use Send Offer API to send a valid or rejected offer to customer.

Accept Offer or Reject Offer

User has option to accept or reject an offer depend on their preference. If use decide to accept the offer, then invoice will be updated to OfferAccepted status. This will reject all other offers and system will reject all incoming offers after accepting an offer. If user choose to reject the offer system will not update the invoice.

Any of this action will trigger an event in webhook system to notify the external provider about the feedback using the endpoints added to the product properties by provider.

Complete the Offer

When user accepted an offer, external sales provider will receive the accepted exteralOffer object to the accepted offer event listener endpoint. Then external sales provider should update the OfferStatus, AccountNumber, FreeText and PaymentID properties of the offer and re-send it to Offer Purchased API endpoint. This will complete the invoice sales process by creating all the required journal entries related to sales fee and update the status of the invoice to Sold.

Credit Note for Sold Invoice

When user raised a credit note for a sold invoice system will undo the fee that been added to the invoice. Accepted ExternlOffer status will be updated to CreditNoteRaised. This will trigger the event that will notify the external vendor about the change using the credit note raised event listener endpoint with the credited externalOffer object.

External sales provider should update the OfferStatus and IsPaymentReleased properties of the offer and re-send it to Credit Note Success API. Will send different notification messages to end user if IsPaymentReleased flag is true.

Invoice Sales APIs

Follwoing APIs can be used by external sales providers to send and update the external offers.

1. Send Offer API

This endpoint used to create new offers. Following are the properties need to set by vendors to create offers. To construct this object external vendors can use the invoice object they receive to their request offer event listener endpoint.

Following properties will be validated

• Method : POST
• Endpoint : api/biz/external-offers
• Body : ExternalOffer object

Response :

• 200 - Success
• 400 - Bad Request

2. Offer Purchased API

External vendors should resend the ExteralOffer object they receive to the Accept Offer Event listener endpoint back to this endpoint with following properties updated. Only accepted offer able to update these values.

Following properties will be validated

• Method: PUT
• Endpoint : api/biz/external-offers?action=purchase-offer
• Body : ExternalOffer object

Response :

• 200 - Success
• 400 - Bad Request

3. Credit Note Success API

When external vendors receive a notification to their credit note event listener with a external offer object which has StautsCode 2060 (CreditNoteRaised) they have to resend the same object back to this API with following field updated.

• Method :PUT
• Endpoint :api/biz/external-offers?action=notify-credit-note-success
• Body : ExternalOffer object

Response :

• 200 - Success
• 400 - Bad Request

IsPaymentReleased property will be used to show two different messages to user. If payment is released it should be set to true otherwise it should be false

When payment is released message would be

Kreditnota er mottatt. Det opprinnelige fakturabeløpet ble utbetalt før mottak av kreditnota, så vi vil sende en faktura for tilbakebetaling av utbetalt beløp.

When payment is not released message would be

Kreditnota er mottatt, og utbetaling av fakturabeløp er stoppet. Tilgjengelig saldo er oppdatert.

Entity Model

External Offer Entity

Offer Status for External Offer

This values need to set to OfferStatus property by external vendor when sending or re-sending the offer

Status Code for External Offer

Unimicro API will set these values to the offer depend on different scenarios. External vendors no need to set StatusCode for exteralOffer when sending offers

Purchase Event Type