List period dates and status
Draft contract · no live API. Generated from OpenAPI 3.1.1, version 1.0.0-draft.
Download the exact YAML. SHA-256: edb36682e0c124e1a67cfc6213ed93dcfa2494e84c63f79181ae7ed12f9851e7.
GET /api/v1/companies/{companyId}/ledger/periods
Section titled “GET /api/v1/companies/{companyId}/ledger/periods”Operation ID: listLedgerPeriods
DRAFT pending owner decision. Revalidate live authority on each page; safe projection only. Stable order (startDate,periodNumber,id). Return periods overlapping inclusive [from,to], to >= from and span <=366 days. No custom sort or other filters.
Authorization
Section titled “Authorization”Alternatives below are OR choices; scopes within each choice are required together.
[ { "DelegatedOAuth": [ "ledger.periods:read" ] }, { "MachineOAuth": [ "ledger.periods:read" ] }]Ownership and limits
Section titled “Ownership and limits”{ "x-domain-owner": "Ledger", "x-permissions": [ "ledger.coa.view" ], "x-modules": [ "ledger" ], "x-data-classification": "Tenant-confidential safe business projection", "x-audit-class": "api.read", "x-limits": { "requestsPerMinute": 300, "burst": 30, "concurrency": 10 }}Parameters
Section titled “Parameters”companyId
Section titled “companyId”path · required
Company must belong to token tenant and current installation/principal scope. Inaccessible and absent companies return indistinguishable 404.
{ "type": "string", "format": "uuid"}query · optional
Page size, default 50/max 200; unknown query fields rejected.
{ "type": "integer", "minimum": 1, "maximum": 200, "default": 50}cursor
Section titled “cursor”query · optional
Opaque cursor from prior page. Repeat the same limit and filters; tampering or changed filters is 400 INVALID_CURSOR; expired snapshot is 409 CURSOR_EXPIRED.
{ "type": "string", "minLength": 1, "maxLength": 2048}query · required
Inclusive business date bound. At most 366 days per query.
{ "type": "string", "format": "date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$"}Example:
"2026-11-01"query · required
Inclusive business date bound. At most 366 days per query.
{ "type": "string", "format": "date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$"}Example:
"2026-11-30"Responses
Section titled “Responses”Current authorized snapshot page.
Content type: application/json
{ "$ref": "#/components/schemas/PeriodsPage"}200 LK example
Section titled “200 LK example”LK synthetic fixture; no real company or tax assertion
{ "items": [ { "id": "12000000-0000-4000-8000-000000000001", "companyId": "10000000-0000-4000-8000-000000000001", "fiscalYearId": "13000000-0000-4000-8000-000000000001", "periodNumber": 8, "startDate": "2026-11-01", "endDate": "2026-11-30", "state": "OPEN" } ], "nextCursor": null, "asOf": "2026-11-06T08:00:00Z"}200 SG example
Section titled “200 SG example”SG synthetic fixture; no real company or tax assertion
{ "items": [ { "id": "22000000-0000-4000-8000-000000000001", "companyId": "20000000-0000-4000-8000-000000000001", "fiscalYearId": "23000000-0000-4000-8000-000000000001", "periodNumber": 11, "startDate": "2026-11-01", "endDate": "2026-11-30", "state": "OPEN" } ], "nextCursor": null, "asOf": "2026-11-06T08:00:00Z"}Response headers:
{ "X-Request-Id": { "description": "Server-generated UUID correlation ID. New per HTTP attempt, including idempotent replay.", "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "description": "No shared or private response caching.", "schema": { "type": "string", "const": "no-store" } }, "X-RateLimit-Limit": { "description": "Proposed custom quota header: current caller bucket capacity per 60-second window; no other tenant usage.", "schema": { "type": "integer", "minimum": 1 } }, "X-RateLimit-Remaining": { "description": "Remaining requests in current caller bucket.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Seconds until this caller bucket resets.", "schema": { "type": "integer", "minimum": 0 } }}Malformed request, unknown fields, invalid cursor, conflicting tenant/company headers or missing/invalid Idempotency-Key.
Content type: application/problem+json
{ "$ref": "#/components/schemas/Problem"}Example:
{ "type": "urn:ginum:problem:invalid-request", "title": "Invalid request", "status": 400, "code": "INVALID_REQUEST", "requestId": "90000000-0000-4000-8000-000000000001", "retryable": false, "instance": "urn:uuid:90000000-0000-4000-8000-000000000001"}Response headers:
{ "X-Request-Id": { "description": "Server-generated UUID correlation ID. New per HTTP attempt, including idempotent replay.", "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "description": "No shared or private response caching.", "schema": { "type": "string", "const": "no-store" } }, "X-RateLimit-Limit": { "description": "Proposed custom quota header: current caller bucket capacity per 60-second window; no other tenant usage.", "schema": { "type": "integer", "minimum": 1 } }, "X-RateLimit-Remaining": { "description": "Remaining requests in current caller bucket.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Seconds until this caller bucket resets.", "schema": { "type": "integer", "minimum": 0 } }}Missing/expired/invalid/wrong issuer or audience token; ID tokens are not API credentials.
Content type: application/problem+json
{ "$ref": "#/components/schemas/Problem"}Example:
{ "type": "urn:ginum:problem:auth-required", "title": "Auth required", "status": 401, "code": "AUTH_REQUIRED", "requestId": "90000000-0000-4000-8000-000000000001", "retryable": false, "instance": "urn:uuid:90000000-0000-4000-8000-000000000001"}Response headers:
{ "X-Request-Id": { "description": "Server-generated UUID correlation ID. New per HTTP attempt, including idempotent replay.", "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "description": "No shared or private response caching.", "schema": { "type": "string", "const": "no-store" } }, "X-RateLimit-Limit": { "description": "Proposed custom quota header: current caller bucket capacity per 60-second window; no other tenant usage.", "schema": { "type": "integer", "minimum": 1 } }, "X-RateLimit-Remaining": { "description": "Remaining requests in current caller bucket.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Seconds until this caller bucket resets.", "schema": { "type": "integer", "minimum": 0 } }, "WWW-Authenticate": { "description": "Bearer challenge with no sensitive details.", "schema": { "type": "string" }, "example": "Bearer realm=\"ginum-api\", error=\"invalid_token\"" }}Operation denied by current scope/grant/module policy; machine writes forbidden. No confidential resource existence disclosed.
Content type: application/problem+json
{ "$ref": "#/components/schemas/Problem"}Example:
{ "type": "urn:ginum:problem:scope-denied", "title": "Scope denied", "status": 403, "code": "SCOPE_DENIED", "requestId": "90000000-0000-4000-8000-000000000001", "retryable": false, "instance": "urn:uuid:90000000-0000-4000-8000-000000000001"}Response headers:
{ "X-Request-Id": { "description": "Server-generated UUID correlation ID. New per HTTP attempt, including idempotent replay.", "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "description": "No shared or private response caching.", "schema": { "type": "string", "const": "no-store" } }, "X-RateLimit-Limit": { "description": "Proposed custom quota header: current caller bucket capacity per 60-second window; no other tenant usage.", "schema": { "type": "integer", "minimum": 1 } }, "X-RateLimit-Remaining": { "description": "Remaining requests in current caller bucket.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Seconds until this caller bucket resets.", "schema": { "type": "integer", "minimum": 0 } }}Resource absent or inaccessible; identical response shape.
Content type: application/problem+json
{ "$ref": "#/components/schemas/Problem"}Example:
{ "type": "urn:ginum:problem:not-found-or-denied", "title": "Not found or denied", "status": 404, "code": "NOT_FOUND_OR_DENIED", "requestId": "90000000-0000-4000-8000-000000000001", "retryable": false, "instance": "urn:uuid:90000000-0000-4000-8000-000000000001"}Response headers:
{ "X-Request-Id": { "description": "Server-generated UUID correlation ID. New per HTTP attempt, including idempotent replay.", "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "description": "No shared or private response caching.", "schema": { "type": "string", "const": "no-store" } }, "X-RateLimit-Limit": { "description": "Proposed custom quota header: current caller bucket capacity per 60-second window; no other tenant usage.", "schema": { "type": "integer", "minimum": 1 } }, "X-RateLimit-Remaining": { "description": "Remaining requests in current caller bucket.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Seconds until this caller bucket resets.", "schema": { "type": "integer", "minimum": 0 } }}IDEMPOTENCY_CONFLICT for changed payload, IDEMPOTENCY_IN_PROGRESS (retryable), IDEMPOTENCY_EXPIRED (not retryable), or CURSOR_EXPIRED (restart pagination).
Content type: application/problem+json
{ "$ref": "#/components/schemas/Problem"}Example:
{ "type": "urn:ginum:problem:idempotency-conflict", "title": "Idempotency conflict", "status": 409, "code": "IDEMPOTENCY_CONFLICT", "requestId": "90000000-0000-4000-8000-000000000001", "retryable": false, "instance": "urn:uuid:90000000-0000-4000-8000-000000000001"}Response headers:
{ "X-Request-Id": { "description": "Server-generated UUID correlation ID. New per HTTP attempt, including idempotent replay.", "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "description": "No shared or private response caching.", "schema": { "type": "string", "const": "no-store" } }, "X-RateLimit-Limit": { "description": "Proposed custom quota header: current caller bucket capacity per 60-second window; no other tenant usage.", "schema": { "type": "integer", "minimum": 1 } }, "X-RateLimit-Remaining": { "description": "Remaining requests in current caller bucket.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Seconds until this caller bucket resets.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Present only for IDEMPOTENCY_IN_PROGRESS; integer delay seconds. Other conflicts are not automatically retried.", "schema": { "type": "integer", "minimum": 1, "maximum": 300 } }}Quota exhausted; bounded retry only after Retry-After.
Content type: application/problem+json
{ "$ref": "#/components/schemas/Problem"}Example:
{ "type": "urn:ginum:problem:rate-limited", "title": "Rate limited", "status": 429, "code": "RATE_LIMITED", "requestId": "90000000-0000-4000-8000-000000000001", "retryable": true, "instance": "urn:uuid:90000000-0000-4000-8000-000000000001"}Response headers:
{ "X-Request-Id": { "description": "Server-generated UUID correlation ID. New per HTTP attempt, including idempotent replay.", "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "description": "No shared or private response caching.", "schema": { "type": "string", "const": "no-store" } }, "X-RateLimit-Limit": { "description": "Proposed custom quota header: current caller bucket capacity per 60-second window; no other tenant usage.", "schema": { "type": "integer", "minimum": 1 } }, "X-RateLimit-Remaining": { "description": "Remaining requests in current caller bucket.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Seconds until this caller bucket resets.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Nonnegative integer delay seconds, bounded at 300.", "schema": { "type": "integer", "minimum": 1, "maximum": 300 }, "example": 30 }}Unexpected failure; no implementation details. A write outcome may be uncertain; reconcile by retrying the same key only.
Content type: application/problem+json
{ "$ref": "#/components/schemas/Problem"}Example:
{ "type": "urn:ginum:problem:internal-error", "title": "Internal error", "status": 500, "code": "INTERNAL_ERROR", "requestId": "90000000-0000-4000-8000-000000000001", "retryable": false, "instance": "urn:uuid:90000000-0000-4000-8000-000000000001"}Response headers:
{ "X-Request-Id": { "description": "Server-generated UUID correlation ID. New per HTTP attempt, including idempotent replay.", "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "description": "No shared or private response caching.", "schema": { "type": "string", "const": "no-store" } }, "X-RateLimit-Limit": { "description": "Proposed custom quota header: current caller bucket capacity per 60-second window; no other tenant usage.", "schema": { "type": "integer", "minimum": 1 } }, "X-RateLimit-Remaining": { "description": "Remaining requests in current caller bucket.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Seconds until this caller bucket resets.", "schema": { "type": "integer", "minimum": 0 } }}Dependency, authorization freshness, audit or quota authority unavailable; fail closed.
Content type: application/problem+json
{ "$ref": "#/components/schemas/Problem"}Example:
{ "type": "urn:ginum:problem:temporarily-unavailable", "title": "Temporarily unavailable", "status": 503, "code": "TEMPORARILY_UNAVAILABLE", "requestId": "90000000-0000-4000-8000-000000000001", "retryable": true, "instance": "urn:uuid:90000000-0000-4000-8000-000000000001"}Response headers:
{ "X-Request-Id": { "description": "Server-generated UUID correlation ID. New per HTTP attempt, including idempotent replay.", "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "description": "No shared or private response caching.", "schema": { "type": "string", "const": "no-store" } }, "X-RateLimit-Limit": { "description": "Proposed custom quota header: current caller bucket capacity per 60-second window; no other tenant usage.", "schema": { "type": "integer", "minimum": 1 } }, "X-RateLimit-Remaining": { "description": "Remaining requests in current caller bucket.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Seconds until this caller bucket resets.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Nonnegative integer delay seconds, bounded at 300.", "schema": { "type": "integer", "minimum": 1, "maximum": 300 }, "example": 30 }}