Register and manage devices

A device holds the NBR credentials used to sign and submit documents. Obtain a
fresh OTP from the NBR portal, then register the taxpayer's software instance:

curl -X POST "$BASE/devices/register" \
  -H "Authorization: Api-Key $KEY" \
  -H "X-NBR-Connected-Account-Id: $ACCOUNT_ID" \
  -H 'Content-Type: application/json' \
  -d '{"otp":"replace_with_fresh_otp","sub_cr":"136690-1"}'

Wafeq generates the key and CSR, obtains a compliance CSID, runs the compliance
checks, and obtains a production CSID. A successful response has status: "ACTIVE" and a device_id. Private keys, certificate tokens and NBR secrets are
never returned.

The terms compliance and production CSID describe the NBR credential lifecycle;
they do not switch the deployment between NBR sandbox and core.

Resume an incomplete registration

If compliance checks fail, the response is HTTP 409, and the device remains
COMPLIANCE. Review the returned findings and use
POST /devices/{device_id}/activate to rerun the checks. Activation reuses the
compliance CSID and does not require another OTP.

If combined connected-account creation and onboarding fails, its error includes
the saved connected_account_id. List that account's devices before trying
again. If the OTP exchange itself failed, retry registration with a valid OTP.

Third-party provider device

Configure the provider's legal name, VAT registration, address and business
category with PATCH /organizations/me, then register it through
POST /organizations/me/devices/register using its own OTP and sub_cr. This
endpoint does not take a connected-account header.

One active provider device serves the organization's THIRD_PARTY suppliers.
List it through GET /organizations/me/devices. Supplier device lists remain
empty for delegated accounts. Provider onboarding requires VAT; TIN-only
provider enrollment is not supported by this flow.

Lifecycle operations

Request	Purpose
`GET /devices?connected_account_id={id}`	List taxpayer devices, optionally filtered by `sub_cr`.
`POST /devices/{id}/activate`	Complete a COMPLIANCE registration.
`POST /devices/{id}/renew`	Renew with `{"otp":"<fresh-otp>"}`.
`POST /devices/{id}/deactivate`	Deactivate with an optional audit `reason`.

The lifecycle endpoints also manage provider devices. Renewal uses a fresh key
and OTP and reruns compliance checks; signing is unavailable until the new
production credentials are ready. If renewal stops in COMPLIANCE, resume with
activate.

Registering a replacement taxpayer device supersedes the prior active device
for that account and branch. A replacement provider registration supersedes
the prior active provider device. Stored document retries retain their original
signing device; they do not select a replacement.