- SAP Managed Tags:
I initially began my career at SAP Concur as an Implementation Project Manager, where my responsibilities included project management and functional design work. As I transitioned into my current role as a Technical Consultant, my focus has shifted towards data integration. In this blog series, I will guide you through the Invoice APIs available via Client Web Services, enabling you to streamline your entire Requisition-to-Payment process. In this first installment, we'll dive into the task of creating and managing vendor records, which serve as the foundation of the entire Invoice module.
Prerequisites
You must be contracted for Invoice Processing and Client Web Services.
This post will not discuss authentication. Please see this post for an introduction to authentication and web service application building within Concur. Please use this link to download a Postman collection for the Invoice APIs. The complete documentation for the Vendor v3.1 API can be found on the SAP Concur Developer Center. Note that this collection assumes you’re using the environment from the authentication blog linked above. You will need an application with the following scope:
- INVVEN
Works with these SAP Concur solutions:
- Invoice – Standard
- Invoice - Professional
Introduction
One of the biggest benefits of using APIs over a flat file is the near real-time data integration ability. Rather than trying to schedule periodic syncing of vendor data, the best-practice approach is to implement an event-driven integration. When a new vendor is created in your system of record, immediately push the vendor to Concur. When a change is made to an existing vendor and the Save button is clicked, immediately push that change to Concur. This not only ensures that Concur is always up-to-date with the latest changes, but also mitigates any performance issues that may occur if you’re trying to sync hundreds or thousands of vendor records at a time.
Create or Update a Vendor
Let’s start by creating a basic vendor record. Within the Vendor Postman collection, expand the folder called ‘Vendors’ and click on the ‘Create / Update Vendor’ request:
The following fields are always required for every vendor:
- AddressCode
- VendorCode
- Country
- Currency
Other fields could be required depending on the configuration of your specific Concur site and the business requirements that were defined. If the VendorName field is not provided, the system will use the VendorCode as the name. Some fields such as PaymentMethodType and PaymentTerms will use system-configured default values if nothing is supplied; therefore, the best practice is to explicitly provide a value where possible. This collection includes every possible available field for completeness; you may omit unused fields from your PUT request.
The schema to update a vendor is exactly the same as it is to create a vendor. The combination of VendorCode and AddressCode is what determines a distinct vendor in Concur. Once these values are set, they cannot be changed. If either of these values needs to be updated, you’ll need to delete the original vendor and create it as a new record with the updated codes.
You may provide multiple vendor records to create or update within the request body. A 200 response code along with the number of records processed is the expected response:
The PUT request to update a vendor is handled as a full-replace; with the exception of the DefaultExpenseTypeName and DefaultEmployeeID fields, any field you don’t explicitly send a value for will get nulled, even if it previously had a value. The Vendor API does not support the PATCH operation.
Retrieve Vendors
Next, we’ll look at how to retrieve a vendor. Switch to the Get Vendor Information request. There are many different parameters that you can use to search / filter for vendors. These are detailed on the Params tab of the request, highlighted in yellow below. For example, we could search by vendorCode to validate that the vendor we sent above was created as expected:
Note that the response will include every available field, even if no value is set for that particular vendor record.
Your Invoice configuration may allow end-users to request a new vendor within the Concur UI. This is useful if they need to enter an invoice for a vendor that doesn’t already exist. However, the vendor will initially be created as an unapproved vendor; before any invoices assigned to that vendor can be fully approved and extracted, that vendor must be approved. The GET vendor endpoint can be used to retrieve these user-created vendors by setting the approved parameter to false:
If this vendor is ultimately approved, you can use the details in this response to add the vendor to your system of record. Normally we use the VendorCode and AddressCode when determining whether to create or update a vendor, but unapproved vendors have random values created for these (as you can see in the above screenshot). Take note of the AddressImportSyncID value instead:
After this vendor has been created in your system of record and gets a true vendor code created, send a PUT request with the details back to Concur. Unlike with a new vendor, this time we’ll need the AddressImportSyncID value populated in the PUT request (this is normally left blank). There will be an additional message in the response noting that we have updated the Unapproved vendor:
Add Vendor Group
Concur Invoice has a concept called Vendor Access Groups, which allows you to limit which vendors a given set of employees has access to. Click on the Add Vendor Group (Employee Access Mapping) Request. There are two parts to adding a vendor group – you must have the vendor code and address code populated in the parameters:
And you add the specific group(s) you want to add within the body of the request:
This API requires the name of the vendor group as it’s configured within Invoice Groups:
Contact your Invoice Administrator to get a list of valid vendor access group names.
Once a group has been added to a vendor, it will be included in the VendorGroupList section of the GET Vendor response:
Note that every vendor will always be assigned to the Global group.
To remove a Vendor Group, click on the Delete Vendor Group request:
This differs slightly in that the group to be deleted is added as a parameter to the request, rather than being sent in the body of the request as when adding a group.
Vendor Banking Info
If you utilize ACH payments via Concur Invoice Pay, then we need to have that vendor’s banking information on file. This can be added using the Add Vendor Banking Request:
If Banking Details have been added to a vendor record, they will be included in the Get Vendor response:
Delete Vendor
If you no longer do business with a given vendor, then that record should be marked as deleted. That will remove it from the list of available vendors that employees can choose from when creating invoices. Select the Delete Vendor request:
The vendor and address codes must be provided in the parameters. Note that any invoices that were assigned to that vendor that were not already fully approved will need to be assigned to a different vendor before they can proceed in the approval workflow.
Conclusion
The Vendor APIs give you more flexibility and control over when vendors are created / updated versus the typical Overnight Job schedule / file delivered to SFTP. Using the information in this post and the accompanying Postman collection, you should be on your way to a more efficient vendor management experience.
Stay tuned for the next post in this series, where we’ll cover how to manage Purchase Requests.
Share and Connect
What do you think? Do you have anything to add? Leave a comment below.
Did you find it useful? Give us a like and share on social media.
Want to know more about SAP Concur? Please follow here.
Want to ask questions about SAP Concur and its offerings? Ask here.
Thank you!
1 Comment
