REST API Guide for InterConnect

First published on: 08/10/2023/6:54 pm

 

 

 

The REST API for InterConnect is accessible via the B1WebAPI web service. This web service provides GET and POST access to query and object data within SAP Business One, adding a layer of security around the data access to ensure your data is protected while still being accessible by authorized applications.

 

The Portals use the REST API to display query content (both custom and out-of-the-box queries) as well as to update objects (such as orders and invoices). In this way, the REST API has been thoroughly tested since the earliest versions of the Portal products.

 

Please note, a single REST API instance can support

  • Up to a max of 600 CRUD actions per hour
  • Up to a max of 3000 queries per hour
  • Direct queries must be used to retrieve data from B1 in place of Object get actions, Object actions should be reserved to add/update/delete.

 

Additional requirements beyond this should be discussed with Vision33 to recommend best practices.

 

REST API Syntax Documentation

The REST API for InterConnect can be accessed via a URL pointing to the B1WebAPI web service. Syntax definitions for the various data types are found below.

 

Multiple Company Profiles

The B1WebAPI web service may be configured to connect to multiple SAP Business One companies. Upon setting up a company, a profile name is set (see Creating or Updating B1WebAPI Profiles for more details). This profile name can be used to specify which company the REST API provides data for. Without a profile name specified, the REST API will connect to the first company profile on the list of B1WebAPI profiles.

 

For example, a query in the “Default” profile may be accessed via the URL /query/salesorder.aspx or /Default/query/salesorder.aspx assuming “Default” is the first profile in the list.

 

Activity - REST API

In general, Activities can be created, updated or retrieved using the keywords below.

 

Keywords

activity/get

The get keyword allows the B1WebAPI web service to retrieve an existing Activity’s object XML.

 

Syntax: [/<optional-profile>]/activity/get/<activity-key>.aspx

 

Example (default profile): /activity/get/12.aspx

 

Example (“myCompany” profile): /myCompany/activity/get/12.aspx

 

Activity/Get XML Response Sample
<Activity>
<ActivityCode>12</ActivityCode>
<CardCode>C23900</CardCode>
<Notes nil="true"/>
<ActivityDate>2016-03-29</ActivityDate>
<ActivityTime>15:14:00</ActivityTime>
<StartDate>2016-03-29</StartDate>
<Closed>tNO</Closed>
<CloseDate nil="true"/>
<Phone>555-0119</Phone>
<Fax nil="true"/>
<Subject>-1</Subject>
<DocType>-1</DocType>
<DocNum nil="true"/>
<DocEntry nil="true"/>
<Priority>pr_Normal</Priority>
<Details>test task</Details>
<Activity>cn_Task</Activity>
<ActivityType>-1</ActivityType>
<Location>-1</Location>
<StartTime>15:14:00</StartTime>
<EndTime>15:29:00</EndTime>
<Duration>15.000000</Duration>
<DurationType>du_Minuts</DurationType>
<SalesEmployee>-1</SalesEmployee>
<ContactPersonCode>3</ContactPersonCode>
<HandledBy nil="true"/>
<Reminder>tNO</Reminder>
<ReminderPeriod>15.000000</ReminderPeriod>
<ReminderType>du_Minuts</ReminderType>
<City nil="true"/>
<PersonalFlag>tNO</PersonalFlag>
<Street nil="true"/>
<ParentObjectId>3</ParentObjectId>
<ParentObjectType>97</ParentObjectType>
<Room nil="true"/>
<InactiveFlag>tNO</InactiveFlag>
<State nil="true"/>
<PreviousActivity nil="true"/>
<Country nil="true"/>
<Status>-2</Status>
<TentativeFlag>tNO</TentativeFlag>
<EndDueDate>2016-03-29</EndDueDate>
<DocTypeEx>-1</DocTypeEx>
<AttachmentEntry nil="true"/>
<RecurrencePattern>rpNone</RecurrencePattern>
<EndType>etNoEndDate</EndType>
<SeriesStartDate>2016-03-29</SeriesStartDate>
<SeriesEndDate nil="true"/>
<MaxOccurrence nil="true"/>
<Interval>1</Interval>
<Sunday>tNO</Sunday>
<Monday>tNO</Monday>
<Tuesday>tNO</Tuesday>
<Wednesday>tNO</Wednesday>
<Thursday>tNO</Thursday>
<Friday>tNO</Friday>
<Saturday>tNO</Saturday>
<RepeatOption>roByDate</RepeatOption>
<BelongedSeriesNum nil="true"/>
<IsRemoved>tNO</IsRemoved>
<AddressName nil="true"/>
<AddressType>bo_ShipTo</AddressType>
<HandledByEmployee>1</HandledByEmployee>
<RecurrenceSequenceSpecifier nil="true"/>
<RecurrenceDayInMonth nil="true"/>
<RecurrenceMonth nil="true"/>
<RecurrenceDayOfWeek nil="true"/>
<SalesOpportunityId>3</SalesOpportunityId>
<SalesOpportunityLine>1</SalesOpportunityLine>
<U_ZEDS_OPPNUM nil="true"/>
<U_ZEDS_OPPLINE nil="true"/>
</Activity>

 

activity/insert

The insert keyword is used to create a new Activity.

 

Syntax: [/<optional-profile>]/activity/insert.aspx

 

Example (default profile): /activity/insert.aspx

 

Example (“myCompany” profile): /myCompany/activity/insert.aspx

 

Activity XML Example

<Activity xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <ActivityCode>12</ActivityCode>
  <CardCode>C44000</CardCode>
  <ActivityDate>2016-03-24T13:08:53.9650306-02:30</ActivityDate>
  <ActivityTime xsi:nil="true" nil="true" />
  <StartDate>2016-03-24T13:08:53.9650306-02:30</StartDate>
  <CloseDate xsi:nil="true" nil="true" />
  <Details>test</Details>
  <Activity>cn_Task</Activity>
  <HandledBy>9</HandledBy>
  <EndDueDate xsi:nil="true" nil="true" />
  <SeriesStartDate xsi:nil="true" nil="true" />
  <SeriesEndDate xsi:nil="true" nil="true" />
  <SalesOpportunityId>118</SalesOpportunityId>
  <SalesOpportunityLine>157</SalesOpportunityLine>
</Activity>

 

activity/update

The update keyword is used to update an existing Activity.

Syntax: [/<optional-profile>]/activity/update/<activity-key>.aspx

 

Example (default profile): /activity/update/12.aspx

 

Example (“myCompany” profile): /myCompany/activity/update/12.aspx

 

Alert Creation

Create and view Alerts for SAP Business One

 

Create an Alert for SAP Business One

Alerts for SAP Business One can be created by posting the following XML format to the B1WebAPI [<profile>]/message/send.aspx.

 

<Message>
  <Priority>pr_Normal</Priority>
  <Subject>Subject</Subject>
  <Text />
  <User />
  <RecipientCollection>
    <Recipient>
      <CellularNumber>123456789</CellularNumber>
      <EmailAddress>manager@zedsuite.com</EmailAddress>
      <FaxNumber>098765543</FaxNumber>
      <NameTo>Jayson Butler</NameTo>
      <SendEmail>tYES</SendEmail>
      <SendFax>tYES</SendFax>
      <SendSMS>tNO</SendSMS>
      <SendInternal>tYES</SendInternal>
      <UserCode>manager</UserCode>
      <UserType>rt_InternalUser</UserType>
    </Recipient>
  </RecipientCollection>
  <MessageDataColumns>
    <MessageDataColumn>
      <ColumnName>B1 Order#</ColumnName>
      <Link>tYES</Link>
      <MessageDataLines>
        <MessageDataLine>
          <Object>17</Object>
          <ObjectKey>355</ObjectKey>
          <Value>335</Value>
        </MessageDataLine>
      </MessageDataLines>
    </MessageDataColumn>
  </MessageDataColumns>
</Message>

 

Alert Schema

Alert Schema for your installed version can be obtained from the following B1WebAPI page: [<profile>]/message/schema.aspx

 

View Alerts Inbox

A user’s inbox may be viewed from the following B1WebAPI page: [<profile>]/message/inbox.aspx

 

This will display the inbox of the user assigned to the specified B1WebAPI profile (or, if unspecified, the default B1WebAPI profile).

 

Sent Items List

A user’s sent items list may be viewed from the following B1WebAPI page: [<profile>]/message/sent.aspx

 

As with viewing alerts and displaying outbox items, this only displays data for the specified B1WebAPI profile’s user.

 

Outbox Items List

A user’s sent items list may be viewed from the following B1WebAPI page: [<profile>]/message/outbox.aspx

 

As with viewing alerts inbox and displaying sent items, this only displays data for the specified B1WebAPI profile’s user.

 

Item Price Lookup - REST API

The Item Price Lookup page is available in the B1WebAPI web service. Go to the Item Prices tab of your B1WebAPI installation, or go to (B1WebAPI-address)/ItemPriceLookup.aspx

 

 

 

Optionally, select a company profile (1). For Single item price lookup, fill in the Card Code (2) and Item Number (3). Optionally fill in the Quantity (4) and/or Date (5) Fields. For Multiple item price lookup, create multi-lookup XML (6) or use the Load Multi-price Sample link as a starting point.

 

Single Item Price Lookup

To look up a single item price, fill in the Card Code and Item Number fields on the Item Price Lookup page (markers 2 and 3 above). Quantity (marker 4 above) and Date (marker 5 above) are optional fields that may be included for a single-item price lookup.

 

Alternatively, the following URL syntax may be used against the B1WebAPI directly:

Syntax: [/<profile-name>]/itempriceservice/<CardCode>/<ItemCode>.aspx[?<optional-parameters>]

 

Example (Default profile): /itempriceservice/C20000/A00001.aspx

 

Example (sample “myProfile” profile, with parameters): /myProfile/itempriceservice/C20000/A00001.aspx?quantity=6

 

Supported Parameters for Item Price Lookup

Parameter Description

Currency

Optional. Currency Code of the desired currency. The lookup will provide the item price in the selected currency, as supported by the SAP Business One DI-API.

 

Sample Usage: /myProfile/itempriceservice/C20000/A00001.aspx?currency=USD

Date

Optional. ISO-formatted date (YYYY-MM-DD) for the price lookup. Can be used to define a date in the case of period pricing.

 

Sample Usage: /myProfile/itempriceservice/C20000/A00001.aspx?date=2016-08-17

Quantity

Optional. Can be used to specify the quantity. For example, pricing on items with volume discounts.

 

Sample Usage: /myProfile/itempriceservice/C20000/A00001.aspx?quantity=6

UoMEntry

Optional. Specifies the DocEntry of a Unit of Measure which should be applied to this price lookup.

 

Sample Usage: /myProfile/itempriceservice/C20000/A00001.aspx?UoMEntry=23

UoMQuantity

Optional. Specifies the Quantity of the selected Unit of Measure. If no UoMEntry is provided, this UoMQuantity is ignored.

 

Sample Usage: /myProfile/itempriceservice/C20000/A00001.aspx?UoMEntry=23&UoMQuantity=6

 

Multiple Item Price Lookup

If multiple price lookups are needed, this may be done by submitting XML using a format similar to the following sample.

  • ItemCode - Required. Defines the item for this lookup record.
  • CardCode - Required. Defines the customer for this lookup record.
  • Quantity - Optional. If included, indicates the quantity for this lookup record. If excluded, the quantity will be “1”.
  • Date - Optional. If included, and not empty, defines the date for the price lookup. If excluded or blank, the date will be today’s date.

 

This can be submitted using the Lookup Multiple Prices block (marker 6 in the screenshot above), or it can be submitted directly to the B1WebAPI: [/<profile-name>]/itempriceservice/batch.aspx

 


<MultiItemPriceLookup xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <QueryList>
    <ItemPriceQuery>
      <ItemCode>A00003</ItemCode>
      <CardCode>C20000</CardCode>
    </ItemPriceQuery>
    <ItemPriceQuery>
      <ItemCode>A00001</ItemCode>
      <CardCode>C20000</CardCode>
      <Quantity>30</Quantity>
      <Date>2015-09-25</Date>
    </ItemPriceQuery>
    <ItemPriceQuery>
      <ItemCode>A00002</ItemCode>
      <CardCode>C20000</CardCode>
      <Quantity xsi:nil="true" />
      <Date xsi:nil="true" />
    </ItemPriceQuery>
    <ItemPriceQuery>
      <ItemCode>A00002</ItemCode>
      <CardCode>C20000</CardCode>
      <Quantity>30</Quantity>
    </ItemPriceQuery>
  </QueryList>
</MultiItemPriceLookup>

 

 

Object - REST API

The object keyword allows the B1WebAPI web service to interface with any DI-API Business One object via XML. Objects can be loaded from SAP Business One and the XML information can be updated and sent back to Business One.

 

Keywords

object

The object XML modes are:

  • edit - Passing this parameter as part of the syntax informs the B1WebAPI to load the DI-API for edit purposes. Read-only DI-API properties are not included when using this flag. Note that you must specify the object key, denoted by the number 1 below.

Syntax: [/<optional-profile>]/object/edit/<object-type>/<object-key>.aspx

 

Example (default profile): /object/edit/oOrders/1.aspx

 

Example (“myCompany” profile): /myCompany/object/edit/oOrders/1.aspx

 

  • display - Passing this parameter as part of the syntax informs the B1WebAPI to load the full DI API XML. Read Only DI API properties are included when using this flag and you will potentially get error messages if you try to update the object using this XML. Note that you must specify the object key, denoted by the number 1 below.

Syntax: [/<optional-profile>]/object/display/<object-type>/<object-key>.aspx

 

Example (default profile): /object/display/oOrders/1.aspx

 

Example (“myCompany” profile): /myCompany/object/display/oOrders/1.aspx

 

Note: **Any supported DI-API object can be accessed with this syntax**. In the above examples, oOrders can be replaced with any of the supported DI-API Object types listed in the [Supported DI-API object types](zic_diapi.html).

 

uow

The uow URL keyword enables the B1WebAPI web service to update or create any DI-API Business One object via XML. The XML that is loaded using the object keyword above can be edited and sent back to Business One using the uow keyword. You can also use the B1WebAPI Test Transaction page to get valid XML samples that can be populated to create new DI-API objects (see How to get valid B1 XML samples using InterConnect).

 

Warning: Deletes are not supported for all object types. Only select objects support deletes through the DI-API. Use at your own risk.

 

The uow XML modes are:

  • update - Syntax: [/<optional-profile>]/uow/update/<object-type>/<object-key>.aspx

Example (default profile): /uow/update/oOrders/1.aspx

 

Example (“myCompany” profile): /myCompany/uow/update/oOrders/1.aspx

 

  • insert - Syntax: [/<optional-profile>]/uow/insert/<object-type>.aspx

Example (default profile): /uow/insert/oOrders.aspx

 

Example (“myCompany” profile): /myCompany/uow/insert/oOrders.aspx

 

 

As with the object keyword, uow provides access to supported DI-API object types listed in Supported DI-API object types.

 

Testing Object Transactions

Object transactions can be tested manually using the B1WebAPI web service. This can aid in troubleshooting data insert or editing errors.

  • Connect to B1WebAPI, typically installed on the SAP Business One server, usually at http://localhost:4033/index.aspx
  • Navigate to Test Transactions, typically http://localhost:4033/Transaction.aspx
  • Select the desired object settings. Make sure the Object Type is set to your desired object, such as “oOrders”.

 

 

 

Select the Object Type (1).

 

  • Enter a key or Core Document Content. The Key can be used to load existing objects in edit or display (read-only) modes. Core Document Content can be used to insert, update, or delete Units of Work (uow).
  • Use the desired transaction button to update an object and retrieve the corresponding REST URL.

 

Shown below are two examples, first showing how to load a specific object for review and the second showing loading a Unit of Work for review.

 

Loading an object

 

 

Enter a transaction type (1) and key (2) to update/view a specific document. Press the Load Object button (3) to view the xml data for the selected key.

 

 

 

After Loading Object, see the result XML (2) and that object's REST URL (1).

 

Loading a Unit of Work

 

 

Enter Core Document Content (1) and use the desired Unit of Work (uow) transaction button (2).

 

 

 

After performing a transaction, see the REST URL for that transaction (1).

 

Query - REST API

Keywords

query

The query keyword is used to interact with query objects inside SAP Business One.

 

The query modes are:

  • run - This is the default mode. This mode will look for the query and execute it against the SAP Business One company database.

Syntax: [/<optional-profile>]/query/<query-name>.aspx.

 

Example (default profile): /query/salesorder.aspx

 

Example (“myCompany” profile): /myCompany/query/salesorder.aspx

 

  • def - returns the SQL syntax of the specified query. Syntax: [/<optional-profile>]/query/<query-name>/def.aspx.

Example (default profile): /query/salesorder/def.aspx

 

Example (“myCompany” profile): /myCompany/query/salesorder/def.aspx

 

queryscalar

The queryscalar URL keyword is used to accept query parameters via an XML posting. These parameters will be included in the HTML POST that is received. An example would be the yahoo stores real time inventory integration that passes a string in the POST, for example: .catalog=yhst-79125732853272&.id=_my_item_&.code=_my_code_.

 

If your query contains a parameter called CARDCODE, then when you call the B1WebAPI web service you will need to pass a URL parameter called CARDCODE and a data value which will be executed with the query. Additional parameters must be followed with an & character.

 

When creating your query in B1 remember the parameter syntax should be as follows: [%cardcode].

 

queries

The queries URL keyword is used to retrieve the list of queries configured in SAP Business One that are contained inside a B1WebAPI category.

 

  • Default B1WebAPI category queries - This mode returns a list of queries available in the default B1WebAPI query category in SAP Business One.

Syntax: [/<optional-profile>]/queries.aspx

 

  • Specified B1WebAPI category queries - This mode returns a list of queries available in the specified B1WebAPI query category in SAP Business One, such as B1WebAPI_CP for Customer Portal queries.

Syntax: [/<optional-profile>]/queries/<query-sub-category>.aspx

 

Example (default profile): /queries/CP.aspx returns all B1WebAPI_CP category queries, while /queries/OP.aspx returns all B1WebAPI_OP category queries. All queries relate to the default (first) B1WebAPI company profile.

 

Example (“myCompany” profile): /myCompany/queries/CP.aspx returns all B1WebAPI_CP category queries for the company specified in the “myCompany” B1WebAPI profile, while /profile/queries/OP.aspx returns all B1WebAPI_OP category queries for the company specified in the “myCompany” B1WebAPI profile.
 

Testing Queries

You can review queries and their results using B1WebAPI.

  • Connect to B1WebAPI, typically installed on the SAP Business One server, usually at http://localhost:4033/index.aspx.
  • Navigate to Test Queries, typically http://localhost:4033/test.aspx
  • Select the desired query and load it. Select the Application and Query, then press the “Load Definition” button to load the query.

 

 

 

Select the Application (1) and Query (2), then load the query (3).

 

 

Review the query.

 

 

 

Review the Query (1), then test the query results by completing parameters (2) and selecting the desired data type (3). Press Run Query to load the qurey results for the specified parameters.

 

 

Load query results by entering the query parameters and running the query (see screenshot above). Results will be displayed as shown below. You may link to these query results directly by using the link provided by the query results.

 

 

 

View query results (1) and link directly to those results (2).

 

Schema - REST API

The schema URL keyword enables the B1WebAPI web service to load the XML schema for any DI-API object that supports XML representation.

 

Keywords

schema

Transactions with this URL keyword call the GetBusinessObjectXmlSchema DI-API Company method that takes the object type and loads the full xml schema document.

 

Syntax: [/<optional-profile>]/schema/<object-type>.aspx

 

Example (default profile): /schema/oOrders.aspx

 

Example (“myCompany” profile): /myCompany/schema/oOrders.aspx

 

xml

The xml URL keyword is a special case that allows for the serving up generic, static XML documents from the B1WebAPI web service. This assumes that the XML document is stored in the B1WebAPI installation directory in the folder /xml/. See our list of Supported DI-API object types for more information.

 

UDT/UDO - REST API

Keywords

udt

The udt URL keyword is used to retrieve the list of UDTs configured in SAP Business One. The B1WebAPI web service provides developers with an interface to UDTs via a HTML GET or a HTML POST.

 

Syntax: /udt.aspx

 

HTML GET

If you provide the name of the UDT and the internal key of a record in that table, then the B1WebAPI web service will return an XML representation of that record.

 

Syntax: [/<optional-profile>]/udt/<UDT-name>/<UDT-key>.aspx Example (default profile): /udt/myCustomTable/10000.aspx Example (“myCompany” profile): /myCompany/udt/myCustomTable/10000.aspx

 

If you just provide the name of the UDT without a key, then the B1WebAPI web service will return all of the records in that UDT in XML format.

 

Syntax: [/<optional-profile>]/udt/<UDT-name>.aspx Example (default profile): /udt/myCustomTable.aspx Example (“myCompany” profile): /myCompany/udt/myCustomTable.asp

 

HTML POST

If you provide the name of the UDT and the internal key of a record in that table the B1WebAPI web service will update the UDT record with the XML that you POST.

 

Syntax: [/<optional-profile>]/udt/<UDT-name>/<UDT-key>.aspx Example (default profile): /udt/myCustomTable/10000.aspx Example (“myCompany” profile): /myCompany/udt/myCustomTable/10000.aspx

 

If you just provide the name of the UDT without a key, then the B1WebAPI web service will insert a new record into that table using the XML that you POST.

 

Syntax: [/<optional-profile>]/udt/<UDT-name>.aspx Example (default profile): /udt/myCustomTable.aspx Example (“myCompany” profile): /myCompany/udt/myCustomTable.aspx

 

Testing UDTs

You can load UDTs and UDT rows using the Test Transactions screen, as outlined below.

  • Connect to B1WebAPI, typically installed on the SAP Business One server, usually at http://localhost:4033/index.aspx.</li>
  • Navigate to Test Transactions, typically http://localhost:4033/transactions.aspx</li>
  • Select “UDT” from the Object Type drop-down, and select your UDT name. If desired fill in the Key (UDT Code field).</li>
  • Press Load UDT to load the data for the UDT or UDT row, as populated in B1. See screenshots below

 

 

 

 

Select the Object Type (1), UDT Name (2) and, if desired, fill in the Key (UDT Code) (3). Load the UDT (4) and view the results (5).

 

 

 

 

UDT in B1, note the Code field (1) is the UDT Key.

 

UDOs (User Defined Objects)

UDO support is very similar to UDT support. First, select UDO from the drop-down, or simply replace the “udt” keyword mentioned above with the keyword “udo”, and use the appropriate UDO name and UDO identifier.

 

Warning: UDOs with spaces in their names are unsupported.

 

User - REST API

Keywords

user

The user URL keyword enables the B1WebAPI web service to update user authentication via standard UDFs that are created in SAP Business One during installation. These UDFs can be found on both the Contact Person records on the Business Partner as well as the Employee Master records in the HR module. user updates support login and resetting the password (setpassword).

 

login

Passing the login keyword as part of the request directs the B1WebAPI web service to authenticate the user information you pass against the UDF information stored in SAP Business One.

 

Syntax: [/<optional-profile>]/user/login/username=<username>&password=<password>

 

Example (default profile): /user/login/username=test%40test.com&password=testing

 

Example (“myCompany” profile): /myCompany/user/login/username=test%40test.com&password=testing
 

setpassword

Passing the setpassword keyword as part of the request directs the B1WebAPI web service to update the user’s password with the new information you pass. This provides the ability to reset a user’s password via xml (which is stored encrypted in SAP Business One).

 

Syntax: [/<optional-profile>]/user/setpassword/username=<username>&oldpassword=<old-password>&newpassword=<new-password>

 

Example (default profile): /user/setpassword/username=test%40test.com&oldpassword=testing&newpassword=newpass

 

Example (“myCompany” profile): /user/setpassword/username=test%40test.com&oldpassword=testing&newpassword=newpass

 

 

 

 

Previous

Next

  

Last modified: 11/14/2023/9:33 pm

On this page

-