Provider API Visual Diagram

This page provides visual references for the Provider API authentication and payload structure.

1) Inspector Inspection Timeline

┌───────────────────────────────┐
│ Start Inspection              │
├───────────────────────────────┤
│ Control                       │
│ • kl_guid                     │
│ • started_at                  │
├───────────────────────────────┤
│ Journey                       │
│ • slnid (required)            │
│ • from_stop_sloid (required)  │
│ • planned_departure (required)│
└───────────────────────────────┘
               │
               │  during journey
               │  ticket checks happen
               │  • paper → category counts
               ▼

┌───────────────────────────────┐
│ Interim Close                 │
├───────────────────────────────┤
│ Control                       │
│ • ended_at                    │
│ • control_grade_pct           │
├───────────────────────────────┤
│ Journey                       │
│ • to_stop_sloid (required)    │
│ • direction (optional)        │
└───────────────────────────────┘

2) Authentication and Request Flow

flowchart LR
    Provider[Provider System] -->|POST /api/provider/v1/controls| API[Data Service Provider API]

    subgraph Headers[Required and Optional Headers]
      H1[Authorization Bearer JWT<br/>mandatory]
      H2[X-Provider-Id<br/>optional]
    end

    Provider --> H1
    Provider --> H2
    H1 --> API
    H2 --> API

    API -->|201 Accepted| R201[ProviderSubmissionResponse]
    API -->|200 Duplicate| R200[ProviderSubmissionResponse]
    API -->|401 Unauthorized| R401[ProblemDetails]
    API -->|403 Forbidden| R403[ProblemDetails]
    API -->|422 Validation Error| R422[ProviderValidationProblemDetails]

Notes

• Authorization: Bearer <JWT> is mandatory and drives authentication.
• JWT must contain the required application role (ProviderApi.Access).
• X-Provider-Id is optional and can be used for provider mapping/tracing.
• ended_at is the provider payload close timestamp (interim close semantics).
• Journey schema contract (source of truth):
  • Required: slnid, from_stop_sloid, to_stop_sloid, planned_departure
  • Optional: direction
  • slnid accepts canonical format only: ^ch:1:slnid:[0-9]{6}$
  • from_stop_sloid and to_stop_sloid accept:
    • Canonical: pattern-based IDs (^ch:1:sloid:...)
    • Legacy: numeric base ID XXXXXX
• Validation details and full schema definitions remain authoritative in openapi/provider-controls.openapi.yaml.