5.9.2.3 Farmer Documents
The Farmer Documents domain of grant. The documents a farmer uploads from a call's check (fascicolo aziendale, visura camerale, registro BDN, report ClassyFarm), private to the research and read by a worker into typed facts with their citations; the farmer sees every fact, can dispute one, and the requirements of a call are evaluated against the facts (req 215 to 218). Uploads go straight to the private bucket through a resumable session; nothing starts a model call from the web app. It is one API, with its own contract and its own version.
5.9.2.3.1 Versions¶
| Version | Status | Prod URL | Contract |
|---|---|---|---|
v1 |
Proposed | https://grant.moonitoring.com/documents/v1 |
documents/v1/openapi.yaml |
The data model has no entities for this domain yet; its schemas are part of the proposal. Follows req 215 to 218. FarmFact rows are stored inside the document's extraction in the MVP and modelled as rows here, as the requirements say. The capabilities grant.documents.manage and grant.checks.run apply through the research's Farm Organization (D21); a guest passes without one.
5.9.2.3.2 Operations¶
Every operation names who calls it and the capability it checks (x-moonitoring-audience, x-moonitoring-capability in the contract); every capability is in the catalog of the data model (req 1002, 1006). Lists are paged by cursor, writes that create something carry an Idempotency-Key, errors are Problem Details.
| Operation | Request | Who | Capability |
|---|---|---|---|
| List my documents | GET /documents |
Organization users, staff or clients | grant.documents.manage |
| Announce an upload | POST /documents |
Organization users, staff or clients | grant.documents.manage |
| Finalize an upload | POST /documents/{document_id}/finalize |
Organization users, staff or clients | grant.documents.manage |
| Retry a reading | POST /documents/{document_id}/retry |
Organization users, staff or clients | grant.documents.manage |
| Read a document | GET /documents/{document_id} |
Organization users, staff or clients | grant.documents.manage |
| Delete a document | DELETE /documents/{document_id} |
Organization users, staff or clients | grant.documents.manage |
| Download my document | POST /documents/{document_id}/download-url |
Organization users, staff or clients | grant.documents.manage |
| List the facts read from a document | GET /documents/{document_id}/facts |
Organization users, staff or clients | grant.documents.manage |
| Dispute a fact | POST /facts/{fact_id}/dispute |
Organization users, staff or clients | grant.documents.manage |
| Read my document profile | GET /profile |
Organization users, staff or clients | grant.documents.manage |
| Read the check of a call | GET /checks/{call_id} |
Organization users, staff or clients | grant.checks.run, entitlement grant.checks |
| List my checks | GET /checks |
Organization users, staff or clients | grant.checks.run, entitlement grant.checks |
| List every farmer document | GET /operator/documents |
Staff | grant.documents.read_all |
| Recover a failed reading | POST /operator/documents/{document_id}/recover |
Staff | grant.sources.manage |
| Pause or resume document processing | POST /operator/processing |
Staff | grant.sources.manage |
5.9.2.3.3 Contract v1¶
Proposed version
v1 is a proposal for review: its endpoints, errors and capabilities were designed from the requirements and the flows and are not confirmed. It leaves proposal with its first release; from then on it changes only as described in Every API Is Versioned.