PassportCraft

Use this when a person asks about the product passports, DPPs or battery passports in their PassportCraft workspace: which exist, which are drafts and which are published. List the product passports in this workspace. Filter by status and by category. Trashed passports are left out unless you ask for that status by name. The answer is ONE PAGE, not the whole set. If `has_more` is true, follow `next_cursor` to the end before you tell anyone that something is not there. Narrow with `category` or `status` before you walk it: every row carries the whole product, so paging a large catalogue to answer one question is slow for the person waiting.

list_passports

List the barcode, size and colour rows on a textile or general passport. The answer is ONE PAGE, not the whole set. If `has_more` is true, follow `next_cursor` to the end before you tell anyone that something is not there. Pass gtin to find one exact customer-supplied barcode. This establishes current state; an earlier add response does not.

list_variants

List the documents attached to a passport. The answer is ONE PAGE, not the whole set. If `has_more` is true, follow `next_cursor` to the end before you tell anyone that something is not there.

list_documents

List the files already in the workspace library, across all products. Check this BEFORE sending a file: one declaration of conformity usually covers a whole product family, so if it is already here, attach the existing file with attach_document rather than sending it again. Every copy you send spends one of the workspace’s file slots. They are managed in the document library — every file in this answer carries `library_url`, which opens it. Give that address to the person. The answer is ONE PAGE, not the whole set. If `has_more` is true, follow `next_cursor` to the end before you tell anyone that something is not there. That matters most here: deciding a file is absent from one page is what produces the duplicate this tool exists to prevent.

list_library

List the individual units recorded against a battery model passport. The answer is ONE PAGE, not the whole set. If `has_more` is true, follow `next_cursor` to the end before you tell anyone that something is not there. A model may carry thousands of serials, so DO NOT page looking for one: to check whether a single serial is recorded, pass `unit_serial` and let the route find it in one call. Each unit carries `qr_target`: exactly what that battery's printed QR code encodes. Each battery gets its own code. Hand over each battery's `qr_target`, never the passport's address, as the code to print on it.

list_units

Propose changes to a passport that is already public. Nothing on the public page changes until a person approves the whole proposal in PassportCraft. Hand them the review_url this returns, and tell them what you changed and why. Send the fields to change in the shape update_passport takes; send a number together with its unit. To change the file behind a field, set <field>__document_id to a document already in the library (list_library). The file must already have the field’s access level; only a person uploads files or changes their level. You cannot propose a barcode, a serial number or a custom field. A new proposal replaces the one already waiting on this passport. If the person tells you no, use withdraw_proposal. Keep the proposal_id.

propose_changes

Send a file you were given — a supplier declaration, a specification sheet, a photograph of a care label — into the workspace library and attach it to a DRAFT passport, in one step. Put the bytes in `content_base64`. READ THIS BEFORE SENDING ANYTHING. You do not transfer this file — you TYPE it, character by character, as part of this call. MEASURED ON A REAL CONNECTION: about 22 bytes of file a second. A 15 KB photograph took eight minutes. 30 KB takes over twenty. 1 MB would take half a day. The 3 MB the server would accept is unreachable through this door, and a smaller limit would not help — the RATE is the cost, not the size. SO THE PERSON UPLOADS IT, NOT YOU, FOR EVERYTHING EXCEPT A SMALL PICTURE. They already have the file. A passport you read ON ITS OWN carries `add_photo_url` and `add_document_url` — give them the one that fits. A passport in a LIST does not carry them, because nobody adds a file to a hundred products at once: read that one passport and the addresses come with it. DO NOT BUILD EITHER ADDRESS YOURSELF: they open the right part of the editor, and an address you assemble opens the wrong one. Each takes about 4 MB, re-encodes nothing, and is done in seconds. Name the file you mean. That is the FIRST thing to offer, not the fallback. IF YOU DO SEND IT YOURSELF, SAY SO FIRST AND SAY HOW LONG. A person watching a chat sit still for eight minutes cannot tell working from broken, and several have assumed it was broken. Tell them roughly how long it will take and let them choose the faster way. AIM FOR UNDER 30 KB, and treat that as the number to act on rather than as a preference. A photograph at about 640 pixels on its longest edge, saved as JPEG at quality 70, lands under 30 KB for ordinary product shots and at about 47 KB for a densely detailed one — measured. Check the size ONCE. If it is over 30 KB, halve the longest edge and send that without checking again. Do not hunt for the smallest possible file; the search costs more time than the bytes it saves. This copy is a working image, not the one a public page deserves — when a brand wants a good photograph on the published product, a person uploads it in the app at full size. NEVER re-encode anything a person will need to READ — a supplier declaration, a specification sheet, a photograph of a care label. Shrinking those destroys the small print, and what we store is meant to be the evidence they can open later, not a copy we degraded. Send such a file as it came; if it is too large for this channel, do not send a worse version — a person can add it themselves in the editor, where the limit is about 4 MB and nothing is re-encoded. Give them this passport’s `add_document_url`, and say which file you mean. If you DO re-encode a photograph, say `image/jpeg`, or the upload is refused for not being the type it claims; naming the file `.jpg` as well is a courtesy to whoever reads the library later. A PICTURE INSIDE A FILE THEY GAVE YOU — a product photograph printed in a datasheet — is worth OFFERING, because they have the datasheet and do not have the picture. This is the ONE exception to never re-encoding a specification sheet, and it is narrow: you are taking the photograph out of it, not shrinking the sheet. The sheet itself still goes as it came, or not at all. Offer it; do not do it unasked. If they say yes, send it yourself with this tool, so it is recorded as yours and named to whoever publishes. Do NOT hand it to them to upload: a file a person uploads is taken as theirs, and this one is not. Send ONLY the picture itself, cropped to it — never a whole page. A page of a datasheet is a page of small print, and shrinking that to fit destroys the thing that makes it worth keeping, which the rule above forbids. Send it as `type: image`, or it is filed as paperwork and nobody finds it among the photos. Say where it came from and do not present it as the manufacturer’s own photograph — pulling a picture out of a document often redraws it rather than copying it, so it can differ from the original in ways neither of you can see. And say what it is FOR: a working image so the draft is not empty. It is small, because you had to type it. TELL THEM TWO THINGS ABOUT IT. First, it becomes the product’s picture in the grid view of their product list, until they pick another one — the photos section of the editor has a chooser. Second, it stays restricted, so nobody outside their workspace sees it and it is not on the public product page. Leave it that way and let them replace it; the visibility rule further down says restricted files stay off the public page. PDF, PNG, JPEG and WebP only, and the content must really be that type. The file is stored as RESTRICTED. Publishing the passport does not change that: a restricted file is never shown on the public product page, and it cannot yet answer a passport field that expects a public document, such as a declaration of conformity. The same is true of a product photograph: it stays out of the public page until someone raises it. To use a file either way, a person has to raise that file’s visibility in the document library — so tell them, and give them the `library_url` this tool returns, which opens that library. It lists every file, so name the file you sent as well as the address. THIS DOES NOT APPLY TO A PICTURE YOU TOOK OUT OF ONE OF THEIR DOCUMENTS. That one stays restricted: it is a placeholder you made, not a file they asked you to store, and putting it on the public page would show a shopper an image a model produced. Attaching to a passport the public can already see is refused. Sending a file withdraws any request to publish that is waiting on this passport, and the person has to be asked again — the withdrawal is decided early, before the file is stored, so a failure from this tool does NOT mean it did not happen. A call this tool refuses on its own, before it sends anything, withdraws nothing; a refusal that comes back FROM PassportCraft may still have withdrawn it. If this call fails, do not assume the request survived: some failures happen after it is already withdrawn. If you hold its approval_id, check with get_publish_approval; if you do not, say you cannot tell, and ask the person to look at their own list.

upload_document

Read the dated values recorded for one battery, including their source and evidence reference. Returns one page; use next_cursor while has_more is true. Pass field to read the history of one value. Model declarations and model-value fallbacks are current values, not historical readings; use list_units for those.

list_unit_readings

Record serial-numbered units against a battery model passport. A unit status must be one the regulation names; free text is refused and the refusal lists what is allowed. Asking twice for the same batch does not record it twice, and a repeat is not a failure. If these serial numbers are already on this battery model, the answer says so and they are on file — tell the person that, rather than that the recording failed. IF A CALL FAILS AND YOU TRY AGAIN, SEND EXACTLY THE SAME ARGUMENTS — the same serial numbers, in the same order, with the same statuses. Changing any of it makes it a different request. New units come back with `qr_target`, exactly what that battery's printed QR code encodes; `list_units` gives it for every unit.

create_unit

Withdraw a proposal that is still waiting, when the person tells you they do not want it. It leaves their list at once. Withdrawing one that is no longer waiting changes nothing and tells you its state.

withdraw_proposal