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. When you send no coordinates, the city and the country of that label are deduced from the calling IP address, through a lookup database read on our side. Your IP address is sent to no outside service. If the position of the scan matters to you, send latitude and longitude. Otherwise, know that the recorded area will be that of the calling machine.

#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": "Authentic product: QR code and blockchain verified.",
  "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"
}

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.

{
  "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": "Invalid product: blockchain verification failed.",
  "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 nine fields of the response.

#The six possible verdicts

#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.