# ISPbills Public API v2

Base URL: `https://app.ispbills.com/api/v2`

- [OpenAPI 3.1 contract](https://ispbills.com/openapi.json)
- [API catalog](https://ispbills.com/.well-known/api-catalog)
- [API Management](https://ispbills.com/docs/en/api_management/)
- [Pricing](https://ispbills.com/pricing/) and [support](https://ispbills.com/support/)

The contract covers 35 implemented operations: authentication, customers,
billing, packages, network inventory, monitoring, SMS, VPN and webhook
registrations. It describes API v2, not the browser-session payment checkout.
Request schemas are derived from route validation. Most success-response
resource fields are intentionally not fully modeled; do not generate strict
response validators from inferred field types.

## Access and authentication

An ISP account owner provisions an API client in API Management and securely
supplies its client ID and secret. There is no anonymous client registration.
API credentials do not grant access to another operator's records. The
documentation is public; API data and the interactive console remain protected.

Exchange the credentials using JSON:

```http
POST /api/v2/auth/token
Accept: application/json
Content-Type: application/json

{"client_id":"your-client-id","client_secret":"your-client-secret"}
```

A successful response contains `access_token` (an opaque 64-character string),
`token_type` (`Bearer`) and `scopes` (an array). This exchange generates a new
token, rather than returning the current one. Use
`Authorization: Bearer <token>` and `Accept: application/json` on protected
requests. Do not put credentials in URLs, logs, prompts or committed examples.
This is a custom client-credential exchange, not a general OAuth
authorization-code, delegated-identity or dynamic-registration service.

Customer operations enforce `customers:read` or `customers:write`; SMS sending
enforces `sms:send`. Other v2 operations currently require a valid client but
do not enforce separate per-operation scopes. A declared scope is not evidence
that every endpoint enforces it.

`POST /auth/revoke` clears the stored token. Authentication caches client
records for up to 300 seconds, so revocation, replacement or disabling a client
must not be treated as instantaneous invalidation.

## Rate limits and errors

The shared API throttle allows 60 requests per minute per authenticated user
or IP. Protected v2 endpoints also apply the API client's configured
requests-per-minute limit in a fixed minute window.

| Status | Meaning and handling |
|---|---|
| 401 | Missing/invalid token or invalid client credentials; JSON `{"error":"Unauthorized"}`. |
| 403 | Insufficient scope on scope-enforced operations; do not retry unchanged. |
| 404 | Resource not found in the request's permitted scope. |
| 422 | Invalid input. Laravel validation returns `message` and field-keyed `errors`; some controller checks instead return `error`. |
| 429 | Rate limit exceeded; wait before retrying. |
| 500 | Server failure; a write's outcome may be ambiguous. Reconcile before retrying. |

The per-client 429 body is
`{"error":"Too Many Requests","retry_after":42}`. Its `retry_after` is seconds
until the next minute window; that limiter does not set a `Retry-After` header.
The shared throttle can instead return `message` and a `Retry-After` header.
Handle both formats, apply bounded backoff and jitter, and avoid retry storms.

## Pagination

Paginated operations accept `page` and `per_page`, with a maximum page size of
100. Start at page 1 and use a positive page size. Customers and billing default
to 20; packages and ONUs default to 50. Collection envelopes vary by endpoint;
the customer list exposes `data`, `total`, `page` and `last_page`. Follow the
returned pagination metadata rather than assuming every list is paginated.

Example read: `GET /customers?page=1&per_page=20` with a Bearer token.

## Idempotency, dry runs and reversibility

There is no general `Idempotency-Key` contract and no API-wide dry-run mode.
Do not blindly retry customer/bill creation, SMS sending or webhook registration
after a timeout: first inspect the result using permitted reads. Repeated token
exchange also changes the stored token.

Customer and bill deletion are destructive. Confirm the scoped resource with a
read before deletion; no API undelete is documented. Updating a record is not a
guaranteed reversal of all side effects. SMS messages cannot be recalled.
Disabling or deleting a webhook registration stops subsequent eligible delivery
attempts but cannot undo a request already delivered.

## Webhook delivery: implemented transport, unwired event producers

Webhook registration CRUD and a queued delivery implementation exist. Automatic
business-event producers are not currently wired to that delivery service.
Registering names such as `payment.received` does **not** establish that those
events will be emitted. Confirm an implemented producer before relying on event
delivery; do not assume an event catalog, stable event ID or ordering guarantee.

When the service is explicitly invoked, it wraps data as `event`, `timestamp`
and `data`, then sends JSON with `X-Webhook-Event` and
`X-Webhook-Signature: sha256=<hex>`. Verify HMAC-SHA256 against the exact raw
request body using the stored secret and a constant-time comparison. Parsing
and re-encoding JSON before verification can change the signature.

The delivery job allows three attempts with configured backoff values
30/60/120 seconds and a 15-second HTTP timeout. Receivers should acknowledge
promptly and process duplicate deliveries safely. A signature authenticates the
body but does not by itself prevent replay; no stable delivery ID is supplied.
Use an HTTPS receiver. The current worker disables outbound TLS certificate
verification, so verified transport hardening remains outstanding.
