Library OpenApi Overview About these APIs Architecture Authentication Error Responses Locating a Server Sessions Design Guides Guides and Hints Examples Pricing for Websites Accepting Vouchers PreAuth Payment Replication Common Apis The most used APIs Create New Sale Payment Completion Multiple Locations Delivery Addresses Customers Locations Products Staff WebHooks eCommerce Apis These APIs are often used with eCommerce website integrations Get Pricing Card Inquiry Report & Analysis Grouped or analysed report data. Typically used to build reports and dashboards Today Login Access Pinboard ReportRequest Advanced Information More indepth information Caller Handling HTTP Protocol Bulk Data Downloads Document Uploading RetailConfig Under Development Details of APIs that will be available shortly. Documentation provided is for early adopters Get Receipt

HTTP Information

Response Codes

Details of the response codes that can be returned by OpenAPI. An individual API may provide additional special case use as well. The application firewall is also able to return and modify HTTP response codes at will, although this is typically only used to return 503 Forbidden or 404 Not Found codes.

200 OK

The OpenAPI request itself was completed correctly, however the response body may be an error packet if the call itself had issues with the request.

400 Bad Request

The OpenAPI request was processed but had an error inside the contents or body of the request. When this code is returned you should receive an error packet with the following format:

{
  "error": {
    "Code": 2003,
    "Message": "The value of field Sale.Phase is invalid, must be 1 (normal), 200 (picking) or 10000 (void)"
  }
}

403 Forbidden

Returned when your authentication is valid (we know and trust who you are), but you are not authorised to access the data requested. You should not retry the request until it is changed, or the Retailer changes their security policies to allow you access.

There are a large number of reasons this code can be returned. There may be a x-fieldpine-trace header giving details of where you were blocked. Some examples of blocks:

You requested access to an API you do not have permission to call
Your call requested information on a customer, but you cannot see that customers details. You might be able to see other customers, but you cannot see this customer
You requested information on sales or trading performance, but your access only permits you to see the last 3 months of data

When this response is returned an additional random delay is added before the response is returned. This is to hinder side-channel leakage.

429 Too Many Requests

This response is sent when server has switched to charge protection mode and cannot delay the response for some reason. This header will only be returned from Fieldpine Servers, retailers running Fieldpine on their own servers do not generally apply rate limiting. If you receive this response, you should wait and try again later.

In order to protect our customers from billing shock caused by unexpected peaks in API requests each retailer is able to set a threshold and limit billing using various options. As an example, a retailer may limit their spend to $10/day, with a threshold of $7. This means that once the use within a day exceeds $7, Fieldpine servers will apply various restrictions to try and limit the maximum spend to $10. The main way this is done is by limiting single transactions and taking longer to respond to requestors that might be issuing frequent requests. Eventually there is a point where the server has no option but to return an error code to the requestor, and this is where a 429 response can be seen.

Out of the box, Fieldpine do not apply rate limits of N calls per hour (some APIs do apply this style of limit themselves though if they are dealing with sensitive data). When an api is called the server typically opens a window of 60 seconds during which you can make multiple calls, the charging is based on the 60 seconds of time, not the number of calls made. Some of the APIs provided are designed for calling while users are typing and we do not want to impact customer experience if possible. It is also easier implement this method over distributed servers.

500 Internal Server Error

This response is not currently returned by Fieldpine applications directly, it is typically generated by a CDN, proxy or Load Balancer placed in front of the Fieldpine servers. In the future we may return this status.

502 Bad Gateway

This response is not returned by Fieldpine applications directly, it is typically generated by a CDN, proxy or Load Balancer placed in front of the Fieldpine servers.

One way this response can arise is if the Fieldpine application firewall has triggered a rule to "drop connection" rather than return any error code. On seeing the network link drop, CDNs and proxies will typically then return a 502 response. The default setting for Fieldpine firewall is to use drop-connection for requests that originate from the internet. This ensures that internet requestors receive zero information that tell them even what software is running.

503 Service Unavailable

We are unable to process this request on this server at this time.

Most commonly this is retured when the request requires the use of a processing agent or micro service, and that service is not currently available and/or could not be started on demand.

HTTP Request Headers

X-api-key: The API key granted to you to, so that you can be uniquely identified to the server. All OpenApi requests originating from the internet must include a X-Api-Key header, without this header your request will be treated as a CSRF attack. LAN requests should include a x-api-key and this will likely be required in a future release.
Some API keys have the text "PublicVisible" as part of the key value. These are for keys that we know are being issued to client applications where the source code or network traffic is easily visible, such as web pages calling OpenApi directly or Android/iPad apps. You should ensure that only keys with "PublicVisible" are used in less secure places.
X-Fieldpine-CallerHandling: Supplies additional details about the requesting programs abilities and expectations. See CallerHandling.htm for more details.
X-Fieldpine-Transform: The request body has been double encrypted. See details below under Response Headers for more information.
X-Fieldpine-CallerTrace: This header can be inserted to provide trace information to the server as to where this call originated from (code source line). You should include something like Math.random() as well so that browser generated duplicates can be detected when reviewing server side traces. This header is NOT required and is only for diagnostic support purposes.

HTTP Response Headers

X-Fieldpine-Trace

For advanced tracing, some Api requests will contain x-fieldpine-trace headers. This header when present is intended for development and support personel. It has details of decisions in the server that cannot easily be returned as an error object or must not for some reason. You must not rely on this response header or its contents - it may change without warning.

Examples

X-Fieldpine-Trace: Firewall Rule AAAABBBBCCCC

The firewall rule may be returned as a header to let you know which rule(s) have been involved in this request. The reply value is the internal keyname of the rule and does not disclose what the rule contains. This value can be useful when attempting to diagnose Fieldpine application security.

X-Fieldpine-Trace: Check ApiKey Failed

The request was processing and was then blocked as the API key does not have access to something.

X-Fieldpine-Transform

If the response body has been encrypted in addition to transport level security via HTTPS, this header contains details of the encryption used, so that client applications can decode the data. This header should not be seen in general operation as it is a feature reserved for programs that support client side encryption, such as master server to server data transfer.

Transform responses are often only a bit slice of the data and clients must assemble multiple responses, typically from different servers, to recreate the response.

Transform header may be seen for requests/responses to Fieldpine.com websites when Fieldpine is being used to route data between stores, but is not storing or processing the data. In this case the data is encrypted using keys that fieldpine.com does not have.