Supplier Invoice

This article explains operations related to supplier invoice.

You will learn,

• How to create a supplier invoice
  • Attach an document
  • Remove an existing attached document
  • Run OCR scan on an attached document
• How to get supplier invoices
  • Get all supplier invoices
  • Get a specific supplier invoice
• Different statuses a supplier invoice can have
• How to submit a supplier invoice for approval

How to create a supplier invoice

Creating a supplier invoice is simple with Unimicro. Only required information you need to create a supplier invoice is the SupplierID.

Endpoint: POST: /api/biz/supplierinvoices

Payload is a JSON text as follows:

{
  
    "SupplierID": 10, // Required. ID of the supplier registered in Unimicro
    "DefaultDimensions": {
        "_createguid": "58e73fd1-cce3-4b93-80a4-a65e2be75a09" // Optional. Passing a GUID you can create a new Dimension. Refer to Diemensions for more info
    },
    "InvoiceNumber": "1", // Optional. But can be used to uniquely identify an invoice
    { ...EXTRA_INFORMATION_YOU_NEED }
}

If you need to include more information to above payload please refer to Swagger section.

If you don't know how to find SupplierIDs refer to Useful information section below

Useful information

To find SupplierIDs, use this endpoint to get list of available suppliers and you'll find id property

Endpoint: GET: /api/biz/suppliers/?expand=info&filter=StatusCode eq 20001 OR StatusCode eq 30001

Attach an document

All attachments in Unimicro is stored on a service called File Server. There are 2 ways to attach a document to a supplier invoice.

• Upload a new document direclty to a supplier invoice
• Link an existing document uploaded to a supplier invoice

Upload a new document direclty to a supplier invoice

You can use following file server endpoint to upload a new attachment to supplier invoice.

Before uploading you need following information,

INVOICE_ID - id of the supplier invoice you are going to attach to. COMPANY_KEY - id of the company under which your supplier invoice is created. ATTACHMENT - { uri: 'document uri', type: 'mime type', name: 'document name', } CAPTION - (optional) a caption for the document you upload.

Finally you can invoke following endpoint to Upload a new document direclty to a supplier invoice.

Endpoint (fileServer): POST: /api/file

NOTE: This endpoint base url must point to Unimicro file server. Refer to File Server docs if you have any issues. File Server baseUrl: https://test-files.unimicro.no

A supplier invoice in 30101, 30102 or 30108 statuses only can perform this action.

Payload is a FormData as follows:

  const form = new FormData();

  form.append('File', ATTACHMENT);
  form.append('FileName', FILENAME);
  form.append('Caption', CAPTION);
  form.append('Key', COMPANY_KEY);
  form.append('EntityID', INVOICE_ID);
  form.append('EntityType', 'SupplierInvoice');

Link an existing document uploaded to a supplier invoice

If you have any documents uploaded to file server and if you want to link them to a supplier invoice, you need following information.

Before uploading you need following information,

INVOICE_ID - id of the supplier invoice you are going to attach to. FILE_ID - id of the document represented in file server.

If you have invoiceId and the fileId, you can invoke following endpoint to link them together.

Endpoint: POST: /api/biz/files/${FILE_ID}?action=link&entitytype=SupplierInvoice&entityid=${INVOICE_ID}

A supplier invoice in 30101, 30102 or 30108 statuses only can perform this action.

Remove an existing attached document

If you need to remove any documents attached to a supplier invoice you need following information,

INVOICE_ID - id of the supplier invoice you are going to update. FILE_ID - id of the document represented in file server.

Now, you can invoke following endpoint to remove an existing attachment from the supplier invoice.

Endpoint: DELETE: /api/biz/files/SupplierInvoice/${INVOICE_ID}/${FILE_ID}

A supplier invoice in 30101, 30102 or 30108 statuses only can perform this action.

Run OCR scan on an attached document

Unimicro provides a OCR scanning facility on supplier invoice documents. You can use this feature to scan any of the attachments and extract useful information in the document.

To run a OCR scan on the document should be uploaded to file server and you must have the fileId.

Before running an OCR scan you need following information,

FILE_ID - id of the document represented in file server.

Endpoint: GET: /api/biz/files/${FILE_ID}?action=ocranalyse

Once the OCR scan is successful, you'll get a response as the following sample:

{
    "Id": 10001,
    "PageNo": 1,
    "ImageHeight": 1753,
    "ImageWidth": 1240,
    "OcrDataUsed": null,
    "OcrTemplateId": null,
    "Language": null,
    "OcrRawData": "...raw scanning data goes here",
    "UniFile": {
        "Name": "Faktura - 2019-12-05T092314.480.png",
        "Description": null,
        "StorageReference": "547607c8-e209-46e5-96ef-a6f901fc8699",
        "ContentLength": 140993,
        "Extension": ".png",
        "ContentType": "image/png",
        "CreatedAt": "2020-05-20T07:31:07.063",
        "ClientId": 161,
        "Pages": 0,
        "PublicAvailableFile": false,
        "ExternalId": "1000",
        "_publictoken": null,
        "_links": null,
        "encryptionID": null,
        "ProcessedPercentage": 100,
        "FullFileProcessed": false,
        "SplitFilePageList": null,
        "IsMultipageFile": false
    },
    "InterpretedProperties": [
        {
            "Id": 19453,
            "OcrInterpretationId": 4176,
            "OcrPropertyId": 1,
            "ProposedCandidateId": 103662,
            "SelectedCandidateId": null,
            "ActualValue": null,
            "ProposedCandidate": {
                "Id": 103662,
                "InterpretedPropertyId": 19453,
                "HitWordId": 3,
                "HitWordText": "Orgnr",
                "HitWordPlacement": 1,
                "Value": "921551517",
                "Top": 1544,
                "Left": 874,
                "Height": 14,
                "Width": 98,
                "ProbabilityFactor": 0.9
            },
            "SelectedCandidate": null,
            "OcrProperty": {
                "Id": 1,
                "Name": "Official number",
                "PropertyType": 1
            },
            "InterpretationCandidates": [
                {
                    "Id": 103662,
                    "InterpretedPropertyId": 19453,
                    "HitWordId": 3,
                    "HitWordText": "Orgnr",
                    "HitWordPlacement": 1,
                    "Value": "921551517",
                    "Top": 1544,
                    "Left": 874,
                    "Height": 14,
                    "Width": 98,
                    "ProbabilityFactor": 0.9
                }
            ]
        },
        {
            "Id": 19454,
            "OcrInterpretationId": 4176,
            "OcrPropertyId": 2,
            "ProposedCandidateId": 103663,
            "SelectedCandidateId": null,
            "ActualValue": null,
            "ProposedCandidate": {
                "Id": 103663,
                "InterpretedPropertyId": 19454,
                "HitWordId": 55,
                "HitWordText": "Bankgiro",
                "HitWordPlacement": 2,
                "Value": "11111111111",
                "Top": 1435,
                "Left": 682,
                "Height": 19,
                "Width": 158,
                "ProbabilityFactor": 0.7
            },
            "SelectedCandidate": null,
            "OcrProperty": {
                "Id": 2,
                "Name": "Bank account number",
                "PropertyType": 3
            },
            "InterpretationCandidates": [
                {
                    "Id": 103663,
                    "InterpretedPropertyId": 19454,
                    "HitWordId": 55,
                    "HitWordText": "Bankgiro",
                    "HitWordPlacement": 2,
                    "Value": "11111111111",
                    "Top": 1435,
                    "Left": 682,
                    "Height": 19,
                    "Width": 158,
                    "ProbabilityFactor": 0.7
                }
            ]
        }
    ]
}

If you take a look at the response, the most important information is under the InterpretedProperties tag. This array includes possible hits found from the OCR scan. OcrProperty.Id in each object within InterpretedProperties array can be used to identify what are the identified properties.

You can also use a simple JS script to extract data as you want. Following is a sample javascript code to extract some data from OCR scanning.

const OcrPropertyType = {
    OfficialNumber: 1,
    IbanNumber: 2,
    BankAccountNumber: 3,
    CustomerIdentificationNumber: 4,
    InvoiceNumber: 5,
    TotalAmount: 6,
    InvoiceDate: 7,
    DueDate: 8,
};

const getProposedValue = (props, propType) => {
    const prop = props.find(x => x.OcrProperty.PropertyType === propType);
    if (prop && prop.ProposedCandidate) {
        return prop.ProposedCandidate.Value;
    }
    return '';
}

const handleOCRData = (result) => {
    if (result && result.InterpretedProperties) {
        const props = result.InterpretedProperties;
        const ocrObj = {};

        ocrObj.Orgno = this.getProposedValue(props, OcrPropertyType.OfficialNumber);
        ocrObj.PaymentID = this.getProposedValue(props, OcrPropertyType.CustomerIdentificationNumber);
        ocrObj.BankAccount = this.getProposedValue(props, OcrPropertyType.BankAccountNumber);
        ocrObj.InvoiceDate = this.getProposedValue(props, OcrPropertyType.InvoiceDate);
        ocrObj.PaymentDueDate = this.getProposedValue(props, OcrPropertyType.DueDate);
        ocrObj.TaxInclusiveAmount = this.getProposedValue(props, OcrPropertyType.TotalAmount);
        ocrObj.InvoiceNumber = this.getProposedValue(props, OcrPropertyType.InvoiceNumber);

        return ocrObj;
    }
    return null;
}

const ocrFormData = handleOCRData(OCRScanResponse.data)

Now you can use ocrFormData values to auto fill any of your UI as you want.

How to get supplier invoices

This section describes how to get a specific invoice details and to get all supplier invoice list.

Get all supplier invoices

You can use any of following endpoints to get invoice list depending on what data you need in yout list.

Get supplier invoice list

Use following endpoint to get all available list of supplier invoices. But using this list you'll not be able to get documents attached to invoice.

Endpoint: GET: /api/biz/supplierinvoices

Get supplier invoice list with the first attachment

If you need to show your supplier invoice list in your UI with an attachment preview this will be very helpful. To get first attached document information along with supplier information you will need to use the Unimicro Statistic API.

Endpoint: GET: /api/statistics?model=supplierinvoice&select=InvoiceNumber as InvoiceNumber,paymentduedate as DueDate,paymentstatus as PaymentStatus,CurrencyCode.Code as CurrencyCode,id as ID,SupplierID as SupplierID,Info.Name as SupplierName,max(file.id) as fileID,file.StorageReference as fileRef,max(file.ContentType) as contentType,StatusCode as Status,TaxInclusiveAmountCurrency as Amount,max(file.name) as fileName&filter=deleted eq 0 and ( fileentitylink.entitytype eq 'supplierinvoice' or isnull(fileentitylink.id,0) eq 0 )&join=supplierinvoice.id eq fileentitylink.entityid and fileentitylink.fileid eq file.id&expand=supplier.info,CurrencyCode&orderby=id`,

Get a specific supplier invoice

To get a specific supplier invoice information you need to know the InvoiceId of that invoice. If you know the ID then you can invoke following endpoints to retrieve information you need.

Get a specific supplier invoice data

Endpoint: GET: /api/biz/supplierinvoices/${InvoiceId}

Get attachment list for a specific supplier invoice

Endpoint: GET: /api/biz/files/SupplierInvoice/${InvoiceId}

Different statuses a supplier invoice can have

In a supplier invoice there are 2 status codes as follows,

• StatusCode
• PaymentStatus

StatusCode

A supplier invoice can have different StatusCodes according to the stage that invoice is in the flow. Following table describes the StatusCode and relevant status description.

PaymentStatus

A supplier invoice can have different PaymentStatus codes according to payments processed. Following table describes the PaymentStatus code and relevant status description.

How to submit a supplier invoice for approval

A supplier inovice should be approved before it is journaled. So to get any approval to proceed ahead a supplier invoice should be sent for an approval.

A supplier invoice in 30101 or 30108 statuses only can perform this action.

You can send your supplier invoice to,

• a specific user
• a list of users
• a specific team
• a list of teams

to get an approval for the invoice.

To submit an invoice for approval you need InvoiceId, Message and UserIDs or TeamIDs. If you don't know how to find UserIDs or TeamIDs refer to Useful information section below

Once you have all above information you can use following endpoint to assign the supplier invoice for approval.

Endpoint: POST: /api/biz/supplierinvoices/${InvoiceId}?action=assign-to

Payload should be as follows:

{
    "Message": "", // String. A comment to your approver
    "UserIDs": [], // String array. List of UserIDs if assign to specific user(s)
    "TeamIDs": [], // String array. List of TeamIDs if assign to specific team(s)
}

Useful information

To find UserIDs, use this endpoint to get list of available users and you'll find id property

Endpoint: GET: /api/biz/users

To find TeamIDs, use this endpoint to get list of available teams and you'll find id property

Endpoint: GET: /api/biz/teams

Locking a supplierinvoice

It is possible to lock a supplierinvoice for modification.

Lock

POST /api/biz/entitylock

{
    "Message": "Integrationpartner is working on it!",
    "EntityType": "SupplierInvoice",
    "EntityID": 202
}

Unlock

PUT /api/biz/entitylock?action=unlock&id=202&entitytype=SupplierInvoice