Getting started¶
Welcome to the Yocuda Receipt API. This guide will explain how to use the API to submit, retrieve and email a receipt.
To begin using the API you must first obtain a key and secret from Yocuda.
Generating a signature¶
Each request made to the Yocuda Receipt API needs to be authenticated using an HMAC signature.
The signature is generated using the HMAC-SHA256 algorithm processed over:
Your assigned API access key.
An expires time in whole seconds since 00:00:00 UTC on 1 January 1970. This is a time when the signature will no longer be valid.
Zero or more consumer identifiers, depending on the resource that the signature will be used with. Multiple consumer identifiers are separated by a comma.
Please see the Authentication for an in-depth explanation and the Signature Example page for help in generating a signature.
The signature will be used in the query string for all requests in this guide, along with the key and the expires parameters. It should look something like this:
expires=1376911980&key=PFJF2POHQKNH7HRAXMCD&signature=7iuC02Kbbe1K6mC3Pk9MHciGPqxd1U2ctgDEo6z0jpo%3D
Sending a receipt¶
This example shows how to submit a fictitious receipt for a pair of cufflinks. The receipt data follows a fixed JSON format which is documented at POST /receipts. All submitted receipts must adhere this format or they will be rejected by the API.
The identifier in the receipt below is optional, but setting it to an email address will make it possible to send an electronic copy of the receipt later. The store reference must be set to a valid reference to a store in your account. You will have received a store reference when your account was provisioned. The transaction id on the receipt is a the string generated by you, or your existing POS system, that uniquely identifies this transaction.
{
"identifier": "example@example.com",
"localtime": "2013-04-30T14:57:00+01:00",
"store_reference": "1",
"total": 10.0,
"transaction_id": "10",
"items": [
{
"name": "Cufflinks",
"quantity": 1,
"total": 10.0
}
]
}
The JSON encoded receipt must be submitted to the receipts resource:
https://api.ereceipts.co.uk/receipts
To authenticate with the API you must include the authentication query string parameters from above. When posting a receipt the consumer parameter is not required in the authentication query string, resulting in the following URL:
https://api.ereceipts.co.uk/receipts?expires=1376911980&key=PFJF2POHQKNH7HRAXMCD&signature=7iuC02Kbbe1K6mC3Pk9MHciGPqxd1U2ctgDEo6z0jpo%3D
You can now use the URL to POST the receipt using the JSON data as the body of the request. Using cURL this would look like:
curl -H "Accept: application/json" \
-H "Content-type: application/json" \
-X POST -d '{"identifier":"example@example.com","localtime":"2013-04-30T14:57:00+01:00","store_reference":"1","total":10.0,"transaction_id":"10","items":[{"name":"Cufflinks","quantity":1,"total":10.0}]}' \
"https://api.ereceipts.co.uk/receipts?expires=1376911980&key=PFJF2POHQKNH7HRAXMCD&signature=7iuC02Kbbe1K6mC3Pk9MHciGPqxd1U2ctgDEo6z0jpo%3D"
If the request was successful, the response will be a JSON dictionary containing
the id of the submitted receipt.
{
"id":"5208f3b453a2810285e699f0"
}
Retrieving a receipt¶
You can retrieve the submitted receipt by using the id from the previous
response in a GET request on receipts resource:
https://api.ereceipts.co.uk/receipts/5208f3b453a2810285e699f0
Performing a GET request to this URL, with the authentication query string parameters added will allow you to request the receipt. Using cURL:
curl -H "Accept: application/json" \
-H "Content-type: application/json" \
"https://api.ereceipts.co.uk/receipts/5208f3b453a2810285e699f0?expires=1376911980&key=PFJF2POHQKNH7HRAXMCD&signature=7iuC02Kbbe1K6mC3Pk9MHciGPqxd1U2ctgDEo6z0jpo%3D"
This should return the original receipt with additional some additional fields added:
Retailer and store information.
Values, such as vat, discounts, net, properties, that were not set in the POSTed receipt have been set to an empty dictionary, empty list, or null as appropriate.
{
"store_reference": "1",
"identifier": "example@example.com",
"retailer": {
"vatno": null,
"name": "Paperless Toys"
},
"id": "5208f3b453a2810285e699f0",
"discounts": [],
"vat": [
{
"rate": null,
"amount": null
}
],
"timestamp": "2013-04-30T13:57:00+00:00",
"net": null,
"total": 10.0,
"properties": {},
"transaction_id": "10",
"localtime": "2013-04-30T14:57:00+01:00",
"items": [
{
"name": "Cufflinks",
"discounts": [],
"net": null,
"total": 10.0,
"properties": {},
"vat": {
"rate": null,
"amount": null
},
"quantity": 1
}
],
"store": {
"address": [
"Colonial Buildings",
"59-61 Hatton Garden"
],
"city": "London",
"name": "Paperless Toys",
"phone": "+440000000000",
"postcode": "EC1N 8LS"
}
}
Emailing a receipt¶
An email receipt is automatically sent if the receipt contains a valid identifier to which an email can be sent (unless this has been disabled for a particular retailer.) The default behaviour with regards to sending email is configurable, and is set up as agreed with the customer. It is possible, on a receipt by receipt basis to override the defaults, as shown below.
If the identifier on a receipt is an email address, then this address will be used as the recipient of the email. If the identifier is not a valid email address, then the Identifier record will be queried for an email address to which to send the email receipt. If there is no identifier on a receipt, no email will be sent. If an identifier is later associated with the receipt (using the PATCH /receipts/{id} resource) an email will never be automatically sent. When an email address is associated with a receipt and an email should be sent, this must be done manually (see Manual email sending.)
Disabling email sending on selected receipts¶
When the default for the retailer is to send email automatically, sending of emails can be suppressed for an individual receipt by using the Email Settings in the receipt Receipt Properties Object, and setting send to false.
Using this setting only makes sense when the receipt has a valid identifier when posted to the POST /receipts resource.
Example:
Setting send to false for this particular receipt; showing only the properties key of a receipt object.
{
"properties": {
"email_settings": {
"send": false
}
}
}
Forcing email sending on selected receipts¶
When the default for the retailer is to not send email automatically, sending of emails can be forced for an individual receipt by using the Email Settings in the receipt Receipt Properties Object, and setting send to true.
Using this setting only makes sense when the receipt has a valid identifier when posted to the POST /receipts resource.
Example:
Setting send to true for this particular receipt; showing only the properties key of a receipt object.
{
"properties": {
"email_settings": {
"send": true
}
}
}
Selecting an alternate email template for selected receipts¶
Using this setting only makes sense when the receipt has a valid identifier when posted to the POST /receipts resource.
Example:
Setting the email template to one named Alternate for this particular receipt; showing only the properties key of a receipt object.
{
"properties": {
"email_settings": {
"template": "Alternate"
}
}
}
Manual email sending¶
Should it be necessary to manually send an email, this can be done using the email resource:
https://api.ereceipts.co.uk/email
The id of the receipt is included in a JSON dictionary which is used as the
body of the request to the email resource with the authentication query
string parameters added. Using cURL this can be achieved as follows:
curl -H "Accept: application/json" \
-H "Content-type: application/json" \
-X POST -d '{"id":"5208f3b453a2810285e699f0"}' \
"https://api.ereceipts.co.uk/email?expires=1376911980&key=PFJF2POHQKNH7HRAXMCD&signature=7iuC02Kbbe1K6mC3Pk9MHciGPqxd1U2ctgDEo6z0jpo%3D"
If the email is sent successfully the resource will return a 204 status code:
HTTP/1.1 204 No Content
