# ModuleCrafter WA API v4

ModuleCrafter WA has two trust boundaries:

- customer/sender APIs under `/api`
- privileged seller provisioning under `/provisioning/v4`

## Worldwide phone-number handling

The gateway normalizes destinations with international phone metadata.

- International numbers work directly: `+15551234567`, `+2348031234567`, `+8801712345678`.
- `00` international prefixes are accepted, for example `0015551234567`.
- Local/national numbers must include an ISO 3166-1 alpha-2 country hint such as `US`, `NG`, `GB`, `KE`, `ZA`, `IN` or `BD`.
- The WHMCS Sender addon supplies the client's stored WHMCS country automatically, so there is no global Default Country Code setting.

Example local number through the public API:

```json
{
  "channel_id": "01...",
  "to": "08031234567",
  "country": "NG",
  "type": "text",
  "payload": { "text": "Hello" }
}
```

For arbitrary manual sends where no country context exists, use international `+` format. A local number cannot be safely assigned to a country from its digits alone.

## Customer API

Base:

```text
https://wa.modulecrafter.com/api
```

Authentication:

```http
Authorization: Bearer mcwa_...
```

### Send a message

```http
POST /api/v1/messages
Idempotency-Key: stable-operation-id
```

Text:

```json
{
  "channel_id": "01...",
  "to": "+15551234567",
  "type": "text",
  "payload": { "text": "Hello" }
}
```

Document/PDF by public URL:

```json
{
  "channel_id": "01...",
  "to": "+2348031234567",
  "type": "document",
  "payload": {
    "url": "https://example.com/invoice.pdf",
    "filename": "Invoice-1001.pdf",
    "mimetype": "application/pdf",
    "caption": "Your invoice is attached."
  }
}
```

Private document/PDF by base64:

```json
{
  "channel_id": "01...",
  "to": "+442079460958",
  "type": "document",
  "payload": {
    "data_base64": "JVBERi0xLjQ...",
    "filename": "Invoice-1001.pdf",
    "mimetype": "application/pdf",
    "caption": "Your invoice is attached."
  }
}
```

Inline media is MIME/size checked, written to private temporary storage, queued through the normal quota path, and cleaned after processing. The base64 body is never returned in message API responses.

Supported media message types: `image`, `video`, `audio`, `document`. Provider-specific restrictions still apply.

### Campaign recipient formats

Campaign APIs accept worldwide recipients as either:

```json
[
  "+15551234567",
  "NG:08031234567",
  { "phone": "020 7946 0958", "country": "GB", "variables": { "name": "Sam" } }
]
```

The `CC:number` shorthand uses a two-letter ISO country code.

### Official Meta template

```json
{
  "channel_id": "01...",
  "to": "+919876543210",
  "type": "template",
  "payload": {
    "name": "invoice_due",
    "language": "en_US",
    "components": []
  }
}
```

## Restricted WHMCS Sender API v4

Connection/status:

```text
GET  /api/v4/whmcs/status
POST /api/v4/whmcs/test-connection
```

Send text:

```http
POST /api/v4/whmcs/send
Authorization: Bearer mcwa_...
Idempotency-Key: invoice-1001-paid
```

```json
{
  "event": "invoice.paid",
  "to": "08031234567",
  "country": "NG",
  "message": "Invoice #1001 is paid."
}
```

The included WHMCS addon fills `country` from `tblclients.country` automatically.

Send a private PDF:

```json
{
  "event": "invoice.created",
  "to": "+15551234567",
  "type": "document",
  "message": "Your invoice is attached.",
  "media": {
    "data_base64": "JVBERi0xLjQ...",
    "filename": "Invoice-1001.pdf",
    "mimetype": "application/pdf"
  }
}
```

Supported WHMCS sender types: `text`, `template`, `image`, `video`, `audio`, `document`.

Allowed event labels:

```text
invoice.created
invoice.paid
invoice.unpaid
invoice.overdue
order.created
order.paid
service.activated
service.suspended
service.unsuspended
service.terminated
custom
```

The v2/v3 sender routes remain for compatibility. New integrations should use v4.

## API/request diagnostics

The dashboard **Logs** page records API request outcome, HTTP status, endpoint, request ID, API key label, duration and sanitized failure reason. It does not store Authorization headers, request bodies, message contents or raw tokens.

Customers can clear their visible API logs and terminal message history. This does not reset quota and does not delete queued/sending work. Platform admins can view cross-account system logs, clear one customer's operational logs, or clear platform-wide customer operational history. Queued/sending work and security audit records are retained. Security/admin audit records are intentionally separate.

## Seller / WHMCS provisioning API v4

Base:

```text
https://wa.modulecrafter.com/provisioning/v4
```

Required headers:

```http
X-MC-Timestamp: <unix-seconds>
X-MC-Nonce: <random-one-time-value>
X-MC-Signature: sha256=<hex-hmac>
Content-Type: application/json
```

Canonical signature input:

```text
timestamp + "." + nonce + "." + rawJsonBody
```

Algorithm:

```text
HMAC-SHA256(PROVISIONING_SECRET, canonicalInput)
```

The v4 contract rejects nonce replay inside the allowed timestamp window.

Endpoints:

```text
GET    /health
GET    /plans
POST   /services
GET    /services/<externalServiceId>
PATCH  /services/<externalServiceId>
POST   /services/<externalServiceId>/suspend
POST   /services/<externalServiceId>/unsuspend
POST   /services/<externalServiceId>/terminate
POST   /services/<externalServiceId>/login-token
POST   /services/<externalServiceId>/password
```

All text/media/WHMCS sends use the same queue, entitlement, provider-permission, idempotency and usage-quota enforcement.