Certificates

A common courseware requirement is to produce a stamped certificate for students that have completed material. This generally needs to include custom information about the student and the material being taken, dates and so on. Described below is a system for defining a certificate-creating mechanism that can be stored for the user in your application.

An Example Certificate Data Structure

The following demonstrates many of the potential “stampable” types when building a certificate. POST this to your API endpoint with the following cURL, and then save the ID for the next step.

curl -X POST -H "App-Token: [APP_TOKEN]" -H "Token: [TOKEN]" -H "Content-Type: application/json" -d '
{
    "cert_type": "pdf",
    "output_format": "A4",
    "orientation": "landscape",
    "stampables": [
        {
            "height": null,
            "img": "https://www.google.com/images/srpr/logo11w.png",
            "stamp_type": "image",
            "width": 40,
            "x": null,
            "x_align": "center",
            "x_align_shift": null,
            "x_percent": null,
            "y": null,
            "y_align": null,
            "y_align_shift": null,
            "y_percent": 5
        },
        {
            "height": null,
            "stamp_type": "text",
            "text": "ACCREDITATION COUNCIL FOR",
            "width": null,
            "x": null,
            "x_align": "center",
            "x_align_shift": null,
            "x_percent": null,
            "y": null,
            "y_align": null,
            "y_align_shift": null,
            "y_percent": 31
        },
        {
            "height": null,
            "stamp_type": "text",
            "text": "CONTINUING MEDICAL EDUCATION",
            "width": null,
            "x": null,
            "x_align": "center",
            "x_align_shift": null,
            "x_percent": null,
            "y": null,
            "y_align": null,
            "y_align_shift": null,
            "y_percent": 35
        },
        {
            "font": "Times",
            "font_size": 16,
            "font_style": "I",
            "height": null,
            "stamp_type": "text",
            "text": "This is to certify that",
            "width": null,
            "x": null,
            "x_align": "center",
            "x_align_shift": null,
            "x_percent": null,
            "y": null,
            "y_align": null,
            "y_align_shift": null,
            "y_percent": 44
        },
        {
            "height": null,
            "stamp_type": "text",
            "text": "{{NAME}}, {{DEGREE}}",
            "width": null,
            "x": null,
            "x_align": "center",
            "x_align_shift": null,
            "x_percent": null,
            "y": null,
            "y_align": null,
            "y_align_shift": null,
            "y_percent": 51
        },
        {
            "font": "Times",
            "font_size": 14,
            "font_style": "",
            "height": null,
            "stamp_type": "text",
            "text": "has participated in the enduring material titled {{ACTIVITY}} on {{CURRENT_DATE}}",
            "width": null,
            "x": null,
            "x_align": "center",
            "x_align_shift": null,
            "x_percent": null,
            "y": null,
            "y_align": null,
            "y_align_shift": null,
            "y_percent": 58
        },
        {
            "font": "Times",
            "font_size": 14,
            "font_style": "I",
            "height": null,
            "stamp_type": "text",
            "text": "This meeting has been accredited by the Council for Medical Education and is designated for a maximum of 2 credits",
            "width": null,
            "x": null,
            "x_align": "center",
            "x_align_shift": null,
            "x_percent": null,
            "y": null,
            "y_align": null,
            "y_align_shift": null,
            "y_percent": 66
        },
        {
            "font": "Times",
            "font_size": 10,
            "font_style": "",
            "height": null,
            "stamp_type": "text",
            "text": "Each participant should claim only those hours of credit that have actually been spent in the educational activity.",
            "width": null,
            "x": null,
            "x_align": "center",
            "x_align_shift": null,
            "x_percent": null,
            "y": null,
            "y_align": null,
            "y_align_shift": null,
            "y_percent": 76
        },
        {
            "font": "Times",
            "font_size": 10,
            "font_style": "",
            "height": null,
            "stamp_type": "text",
            "text": "__________________________________________",
            "width": null,
            "x": null,
            "x_align": "center",
            "x_align_shift": 90,
            "x_percent": null,
            "y": null,
            "y_align": null,
            "y_align_shift": null,
            "y_percent": 89
        },
        {
            "font": "Times",
            "font_size": 10,
            "font_style": "",
            "height": null,
            "stamp_type": "text",
            "text": "Doctor Bob, MD",
            "width": null,
            "x": null,
            "x_align": "center",
            "x_align_shift": 90,
            "x_percent": null,
            "y": null,
            "y_align": null,
            "y_align_shift": null,
            "y_percent": 92
        },
        {
            "font": "Times",
            "font_size": 10,
            "font_style": "",
            "height": null,
            "stamp_type": "text",
            "text": "Course Director",
            "width": null,
            "x": null,
            "x_align": "center",
            "x_align_shift": 90,
            "x_percent": null,
            "y": null,
            "y_align": null,
            "y_align_shift": null,
            "y_percent": 94
        }
    ]
}' http://<yoursitehere>.api.enfix.com/api/v1/certificates/

You’ll see the standard POST response:

{"resource_url": "http://<yoursitehere>.api.enfix.com/api/v1/certificates/52e9d26fa64c9e83498dea7d", "_id": "52e9d26fa64c9e83498dea7d"}

Fetching a Certificate

To fetch the base certificate, you’ll want to use the ID from above in the following endpoint:

http://<yoursitehere>.api.enfix.com/api/v1/certificate_generator/52e9d26fa64c9e83498dea7d.pdf

Certificates can be customized via the GET parameters. In the “text” or “img” key on a stampable, anything specified inside double curly braces ({{...}}) is treated as a variable name to populate from the GET. For example:

http://<yoursitehere>.api.enfix.com/api/v1/certificate_generator/52e9d26fa64c9e83498dea7d.pdf?NAME=John%20Thomas&DEGREE=M.D.

Currently Supported Output Formats

At the moment, only PDF is supported. Specify a cert_type of pdf to provide this.

Paper Types

output_format can be one of: A3, A4, A5, Letter, Legal. Defaults to Letter.

orientation is either portrait or landscape. Defaults to landscape.

How Stampable Positioning Works

For each of the x and y coordinate, there are 4 potential positioning factors:

  1. [x/y]. This places the item directly at that coordinate. Be careful that the coordinates are appropriate to the space that you’re working in. PDF coordinate space is not the same as traditional image coordinate space.
  2. [x/y]_percent. Given the width of the entire document, places the left/top edge of the element at that percentage of the document’s dimension appropriate to the coordinate.
  3. [x/y]_align. This places the item in the document with the given alignment. Valid options are:
    • left: Fully left-aligned, very left edge of the document.
    • right: Fully right-aligned, very right edge of the document.
    • center: Centered, measured string put directly in center of document, balanced equal lengths
      on both sides of center.
  4. [x/y]_align_shift. Only works if [x/y]_align is specified. This “nudges” the item from its base positioning, and works appropriately for both negative and positive values, if that does not otherwise violate boundaries. This is best used for things like pushing something off the hard edge of the document’s margins.

Embedding Images

Putting images onto your certificate is just done via a stampable with an img key. An example from above:

{
    "height": null,
    "img": "https://www.google.com/images/srpr/logo11w.png",
    "stamp_type": "image",
    "width": 40,
    "x": null,
    "x_align": "center",
    "x_align_shift": null,
    "x_percent": null,
    "y": null,
    "y_align": null,
    "y_align_shift": null,
    "y_percent": 5
},

Placement rules are the same as for text as described in stampable positioning. The image must reside at a URL accessible from the API server.

Whenever possible, use PNGs for your embedded images. JPEGs do work in some cases, but are more unreliable for the PDF type.

The img tag can take dynamic variables, like in the following:

{
    "height": null,
    "img": "https://www.google.com/images/srpr/logo{{SCORE}}.png",
    "stamp_type": "image",
    "width": 40,
    "x": null,
    "x_align": "center",
    "x_align_shift": null,
    "x_percent": null,
    "y": null,
    "y_align": null,
    "y_align_shift": null,
    "y_percent": 5
},

Send a ?SCORE=... as part of the URL and the img will be resolved with that variable before attempting to fetch.