Article 6 of 8
What the API returns
JSON, always the complete resource, and a stable error code when something blocks.
The responses
- Creating a watch returns the watch, with its
watchId. ThatwatchId(notid) is what you give next to link the card. - Checking a card (
can-link-card) returnscanLinkCardand apassportCheck: the level kept, the missing fields, the serial numbers already registered. - Linking the card returns the passport created, with its card number (
certificateCardId). - Reading a passport returns all its information: the watch, its photos, its level of attestation, its stolen status, its warranty, its owner as you are allowed to see them.
Lists are paginated. Labels follow the language asked for in the accept-language header (English by default).
Finding a passport by your reference
GET /certificates/by-external-ref/{ref} returns the passport created for your reference, the same response as GET /certificates/{certificateCardId}. You only see what you created. The search ignores case and spaces, and a reference that holds / is encoded as %2F.
As long as the card is not linked, the response is 404: GET /watches/by-external-ref/{ref} finds the watch at every step.
The errors
An error returns an HTTP code and, in the body, a stable code (code), a message in the request's language (message) and sometimes details (params). Read the code, not the message, which may change. For example:
| HTTP code | code | What it means |
|---|---|---|
| 422 | PASSPORT_ | Fields are missing: params.missingFields lists them |
| 409 | PASSPORT_ | Another passport of the manufacture has this serial number |
| 403 | PASSPORT_ | This level of attestation is not open to your trade |
| 400 | OWNERSHIP_ | The address declared as owner is a professional's |