Resource Patterns

Read, modify, and write resources

The Finale Inventory API follows the REST architecture. The intial authentication URL returns a set of URLs for the various resource collections defined in the API. Performing a GET on any of the collections returns a column major representation of the resource in the collection. Each resource is identified with a URL which can be used with GET to retrieve a representation of the resource and POST to update the resource (using POST instead of PUT is the primary departure from the REST architecture).

URL for modifying resources

Finale uses a different internal identifier than the external resource id for some resources. This is especially true on the product resource collection (URL is not always "/[account name]/[resource collection name]/[resource id]"). The correct resource URL can be retrieved on product creation (https://support.finaleinventory.com/hc/en-us/articles/115007830888-Complete-example), by downloading the whole resource collection and retrieving the correct product (see below), or by filtering by id(https://support.finaleinventory.com/hc/en-us/articles/115007936708-Filtering-resources).

Action URLs

Some resource have additional operations that can be triggered through a POST to a specific URL for that resource. For example, a shipment is shipped by posting information about the shipment operation to the URL contained actionUrlShip field of the shipment representation. The API documentation for the various resource representation describe these action URLs. These action URLs are included in the representation returned from the server only when the action is valid given the current state of the resource (otherwise they are omitted or are null).

Column major collection representation

Peforming a GET operation on the URL of a resource collection will return a column major representation of the collection. For example, consider the product resource collection with three fields: productId, productUrl, and internalName (the product representation has additional fields but three fields are enough for this discussion).

When retrieving a representation of the single resource, the JSON document will be returned as an object with the three fields as the keys and the value of each key being the value for of the field for the resource:

    { "productId" : "NCP-002",
      "internalName" : "Green peony to crackle",
      "productUrl" : "/newcentury/api/product/NCP-002",
    } 

When retrieving the representation of the resource collection, the JSON document will still be returned with the three fields as the keys but the value of each key will be an array with exactly one entry per resource in the collection:

    { "productId" : ["NCP-002","NCP-018"],
      "internalName" : ["Green peony to crackle","Blue mine"],
      "productUrl" : ["/newcentury/api/product/NCP-002","/newcentury/api/product/NCP-018"],
    }

This example shows the representation for a product resource collection containing two resources. The first resource has the value at position 0 in each array, and the second resource has the value at position 1.

Finale Inventory uses this representation to reduce the number of HTTP requests required for API clients to retrieve a local copy of commonly used data, such as the complete list of products or customers. This representation supports retrieving an entire resource collection in a single HTTP request. The column major structure interacts well with HTTP compression to create a very compact representation over the network.

Common data structures and data types

Contact mechanism

A contact mechanism is JSON structure which represents a physical address, telephone number, email address, or web address. Several resource types makes use of the contact mechanisms.

Fields in a contact mechanism structure:

• contactMechTypeId

  The type must be one of the following values: EMAIL_ADDRESS, POSTAL_ADDRESS, TELECOM_NUMBER, or WEB_ADDRESS.

• infoString

  For EMAIL_ADDRESS, TELECOM_NUMBER, or WEB_ADDRESS this is the email address, telephone number, or web address respectively. String of up to 255 characters.

• address1

  Street address. Applicable only to POSTAL_ADDRESS. String of up to 255 characters.

• city

  City. Applicable only to POSTAL_ADDRESS. String of up to 100 characters.

• stateProvinceGeoId

  Enumerated value for the state / province. Applicable only to POSTAL_ADDRESS. Must be one of the following (the bold letters are the value, the name is not part of the value):

  AK Alaska, AL Alabama, AR Arkansas, AZ Arizona, CA California, CO Colorado, CT Connecticut, DC District of Columbia, DE Delaware, FL Florida, GA Georgia, HI Hawaii, IA Iowa, ID Idaho, IL Illinois, IN Indiana, KS Kansas, KY Kentucky, LA Louisiana, MA Massachusetts, MD Maryland, ME Maine, MI Michigan, MN Minnesota, MO Missouri, MS Mississippi, MT Montana, NC North Carolina, ND North Dakota, NE Nebraska, NH New Hampshire, NJ New Jersey, NM New Mexico, NV Nevada, NY New York, OH Ohio, OK Oklahoma, OR Oregon, PA Pennsylvania, PR Puerto Rico, RI Rhode Island, SC South Carolina, SD South Dakota, TN Tennessee, TX Texas, UT Utah, VA Virginia, VT Vermont, WA Washington, WI Wisconsin, WV West Virginia, WY Wyoming, AB Alberta, BC British Columbia, MB Manitoba, NB New Brunswick, NL Newfoundland and Labrador, NS Nova Scotia, NT Northwest Territories, NU Nunavut, ON Ontario, PE Prince Edward Island, QC Quebec, SK Saskatchewan, YT Yukon, AU-ACT Australian Capital Territory, AU-NSW New South Wales, AU-NT Northern Territory, AU-QLD Queensland, AU-SA South Australia, AU-TAS Tasmania, AU-VIC Victoria, AU-WA Western Australia.

• countryGeoId

  Enumerated value for the country. Applicable only to POSTAL_ADDRESS. Must be one of the following (the bold letters are the value, the name is not part of the value):

  AUS Australia, AUT Austria, BEL Belgium, CAN Canada, CHE Switzerland, CHN China, DEU Germany, DNK Denmark, ESP Spain, FIN Finland, FRA France, GBR United Kingdom, HKG Hong Kong, IRL Ireland, ISL Iceland, ITA Italy, JPN Japan, MEX Mexico, MLT Malta, NLD Netherlands, NOR Norway, NZL New Zealand, PRT Portugal, SWE Sweden, USA United States, ZAF South Africa.

• contactMechId

  Assigned by the server. Read only.

Example contact mechanism structures:

   { "contactMechId":"10035",
     "contactMechTypeId":"TELECOM_NUMBER",
     "infoString":"(212) 123-0193",
     "contactMechPurposeTypeId":"FAX_NUMBER"
   }

   { "contactMechTypeId":"POSTAL_ADDRESS",
     "infoString":"",
     "address1":"89812 Lowell Ave.",
     "city":"Campbell",
     "stateProvinceGeoId":"CA",
     "postalCode":"91022"
   }

Dates and times

The system expects all dates and times to be specified as ISO 8601 strings in UTC.

Normalized packing string

Most lists of items (e.g. shipment items, order items, etc.) in Finale have a normalizedPackingString field that specifies the packing for the item. If null, then the item is an open stock item. If not null, the normalized packing string starts with a floating point number which is the conversion factory. The conversion factor is followed by a space and then the user visible representation of the packing. The conversion factor is number of open stock units in each case of this packing. Currently the user visible representation must start with the letters cs indicating case.

Examples:

• 12 cs 12/1 Each packed unit converts to 12 open stock units and displays to the users as cs 12/1 or 12/1 depending on context
• 12 cs 4/3 Each packed unit converts to 12 open stock units, however is not interchangable with the previous example of cases packed 12 cs 12/1. Displays to the users as cs 4/3 or 4/3 depending on context
• cs 12/1 This is an error, missing conversion factor
• 18 This is an error, missing user visible representation