# Bahrain NBR e-Invoicing API

> A platform API for submitting invoices to Bahrain's National Bureau for Revenue (NBR). The
> service handles CSR generation, XAdES signing, the QR stamp, BR-BH validation, and clearance
> (standard/B2B) or reporting (simplified/B2C). You send a minimal document and get back the
> NBR outcome. NBR e-invoicing is ZATCA Phase-2-equivalent (UBL 2.1 + XAdES + TLV QR + BR-BH).

## Mental model

```
Organization (you, the platform - holds one API key)
  ├── Provider device (shared by THIRD_PARTY suppliers)
  └── Connected Account (taxpayer; unique per VAT/TRN)
        ├── Supplier devices (DIRECT only; one per branch / sub-CR)
        └── Documents (cleared or reported)
```

- Authenticate as an organization: `Authorization: Api-Key <key>`. Keys are issued by Wafeq; you
  do not create or rotate them.
- Route each invoicing call with headers, never a device id:
  - `X-NBR-Connected-Account-Id` - which taxpayer.
  - `X-NBR-Sub-CR` - which branch (required only when a taxpayer has more than one active branch).
- The seller/taxpayer VAT is derived from the connected account (you can only invoice for the
  taxpayer you onboarded), except self-billing (route to the buyer) and imported-services RCM.
- A device is a registered EGS software instance with credentials stored server-side.
- The API organization itself is the third party. Configure its legal name, VAT, address and
  business_category using PATCH /organizations/me, then register its device once using
  POST /organizations/me/devices/register with the provider OTP and sub_cr.
- Create each supplier via POST /connected-accounts with onboarding.mode THIRD_PARTY and optional
  top-level metadata (any JSON object, stored locally; no automatic expiry or NBR transmission).
  No supplier OTP is needed. Invoices automatically include THIRD_PARTY and the organization agent.
  The supplier header still controls invoice ownership and VAT; the provider device signs/submits.
  The branch header records the supplier branch without selecting another provider device.
- DIRECT onboarding takes a supplier otp and sub_cr. Omit onboarding for account-only creation
  and use /devices/register later. DIRECT accounts keep their own credentials and omit AgentParty.
  Document indicators cannot include THIRD_PARTY and inline third_party is not accepted (422).
  Account mode alone controls the XML third-party bit and organization agent details.
- Account mode cannot be changed. All accounts support top-level metadata; PATCH metadata
  replaces its complete object (null clears it), including accounts with active devices.
  Organization identity cannot change while provider devices are COMPLIANCE or ACTIVE.
  Stored invoice XML is immutable; pending retries retain the original signing device.

## Document type is the endpoint (not a payload field)

- Standard (B2B) -> NBR clearance -> returns CLEARED + NBR-signed XML + QR.
- Simplified (B2C) -> NBR reporting -> returns REPORTED (QR/stamp applied locally).
- Families: invoices (388), credit-notes (381), debit-notes (383), prepayment-invoices (386),
  each with a `simplified-*` variant. All submissions share the same body shape.

## Document downloads

- GET /{family}/{id}/download?type=xml returns the stored signed/cleared UBL.
- type=pdf returns a bilingual invoice with the NBR QR and connected-account logo; long invoices
  span multiple pages. Prepaid amounts and the remaining amount due are shown separately.
- PDF generation failures return 502 (renderer failure), 503 (not configured), or 504 (timeout).
  Retry the PDF download; XML downloads remain independent of the renderer.

## Party sources

- Organization identity/address fills AgentParty for THIRD_PARTY connected accounts.
- Connected account name, VAT, identification and address fill its own party: Supplier for ordinary
  sales, Buyer for SELF_BILLING and IMPORT_SERVICES_RCM.
- Document.counterparty is required in every request: Buyer for ordinary sales (including third-party
  billing), external Supplier for SELF_BILLING and IMPORT_SERVICES_RCM.
- document.supplier and document.customer have been removed; sending either returns 422, even if null.
  Rename your former customer object to counterparty for ordinary sales, or your former supplier
  object to counterparty for buyer-issued documents. This applies to submission, validation and bulk.
- Configure connected account identification once, e.g. {"type":"SUBCRN","value":"136690-1"}.
  PATCH replaces identification (null clears it), including when devices are active.
  Without identification, DIRECT accounts use the selected supplier device Sub-CR.
  THIRD_PARTY accounts require their own identification; never use the provider Sub-CR.
- Existing accounts must have complete supplier details; missing fields return 422.
- Seller counterparties require name, identification and full address. Seller Bahrain VAT is
  required for SELF_BILLING and optional for IMPORT_SERVICES_RCM. Buyer rules depend on endpoint
  and indicators. The request supplies only the counterparty; the account fills its own party.
- Stored XML and accepted replays retain their original parties.

## Gateway-aligned validation

- Applied prepayments with VAT are supported: sale net 100 + VAT 10 = gross 110;
  prepayment net 20 + VAT 2 = prepaid 22; payable 88. Do not add prepayment VAT to gross.
- Foreign-currency BHD gross/VAT totals round to three decimal places; incorrect totals
  still fail BR-BH-68/69. Domestic RCM permits multiple VAT breakdowns, each with zero VAT.
- Same-day prepayments remain rejected with BR-BH-58, including at the NBR sandbox.
  Preserve the actual original issue date; do not change dates to avoid rejection.
- Invoice validation accepts third-party VAT with VAT scheme, or TIN with TIN scheme.
  TIN must contain 10 digits starting with 20 or 22. Missing/invalid identity still fails.
  TIN-only provider onboarding is not enabled: registration still requires organization VAT,
  and submission requires identity to match the active provider device.
- These arithmetic and identity rules were verified directly against the sandbox on 2026-10-21.
  The API uses an application validation profile; original SDK files remain unchanged.
  Gateway validation responses are authoritative and are never filtered.

## Customer addresses

- Simplified invoices, credit/debit notes and prepayment invoices accept omitted, null, empty
  or partial counterparty.address. This also applies to simplified validation and bulk requests.
- Omitted/null addresses produce no customer PostalAddress in XML. Supplied address objects
  default country to BH; no street-level values are invented.
- Standard domestic documents still require street, block, building_name, flat and city.
  Standard exports require an explicit country-only address.
- Customer name and tax/identification requirements, supplier addresses and organization
  agent addresses are unchanged.
- Local validation permits omitted simplified buyer addresses, following the integration owner's
  confirmation of NBR's updated policy. It adjusts only the older SDK BR-BH-46/47 presence rules and
  the missing-street condition of EC-BH-F-01-C79. Supplied-value limits and other rules remain active.
- Gateway responses are returned unchanged. Live acceptance after the NBR update is not yet verified.

## Line VAT

The rate is derived from the tax category; you never send a percentage unless overriding within
NBR's allowed set. Categories: S (standard, 5 or 10; default 10), Z (zero-rated), E (exempt),
O (out of scope / not subject). Z/E/O require a Bahrain exemption reason (VATEX-BH-*). Amounts,
the UUID and the issue timestamp are computed server-side.

## How to consume this API

- API base URL: https://api.wafeq.com/bh/v1
- OpenAPI schema (machine-readable, authoritative): https://api.wafeq.com/bh/v1/openapi.json
- Integration guides and API reference: https://docs.wafeq.com/bahrain-einvoicing
- Every endpoint below authenticates with `Authorization: Api-Key <key>` unless noted.

## Endpoints

### Credit notes
- `GET /credit-notes/summary` — Get status summary
- `GET /credit-notes/{invoice_id}/download` — Download XML or PDF
- `GET /credit-notes/{invoice_id}` — Retrieve credit note
- `GET /credit-notes` — List credit notes
- `POST /credit-notes/validate` — Validate credit note
- `POST /credit-notes/{invoice_id}/retry` — Retry credit note
- `POST /credit-notes` — Clear credit note

### Debit notes
- `GET /debit-notes/summary` — Get status summary
- `GET /debit-notes/{invoice_id}/download` — Download XML or PDF
- `GET /debit-notes/{invoice_id}` — Retrieve debit note
- `GET /debit-notes` — List debit notes
- `POST /debit-notes/validate` — Validate debit note
- `POST /debit-notes/{invoice_id}/retry` — Retry debit note
- `POST /debit-notes` — Clear debit note

### Invoices
- `GET /invoices/summary` — Get status summary
- `GET /invoices/{invoice_id}/download` — Download XML or PDF
- `GET /invoices/{invoice_id}` — Retrieve invoice
- `GET /invoices` — List invoices
- `POST /invoices/bulk-validate` — Validate invoices (bulk)
- `POST /invoices/bulk` — Clear invoices (bulk)
- `POST /invoices/validate` — Validate invoice
- `POST /invoices/{invoice_id}/retry` — Retry invoice
- `POST /invoices` — Clear invoice

### Prepayment invoices
- `GET /prepayment-invoices/summary` — Get status summary
- `GET /prepayment-invoices/{invoice_id}/download` — Download XML or PDF
- `GET /prepayment-invoices/{invoice_id}` — Retrieve prepayment invoice
- `GET /prepayment-invoices` — List prepayment invoices
- `POST /prepayment-invoices/validate` — Validate prepayment invoice
- `POST /prepayment-invoices/{invoice_id}/retry` — Retry prepayment invoice
- `POST /prepayment-invoices` — Clear prepayment invoice

### Simplified credit notes
- `GET /simplified-credit-notes/summary` — Get status summary
- `GET /simplified-credit-notes/{invoice_id}/download` — Download XML or PDF
- `GET /simplified-credit-notes/{invoice_id}` — Retrieve credit note
- `GET /simplified-credit-notes` — List credit notes
- `POST /simplified-credit-notes/validate` — Validate credit note
- `POST /simplified-credit-notes/{invoice_id}/retry` — Retry credit note
- `POST /simplified-credit-notes` — Report credit note

### Simplified debit notes
- `GET /simplified-debit-notes/summary` — Get status summary
- `GET /simplified-debit-notes/{invoice_id}/download` — Download XML or PDF
- `GET /simplified-debit-notes/{invoice_id}` — Retrieve debit note
- `GET /simplified-debit-notes` — List debit notes
- `POST /simplified-debit-notes/validate` — Validate debit note
- `POST /simplified-debit-notes/{invoice_id}/retry` — Retry debit note
- `POST /simplified-debit-notes` — Report debit note

### Simplified invoices
- `GET /simplified-invoices/summary` — Get status summary
- `GET /simplified-invoices/{invoice_id}/download` — Download XML or PDF
- `GET /simplified-invoices/{invoice_id}` — Retrieve invoice
- `GET /simplified-invoices` — List invoices
- `POST /simplified-invoices/bulk-validate` — Validate invoices (bulk)
- `POST /simplified-invoices/bulk` — Report invoices (bulk)
- `POST /simplified-invoices/validate` — Validate invoice
- `POST /simplified-invoices/{invoice_id}/retry` — Retry invoice
- `POST /simplified-invoices` — Report invoice

### Simplified prepayment invoices
- `GET /prepayment-simplified-invoices/summary` — Get status summary
- `GET /prepayment-simplified-invoices/{invoice_id}/download` — Download XML or PDF
- `GET /prepayment-simplified-invoices/{invoice_id}` — Retrieve prepayment invoice
- `GET /prepayment-simplified-invoices` — List prepayment invoices
- `POST /prepayment-simplified-invoices/validate` — Validate prepayment invoice
- `POST /prepayment-simplified-invoices/{invoice_id}/retry` — Retry prepayment invoice
- `POST /prepayment-simplified-invoices` — Report prepayment invoice

### connected-accounts
- `DELETE /connected-accounts/{account_id}` — Delete Connected Account
- `GET /connected-accounts/{account_id}/devices` — List Account Devices
- `GET /connected-accounts/{account_id}` — Get Connected Account
- `GET /connected-accounts` — List Connected Accounts
- `PATCH /connected-accounts/{account_id}` — Update Connected Account
- `POST /connected-accounts` — Create Connected Account

### devices
- `GET /devices` — List Devices
- `POST /devices/deactivate-all` — Deactivate All Devices
- `POST /devices/register` — Register Device
- `POST /devices/{device_id}/activate` — Activate Device
- `POST /devices/{device_id}/deactivate` — Deactivate Device
- `POST /devices/{device_id}/renew` — Renew Device

### organizations
- `GET /organizations/me/devices` — List Organization Devices
- `GET /organizations/me` — Whoami
- `PATCH /organizations/me` — Update Organization
- `POST /organizations/me/devices/register` — Register Organization Device