Purchase Orders - API Getting Started – Semine

The main audience for this article is API integrators getting started with Semine Purchase Order. It is still useful for anyone who wants to get a short introduction of Semine PO data flow and PO User Interface.

Introduction

Semine will match invoices with purchase orders, line by line. All potential line matches above a certain probability can be automated leaving only the final verification to the controller. Additional, unplanned cost lines on the invoice can be captured and accounted automatically with the help of keywords.

Important: If your ERP system uses Goods Receipt Notes, please visit Semine Settings -->Purchase Orders and set "Enable Goods Received" to checked/on.

Important: At this time, the PO must be synced to Semine before the invoice in order to perform an automatic match.
It is still possible to insert the PO after the invoice but the match will then have to be performed manually.

Process Flow

The purchase order is updated or added to Semine from ERP. Any Goods Received Notes can be updated on arrival or return of goods as well. Semine will auto match or suggest matches of inbound purchase order invoices with the correct purchase order on an per-line level. After final approval and posting, Semine AI is trained to improve future matching automation.

Add Master Data

See: Semine Integration API - Getting started

Capturing Additional Cost with Categories

Automation: Additional cost lines, such as "freight" or similar may be automatically captured and tagged by keyword categories. It works by searching in the invoice line description for the category keywords in order to set correct category. For example, the category "freight" may have multiple search keywords such as "frakt", "transport". If any of those keywords is found in the invoice line description (and the line is not already automatically matched to a PO line), the line will receive that category.

Capturing Additional Cost with Categories

Requirement: You will have to use a category or a supplierItemNumberon each PO line. See: Setting up categories below

Automation: Additional cost lines, such as "freight: 200 kr" or similar will be automatically captured and tagged with a keyword category. Note that final accounting will be manual for these lines.

Setting up categories

Requirement : At least one categoryCodehas to be defined.

Request route : POST https://api.semine.no/api/v1.0/organizations/ID/clients/ID/purchaseOrders/categories

Request body : { "categoryCode": "Shipping", "description": "Shipping Description" }

Setting up cost categories with keywords

This POST request is an UPSERT.POST /api/v1.0/organizations/{organizationId}/clients/{clientId}/purchaseOrders/categories

Category keywords

In addition, Semine can perform automatic coding through matching of category keywords found on the invoice lines. To enable this feature, simply add a list of search keywords for a given category. If the category "Shipping" are given the keywords "Shipping", "Freight", "Transport", then all invoice lines containing this exact word will receive the "Shipping" category.

1. Sync a PO from ERP

POST /api/v1.0/organizations/{organizationId}/clients/{clientId}/purchaseOrders

Add a Purchase Order through the Public Integration API.

This POST is an UPSERT which means you can both INSERT and UPDATE the PO through the same POST request:

Important : Maximum PO request body size is 30MB (30000000 bytes)

Tip : Already existing POs with matching purchaseOrderNumber will be replaced with the posted PO.

Tip : Conversely, a new PO will be created if the posted purchaseOrderNumber does not already exist.

This is a minimal PO request body

"purchaseOrderNumber": "55555" will be used for the PO Invoice <--> PO matching.
"purchaseOrderLineNumber": "1" will be used for the PO Invoice Line <--> PO Line Matching

{
    "currency": "NOK",
    "erpVendorId": "1234",
    "purchaseOrderNumber": "55555",
    "status": "Open",
    "purchaseOrderLines": [
        {
            "status": "Open",
            "SupplierItemNumber":"777777",
            "purchaseOrderLineNumber": "1",
            "quantityOrdered": 5,
            "quantityReceived": 0,
            "quantityRemaining": 5,
            "quantityInvoiced": 0,
            "unitPrice": 10.0,
            "unit": "kg",
            "vatPercentage": 25,
            "netAmount": 50,
            "totalAmount": 62.5
        }
    ]
}

A successful PO post returns http status code 201 Created

2. Add a PO Invoice

Alternative A: Add a Purchase Order Invoice through the integration API by running POST .../invoices

Alternative B: Add a Purchase Order Invoice through email by filling in the Semine-UBL-Invoice.xml template as described.

2.1 Auto Match PO Invoice <--> PO

Automation 1: We will add our purchaseOrderNumber as OrderReference to the regular invoice in order to trigger the automatic matching of PO and Invoice. At the same time the invoice will be converted from a Cost Invoice to a PO Invoice. It is also possible to manually convert an Cost Invoice to an PO Invoice (see below).See: cac-OrderReference/cbc-ID/

    <cac:OrderReference>
        <cbc:ID> 55555 </cbc:ID> 
    </cac:OrderReference>

Automation 2: Add a unique purchaseOrderLineNumber to each Invoice Line in to the regular invoice in order to trigger the automatic PO Line Matching.See: cac-InvoiceLine/cac-OrderLineReference/cbc-LineID/

2.2 Match PO Invoice Line <--> PO Line

PO Line

Has to be unique per line in the PO

    ...
    "purchaseOrderLineNumber": "1",
    ...

Invoice Line

Reference the same PO Line Number

    ...
    <cac:InvoiceLine>
        <cac:OrderLineReference>
            <cbc:ID> 1 </cbc:ID> 
        </cac:OrderLineReference>
    </cac:InvoiceLine>
    ...

2.3. Setting as Purchase Invoice Manually

If the invoice is not automatically recognized as a Purchase Invoice you can simply check the "Purchase Invoice" checkbox instead.

Confirm changing the invoice type.

Then, enter the PO Number directly or select it from the list.

3. Process the PO Invoice

Select a PO Invoice Line and then click Run PO Matching. The Purchase Order field should be filled in automatically and the Purchase Order Line field will display the count of possible matching PO Lines.If this does not happen, manually select the PO from the Purchase Order field and try again.

Note: Review Automatic PO to Invoice Matching in order to make best use of the PO Line fields. By completing more PO Line fields, more PO invoices will match automatically.

In Semine UI, the list of suggestions is displayed in a popover menu at each PO Line Number cell.

3.3 View PO Line Matching Suggestions

See: PO Line Matching Quality for further details.

Click the Purchase Order Line field to see the full list of suggestions.The popover menu presents the list of matching lines found sorted by matching quality.

Note: The top match suggestion will be applied automatically if it is above the minimum match quality limit. If there is a tie between multiple top match suggestions, the user will need to select the PO Line manually.

In the example below, there are 4 matches at 75% quality so the user is prompted to select one of them manually.

3.2 Post PO Invoice

Click "Post PO" in order to set the invoice ready for posting to ERP

Important: At this time, Semine only exports the journal of PO and Invoice Match. Accounting lines are not generated or exported for PO Invoices.

Troubleshooting

Validation Messages

Introduction

Process Flow

Add Master Data

Capturing Additional Cost with Categories

Capturing Additional Cost with Categories

Setting up categories

Setting up cost categories with keywords

Categories

Category keywords

1. Sync a PO from ERP

2. Add a PO Invoice

2.1 Auto Match PO Invoice <--> PO

2.2 Match PO Invoice Line <--> PO Line

2.3. Setting as Purchase Invoice Manually

3. Process the PO Invoice

3.3 View PO Line Matching Suggestions

3.2 Post PO Invoice

Troubleshooting

Validation Messages

Categories

Relaterte artikler