Bufdir API Client
Component Detail
Description
Phase 3 integration client for submitting export data directly to Bufdir's API once Norse Digital Products completes API negotiations. Designed now with a clean interface so the PDF/CSV path and the API submission path share the same internal data model.
bufdir-api-client
Summaries
The Bufdir API Client represents NHF's strategic path to fully automated, direct government reporting — eliminating the manual step of downloading and uploading files to Bufdir's systems. Once the API negotiation with Norse Digital Products is complete, this component will allow reports to be submitted with a single click, with confirmation references returned and stored automatically. This reduces administrative workload for chapter administrators, eliminates the risk of lost or incorrectly uploaded files, and positions NHF as a digital-first organisation meeting government reporting standards in the most efficient manner available. The investment made now in clean interface design protects future implementation costs.
The Bufdir API Client is the highest-complexity component in the export pipeline and carries significant external dependency risk: implementation is blocked on completion of API negotiations between Norse Digital Products and Bufdir, a timeline outside the project team's control. The recommended scheduling strategy is to complete interface and authentication scaffolding in an early sprint, then stub the submit() call with a mock response so that all downstream integration testing can proceed without the live API. The retrySubmission interface introduces a requirement for idempotency testing. Plan a dedicated security review sprint for the authentication and credential storage mechanism before any production deployment.
Ensure the submission reference storage requirement is included in database migration planning.
The Bufdir API Client is a high-complexity backend service designed for Phase 3 direct API submission to Bufdir. It consumes the generated-report and bufdir-category-mapping data models, sharing the same internal payload structure used by the PDF and CSV paths, which allows all three output channels to be driven from a single export orchestration layer. The submit(payload) interface is the primary entry point; authenticate(credentials) must be called first and should store tokens with expiry handling. validatePayload(payload) provides pre-submission schema conformance checking against Bufdir's API contract.
getSubmissionStatus(referenceId) and retrySubmission(referenceId) support asynchronous confirmation flows if Bufdir's API uses a queued submission model. Implement with circuit-breaker logic and exponential backoff on retrySubmission. Store API credentials in Supabase Vault, never in environment variables or database rows. Design authenticate() to be callable independently so token refresh can be scheduled without triggering a full submission.
Responsibilities
- Submit structured export payload to Bufdir API endpoint
- Handle authentication with Bufdir API
- Map internal payload to Bufdir API request schema
- Process submission confirmation and store reference
Interfaces
submit(payload)
authenticate(credentials)
getSubmissionStatus(referenceId)
validatePayload(payload)
retrySubmission(referenceId)
Used Integrations (1)
External integrations and APIs this component relies on