Attachment Object

Attachments may be used to submit additional 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.

Name	Type	Description
id	string, optional, mutually exclusive with data, required if data not set	the identifier of an existing attachment
data	string, optional, mutually exclusive with id, required if id not set	the base64-encoded data of a new attachment
content_type	string, optional	value of the new attachment’s Content-Type header
content_disposition	string, optional	value of the new attachment’s Content-Disposition header

Inline attachments

Small attachments, up to 1 MB in combined size, may be submitted inline with the receipt:

{
  "attachments": {
    "customer_signature_png": {
      "content_type": "image/png",
      "data": "ZGF0YQ=="
    },
    "fiscal_receipt_pdf": {
      "content_disposition": "attachment; filename=\"fiscal_receipt.pdf\"",
      "content_type": "application/pdf",
      "data": "ZGF0YQ=="
    }
  },
  "identifier": "990000000001",
  "items": [
    {
      "name": "Cufflinks",
      "quantity": 1,
      "total": 10.0
    }
  ],
  "localtime": "2013-04-30T14:57:00+01:00",
  "store_reference": "1",
  "total": 10.0,
  "transaction_id": "0011120008"
}

Large attachments

Attachments larger than 1 MB must be posted separately:

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 may be used to link the attachment with a posted receipt:

{
  "attachments": {
    "large_pdf": {
      "id": "yocuda.eabb4076-1503-4c8d-b41d-a33ccf95fcd4"
    }
  },
  "identifier": "990000000001",
  "items": [
    {
      "name": "Cufflinks",
      "quantity": 1,
      "total": 10.0
    }
  ],
  "localtime": "2013-04-30T14:57:00+01:00",
  "store_reference": "1",
  "total": 10.0,
  "transaction_id": "0011120008"
}

Linking attachments using headers

While the default workflow assumes that the attachment is created before a receipt is submitted, this may not always be practical. For example, it may be difficult to coordinate such process if the attachment and the receipt are submitted by independent parties.

Alternatively, an attachment may be linked with a receipt by providing its unique transaction identifier and the attachment label in headers:

POST /attachments HTTP/1.1
Content-Type: application/pdf
Content-Length: 5000000
Content-Disposition: attachment; filename="attachment.pdf"
ereceipts-transaction-id: 0011120008
ereceipts-attachment-label: fiscal_receipt_pdf
Host: api.ereceipts.co.uk

... data ...

A successful response contains a link to the receipt:

HTTP/1.1 201 Created
Content-Type: application/json
Content-Length: 295
Location: https://api.ereceipts.co.uk/attachments/yocuda.182099e0-e6b1-4ab4-98b8-1e641aef810b

{
    "id": "yocuda.182099e0-e6b1-4ab4-98b8-1e641aef810b",
    "url": "https://api.ereceipts.co.uk/attachments/yocuda.182099e0-e6b1-4ab4-98b8-1e641aef810b",
    "_links": {
        "receipt": {
            "href": "https://api.ereceipts.co.uk/receipts/513e2391ee5e525ff9000000"
        }
    }
}

If the provided transaction identifier does not match an existing receipt:

• the attachment is queued for linking, with the assumption that a matching receipt will be posted in the future,

• a successful response does not contain a receipt link.

If the linking fails, a 400 Bad Request response is returned. Specifically, this can happen when the referenced receipt already contains an attachment with the provided label.