NOTE: For information on the Ship/FX API, consult the following: Ship/FX API Management (Developer Resources)

Drop Ship

Calling the eFORMz dropship template library makes use of the ‘output’ endpoint, which is described in more detail below.

Dropship Standardized XML Schema: DropShipSchema

Call Dropship (JSON): DropShipSample

Endpoints: Director/Output

There are two primary endpoints available to eFORMz customers. These are the ‘director’ and ‘output’ endpoints.

An “endpoint” is one end of a communication channel. When an API interacts with another system, the touchpoints of this communication are considered endpoints. For APIs, an endpoint can include a URL of a server or service. The place that APIs send requests and where the resource lives is called an endpoint.

The ‘director’ endpoint returns success or failure only. It processes data in the background. The ‘output’ endpoint processes data during the call and returns the results as part of the web service call. Both of these endpoints can take parameters either through the URL or in the data.

While the portion of the URL with authentication is encrypted for transmission, many people have policies restricting this practice. Passing the parameters in the data, including authentication, is possible using either XML or JSON. The order or sequence of elements in either format is not relevant to the processing.

eFORMz Web Service API response codes

As stated above, for an API call to the “director” endpoint, there are the two responses: success or failure. Effectively, you are pushing data into an ‘-ac’ (accessible) Local Director Queue. The response codes are 200 for success and 500 for an error.

The ‘output’ endpoint executes a project, which can call other projects, and returns output. The type of project output is configurable. There are quite a few responses possible if the URL is not formed in an expected fashion. A good source for the ‘types’ of endpoints is the AuthenticationCfg.xml file. There you will find:
• <Authentication Name=”activeFORMz”
• <Authentication Name=”eFORMz Web Services”
• <Authentication Name=”ServiceManagerManagement”
• <Authentication Name=”ServiceManagerConfiguration”

The AuthenticationCfg.xml has 401 responses in addition to the 200 and 500 codes.

Authentication/Authorization

Authentication proves who you are. Authorization refers to what you are allowed to see and do. AuthenticationCfg.xml is the file that handles authentication and authorization. Web Service Authentication can be through username/password, LDAP, Kerberos or Azure AD.

Basic (username:password)
Authenticator="com.minisoft.common.CredentialsInXMLFileAuthenticator"
Authenticator="com.minisoft.common.ADAuthenticator"
Authenticator="com.minisoft.common.LDAPAuthenticator"

Bearer (Token-based authentication)
Authenticator="com.minisoft.common.AADAuthenticator"

The on-premises Microsoft Active Directory is accessed through Kerberos. Azure Active Directory is web-based and has its own definition within the AuthenticationCfg.xml. Web Service Authorization (for an authenticated user) is through the URL/URI used. This depends on the endpoint used and can be the project of config parameters. For example:

<Group Name="Testing">
     <Member Name="projects/eSHIP/SHIPFXConfiguration.xml" />
     <Member Name="projects/SHIPFX/SHIPFXAdmin.xml" />
     <Member Name="projects/eSHIP/ShipperWS.efz" />
     <Member Name="projects/eSHIP/GetRatesWS.efz" />
</Group>

URL Formats

eFORMz API: URL Formats

Parameters

eFORMz API URL Parameters

Director Sample

URL

http://localhost:8001/servlet/com.minisoft.AppServer.AppServer?APP=com.minisoft.eformz.eFORMzApp

XML

<?xml version="1.0" encoding="UTF-8"?>
<ServiceConfiguration ServiceType="director" Host="localhost" Port="9996" ConfigurationName="accessible.cfg" QueueName="Accessible" NameTemplate="data_.xml" ProcessData="true" UseParmsAsData="false">
  <InputData usepostdata="false" format="XML" encoding="none">
    <Data>
      <AdditionalInfo>
                <misc>info</misc>
      </AdditionalInfo>
    </Data>
  </InputData>
</ServiceConfiguration>

JSON

{
    "ServiceConfiguration":
          {
             "ServiceType":"director",
             "Port":9996,
             "NameTemplate":"data_.json",
             "Host":"localhost",
             "UseParmsAsData":false,
             "ConfigurationName":"accessible.cfg",
             "InputData":
             {
                    "usepostdata":false,
                    "format":"JSON",
                    "Data":
                    {
                          "AdditionalInfo":
                               {
                               “misc”:”info”
                               },
                    },
                    "encoding":"none"
             },
             "QueueName":"Accessible",
             "ProcessData":true
          }
}

Output Sample

XML

http://localhost:8001/servlet/com.minisoft.AppServer.AppServer?APP=com.minisoft.eformz.eFORMzApp&config=projects/OutputGuideServer/configOutputUsePostData.xml

<?xml version="1.0" encoding="utf-8"?> 
<ServiceConfiguration ServiceType="output" project="projects/OutputGuideServer/MapPackSlipData0.efz" format=".xml"> 
  <InputData format="XML"> 
    <Root> 
      <abc>test</abc> 
    </Root> 
  </InputData> 
</ServiceConfiguration> 

The root node must be named ServiceConfiguration and the parameters are specified as attributes of that node. The output parameter directs the eFORMz web service to return the output of an eFORMz project specified by the project parameter. The calling application can pass in input data for the project in a variety of ways. The InputData node with the attribute format specifies the format of the embedded data. The data passed to the project is the Root node and all of its descendant nodes (abc in this example).

JSON

http://localhost:8001/servlet/com.minisoft.AppServer.AppServer?APP=com.minisoft.eformz.eFORMzApp&output&project=projects/JSON/MirrorTest.efz&usepostdata&dataformat=JSON&format=.txt

{
    "success": true,
    "header": null,
    "data": {
        "Messages": null,
        "FulfillmentAddress": [
            {
                "AddressTypeId": {
                    "AddressTypeId": "Billing"
                },
                "Address": {
                    "FirstName": "First",
                    "LastName": "Last",
                    "Address1": "1024 First Street",
                    "Address2": "Suite 311",
                    "Address3": null,
                    "City": "Snohomish",
                    "State": "WA",
                    "PostalCode": "98290",
                    "County": null,
                    "Country": "US",
                    "Phone": "8006820200",
                    "Email": "sales@minisoft.com"
                },
                "Process": null
            },
        ],
    },
    "message": null,
    "errors": [],
    "exceptions": [],
    "messages": {
        "Message": [],
        "Size": 0
    },
}

Download the working sample with a Postman test call here: JSONTest. JSON comes in, the MirrorAction.efz project affects the fields and JSON is sent out.

Set Response Header

Response headers can be set by the project defining and setting global variables:

Source Parameter (Create JSON)

&Source is an API parameter used to to identify a Global Variable in the called project.

http://localhost:8001/servlet/com.minisoft.AppServer.AppServer?APP=com.minisoft.eformz.eFORMzApp&output&project=projects/sample/JSON_IO.efz&usepostdata=true&source=gsource

When the variable is found in the set of Global Variables having the “Pass last value to Queue Monitor” set, the last value is returned as the API call return data.

Tag: Make an API call