11.10 Reporting exports

Report exports are gated by configuration. If REPORTING_EXPORTS_ENABLED is not true, or neither R2_EXPORTS_ENABLED nor OBJECT_STORAGE_EXPORTS_ENABLED is true, every reporting route returns 503 FEATURE_UNAVAILABLE.

Catalogue codes (REPORT_CATALOGUE): FINANCIAL_TRANSACTIONS, GENERAL_LEDGER, AUDIT_TRAIL, RECONCILIATION, MARKETPLACE_APPLICATIONS, FACILITY_ALLOCATION_UTILIZATION, FACILITY_INSTRUMENT_BALANCES, APPLICATION_PIPELINE, CONDITIONS_PRECEDENT_AGING, PORTFOLIO_PERFORMANCE, GUARANTEE_EXPOSURE, INSURANCE_COVERAGE, WAREHOUSE_INVENTORY, OFFTAKE_DELIVERY_SETTLEMENT, INFRASTRUCTURE_PPP, FACILITY_KPI_PACK, EARLY_WARNING_REGISTER.

GET /api/v1/reporting/jobs

• Purpose. Lists export jobs for the tenant.
• Authentication. Session cookie. MFA enrolment only if the tenant policy requires it. No tenant header (tenant from the account).
• Role. PSA, CSA, PA, SCA, IA, FA, MA, AC, EDV, IV.
• Query. limit (1 to 100, default 25), cursor (UUID).
• Scope. Any read-role member sees all tenant jobs (not limited to the requester). Result rows include parameters.

curl -s "https://dffms.org/api/v1/reporting/jobs?limit=5" \
  -H 'Cookie: __Secure-dffms.session_token=<session-cookie>'

Response (200):

{
  "data": {
    "items": [
      {
        "id": "0190f2c4-6b3e-7a1d-8c2f-000000000100",
        "definitionId": null,
        "status": "SUCCEEDED",
        "parameters": { "reportCode": "FINANCIAL_TRANSACTIONS", "format": "CSV", "fileLabel": "Oct-2026" },
        "sizeBytes": "182736",
        "expiresAt": "2026-10-27T08:00:00.000Z",
        "createdAt": "2026-10-26T08:00:00.000Z",
        "updatedAt": "2026-10-26T08:02:00.000Z"
      }
    ],
    "nextCursor": null
  },
  "error": null,
  "requestId": "<request-id>"
}

Status values: QUEUED, PROCESSING, SUCCEEDED, FAILED, DEAD_LETTER.

Errors: 400 VALIDATION_ERROR, 401 UNAUTHENTICATED, 403 MFA_REQUIRED or FORBIDDEN, 503 FEATURE_UNAVAILABLE, 500 INTERNAL_ERROR.

POST /api/v1/reporting/jobs

• Purpose. Schedules an export. The file is generated asynchronously and stored privately.
• Authentication. Session cookie, Origin, Content-Type: application/json. MFA enrolment is always required for this action. No tenant header.
• Role. PSA, CSA, PA, SCA, IA, FA, MA, AC.
• Body. Strict object.

Field	Type	Required	Rules
reportCode	string	Yes	^[A-Z][A-Z0-9_]{2,63}$ (see catalogue)
format	enum	Yes	CSV, XLSX, PDF
parameters	object	No	Free-form; default {}. Shape depends on the report (not specified in this API)
expectedMaxBytes	integer	No	1 to 50,000,000; default 5,000,000
definitionId	UUID	No	Must be an active report definition in the tenant
notBefore	ISO datetime	No	Within 30 seconds in the past up to 30 days ahead
fileLabel	string	No	^[A-Za-z0-9][A-Za-z0-9 _.-]{0,79}$

curl -s -X POST https://dffms.org/api/v1/reporting/jobs \
  -H 'Cookie: __Secure-dffms.session_token=<session-cookie>' \
  -H 'Origin: https://dffms.org' \
  -H 'Content-Type: application/json' \
  -d '{
    "reportCode": "FINANCIAL_TRANSACTIONS",
    "format": "CSV",
    "parameters": { "from": "2026-10-01", "to": "2026-10-31" },
    "expectedMaxBytes": 2000000,
    "fileLabel": "Oct-2026-transactions"
  }'

Response (202):

{
  "data": {
    "id": "0190f2c4-6b3e-7a1d-8c2f-000000000101",
    "status": "QUEUED",
    "format": "CSV",
    "availableAt": "2026-10-26T08:00:00.000Z",
    "expiresAt": "2026-10-27T08:00:00.000Z",
    "expectedMaxBytes": "2000000"
  },
  "error": null,
  "requestId": "<request-id>"
}

Errors:

HTTP	Code	Meaning
400	VALIDATION_ERROR	Schema error (fields), or reportCode format invalid.
400	INVALID_REPORT	definitionId unavailable, or notBefore outside the allowed window.
401	UNAUTHENTICATED	No session.
403	MFA_REQUIRED / FORBIDDEN	Not enrolled, or role not permitted.
429	LIMIT_REACHED	Active or daily job limit reached.
503	FEATURE_UNAVAILABLE	Exports disabled, policy values invalid, or storage ceiling reached.

Side effects: inserts a QUEUED job with a retention of REPORTING_RETENTION_SECONDS (default 86,400; max 604,800), an outbox report.generate.requested job, and updates aggregate storage counters. The handler writes no audit row. The worker's generation step is not documented here beyond its outbox topic.

GET /api/v1/reporting/jobs/{jobId}/download

• Purpose. Returns a short-lived signed URL for a completed export.
• Authentication. Session cookie. MFA only if tenant policy requires.
• Role. Read roles (as for list).
• Path. jobId: UUID. Invalid UUID: 400.

curl -s https://dffms.org/api/v1/reporting/jobs/0190f2c4-6b3e-7a1d-8c2f-000000000101/download \
  -H 'Cookie: __Secure-dffms.session_token=<session-cookie>'

Response (200):

{
  "data": {
    "url": "https://<private-bucket-host>/<object-key>?<signature-parameters>",
    "expiresAt": "2026-10-26T08:01:00.000Z"
  },
  "error": null,
  "requestId": "<request-id>"
}

• The URL lifetime is REPORTING_SIGNED_URL_SECONDS (default 60; max 300).
• Errors: 400 VALIDATION_ERROR (bad id), 401, 403, 409 NOT_READY, 503 FEATURE_UNAVAILABLE (exports disabled or storage ceiling reached).
• NOT_READY (409) is returned for unknown jobs, jobs in another tenant, jobs not SUCCEEDED, and expired jobs. The response does not distinguish these cases.
• Side effects: none in this handler. No audit row is written by the handler.