GETMethod GET/certificate/{identifier}/download

You get back a PDF file ready to print or to attach to a message: the certificate of authenticity of an item, in your brand's colors, in French or in English.

The full URL is https://api.sealtrust.io/v1/certificate/{identifier}/download. The same endpoint exists without the /v1 prefix, and the /v1 form is the recommended one for a new integration.

On success, the response is the document itself, of type application/pdf, served as an attachment. Write the body of the response into a file. Do not try to read it as text.

The server builds the document on every call and stores it nowhere. Two successive calls can therefore give two different files if the state of the certificate changed in between.

#Authorization

None, public endpoint. It expects neither an API key, nor a session cookie, nor an Authorization header. A server-to-server call is accepted.

#Rate limit

60 calls per 60 second window, counted per calling IP address. Every URL that starts with /certificate shares this counter, and the form /v1/certificate/{identifier}/download counts in the same counter as the form without the prefix.

Under normal conditions, every response carries the headers X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset, the last one giving the reset time in seconds since January 1, 1970. Treat these three headers as optional: read them when they are there, do not make your integration depend on their presence. Going over returns 429 with, in addition, Retry-After, in seconds.

This endpoint consumes no quota of your plan.

#Path and query parameters

#The four forms of the identifier

The server tries the certificate number first. If that leads nowhere, it looks at the shape of the value: 0x followed by 64 hexadecimal characters is treated as an item hash, any other value as a token identifier. A hash is therefore never tried as a token identifier, nor the other way around. As a last resort, the server tries the printed serial number.

The last three forms designate an item. The server then looks for the certificate of that item: the certificate currently valid if there is one, otherwise the most recent one whatever its state.

When it resolves those three forms, the server sets aside items that were destroyed and items withdrawn from the catalog, and answers 404. The certificate number does not go through the item: it finds the certificate row directly, and the document downloads even when the item was destroyed or withdrawn from the catalog.

#The language of the document

fr and en are the two values provided for, in lowercase. A value that starts with neither fr nor en produces a document in English.

#Request body

None. This is a GET request, everything goes through the URL.

#Example request

curl -sS -D - \
  -o certificat.pdf \
  "https://api.sealtrust.io/v1/certificate/ST-CERT-000000000000/download?lang=fr"

import { writeFile } from "node:fs/promises";

const response = await fetch(
  "https://api.sealtrust.io/v1/certificate/ST-CERT-000000000000/download?lang=fr",
);

if (!response.ok) {
  throw new Error(`${response.status} ${await response.text()}`);
}

console.log(response.headers.get("Content-Type"));
console.log(response.headers.get("Content-Disposition"));
console.log(response.headers.get("X-RateLimit-Remaining"));

await writeFile("certificat.pdf", Buffer.from(await response.arrayBuffer()));

import requests

response = requests.get(
    "https://api.sealtrust.io/v1/certificate/ST-CERT-000000000000/download",
    params={"lang": "fr"},
    timeout=60,
)
response.raise_for_status()

print(response.headers["Content-Type"])
print(response.headers["Content-Disposition"])
print(response.headers["X-RateLimit-Remaining"])

with open("certificat.pdf", "wb") as fichier:
    fichier.write(response.content)

#Example response

HTTP code 200. The body is the PDF file.

HTTP/1.1 200 OK
Content-Type: application/pdf
Content-Disposition: attachment; filename="certificate-ST-CERT-000000000000.pdf"
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 59
X-RateLimit-Reset: 1755000060

The file name offered is always certificate- followed by the certificate number, then .pdf. That number can differ from the identifier you sent: if you queried the item by its serial number, the file name carries the number of the certificate found.

#What the document contains

One A4 page. Here is what the server draws on it, from top to bottom, then the border that surrounds the whole page.

The server cuts a value that is too long for its line and ends it with a continuation character. That is the case of the token identifier, which is 77 to 78 digits long. Do not copy a long value from the document, read it from the API.

The document takes up the primary color and the secondary color of your brand. If your brand has filled in no color, the document uses #6386F1 as the primary and #0f172a as the secondary.

The logo and the two colors are the three settings that change the look of the document, and you set them yourself in the administration, tab Settings, then Brand. They apply to the certificate as of the next download. Every paid plan opens this screen. The free trial keeps it closed.

#Errors

The errors, for their part, are JSON. A document starts with %PDF. A body that starts with { signals a refusal. Check the HTTP code before writing the file.

This endpoint has no other refusal code. The lang parameter is never rejected, and the identifier is accepted whatever its shape, even if that means finding nothing.

#See also

• GET /certificate/{identifier}, read the certificate of authenticity of an item.
• GET /resolve/{identifier}, read in one call everything a product page displays.
• Basics, tell model, batch and item apart before ordering a single label.