The headed paper under the pages

In plain words

Written for anybody. It says what this puts on a sheet of paper, and asks nothing of you beyond that.

Many firms have headed paper: the logo at the top, the address at the bottom, and a wide blank in between to write on. It is the same thing here, in digital form. You supply the background once, already made, and the text comes to sit on top of it. You may even supply three: one for the first page, one for the pages in between, one for the last — the signature sheet, for instance.

For a developer

Written for somebody who writes the calling program: the model, the units, and the settings that carry the weight.

templates names up to three background PDFs, by page position: the start, the middle, the end. The bytes of each background arrive alongside the request, in a form part carrying exactly that name. The middle background holds one single page, repeated as many times as needed; the start and end backgrounds may run to several. All three keys are optional: a request may give just one.

Every key, with its default

The reference: which keys are required, which are optional, what each one defaults to and which combinations the server declines.

• templates — object, optional, absent by default.
• templates.start — string, optional. The name of the supplied part holding the template laid under the document's first pages.
• templates.middle — string, optional. The name of the part holding the single-page template laid under the pages between first and last. A template of several pages is refused here.
• templates.end — string, optional. The name of the part holding the template laid under the document's last pages.

Each name refers to a part of the multipart/form-data body, alongside json_data. A name no part carries is refused. Bringing a page in from another document mid-page is a pdf_page item, which draws on the same pool of supplied parts.

A whole request that draws it

Post this as it stands and a PDF comes back. Nothing has been left out of it.

{
  "templates": { "start": "letterhead" },
  "standard_fonts": [{ "name": "sans", "face": "helvetica" }],
  "items": [
    {
      "type": "text",
      "rect": { "llx": 60, "lly": 640, "urx": 535, "ury": 700 },
      "content": ["Dear Madam,\nThank you for your order of 4 August."],
      "font": "sans",
      "font_size": 11,
      "leading": 15
    }
  ]
}

The line that sends it, in three languages

Glossary

byte

The unit a file's weight is counted in, the way a parcel is counted in grams. A thousand of them make a kilobyte, and a million make a megabyte — the size of one photograph taken with a telephone. A one-page PDF here weighs between six thousand and a hundred and twenty thousand, so a hundred of them fit in the space of five photographs.

signature

A seal inside the document that proves two things at once: who approved it, and that not one byte has changed since. A reader shows it as a banner at the top of the page.

request

One call to the service: you send what the document should say, and get the document back. Your bill counts these calls, one for each document. The number of pages inside a document is never counted.

template

A PDF file made once and reused as the background of new pages: your letterhead, a plain sheet for the pages that follow, the page of terms you always attach at the end. The file is laid down exactly as it stands, to the millimetre, and the new text is written on top.

multipart form

A way of packing several things into one call: each gets a name and travels in its own part, and they can be text or files alike. It is what a web page uses to upload a photograph, and what carries a document's description alongside the pictures it draws.

Every word the site explains