GETMethod GET/qr/verify

You get an authenticity verdict for an item, from the signed parameters of a verification address, without any API key.

The full address is https://api.sealtrust.io/v1/qr/verify. The same route exists without the /v1 prefix, and the /v1 form is the one recommended for a new integration.

This endpoint replies 200 even when the verdict is negative. A tampered QR code, a QR code that is too old, an item not yet minted: in all three cases the response is a 200 whose valid field is false. The 4xx and 5xx codes are reserved for the cases where no verdict can be returned.

#Authorization

None, public endpoint. It expects no API key, no session cookie, and no Authorization header.

Call it from your server. Our cross-origin sharing policy allows only the public site and the SealTrust console. From a web page hosted on another domain, the browser blocks the response, and the X-RateLimit-Remaining header is never exposed to a page script anyway.

What is authoritative here is the s value. It is the signature that we affixed when producing the verification address. Without it, or with a modified value, the verdict is negative.

#Call limit

30 calls per 60-second window, counted per calling IP address. The limit is shared by all the addresses that start with /qr, and it applies to /qr/verify as well as to /v1/qr/verify.

The responses carry the X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers, the last one giving the reset time in seconds since January 1, 1970. Going over returns 429 with Retry-After in addition, in seconds.

Do not make your code depend on the presence of these headers: read them if they are there, and carry on if they are missing.

This endpoint consumes no quota of your plan.

#Path and query parameters

This endpoint has no path parameter.

latitude and longitude go in pairs. If you send only one of them, it is discarded and the scan is recorded without coordinates.

The response never returns coordinates: at best an area label. The coordinates you send are rounded to 2 decimal places (about 1 km) as soon as they are received, and the label is then the town nearest to that point, found in a table of towns read on our side. When you send no coordinates, the city and the country are deduced from the calling IP address, through a lookup database read on our side; the address of a hosting provider or a data centre gets none. Your IP address is sent to no outside service. If the position of the scan matters to you, send latitude and longitude. These coordinates are not covered by the signature: a grey-market alert never counts them as a GPS position, but as a network location (country_source is client). Otherwise, know that the recorded area will be that of the calling machine's network.

#Request body

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

#Example request

curl -i -G https://api.sealtrust.io/v1/qr/verify \
  --data-urlencode "u=0x0000000000000000000000000000000000000000000000000000000000000000" \
  --data-urlencode "t=1024" \
  --data-urlencode "ts=1755000000" \
  --data-urlencode "c=0x00000000" \
  --data-urlencode "s=0000000000000000000000000000000000000000000000000000000000000000"

// To be run on your server, with Node 18 or newer.
// From a web page on another domain, the browser blocks the response.
const parametres = new URLSearchParams({
  u: "0x0000000000000000000000000000000000000000000000000000000000000000",
  t: "1024",
  ts: "1755000000",
  c: "0x00000000",
  s: "0000000000000000000000000000000000000000000000000000000000000000",
});

const response = await fetch(
  `https://api.sealtrust.io/v1/qr/verify?${parametres.toString()}`,
);

console.log(response.status);
// This header is readable only from a server call, and it can be missing.
console.log(response.headers.get("X-RateLimit-Remaining"));
console.log(await response.json());

import requests

response = requests.get(
    "https://api.sealtrust.io/v1/qr/verify",
    params={
        "u": "0x0000000000000000000000000000000000000000000000000000000000000000",
        "t": "1024",
        "ts": "1755000000",
        "c": "0x00000000",
        "s": "0000000000000000000000000000000000000000000000000000000000000000",
    },
    timeout=30,
)

print(response.status_code)
# This header can be missing, so read it without requiring its presence.
print(response.headers.get("X-RateLimit-Remaining"))
print(response.json())

#Example response

HTTP code 200, positive verdict.

{
  "valid": true,
  "message": "Registered number: the QR signature and the on-chain record match. A QR code can be copied: it does not prove the item in hand is the original.",
  "uid_hash": "0x0000000000000000000000000000000000000000000000000000000000000000",
  "token_id": "1024",
  "product_name": "Sac de voyage Exemple SAS",
  "brand_name": "Exemple SAS",
  "image_url": null,
  "contract_address": "0x0000000000000000000000000000000000000000",
  "scan_area": "Lyon, FR",
  "scan_ref": "dGhpcy1pcy1hbi1leGFtcGxlLXJlZg"
}

Here the item has no cover image, so image_url is null. When it has one, the field carries its public address. The scan_area field is filled in because the call could be located. It is null otherwise.

HTTP code 200 as well when the verdict is negative, and the response does not have the same shape depending on the verdict.

Three negative verdicts are returned before any read on the chain: signature refused, address too old, item not yet minted. These three responses carry only uid_hash, like the two negative verdicts specific to a piece in anchored mode (see the table below).

{
  "valid": false,
  "message": "Invalid QR code signature. This QR code may be tampered with.",
  "uid_hash": "0x0000000000000000000000000000000000000000000000000000000000000000",
  "token_id": null,
  "product_name": null,
  "brand_name": null,
  "image_url": null,
  "contract_address": null,
  "scan_area": null
}

The fourth negative verdict is returned after the read on the chain, when the fingerprint read does not match. This response describes the item, like the positive verdict. Only scan_area stays null, because the area is computed only on a positive verdict.

{
  "valid": false,
  "message": "Unrecognised code: the QR signature or the on-chain record does not match.",
  "uid_hash": "0x0000000000000000000000000000000000000000000000000000000000000000",
  "token_id": "1024",
  "product_name": "Sac de voyage Exemple SAS",
  "brand_name": "Exemple SAS",
  "image_url": null,
  "contract_address": "0x0000000000000000000000000000000000000000",
  "scan_area": null
}

The ten fields of the response.

#The eight possible verdicts

A piece in anchored mode that does not have its token yet is verified by the proof of its lot, not by a token: the positive verdict above is returned to it once the record of its lot is confirmed and its proof checked, with token_id set to null. The root is read on the contract, once per lot, and that result is kept when it matches; if the chain cannot be read, the response is a 503 and no verdict is returned. This verdict counts as a scan, as for any piece, but is not recorded as a token verification. See Pieces registered by lot.

#Errors

#See also

• GET /p/{serial}, translate the printed serial number into the address of a consumer page.
• GET /resolve/{identifier}, read in one call everything a product page displays.
• Physical identification, QR and NFC, choose the physical carrier and the exact form of the GS1 Digital Link.