# eMoney Token Factory API Endpoints

Complete reference of all API endpoints with their Fully Qualified Domain Names (FQDNs).

## Base URLs

### Production
- **REST API**: `https://api.d-bis.org`
- **Mapping Service**: `https://mappings.api.d-bis.org`
- **Webhook Service**: `https://webhooks.api.d-bis.org`
- **Orchestrator Service**: `https://orchestrator.api.d-bis.org`
- **Packet Service**: `https://packets.api.d-bis.org`

### Staging
- **REST API**: `https://api-staging.d-bis.org`
- **Mapping Service**: `https://mappings.api-staging.d-bis.org`
- **Webhook Service**: `https://webhooks.api-staging.d-bis.org`
- **Orchestrator Service**: `https://orchestrator.api-staging.d-bis.org`
- **Packet Service**: `https://packets.api-staging.d-bis.org`

### Local Development
- **REST API**: `http://localhost:3000`
- **Mapping Service**: `http://localhost:3004`
- **Webhook Service**: `http://localhost:3001`
- **Orchestrator Service**: `http://localhost:3002`
- **Packet Service**: `http://localhost:3003`

---

## REST API Service

Base Path: `/v1`

### Tokens

#### Deploy Token
- **Method**: `POST`
- **Path**: `/v1/tokens`
- **FQDN**: `https://api.d-bis.org/v1/tokens`
- **Description**: Deploy a new eMoney token on ChainID 138
- **Auth**: Requires `TOKEN_DEPLOYER` role
- **Idempotent**: Yes

#### List Tokens
- **Method**: `GET`
- **Path**: `/v1/tokens`
- **FQDN**: `https://api.d-bis.org/v1/tokens`
- **Description**: List all deployed tokens with optional filtering
- **Query Parameters**: `code`, `issuer`, `limit`, `offset`

#### Get Token
- **Method**: `GET`
- **Path**: `/v1/tokens/{code}`
- **FQDN**: `https://api.d-bis.org/v1/tokens/{code}`
- **Description**: Get token metadata and configuration by code
- **Path Parameters**: `code` (token code, e.g., USDW)

#### Update Token Policy
- **Method**: `PATCH`
- **Path**: `/v1/tokens/{code}/policy`
- **FQDN**: `https://api.d-bis.org/v1/tokens/{code}/policy`
- **Description**: Update token policy configuration (pause, lienMode, bridgeOnly, etc.)
- **Auth**: Requires `POLICY_OPERATOR` role

#### Mint Tokens
- **Method**: `POST`
- **Path**: `/v1/tokens/{code}/mint`
- **FQDN**: `https://api.d-bis.org/v1/tokens/{code}/mint`
- **Description**: Mint new tokens to an address
- **Auth**: Requires `ISSUER` role
- **Idempotent**: Yes

#### Burn Tokens
- **Method**: `POST`
- **Path**: `/v1/tokens/{code}/burn`
- **FQDN**: `https://api.d-bis.org/v1/tokens/{code}/burn`
- **Description**: Burn tokens from an address
- **Auth**: Requires `ISSUER` role
- **Idempotent**: Yes

#### Clawback Tokens
- **Method**: `POST`
- **Path**: `/v1/tokens/{code}/clawback`
- **FQDN**: `https://api.d-bis.org/v1/tokens/{code}/clawback`
- **Description**: Clawback tokens from an address
- **Auth**: Requires `ENFORCEMENT` role
- **Idempotent**: Yes

#### Force Transfer Tokens
- **Method**: `POST`
- **Path**: `/v1/tokens/{code}/force-transfer`
- **FQDN**: `https://api.d-bis.org/v1/tokens/{code}/force-transfer`
- **Description**: Force transfer tokens between addresses
- **Auth**: Requires `ENFORCEMENT` role
- **Idempotent**: Yes

### Liens

#### Place Lien
- **Method**: `POST`
- **Path**: `/v1/liens`
- **FQDN**: `https://api.d-bis.org/v1/liens`
- **Description**: Place a lien (encumbrance) on an account
- **Auth**: Requires `DEBT_AUTHORITY` role

#### List Liens
- **Method**: `GET`
- **Path**: `/v1/liens`
- **FQDN**: `https://api.d-bis.org/v1/liens`
- **Description**: List liens with optional filtering
- **Query Parameters**: `debtor`, `active`, `limit`, `offset`

#### Get Lien
- **Method**: `GET`
- **Path**: `/v1/liens/{lienId}`
- **FQDN**: `https://api.d-bis.org/v1/liens/{lienId}`
- **Description**: Get lien details by ID
- **Path Parameters**: `lienId` (numeric lien identifier)

#### Reduce Lien
- **Method**: `PATCH`
- **Path**: `/v1/liens/{lienId}`
- **FQDN**: `https://api.d-bis.org/v1/liens/{lienId}`
- **Description**: Reduce lien amount
- **Auth**: Requires `DEBT_AUTHORITY` role

#### Release Lien
- **Method**: `DELETE`
- **Path**: `/v1/liens/{lienId}`
- **FQDN**: `https://api.d-bis.org/v1/liens/{lienId}`
- **Description**: Release (remove) a lien
- **Auth**: Requires `DEBT_AUTHORITY` role

#### Get Account Liens
- **Method**: `GET`
- **Path**: `/v1/liens/accounts/{accountRefId}/liens`
- **FQDN**: `https://api.d-bis.org/v1/liens/accounts/{accountRefId}/liens`
- **Description**: Get all liens for a specific account
- **Path Parameters**: `accountRefId` (0x-prefixed 64-char hex string)
- **Query Parameters**: `active` (optional boolean)

#### Get Encumbrance
- **Method**: `GET`
- **Path**: `/v1/liens/accounts/{accountRefId}/encumbrance`
- **FQDN**: `https://api.d-bis.org/v1/liens/accounts/{accountRefId}/encumbrance`
- **Description**: Get active encumbrance and free balance for an account by token
- **Path Parameters**: `accountRefId` (0x-prefixed 64-char hex string)
- **Query Parameters**: `token` (optional Ethereum address)

### Compliance

#### Set Account Compliance
- **Method**: `PUT`
- **Path**: `/v1/compliance/accounts/{accountRefId}`
- **FQDN**: `https://api.d-bis.org/v1/compliance/accounts/{accountRefId}`
- **Description**: Set compliance status for an account
- **Auth**: Requires `COMPLIANCE` role
- **Path Parameters**: `accountRefId` (0x-prefixed 64-char hex string)

#### Get Account Compliance
- **Method**: `GET`
- **Path**: `/v1/compliance/accounts/{accountRefId}`
- **FQDN**: `https://api.d-bis.org/v1/compliance/accounts/{accountRefId}`
- **Description**: Get compliance profile for an account
- **Path Parameters**: `accountRefId` (0x-prefixed 64-char hex string)

#### Freeze/Unfreeze Account
- **Method**: `PUT`
- **Path**: `/v1/compliance/accounts/{accountRefId}/freeze`
- **FQDN**: `https://api.d-bis.org/v1/compliance/accounts/{accountRefId}/freeze`
- **Description**: Freeze or unfreeze an account
- **Auth**: Requires `COMPLIANCE` role
- **Path Parameters**: `accountRefId` (0x-prefixed 64-char hex string)

#### Set Account Tier
- **Method**: `PUT`
- **Path**: `/v1/compliance/accounts/{accountRefId}/tier`
- **FQDN**: `https://api.d-bis.org/v1/compliance/accounts/{accountRefId}/tier`
- **Description**: Set risk tier for an account
- **Auth**: Requires `COMPLIANCE` role
- **Path Parameters**: `accountRefId` (0x-prefixed 64-char hex string)

#### Set Account Jurisdiction Hash
- **Method**: `PUT`
- **Path**: `/v1/compliance/accounts/{accountRefId}/jurisdiction`
- **FQDN**: `https://api.d-bis.org/v1/compliance/accounts/{accountRefId}/jurisdiction`
- **Description**: Set jurisdiction hash for an account
- **Auth**: Requires `COMPLIANCE` role
- **Path Parameters**: `accountRefId` (0x-prefixed 64-char hex string)

#### Set Wallet Compliance
- **Method**: `PUT`
- **Path**: `/v1/compliance/wallets/{walletRefId}`
- **FQDN**: `https://api.d-bis.org/v1/compliance/wallets/{walletRefId}`
- **Description**: Set compliance status for a wallet
- **Auth**: Requires `COMPLIANCE` role
- **Path Parameters**: `walletRefId` (0x-prefixed 64-char hex string)

#### Get Wallet Compliance
- **Method**: `GET`
- **Path**: `/v1/compliance/wallets/{walletRefId}`
- **FQDN**: `https://api.d-bis.org/v1/compliance/wallets/{walletRefId}`
- **Description**: Get compliance profile for a wallet
- **Path Parameters**: `walletRefId` (0x-prefixed 64-char hex string)

#### Freeze/Unfreeze Wallet
- **Method**: `PUT`
- **Path**: `/v1/compliance/wallets/{walletRefId}/freeze`
- **FQDN**: `https://api.d-bis.org/v1/compliance/wallets/{walletRefId}/freeze`
- **Description**: Freeze or unfreeze a wallet
- **Auth**: Requires `COMPLIANCE` role
- **Path Parameters**: `walletRefId` (0x-prefixed 64-char hex string)

#### Set Wallet Tier
- **Method**: `PUT`
- **Path**: `/v1/compliance/wallets/{walletRefId}/tier`
- **FQDN**: `https://api.d-bis.org/v1/compliance/wallets/{walletRefId}/tier`
- **Description**: Set risk tier for a wallet
- **Auth**: Requires `COMPLIANCE` role
- **Path Parameters**: `walletRefId` (0x-prefixed 64-char hex string)

#### Set Wallet Jurisdiction Hash
- **Method**: `PUT`
- **Path**: `/v1/compliance/wallets/{walletRefId}/jurisdiction`
- **FQDN**: `https://api.d-bis.org/v1/compliance/wallets/{walletRefId}/jurisdiction`
- **Description**: Set jurisdiction hash for a wallet
- **Auth**: Requires `COMPLIANCE` role
- **Path Parameters**: `walletRefId` (0x-prefixed 64-char hex string)

### Mappings

#### Link Account to Wallet
- **Method**: `POST`
- **Path**: `/v1/mappings/account-wallet/link`
- **FQDN**: `https://api.d-bis.org/v1/mappings/account-wallet/link`
- **Description**: Create a mapping between an account reference and a wallet reference

#### Unlink Account from Wallet
- **Method**: `POST`
- **Path**: `/v1/mappings/account-wallet/unlink`
- **FQDN**: `https://api.d-bis.org/v1/mappings/account-wallet/unlink`
- **Description**: Remove a mapping between an account reference and a wallet reference

#### Get Wallets for Account
- **Method**: `GET`
- **Path**: `/v1/mappings/accounts/{accountRefId}/wallets`
- **FQDN**: `https://api.d-bis.org/v1/mappings/accounts/{accountRefId}/wallets`
- **Description**: Get all wallet references linked to an account reference
- **Path Parameters**: `accountRefId` (0x-prefixed 64-char hex string)

#### Get Accounts for Wallet
- **Method**: `GET`
- **Path**: `/v1/mappings/wallets/{walletRefId}/accounts`
- **FQDN**: `https://api.d-bis.org/v1/mappings/wallets/{walletRefId}/accounts`
- **Description**: Get all account references linked to a wallet reference
- **Path Parameters**: `walletRefId` (0x-prefixed 64-char hex string)

#### Connect Provider
- **Method**: `POST`
- **Path**: `/v1/mappings/providers/{provider}/connect`
- **FQDN**: `https://api.d-bis.org/v1/mappings/providers/{provider}/connect`
- **Description**: Connect a provider (WalletConnect, Fireblocks, etc.)
- **Path Parameters**: `provider` (provider name)

#### Get Provider Status
- **Method**: `GET`
- **Path**: `/v1/mappings/providers/{provider}/connections/{connectionId}/status`
- **FQDN**: `https://api.d-bis.org/v1/mappings/providers/{provider}/connections/{connectionId}/status`
- **Description**: Get connection status for a provider
- **Path Parameters**: `provider`, `connectionId`

### Triggers

#### List Triggers
- **Method**: `GET`
- **Path**: `/v1/triggers`
- **FQDN**: `https://api.d-bis.org/v1/triggers`
- **Description**: List payment rail triggers with filtering
- **Query Parameters**: `state`, `rail`, `msgType`, `instructionId`, `limit`, `offset`

#### Get Trigger
- **Method**: `GET`
- **Path**: `/v1/triggers/{triggerId}`
- **FQDN**: `https://api.d-bis.org/v1/triggers/{triggerId}`
- **Description**: Get trigger details by ID
- **Path Parameters**: `triggerId` (64-char hex string)

#### Validate and Lock Trigger
- **Method**: `POST`
- **Path**: `/v1/triggers/{triggerId}/validate-and-lock`
- **FQDN**: `https://api.d-bis.org/v1/triggers/{triggerId}/validate-and-lock`
- **Description**: Orchestrator step - validate trigger and lock funds
- **Auth**: Requires `POLICY_OPERATOR` role
- **Path Parameters**: `triggerId` (64-char hex string)

#### Mark Trigger Submitted
- **Method**: `POST`
- **Path**: `/v1/triggers/{triggerId}/mark-submitted`
- **FQDN**: `https://api.d-bis.org/v1/triggers/{triggerId}/mark-submitted`
- **Description**: Mark trigger as submitted to rail (includes railTxRef)
- **Auth**: Requires `POLICY_OPERATOR` role
- **Path Parameters**: `triggerId` (64-char hex string)

#### Confirm Trigger Settled
- **Method**: `POST`
- **Path**: `/v1/triggers/{triggerId}/confirm-settled`
- **FQDN**: `https://api.d-bis.org/v1/triggers/{triggerId}/confirm-settled`
- **Description**: Confirm trigger has settled on the rail
- **Auth**: Requires `POLICY_OPERATOR` role
- **Idempotent**: Yes
- **Path Parameters**: `triggerId` (64-char hex string)

#### Confirm Trigger Rejected
- **Method**: `POST`
- **Path**: `/v1/triggers/{triggerId}/confirm-rejected`
- **FQDN**: `https://api.d-bis.org/v1/triggers/{triggerId}/confirm-rejected`
- **Description**: Confirm trigger was rejected on the rail
- **Auth**: Requires `POLICY_OPERATOR` role
- **Idempotent**: Yes
- **Path Parameters**: `triggerId` (64-char hex string)

### ISO-20022

#### Submit Inbound Message
- **Method**: `POST`
- **Path**: `/v1/iso/inbound`
- **FQDN**: `https://api.d-bis.org/v1/iso/inbound`
- **Description**: Submit an inbound ISO-20022 message (from rail adapter)
- **Auth**: mTLS or OAuth2 with `POLICY_OPERATOR` role
- **Idempotent**: Yes

#### Submit Outbound Message
- **Method**: `POST`
- **Path**: `/v1/iso/outbound`
- **FQDN**: `https://api.d-bis.org/v1/iso/outbound`
- **Description**: Submit an outbound ISO-20022 message (from ops/client)
- **Idempotent**: Yes

### Packets

#### Generate Packet
- **Method**: `POST`
- **Path**: `/v1/packets`
- **FQDN**: `https://api.d-bis.org/v1/packets`
- **Description**: Generate a non-scheme integration packet (PDF + sidecars)
- **Idempotent**: Yes

#### List Packets
- **Method**: `GET`
- **Path**: `/v1/packets`
- **FQDN**: `https://api.d-bis.org/v1/packets`
- **Description**: List packets with optional filtering
- **Query Parameters**: `triggerId`, `instructionId`, `status`, `limit`, `offset`

#### Get Packet
- **Method**: `GET`
- **Path**: `/v1/packets/{packetId}`
- **FQDN**: `https://api.d-bis.org/v1/packets/{packetId}`
- **Description**: Get packet metadata and hashes
- **Path Parameters**: `packetId` (64-char hex string)

#### Download Packet
- **Method**: `GET`
- **Path**: `/v1/packets/{packetId}/download`
- **FQDN**: `https://api.d-bis.org/v1/packets/{packetId}/download`
- **Description**: Download packet file (PDF, XML, etc.)
- **Path Parameters**: `packetId` (64-char hex string)

#### Dispatch Packet
- **Method**: `POST`
- **Path**: `/v1/packets/{packetId}/dispatch`
- **FQDN**: `https://api.d-bis.org/v1/packets/{packetId}/dispatch`
- **Description**: Dispatch packet via email/AS4/portal
- **Idempotent**: Yes
- **Path Parameters**: `packetId` (64-char hex string)

#### Acknowledge Packet
- **Method**: `POST`
- **Path**: `/v1/packets/{packetId}/ack`
- **FQDN**: `https://api.d-bis.org/v1/packets/{packetId}/ack`
- **Description**: Record an acknowledgement/receipt for a packet
- **Idempotent**: Yes
- **Path Parameters**: `packetId` (64-char hex string)

### Bridge

#### Lock Tokens
- **Method**: `POST`
- **Path**: `/v1/bridge/lock`
- **FQDN**: `https://api.d-bis.org/v1/bridge/lock`
- **Description**: Lock tokens in bridge vault for cross-chain transfer

#### Unlock Tokens
- **Method**: `POST`
- **Path**: `/v1/bridge/unlock`
- **FQDN**: `https://api.d-bis.org/v1/bridge/unlock`
- **Description**: Unlock tokens from bridge vault (requires proof)
- **Auth**: Requires `BRIDGE_OPERATOR` role
- **Idempotent**: Yes

#### Get Bridge Lock Status
- **Method**: `GET`
- **Path**: `/v1/bridge/locks/{lockId}`
- **FQDN**: `https://api.d-bis.org/v1/bridge/locks/{lockId}`
- **Description**: Get bridge lock status by ID
- **Path Parameters**: `lockId` (64-char hex string)

#### Get Bridge Corridors
- **Method**: `GET`
- **Path**: `/v1/bridge/corridors`
- **FQDN**: `https://api.d-bis.org/v1/bridge/corridors`
- **Description**: Get list of supported bridge corridors and verification modes

### Health Check

#### Health Check
- **Method**: `GET`
- **Path**: `/health`
- **FQDN**: `https://api.d-bis.org/health`
- **Description**: Health check endpoint

---

## Mapping Service

Base Path: `/v1/mappings`

### Account-Wallet Mappings

#### Link Account to Wallet
- **Method**: `POST`
- **Path**: `/v1/mappings/account-wallet/link`
- **FQDN**: `https://mappings.api.d-bis.org/v1/mappings/account-wallet/link`
- **Description**: Create a mapping between an account reference and a wallet reference

#### Unlink Account from Wallet
- **Method**: `POST`
- **Path**: `/v1/mappings/account-wallet/unlink`
- **FQDN**: `https://mappings.api.d-bis.org/v1/mappings/account-wallet/unlink`
- **Description**: Remove a mapping between an account reference and a wallet reference

#### Get Wallets for Account
- **Method**: `GET`
- **Path**: `/v1/mappings/accounts/{accountRefId}/wallets`
- **FQDN**: `https://mappings.api.d-bis.org/v1/mappings/accounts/{accountRefId}/wallets`
- **Description**: Get all wallet references linked to an account reference
- **Path Parameters**: `accountRefId` (0x-prefixed 64-char hex string)

#### Get Accounts for Wallet
- **Method**: `GET`
- **Path**: `/v1/mappings/wallets/{walletRefId}/accounts`
- **FQDN**: `https://mappings.api.d-bis.org/v1/mappings/wallets/{walletRefId}/accounts`
- **Description**: Get all account references linked to a wallet reference
- **Path Parameters**: `walletRefId` (0x-prefixed 64-char hex string)

### Provider Management

#### Connect Provider
- **Method**: `POST`
- **Path**: `/v1/mappings/providers/{provider}/connect`
- **FQDN**: `https://mappings.api.d-bis.org/v1/mappings/providers/{provider}/connect`
- **Description**: Connect a provider (WalletConnect, Fireblocks, MetaMask, etc.)
- **Path Parameters**: `provider` (provider name)

#### Get Provider Status
- **Method**: `GET`
- **Path**: `/v1/mappings/providers/{provider}/connections/{connectionId}/status`
- **FQDN**: `https://mappings.api.d-bis.org/v1/mappings/providers/{provider}/connections/{connectionId}/status`
- **Description**: Get connection status for a provider
- **Path Parameters**: `provider`, `connectionId`

#### List Providers
- **Method**: `GET`
- **Path**: `/v1/mappings/providers`
- **FQDN**: `https://mappings.api.d-bis.org/v1/mappings/providers`
- **Description**: List all available providers

### WEB3-ETH-IBAN

#### Convert Address to IBAN
- **Method**: `POST`
- **Path**: `/v1/mappings/web3/address-to-iban`
- **FQDN**: `https://mappings.api.d-bis.org/v1/mappings/web3/address-to-iban`
- **Description**: Convert Ethereum address to WEB3-ETH-IBAN format

#### Convert IBAN to Address
- **Method**: `POST`
- **Path**: `/v1/mappings/web3/iban-to-address`
- **FQDN**: `https://mappings.api.d-bis.org/v1/mappings/web3/iban-to-address`
- **Description**: Convert WEB3-ETH-IBAN to Ethereum address

#### Validate IBAN
- **Method**: `POST`
- **Path**: `/v1/mappings/web3/validate-iban`
- **FQDN**: `https://mappings.api.d-bis.org/v1/mappings/web3/validate-iban`
- **Description**: Validate IBAN format and extract Ethereum address

#### Validate Address
- **Method**: `POST`
- **Path**: `/v1/mappings/web3/validate-address`
- **FQDN**: `https://mappings.api.d-bis.org/v1/mappings/web3/validate-address`
- **Description**: Validate Ethereum address format and checksum

### Health Check

#### Health Check
- **Method**: `GET`
- **Path**: `/health`
- **FQDN**: `https://mappings.api.d-bis.org/health`
- **Description**: Health check endpoint

---

## Webhook Service

Base Path: `/v1/webhooks`

### Webhook Management

#### Create Webhook
- **Method**: `POST`
- **Path**: `/v1/webhooks`
- **FQDN**: `https://webhooks.api.d-bis.org/v1/webhooks`
- **Description**: Create a new webhook subscription

#### List Webhooks
- **Method**: `GET`
- **Path**: `/v1/webhooks`
- **FQDN**: `https://webhooks.api.d-bis.org/v1/webhooks`
- **Description**: List all webhook subscriptions
- **Query Parameters**: `limit`, `offset`

#### Get Webhook
- **Method**: `GET`
- **Path**: `/v1/webhooks/{id}`
- **FQDN**: `https://webhooks.api.d-bis.org/v1/webhooks/{id}`
- **Description**: Get webhook details by ID
- **Path Parameters**: `id` (webhook identifier)

#### Update Webhook
- **Method**: `PATCH`
- **Path**: `/v1/webhooks/{id}`
- **FQDN**: `https://webhooks.api.d-bis.org/v1/webhooks/{id}`
- **Description**: Update webhook configuration
- **Path Parameters**: `id` (webhook identifier)

#### Delete Webhook
- **Method**: `DELETE`
- **Path**: `/v1/webhooks/{id}`
- **FQDN**: `https://webhooks.api.d-bis.org/v1/webhooks/{id}`
- **Description**: Delete a webhook subscription
- **Path Parameters**: `id` (webhook identifier)

#### Test Webhook
- **Method**: `POST`
- **Path**: `/v1/webhooks/{id}/test`
- **FQDN**: `https://webhooks.api.d-bis.org/v1/webhooks/{id}/test`
- **Description**: Send a test event to the webhook
- **Path Parameters**: `id` (webhook identifier)

#### Replay Webhooks
- **Method**: `POST`
- **Path**: `/v1/webhooks/{id}/replay`
- **FQDN**: `https://webhooks.api.d-bis.org/v1/webhooks/{id}/replay`
- **Description**: Replay webhook deliveries since a timestamp
- **Path Parameters**: `id` (webhook identifier)
- **Query Parameters**: `since` (optional ISO timestamp)

#### Get Delivery Attempts
- **Method**: `GET`
- **Path**: `/v1/webhooks/{id}/attempts`
- **FQDN**: `https://webhooks.api.d-bis.org/v1/webhooks/{id}/attempts`
- **Description**: Get delivery attempt history for a webhook
- **Path Parameters**: `id` (webhook identifier)

### Dead Letter Queue (DLQ)

#### Get DLQ Entries
- **Method**: `GET`
- **Path**: `/v1/webhooks/dlq`
- **FQDN**: `https://webhooks.api.d-bis.org/v1/webhooks/dlq`
- **Description**: Get entries from the dead letter queue
- **Query Parameters**: `limit`, `offset`

#### Retry DLQ Entry
- **Method**: `POST`
- **Path**: `/v1/webhooks/dlq/{id}/retry`
- **FQDN**: `https://webhooks.api.d-bis.org/v1/webhooks/dlq/{id}/retry`
- **Description**: Retry a failed webhook delivery from the DLQ
- **Path Parameters**: `id` (DLQ entry identifier)

### Health Check

#### Health Check
- **Method**: `GET`
- **Path**: `/health`
- **FQDN**: `https://webhooks.api.d-bis.org/health`
- **Description**: Health check endpoint

---

## Orchestrator Service

Base Path: `/v1/orchestrator`

### Trigger Management

#### Get Trigger
- **Method**: `GET`
- **Path**: `/v1/orchestrator/triggers/{triggerId}`
- **FQDN**: `https://orchestrator.api.d-bis.org/v1/orchestrator/triggers/{triggerId}`
- **Description**: Get trigger details by ID
- **Path Parameters**: `triggerId` (64-char hex string)

#### List Triggers
- **Method**: `GET`
- **Path**: `/v1/orchestrator/triggers`
- **FQDN**: `https://orchestrator.api.d-bis.org/v1/orchestrator/triggers`
- **Description**: List payment rail triggers with filtering
- **Query Parameters**: `state`, `rail`, `accountRef`, `walletRef`, `limit`, `offset`

#### Validate and Lock Trigger
- **Method**: `POST`
- **Path**: `/v1/orchestrator/triggers/{triggerId}/validate-and-lock`
- **FQDN**: `https://orchestrator.api.d-bis.org/v1/orchestrator/triggers/{triggerId}/validate-and-lock`
- **Description**: Orchestrator step - validate trigger and lock funds
- **Path Parameters**: `triggerId` (64-char hex string)

#### Mark Trigger Submitted
- **Method**: `POST`
- **Path**: `/v1/orchestrator/triggers/{triggerId}/mark-submitted`
- **FQDN**: `https://orchestrator.api.d-bis.org/v1/orchestrator/triggers/{triggerId}/mark-submitted`
- **Description**: Mark trigger as submitted to rail (includes railTxRef)
- **Path Parameters**: `triggerId` (64-char hex string)

#### Confirm Trigger Settled
- **Method**: `POST`
- **Path**: `/v1/orchestrator/triggers/{triggerId}/confirm-settled`
- **FQDN**: `https://orchestrator.api.d-bis.org/v1/orchestrator/triggers/{triggerId}/confirm-settled`
- **Description**: Confirm trigger has settled on the rail
- **Path Parameters**: `triggerId` (64-char hex string)

#### Confirm Trigger Rejected
- **Method**: `POST`
- **Path**: `/v1/orchestrator/triggers/{triggerId}/confirm-rejected`
- **FQDN**: `https://orchestrator.api.d-bis.org/v1/orchestrator/triggers/{triggerId}/confirm-rejected`
- **Description**: Confirm trigger was rejected on the rail
- **Path Parameters**: `triggerId` (64-char hex string)

### ISO-20022 Router

#### ISO Router Endpoints
- **Base Path**: `/v1/iso`
- **FQDN**: `https://orchestrator.api.d-bis.org/v1/iso`
- **Description**: ISO-20022 message routing endpoints (internal use)

### Health Check

#### Health Check
- **Method**: `GET`
- **Path**: `/health`
- **FQDN**: `https://orchestrator.api.d-bis.org/health`
- **Description**: Health check endpoint

---

## Packet Service

Base Path: `/v1/packets`

### Packet Management

#### Generate Packet
- **Method**: `POST`
- **Path**: `/v1/packets`
- **FQDN**: `https://packets.api.d-bis.org/v1/packets`
- **Description**: Generate a non-scheme integration packet (PDF + sidecars)

#### List Packets
- **Method**: `GET`
- **Path**: `/v1/packets`
- **FQDN**: `https://packets.api.d-bis.org/v1/packets`
- **Description**: List packets with optional filtering
- **Query Parameters**: `triggerId`, `status`, `channel`, `limit`, `offset`

#### Get Packet
- **Method**: `GET`
- **Path**: `/v1/packets/{packetId}`
- **FQDN**: `https://packets.api.d-bis.org/v1/packets/{packetId}`
- **Description**: Get packet metadata
- **Path Parameters**: `packetId` (64-char hex string)

#### Download Packet
- **Method**: `GET`
- **Path**: `/v1/packets/{packetId}/download`
- **FQDN**: `https://packets.api.d-bis.org/v1/packets/{packetId}/download`
- **Description**: Download packet file (PDF, XML, etc.)
- **Path Parameters**: `packetId` (64-char hex string)

#### Dispatch Packet
- **Method**: `POST`
- **Path**: `/v1/packets/{packetId}/dispatch`
- **FQDN**: `https://packets.api.d-bis.org/v1/packets/{packetId}/dispatch`
- **Description**: Dispatch packet via email/AS4/portal
- **Path Parameters**: `packetId` (64-char hex string)

#### Acknowledge Packet
- **Method**: `POST`
- **Path**: `/v1/packets/{packetId}/ack`
- **FQDN**: `https://packets.api.d-bis.org/v1/packets/{packetId}/ack`
- **Description**: Record an acknowledgement/receipt for a packet
- **Path Parameters**: `packetId` (64-char hex string)

### Health Check

#### Health Check
- **Method**: `GET`
- **Path**: `/health`
- **FQDN**: `https://packets.api.d-bis.org/health`
- **Description**: Health check endpoint

---

## Authentication

All endpoints require authentication unless otherwise specified. The API supports:

- **OAuth2** (Client Credentials flow) - Primary authentication method
- **mTLS** - For high-trust adapters (ISO inbound endpoints)
- **API Key** - For internal services (optional)

### Required Roles

- `TOKEN_DEPLOYER` - Deploy new tokens
- `ISSUER` - Mint and burn tokens
- `ENFORCEMENT` - Clawback and force transfer
- `DEBT_AUTHORITY` - Manage liens
- `COMPLIANCE` - Manage compliance registry
- `POLICY_OPERATOR` - Configure token policies and manage triggers
- `BRIDGE_OPERATOR` - Manage bridge operations

---

## Request/Response Format

- **Content-Type**: `application/json`
- **Response Format**: JSON
- **Error Format**: 
  ```json
  {
    "code": "ERROR_CODE",
    "message": "Human-readable error message",
    "reasonCode": "REASON_CODE",
    "details": {},
    "requestId": "request-id"
  }
  ```

---

## Rate Limiting

Rate limits are applied per API key/client credentials. Contact support for rate limit information.

---

## Versioning

All endpoints are versioned using the `/v1` prefix. Future versions will use `/v2`, `/v3`, etc.

---

## Support

For API support, contact: api-support@d-bis.org

---

**Last Updated**: 2024-01-XX  
**API Version**: 1.0.0