POST /pos/receipts¶
Post raw receipts in any format. The raw receipt data will be processed asynchronously and turned into an actual receipt. The transformation of the raw receipt data to a structured receipt must be set up in advance.
Authentication is performed using one of the standard authentication methods, though bearer tokens are recommended.
Example request:
POST /pos/receipts HTTP/1.1
Content-Type: text/xml
Content-Length: 10000
Authorization: Bearer eyJhbGciOiJIUzI1NiIsImtpZCI6IkxGUlRNTEtIUU1VUTlXNklKRVBNIiwidHlwIjoiSldUIn0.eyJqdGkiOiI3NTE1MDc4My0yOTc0LTRkZmMtODk0Yy00ZWYyZjk1YWRkZGYifQ.r4kEkNDFwk29_LK05d5odtM35BJRlcc3RMVDEeGOuCc
Host: api.ereceipts.co.uk
<xml>... data ...</xml>
Example response:
HTTP/1.1 202 Accepted
Properties¶
Properties relating the posted receipt(s) may be sent with the request using two different methods:
query arguments prefixed with
property-headers prefixed with
ereceipts-property-
This could be data such as: a customer email address, a flag indicating a receipt delivery method, or any other data that isn’t directly available in the payload. There is no pre-defined format for the individual properties. It is therefore possible to send simple strings, or more structured data, such as JSON, if required.
POST /pos/receipts?property-email=me%40example.com&property-send=true HTTP/1.1
Host: api.ereceipts.co.uk
... data ...
POST /pos/receipts HTTP/1.1
ereceipts-property-email: me@example.com
ereceipts-property-send: true
Host: api.ereceipts.co.uk
... data ...
If the same property is specified in the query string and as a header, the header value will always be used. If the same name is defined multiple times, the first value will be used. Case is ignored and - and _ are considered the same character.
Metadata¶
In addition to the free-form properties, the following metadata can be sent along with a request:
Name |
Query argument |
Header |
|---|---|---|
n/a |
|
|
|
|
|
|
|
If the same metadata key is specified in the query string and as a header, the header value will always be used.
Attachments¶
Attachments may be used to submit larger data with a receipt. For example, an image
of the customer’s signature or a fiscal receipt PDF to be presented with the digital
receipt. Linking attachments can be done using the ereceipts-attachment-id header,
and attachments are submitted separately using the
POST /attachments API. Linking attachments using query
arguments is not supported.
POST /attachments HTTP/1.1
Content-Type: application/pdf
Content-Length: 5000000
Content-Disposition: attachment; filename="attachment.pdf"
Host: api.ereceipts.co.uk
... data ...
HTTP/1.1 201 Created
Content-Type: application/json
Content-Length: 157
Location: https://api.ereceipts.co.uk/attachments/yocuda.eabb4076-1503-4c8d-b41d-a33ccf95fcd4
{
"id": "yocuda.eabb4076-1503-4c8d-b41d-a33ccf95fcd4",
"url": "https://api.ereceipts.co.uk/attachments/yocuda.eabb4076-1503-4c8d-b41d-a33ccf95fcd4"
}
The returned attachment id should be used to link the attachment with a request,
using the ereceipts-attachment-id header:
POST /pos/receipts HTTP/1.1
ereceipts-attachment-id: yocuda.eabb4076-1503-4c8d-b41d-a33ccf95fcd4; label=large_pdf
Host: api.ereceipts.co.uk
... data ...
which can be used multiple times when more than one attachment is required:
POST /pos/receipts HTTP/1.1
ereceipts-attachment-id: yocuda.eabb4076-1503-4c8d-b41d-a33ccf95fcd4; label=large_pdf
ereceipts-attachment-id: yocuda.2b6971c4-e922-43aa-81d4-c8023ef3b48a; label=medium_pdf
Host: api.ereceipts.co.uk
... data ...
alternatively multiple attachments can be separated using a commas:
POST /pos/receipts HTTP/1.1
ereceipts-attachment-id: yocuda.eabb4076-1503-4c8d-b41d-a33ccf95fcd4; label=large_pdf, yocuda.2b6971c4-e922-43aa-81d4-c8023ef3b48a; label=medium_pdf
Host: api.ereceipts.co.uk
... data ...
Syntax¶
ereceipts-attachment-id: <attachment-id>; param1=value1; param2="value2"
The attachment-id is obtained by submitting an attachment using
POST /attachments. The following parameters are supported:
Name |
Required |
Value |
|---|---|---|
|
yes |
the label to associate with this attachment |
Duplicate¶
The duplicate=true query argument or ereceipts-duplicate: true header may be
used to indicate a duplicate receipt. See: Duplicate Receipts for
more information on duplicate receipts.
POST /pos/receipts?duplicate=true HTTP/1.1
Host: api.ereceipts.co.uk
... data ...
POST /pos/receipts HTTP/1.1
ereceipts-duplicate: true
Host: api.ereceipts.co.uk
... data ...
External ID¶
The external-id query argument or ereceipts-external-id header can be used
to send a UUIDv4 (as defined in RFC 4122) to support, for example, QR code journeys.
POST /pos/receipts?external-id=44294519-1d3e-46a5-954b-099d63c6c47f HTTP/1.1
Host: api.ereceipts.co.uk
... data ...
POST /pos/receipts HTTP/1.1
ereceipts-external-id: 44294519-1d3e-46a5-954b-099d63c6c47f
Host: api.ereceipts.co.uk
... data ...
Limits¶
There are limits imposed on the size of:
the query string
individual headers
the combined headers
the request body
In general the limits are smallest at the top of the list (query string) and larger at the bottom (request body) and the different methods of sending additional data should be used accordingly. The Attachments API should be used to post larger attachments that should be associated with the receipt data.
Should any of the limits be exceeded, the server will return the following error codes:
- 414 Request-URI Too Large
for requests where the query string limit is exceeded
- 413 Entity Too Large
for requests where the individual or combined header limit is exceeded
- 413 Request Entity Too Large
for requests where the body size limit is exceeded
The default limits should be sufficient for normal use of the Yocuda API, however if you need to discuss the limits please contact your representative.
