{"openapi":"3.1.0","info":{"title":"MayoSynced FBR Digital Invoicing API","version":"1.0.0","description":"Tenant-scoped compliance API. Mutations require Idempotency-Key. PRAL bearer tokens are never exposed."},"servers":[{"url":"/api/v1"}],"paths":{"/reports/sales":{"get":{"summary":"Sales grouped by invoice, buyer, item, month or day; tenant-scoped business sale invoices only","security":[{"ApiKey":[]}],"responses":{"200":{"description":"Successful response"},"400":{"description":"RFC 9457 problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"RFC 9457 problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"413":{"description":"RFC 9457 problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"parameters":[{"name":"view","in":"query","schema":{"enum":["invoice","buyer","item","month","day"]}},{"name":"format","in":"query","schema":{"enum":["json","csv","pdf"]}},{"name":"from","in":"query","schema":{"type":"string"}},{"name":"to","in":"query","schema":{"type":"string"}},{"name":"environment","in":"query","schema":{"type":"string"}},{"name":"state","in":"query","schema":{"type":"string"}},{"name":"buyer","in":"query","schema":{"type":"string"}},{"name":"item","in":"query","schema":{"type":"string"}}]}},"/settings/invoice-branding":{"get":{"summary":"Read company display name, normalized PNG logo and default plain-text payment terms","security":[{"ApiKey":[]}],"responses":{"200":{"description":"Successful response"},"401":{"description":"RFC 9457 problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"RFC 9457 problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"post":{"summary":"Save tenant invoice appearance for new invoice versions; requires settings:write","security":[{"ApiKey":[]}],"responses":{"200":{"description":"Successful response"},"413":{"description":"RFC 9457 problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"RFC 9457 problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"displayName":{"type":"string","maxLength":150},"logoPng":{"type":"string","maxLength":200000,"description":"Base64 PNG or JPEG; normalized and resized to PNG on save"},"terms":{"type":"string","maxLength":1000}}}}}}}},"/invoices/{id}/delivery":{"parameters":[{"$ref":"#/components/parameters/Id"}],"get":{"summary":"Read default customer email and delivery history; secret links are never returned","security":[{"ApiKey":[]}],"responses":{"200":{"description":"Successful response"},"401":{"description":"RFC 9457 problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"RFC 9457 problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"post":{"summary":"Queue an accepted invoice PDF email or revoke a private download link; requires invoices:write","security":[{"ApiKey":[]}],"responses":{"200":{"description":"Successful response"},"404":{"description":"RFC 9457 problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"RFC 9457 problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"413":{"description":"RFC 9457 problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"RFC 9457 problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"RFC 9457 problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"oneOf":[{"type":"object","required":["action","recipient"],"properties":{"action":{"const":"send"},"recipient":{"type":"string","format":"email"},"expiresInDays":{"type":"integer","minimum":1,"maximum":30,"default":7}}},{"type":"object","required":["action","deliveryId"],"properties":{"action":{"const":"revoke"},"deliveryId":{"type":"string","format":"uuid"}}}]}}}}}},"/invoices/complete":{"post":{"summary":"Save or revise an invoice and optionally continue its approval/submission workflow","security":[{"ApiKey":[]}],"responses":{"200":{"description":"Successful response"},"201":{"description":"Successful response"},"409":{"description":"RFC 9457 problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"RFC 9457 problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["intent","invoice"],"properties":{"intent":{"enum":["SAVE","CONTINUE"]},"invoice":{"$ref":"#/components/schemas/InvoiceDraft"},"invoiceId":{"type":"string","format":"uuid"},"workingDraftId":{"type":"string","format":"uuid"},"workingDraftRevision":{"type":"integer","minimum":1}}}}}}}},"/invoices/export":{"get":{"summary":"Download filtered business invoices as Excel-compatible CSV; maximum 10,000 rows","security":[{"ApiKey":[]}],"responses":{"200":{"description":"UTF-8 CSV with formula escaping","content":{"text/csv":{"schema":{"type":"string"}}}},"400":{"description":"RFC 9457 problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"413":{"description":"RFC 9457 problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/working-drafts":{"get":{"summary":"List the signed-in user's unfinished drafts; requires invoices:write","security":[{"Session":[]}],"responses":{"200":{"description":"Successful response"},"401":{"description":"RFC 9457 problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"RFC 9457 problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/working-drafts/{id}":{"parameters":[{"$ref":"#/components/parameters/Id"}],"get":{"summary":"Read a personal working draft","security":[{"Session":[]}],"responses":{"200":{"description":"Successful response"},"401":{"description":"RFC 9457 problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"RFC 9457 problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"put":{"summary":"Save incomplete work using optimistic revision matching; never creates an invoice","security":[{"Session":[]}],"responses":{"200":{"description":"Successful response"},"409":{"description":"RFC 9457 problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"413":{"description":"RFC 9457 problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"RFC 9457 problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["revision","content"],"properties":{"revision":{"type":"integer","minimum":0},"content":{"type":"object","additionalProperties":true}}}}}}},"delete":{"summary":"Discard an owned unfinished working draft","security":[{"Session":[]}],"responses":{"200":{"description":"Successful response"},"401":{"description":"RFC 9457 problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"RFC 9457 problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}]}},"/invoices":{"get":{"summary":"List business invoices, excluding certification tests","security":[{"ApiKey":[]}],"responses":{"200":{"description":"Successful response"},"401":{"description":"RFC 9457 problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"RFC 9457 problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"parameters":[{"name":"q","in":"query","schema":{"type":"string"}},{"name":"state","in":"query","schema":{"type":"string"}},{"name":"environment","in":"query","schema":{"type":"string"}},{"name":"from","in":"query","schema":{"type":"string"}},{"name":"to","in":"query","schema":{"type":"string"}},{"name":"cursor","in":"query","schema":{"type":"string"}},{"name":"page","in":"query","schema":{"type":"integer","minimum":1}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1}}]},"post":{"summary":"Create invoice draft","security":[{"ApiKey":[]}],"responses":{"201":{"description":"Successful response"},"409":{"description":"RFC 9457 problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"RFC 9457 problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"$ref":"#/components/requestBodies/InvoiceDraft"}}},"/invoices/preflight":{"post":{"summary":"Run the authoritative FBR ReadyCheck without saving or transmitting","security":[{"ApiKey":[]}],"responses":{"200":{"description":"Successful response"}},"requestBody":{"$ref":"#/components/requestBodies/InvoiceDraft"}}},"/invoices/batch":{"post":{"summary":"Create 1 to 1,000 invoice drafts with independent per-invoice outcomes","security":[{"ApiKey":[]}],"responses":{"207":{"description":"Successful response"},"409":{"description":"RFC 9457 problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"RFC 9457 problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["invoices"],"properties":{"invoices":{"type":"array","minItems":1,"maxItems":1000,"items":{"$ref":"#/components/schemas/InvoiceDraft"}}}}}}}}},"/invoices/{id}":{"get":{"summary":"Get invoice and submission evidence","security":[{"ApiKey":[]}],"responses":{"200":{"description":"Successful response"},"401":{"description":"RFC 9457 problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"RFC 9457 problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"put":{"summary":"Create a new immutable invoice version","security":[{"ApiKey":[]}],"responses":{"200":{"description":"Successful response"},"409":{"description":"RFC 9457 problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"RFC 9457 problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"parameters":[{"$ref":"#/components/parameters/Id"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"$ref":"#/components/requestBodies/InvoiceDraft"}}},"/invoices/{id}/{action}":{"post":{"summary":"Request approval, approve, reject, validate, or submit","security":[{"ApiKey":[]}],"responses":{"200":{"description":"Successful response"},"202":{"description":"Durable asynchronous operation accepted"},"409":{"description":"RFC 9457 problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"RFC 9457 problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"parameters":[{"$ref":"#/components/parameters/Id"},{"name":"action","in":"path","required":true,"schema":{"enum":["request-approval","approve-direct","approve","reject","validate","submit","approve-submit","validate-submit"]}},{"$ref":"#/components/parameters/IdempotencyKey"}]}},"/customers":{"put":{"summary":"Update or archive a tenant customer; id and complete editable fields required","security":[{"ApiKey":[]}],"responses":{"200":{"description":"Successful response"},"404":{"description":"RFC 9457 problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"RFC 9457 problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"RFC 9457 problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}]},"get":{"summary":"Search customers; status=all includes archived records","security":[{"ApiKey":[]}],"responses":{"200":{"description":"Successful response"},"401":{"description":"RFC 9457 problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"RFC 9457 problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"post":{"summary":"Create customer","security":[{"ApiKey":[]}],"responses":{"201":{"description":"Successful response"},"422":{"description":"RFC 9457 problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}]}},"/products":{"put":{"summary":"Update or archive a tenant product and optional effective tax profile","security":[{"ApiKey":[]}],"responses":{"200":{"description":"Successful response"},"404":{"description":"RFC 9457 problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"RFC 9457 problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"RFC 9457 problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}]},"get":{"summary":"Search products and prices; date=YYYY-MM-DD selects the effective mapping; status=all includes archived records","security":[{"ApiKey":[]}],"responses":{"200":{"description":"Successful response"},"401":{"description":"RFC 9457 problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"RFC 9457 problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"post":{"summary":"Create product and optional tax profile","security":[{"ApiKey":[]}],"responses":{"201":{"description":"Successful response"},"422":{"description":"RFC 9457 problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}]}},"/imports":{"get":{"summary":"List CSV imports","security":[{"ApiKey":[]}],"responses":{"200":{"description":"Successful response"},"401":{"description":"RFC 9457 problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"RFC 9457 problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"post":{"summary":"Stage UTF-8 v2 CSV; invoiceGroup joins lines into one invoice and blank groups retain v1 row behavior","security":[{"ApiKey":[]}],"responses":{"202":{"description":"Successful response"},"413":{"description":"RFC 9457 problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"RFC 9457 problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}]}},"/imports/{id}":{"get":{"summary":"Get staged import rows","security":[{"ApiKey":[]}],"responses":{"200":{"description":"Successful response"},"401":{"description":"RFC 9457 problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"RFC 9457 problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"post":{"summary":"Promote/resume valid rows, retry promotion failures, or cancel the remainder","security":[{"ApiKey":[]}],"responses":{"200":{"description":"Successful response"},"409":{"description":"RFC 9457 problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"parameters":[{"$ref":"#/components/parameters/Id"},{"$ref":"#/components/parameters/IdempotencyKey"}]}},"/imports/template.csv":{"get":{"summary":"Download the versioned CSV template","security":[{"ApiKey":[]}],"responses":{"200":{"description":"Successful response"},"401":{"description":"RFC 9457 problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"RFC 9457 problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/imports/{id}/errors.csv":{"get":{"summary":"Download row and field errors as CSV","security":[{"ApiKey":[]}],"responses":{"200":{"description":"Successful response"},"401":{"description":"RFC 9457 problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"RFC 9457 problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/imports/{id}/report.csv":{"get":{"summary":"Download complete per-row import status report","security":[{"ApiKey":[]}],"responses":{"200":{"description":"Successful response"},"401":{"description":"RFC 9457 problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"RFC 9457 problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/reference-data":{"get":{"summary":"Search retained PRAL reference data","security":[{"ApiKey":[]}],"responses":{"200":{"description":"Successful response"},"401":{"description":"RFC 9457 problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"RFC 9457 problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"post":{"summary":"Queue PRAL reference synchronization","security":[{"ApiKey":[]}],"responses":{"202":{"description":"Durable asynchronous operation accepted"},"409":{"description":"RFC 9457 problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}]}},"/reference-data/{id}":{"get":{"summary":"Read a PRAL reference synchronization status","security":[{"ApiKey":[]}],"responses":{"200":{"description":"Successful response"},"401":{"description":"RFC 9457 problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"RFC 9457 problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"parameters":[{"$ref":"#/components/parameters/Id"}]}},"/registration-checks":{"get":{"summary":"List retained registration checks","security":[{"ApiKey":[]}],"responses":{"200":{"description":"Successful response"},"401":{"description":"RFC 9457 problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"RFC 9457 problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"post":{"summary":"Queue STATL/registration-type checks","security":[{"ApiKey":[]}],"responses":{"202":{"description":"Durable asynchronous operation accepted"},"409":{"description":"RFC 9457 problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}]}},"/corrections":{"get":{"summary":"List linked correction cases","security":[{"ApiKey":[]}],"responses":{"200":{"description":"Successful response"},"401":{"description":"RFC 9457 problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"RFC 9457 problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"post":{"summary":"Create correction/debit-note case","security":[{"ApiKey":[]}],"responses":{"201":{"description":"Successful response"},"409":{"description":"RFC 9457 problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"RFC 9457 problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}]}},"/outages":{"get":{"summary":"List interruption incidents","security":[{"ApiKey":[]}],"responses":{"200":{"description":"Successful response"},"401":{"description":"RFC 9457 problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"RFC 9457 problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"post":{"summary":"Start, restore, or report an incident","security":[{"ApiKey":[]}],"responses":{"200":{"description":"Successful response"},"201":{"description":"Successful response"},"409":{"description":"RFC 9457 problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"RFC 9457 problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}]}},"/outages/{id}/report":{"get":{"summary":"Download the retained incident report PDF","security":[{"ApiKey":[]}],"responses":{"200":{"description":"Successful response"},"401":{"description":"RFC 9457 problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"RFC 9457 problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"parameters":[{"$ref":"#/components/parameters/Id"}]}},"/invoices/{id}/offline":{"post":{"summary":"Issue or queue an offline invoice","security":[{"ApiKey":[]}],"responses":{"200":{"description":"Successful response"},"202":{"description":"Durable asynchronous operation accepted"},"409":{"description":"RFC 9457 problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"parameters":[{"$ref":"#/components/parameters/Id"},{"$ref":"#/components/parameters/IdempotencyKey"}]}},"/invoices/{id}/reconciliation":{"post":{"summary":"Resolve an ambiguous PRAL POST with human evidence","security":[{"ApiKey":[]}],"responses":{"200":{"description":"Successful response"},"409":{"description":"RFC 9457 problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"RFC 9457 problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"parameters":[{"$ref":"#/components/parameters/Id"},{"$ref":"#/components/parameters/IdempotencyKey"}]}},"/reconciliations":{"get":{"summary":"List FBR dashboard reconciliation runs","security":[{"ApiKey":[]}],"responses":{"200":{"description":"Successful response"},"401":{"description":"RFC 9457 problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"RFC 9457 problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"post":{"summary":"Import an FBR dashboard reconciliation export","security":[{"ApiKey":[]}],"responses":{"201":{"description":"Successful response"},"422":{"description":"RFC 9457 problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}]}},"/closings":{"get":{"summary":"List immutable closing snapshots","security":[{"ApiKey":[]}],"responses":{"200":{"description":"Successful response"},"401":{"description":"RFC 9457 problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"RFC 9457 problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"post":{"summary":"Create a daily, weekly, monthly, quarterly, or tax-period closing","security":[{"ApiKey":[]}],"responses":{"201":{"description":"Successful response"},"422":{"description":"RFC 9457 problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}]}},"/certification-runs":{"get":{"summary":"List official sandbox certification runs","security":[{"ApiKey":[]}],"responses":{"200":{"description":"Successful response"},"401":{"description":"RFC 9457 problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"RFC 9457 problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"post":{"summary":"Queue a sandbox scenario test without creating an organization invoice","security":[{"ApiKey":[]}],"responses":{"202":{"description":"Durable asynchronous operation accepted"},"409":{"description":"RFC 9457 problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"RFC 9457 problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}]}},"/certification-runs/{id}":{"get":{"summary":"Download retained sandbox test request and responses","security":[{"ApiKey":[]}],"responses":{"200":{"description":"Successful response"},"401":{"description":"RFC 9457 problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"RFC 9457 problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"post":{"summary":"Review an uncertain sandbox result and allow a new test without marking a pass","security":[{"ApiKey":[]}],"responses":{"200":{"description":"Durable asynchronous operation accepted"},"409":{"description":"RFC 9457 problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"RFC 9457 problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}]}},"/certification-templates/{scenarioId}":{"get":{"summary":"Download a built-in seller-specific sandbox scenario JSON","security":[{"ApiKey":[]}],"responses":{"200":{"description":"Successful response"},"401":{"description":"RFC 9457 problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"RFC 9457 problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"post":{"summary":"Prepare current FBR references for a built-in sandbox scenario","security":[{"ApiKey":[]}],"responses":{"202":{"description":"Durable asynchronous operation accepted"},"409":{"description":"RFC 9457 problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"RFC 9457 problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"parameters":[{"name":"scenarioId","in":"path","required":true,"schema":{"type":"string","pattern":"^SN(?:00[1-9]|01[0-9]|02[0-8])$"}},{"$ref":"#/components/parameters/IdempotencyKey"}]}},"/documents":{"get":{"summary":"List retained compliance evidence","security":[{"ApiKey":[]}],"responses":{"200":{"description":"Successful response"},"401":{"description":"RFC 9457 problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"RFC 9457 problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"post":{"summary":"Upload signature-checked and malware-scanned compliance evidence","security":[{"ApiKey":[]}],"responses":{"201":{"description":"Successful response"},"413":{"description":"RFC 9457 problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"415":{"description":"RFC 9457 problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"RFC 9457 problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/documents/{id}":{"get":{"summary":"Download evidence after content-hash verification","security":[{"ApiKey":[]}],"responses":{"200":{"description":"Successful response"},"401":{"description":"RFC 9457 problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"RFC 9457 problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"parameters":[{"$ref":"#/components/parameters/Id"}]}},"/onboarding":{"get":{"summary":"Read onboarding state","security":[{"ApiKey":[]}],"responses":{"200":{"description":"Successful response"},"401":{"description":"RFC 9457 problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"RFC 9457 problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"post":{"summary":"Configure seller, branches, scenarios, and fixed egress evidence","security":[{"ApiKey":[]}],"responses":{"200":{"description":"Successful response"},"201":{"description":"Successful response"},"422":{"description":"RFC 9457 problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}]}},"/production-readiness":{"get":{"summary":"Read all fail-closed production gates","security":[{"ApiKey":[]}],"responses":{"200":{"description":"Successful response"},"401":{"description":"RFC 9457 problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"RFC 9457 problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"post":{"summary":"Record/revoke official evidence or activate production","security":[{"ApiKey":[]}],"responses":{"200":{"description":"Successful response"},"409":{"description":"RFC 9457 problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"RFC 9457 problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}]}},"/team":{"get":{"summary":"List memberships and invitations","security":[{"ApiKey":[]}],"responses":{"200":{"description":"Successful response"},"401":{"description":"RFC 9457 problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"RFC 9457 problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"post":{"summary":"Invite, suspend, reactivate, revoke, or transfer ownership","security":[{"ApiKey":[]}],"responses":{"200":{"description":"Successful response"},"201":{"description":"Successful response"},"409":{"description":"RFC 9457 problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"RFC 9457 problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}]}},"/support-grants":{"get":{"summary":"List audited time-limited support grants","security":[{"ApiKey":[]}],"responses":{"200":{"description":"Successful response"},"401":{"description":"RFC 9457 problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"RFC 9457 problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"post":{"summary":"Grant or revoke allowlisted read-only platform support","security":[{"ApiKey":[]}],"responses":{"200":{"description":"Successful response"},"422":{"description":"RFC 9457 problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}]}},"/webhooks":{"get":{"summary":"List webhook endpoints","security":[{"ApiKey":[]}],"responses":{"200":{"description":"Successful response"},"401":{"description":"RFC 9457 problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"RFC 9457 problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"post":{"summary":"Register HMAC-signed webhook","security":[{"ApiKey":[]}],"responses":{"201":{"description":"Successful response"},"422":{"description":"RFC 9457 problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}]}},"/api-keys":{"get":{"summary":"List API-key metadata","security":[{"ApiKey":[]}],"responses":{"200":{"description":"Successful response"},"401":{"description":"RFC 9457 problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"RFC 9457 problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"post":{"summary":"Create one-time API key","security":[{"ApiKey":[]}],"responses":{"201":{"description":"Successful response"},"422":{"description":"RFC 9457 problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}]}},"/webhooks/{id}":{"delete":{"summary":"Disable a webhook endpoint","security":[{"ApiKey":[]}],"responses":{"200":{"description":"Successful response"},"401":{"description":"RFC 9457 problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"RFC 9457 problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"parameters":[{"$ref":"#/components/parameters/Id"},{"$ref":"#/components/parameters/IdempotencyKey"}]}},"/api-keys/{id}":{"delete":{"summary":"Revoke an API key","security":[{"ApiKey":[]}],"responses":{"200":{"description":"Successful response"},"401":{"description":"RFC 9457 problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"RFC 9457 problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"parameters":[{"$ref":"#/components/parameters/Id"},{"$ref":"#/components/parameters/IdempotencyKey"}]}},"/settings/environment":{"put":{"summary":"Switch the organization workspace environment; user settings permission required; retained invoice versions and queued work remain unchanged","security":[{"ApiKey":[]}],"responses":{"200":{"description":"Successful response"},"401":{"description":"RFC 9457 problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"RFC 9457 problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["environment"],"properties":{"environment":{"enum":["sandbox","production"]}}}}}}}},"/metrics":{"get":{"summary":"Read tenant operational metrics","security":[{"ApiKey":[]}],"responses":{"200":{"description":"Successful response"},"401":{"description":"RFC 9457 problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"RFC 9457 problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}}},"components":{"securitySchemes":{"Session":{"type":"apiKey","in":"cookie","name":"mayo_session","description":"Signed-in session; send X-Tenant-Id or the active_tenant cookie. Mutations require the same-origin Origin header."},"ApiKey":{"type":"http","scheme":"bearer","bearerFormat":"mayo_<prefix>.<secret>"}},"parameters":{"Id":{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},"IdempotencyKey":{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":200}}},"requestBodies":{"InvoiceDraft":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvoiceDraft"}}}}},"schemas":{"Problem":{"type":"object","required":["type","title","status","detail"],"properties":{"type":{"type":"string","format":"uri-reference"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"}}},"InvoiceDraft":{"type":"object","additionalProperties":false,"required":["documentType","invoiceDate","branchId","sellerNTNCNIC","sellerBusinessName","sellerProvince","sellerAddress","buyerNTNCNIC","buyerBusinessName","buyerProvince","buyerAddress","buyerRegistrationType","invoiceRefNo","items"],"properties":{"purchaseOrder":{"type":"string","maxLength":100},"deliveryChallan":{"type":"string","maxLength":100},"notes":{"type":"string","maxLength":4000},"paymentTerms":{"type":"string","maxLength":1000},"dueDate":{"type":"string","format":"date"},"environment":{"enum":["sandbox","production"],"description":"Omit to inherit FBR setup. An explicit conflicting environment is rejected."},"documentType":{"enum":["SALE_INVOICE","DEBIT_NOTE","CREDIT_NOTE"]},"invoiceDate":{"type":"string","format":"date"},"branchId":{"type":"string","format":"uuid"},"customerId":{"type":"string","format":"uuid"},"externalKey":{"type":"string","maxLength":150},"scenarioId":{"type":"string","pattern":"^SN(?:00[1-9]|01[0-9]|02[0-8])$"},"sellerNTNCNIC":{"type":"string"},"sellerBusinessName":{"type":"string"},"sellerProvince":{"type":"string"},"sellerAddress":{"type":"string"},"buyerNTNCNIC":{"type":"string"},"buyerBusinessName":{"type":"string"},"buyerProvince":{"type":"string"},"buyerAddress":{"type":"string"},"buyerRegistrationType":{"enum":["Registered","Unregistered"]},"invoiceRefNo":{"type":"string"},"items":{"type":"array","minItems":1,"maxItems":1000,"items":{"$ref":"#/components/schemas/InvoiceItem"}},"overrides":{"type":"array","items":{"$ref":"#/components/schemas/Override"}}}},"InvoiceItem":{"type":"object","additionalProperties":false,"required":["hsCode","productDescription","rate","uoM","quantity","valueSalesExcludingST","fixedNotifiedValueOrRetailPrice","salesTaxApplicable","salesTaxWithheldAtSource","extraTax","furtherTax","sroScheduleNo","fedPayable","discount","saleType","sroItemSerialNo"],"properties":{"unitConversion":{"type":"object","required":["unit","quantity","factor","price"],"properties":{"unit":{"type":"string","maxLength":100},"quantity":{"type":"string"},"factor":{"type":"string"},"price":{"type":"string"}},"description":"Commercial unit metadata. quantity times factor must equal the FBR quantity exactly at four decimals; quantity times price must match the pre-tax amount at two decimals. Cannot be combined with unitPrice."},"unitPrice":{"type":"string","description":"Optional nonnegative price before tax; quantity times price must match the line value after rounding to two decimals."},"hsCode":{"type":"string"},"productDescription":{"type":"string"},"rate":{"type":"string"},"uoM":{"type":"string"},"quantity":{"type":"string","pattern":"^\\d+(?:\\.\\d{1,6})?$"},"valueSalesExcludingST":{"type":"string","pattern":"^\\d+(?:\\.\\d{1,6})?$"},"fixedNotifiedValueOrRetailPrice":{"type":"string","pattern":"^\\d+(?:\\.\\d{1,6})?$"},"salesTaxApplicable":{"type":"string","pattern":"^\\d+(?:\\.\\d{1,6})?$"},"salesTaxWithheldAtSource":{"type":"string","pattern":"^\\d+(?:\\.\\d{1,6})?$"},"extraTax":{"type":"string","pattern":"^\\d+(?:\\.\\d{1,6})?$"},"furtherTax":{"type":"string","pattern":"^\\d+(?:\\.\\d{1,6})?$"},"sroScheduleNo":{"type":"string"},"fedPayable":{"type":"string","pattern":"^\\d+(?:\\.\\d{1,6})?$"},"discount":{"type":"string","pattern":"^\\d+(?:\\.\\d{1,6})?$"},"saleType":{"type":"string"},"sroItemSerialNo":{"type":"string"}}},"Override":{"type":"object","required":["fieldPath","overrideValue","reasonCode","explanation"],"properties":{"fieldPath":{"type":"string"},"overrideValue":{"type":"string"},"reasonCode":{"type":"string"},"explanation":{"type":"string","minLength":10},"attachmentId":{"type":"string","format":"uuid"}}}}}}