opsd 0.4.0

Rust client library for the Opsd API
Documentation

Opsd Rust library

opsd is the Rust client library for the Opsd API. It provides a small typed wrapper around the current public endpoints, including business, practice, payroll and billing workflows and the existing sandbox endpoints.

The public opsd::types module owns the API-facing domain and operation types independently of the optional HTTP client.

The default constructor, OpsdClient::new(), targets the production API at https://api.opsd.sh/v1/. For local development, tests, or non-production deployments, use OpsdClient::new_base(url, credential) with a parsed url::Url. Successful responses deserialize into typed Rust structs, and non-2xx responses are surfaced as Error::Api with the underlying ProblemDetails attached.

Clients require an API credential. OAuth access tokens and API keys both use the HTTP Bearer scheme without exposing the secret in debug output:

let credential = ApiCredential::new(secret)?;
let client = OpsdClient::new(credential)?;

Practices and billing

Practice methods follow the business API's membership and invitation pattern: create/list/get practices, manage members, and create/list/cancel/accept/decline invitations. create_practice_business creates a new client business without direct members; it does not link an existing business. Practice roles are Admin and Member.

Standalone businesses use subscribe_to_payroll, get_payroll_subscription and cancel_payroll_subscription. Practice admins instead use enable_practice_payroll, get_practice_payroll and disable_practice_payroll with both practice and business IDs. Agreement status is separate from suspension. Enabling or subscribing starts monthly base fees without clearing suspension. Mutations take PayrollSubscriptionAction with expected_version from the status response’s subscription_version.

Both payer types have billing-status, payment-method listing/default selection, invoice listing, detailed invoice lines and PDF-download methods. Practice variants include practice in their names, such as list_practice_invoices. Billing operations require administrator access. Billing status and payment methods come from Stripe live; invoice lists and breakdowns are saved Opsd data. Selecting a default method does not retry invoices or clear suspension.

List methods take typed query structs; Default::default() uses server defaults. Use next_before, next_offset or next_starting_after in the next request to continue pagination. Invoice subtotals are not remaining balances. Practice invoice lines identify each client business; the PDF contains summary lines. PDF methods return Vec<u8> without writing files or opening a browser.

Website billing-portal sessions use browser cookies, not API credentials, and are intentionally not included. All public models remain available with default-features = false when only API types are needed.

Payroll calculations

Scheme creation requires tax_year_start and an explicit EmploymentAllowance decision. Create a monthly schedule with create_pay_schedule before creating employments or draft runs; both requests require its PayScheduleId.

New employments require a start date, NI category, monthly gross pay and StarterInformation (P45, Checklist or NotProvided), a NormalWeeklyHoursBand, and explicit StudentLoan::NotApplicable and PostgraduateLoan::NotApplicable declarations. Loan deductions are not yet supported; do not use these declarations where deductions apply. P45 tax details and HMRC notices use cumulative/non-cumulative enum variants so irrelevant amounts cannot accompany W1/M1 treatment. Amounts are sterling pence; tax amounts are signed to preserve refunds. Tax codes and year-specific HMRC rules are validated by the server; this public library has no dependency on HMRC calculation crates.

get_employment returns the original starter evidence and active-year tax settings. update_employment accepts UpdateEmploymentRequest::Settings or ::TaxCodeNotice; notice updates cannot also contain starter changes. For a cumulative notice, omitted earlier-job amounts retain stored cumulative totals. Switching from non-cumulative treatment requires explicit amounts, including zero where appropriate. These amounts are separate from this employment's YTD.

preview_payroll_run calculates a draft with current settings and saved gross inputs. update_payroll_payment overrides one draft payment in pence, and discard_payroll_run deletes a draft. Finalisation stores the calculation; get_payroll_run and finalize_payroll_run retain its payments, inputs, YTD and totals in details.calculation. Drafts and historical runs without saved results have None. Subsequent notices do not rewrite saved results.

rollover_paye_scheme takes the destination year, Employment Allowance decision and an explicit list of new-year notices ([] after checking none apply). The rollover contract includes opserver sending an end-of-year FPS for the closing year and an EPS declaring the Employment Allowance decision for the new year, alongside closing the old year and preparing new-year employment settings. Use list_paye_scheme_rollovers to recover a rollover ID after a lost response, then get_paye_scheme_rollover to inspect progress and available_actions. Use the explicit retry, resume or cancel methods with the saved version; repeating the start request is not a resume operation. The response reports separate final-FPS and new-year-EPS progress. The server currently supports 2026–27 calculations and rollover rules; entering 2027–28 is not yet supported.

These changes add required fields to the creation requests. Release the updated SDK before updating consumers that use the published crate. All payroll models remain available with default-features = false.

Current API changes in 0.4

Employee creation requires date of birth, sex (M or F) and an address, in addition to names. Title, passport number and National Insurance number are optional. UpdateEmployeeRequest uses FieldUpdate::Unchanged, ::Set(value) and ::Clear for these nullable fields. Other omitted update fields retain their values. The server enforces HMRC validation and payroll-history edit rules.

Practice creation requires PracticeReportingDetails. Read or replace them with get_practice_hmrc_reporting and update_practice_hmrc_reporting. Scheme creation also accepts an optional Corporation Tax company_utr.

finalize_payroll_run takes FinalizePayrollRunRequest: the run's current version, Government Gateway sender ID and HmrcPassword, plus an optional late-reporting reason. Successful HTTP completion does not mean HMRC acceptance. PayrollRunStatus::Finalized carries submission progress; ::Accepted establishes acceptance. Read available_actions before retrying, reopening, cancelling or resuming. Resuming polling requires only the version; reconciliation also needs the original sender's password. The client never retries these actions automatically.

Rollover creation additionally requires expected_generation from the scheme's rollover_generation. Subsequent rollover actions take its own version. History methods return revisions, attempts, actions and safe diagnostic messages. An API conflict with an HMRC waiting period exposes Error::retry_after_seconds(). Re-read progress after a conflict or uncertain transport result; do not silently substitute a newer version and repeat an action.

HmrcPassword redacts Debug output, but serialization exposes its value for the request. Do not log serialized credential-bearing requests. Credentials are not returned in progress or history responses. Automatic HTTP redirects are disabled to prevent forwarding credential-bearing request bodies; redirects are returned as errors for the caller to investigate.

License

Licensed under either the Apache License, Version 2.0 or the MIT license, at your option.