# NonVoipUsNumber API Full AI Integration Guide

This file gives AI agents and app builders enough context to create web applications that use the NonVoipUsNumber API correctly. The machine-readable source of truth is the OpenAPI document at https://nonvoipusnumber.com/manager/api-docs/openapi.json.

## Canonical Links

- OpenAPI JSON: https://nonvoipusnumber.com/manager/api-docs/openapi.json
- Static OpenAPI JSON: https://nonvoipusnumber.com/manager/openapi.json
- Human API docs: https://nonvoipusnumber.com/manager/api-docs
- Swagger UI: https://nonvoipusnumber.com/manager/api-docs/swagger
- Robots file: https://nonvoipusnumber.com/robots.txt
- Sitemap: https://nonvoipusnumber.com/sitemap.xml

## Base URL And Request Format

- Base URL: `https://nonvoipusnumber.com/manager`
- All documented API paths are under `/api`.
- All documented external API endpoints use `POST`.
- Supported request formats: JSON, URL-encoded form, and multipart form data.
- Recommended format for new applications: `Content-Type: application/json`.
- Authentication: send `email` and `password` in the body of every API request unless the endpoint explicitly says otherwise.
- Rate limit headers may be present: `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and `X-RateLimit-Reset`.

## Web Application Build Guidance

- Prefer a backend integration layer for production web apps. Store API credentials server-side or ask the end user to enter their own credentials securely.
- Do not hard-code account passwords in public frontend JavaScript, mobile bundles, or static pages.
- A typical web app flow is: authenticate form or stored credentials, call `/api/products`, let the user choose a product, call `/api/order`, then poll `/api/getsms` or rely on callbacks.
- For server-rendered dashboards, keep the user's API credentials in a secure server-side session or encrypted storage.
- For client-only demos, clearly ask the user for their own email and password and do not persist them unless explicitly requested.
- Always show price-change and premium-bid confirmation states to the user before retrying an order with `accepted_max_price` or `auction`.

## Endpoint Summary

### `POST /api/balance`

Returns current account balance.

Request:

```json
{
  "email": "user@example.com",
  "password": "your_password"
}
```

Success response:

```json
{
  "status": "success",
  "balance": "50.00"
}
```

### `POST /api/products`

Returns USA products, pricing, and stock. Always use returned `product_id` values for ordering.

Useful request fields:

- `grouped`: boolean. Use `true` to group products as 10-minutes, 30-days, 1-day, and legacy categories.
- `type`: optional filter. Common values are `short_term`, `long_term`, `one_day`, and `3days`.
- `id` or `product_id`: optional single-product lookup.

Grouped request:

```json
{
  "email": "user@example.com",
  "password": "your_password",
  "grouped": true
}
```

Grouped response shape:

```json
{
  "status": "success",
  "message": {
    "10-minutes": [
      {
        "product_id": 10000086,
        "name": "Instagram",
        "price": "0.36",
        "available": 6841
      }
    ],
    "30-days": [
      {
        "product_id": 9044,
        "name": "WhatsApp",
        "price": "2.00",
        "available": 100
      }
    ],
    "1-day": [
      {
        "product_id": 9441,
        "name": "Telegram",
        "price": "1.25",
        "available": 100
      }
    ]
  }
}
```

### `POST /api/order`

Places a USA order. Use `product_id` from `/api/products`.

Short-term order request:

```json
{
  "email": "user@example.com",
  "password": "your_password",
  "product_id": 10000086
}
```

Short-term success response:

```json
{
  "status": "success",
  "message": [
    {
      "order_id": 146185,
      "status": "Reserved",
      "number": "16095550123",
      "service": "Instagram",
      "expiration": 900,
      "type": "short_term"
    }
  ]
}
```

30-days multi-service request:

```json
{
  "email": "user@example.com",
  "password": "your_password",
  "product_ids": [9044, 8555]
}
```

Important order responses:

- `Price_Change_Required`: show `available_price` to the user. Retry only after the user accepts, sending `accepted_max_price`.
- `Premium_Available`: show the recommended bid to the user. Retry only after the user accepts, sending `auction`.
- `success`: store `order_id`, `number`, `service`, `type`, and expiration fields.

Price-change retry:

```json
{
  "email": "user@example.com",
  "password": "your_password",
  "product_id": 10000086,
  "accepted_max_price": 1.70
}
```

Premium-bid retry:

```json
{
  "email": "user@example.com",
  "password": "your_password",
  "product_id": 10000086,
  "auction": 20
}
```

### `POST /api/country/products`

Returns country-wise products.

Request:

```json
{
  "email": "user@example.com",
  "password": "your_password"
}
```

Response shape:

```json
{
  "status": "success",
  "message": [
    {
      "product_id": 501,
      "name": "Telegram",
      "country": "United States",
      "price": "0.45",
      "available": 120
    }
  ]
}
```

### `POST /api/country/order`

Creates a country-wise order using a `product_id` from `/api/country/products`.

```json
{
  "email": "user@example.com",
  "password": "your_password",
  "product_id": 501
}
```

### `POST /api/getsms`

Gets the latest SMS for an order. Prefer `order_id`.

```json
{
  "email": "user@example.com",
  "password": "your_password",
  "order_id": "146185"
}
```

Success response:

```json
{
  "status": "success",
  "number": "16095170503",
  "service": "Instagram",
  "sms": "Your Instagram OTP is 545",
  "pin": "545",
  "type": "short_term"
}
```

### `POST /api/reuse`

Reuses a short-term number. Prefer `order_id`; otherwise use `service` plus `number`.

```json
{
  "email": "user@example.com",
  "password": "your_password",
  "order_id": "35749684"
}
```

### `POST /api/reject`

Rejects a number before SMS is received. Prefer `order_id`.

```json
{
  "email": "user@example.com",
  "password": "your_password",
  "order_id": "146185"
}
```

### `POST /api/activate`

Activates an eligible long-term, 1-day, or 3-days number. Prefer `order_id`.

```json
{
  "email": "user@example.com",
  "password": "your_password",
  "order_id": "146187"
}
```

### `POST /api/renew`

Renews a rented number. Prefer `order_id`.

```json
{
  "email": "user@example.com",
  "password": "your_password",
  "order_id": "146187",
  "duration": "30d"
}
```

### `POST /api/saveurl`

Saves the callback URL that receives SMS and premium-bid event callbacks.

```json
{
  "url": "https://example.com/callback",
  "userId": 1234
}
```

## Callback Payloads

Incoming SMS callback:

```json
{
  "event": "incoming_message",
  "message": {
    "order_id": 454303,
    "number": "16095170503",
    "service": "Instagram",
    "sender": "8843",
    "sms": "Your Instagram OTP is 545",
    "code": "545",
    "type": "str"
  }
}
```

Premium bid winning callback:

```json
{
  "event": "auction_wining",
  "message": [
    {
      "order_id": 4545,
      "number": "16095170503",
      "service": "GMail",
      "expiration": 900
    }
  ]
}
```

## Recommended App Workflows

### Display Products And Create Order

1. Collect or load the user's API email and password.
2. Call `POST /api/products` with `grouped: true`.
3. Display product groups, names, prices, availability, and `product_id`.
4. On selection, call `POST /api/order`.
5. If success, store `order_id`, show the number, and start SMS polling or wait for callback.
6. If `Price_Change_Required`, ask the user to accept the higher `available_price`; retry with `accepted_max_price`.
7. If `Premium_Available`, ask the user to accept premium bidding; retry with `auction`.

### Poll SMS

1. Use the `order_id` from the order response.
2. Call `POST /api/getsms` periodically until an SMS is returned or the order expires.
3. Show `sms` and `pin` when available.
4. Stop polling when the order is completed, rejected, or expired.

### Callback Integration

1. Create a public HTTPS endpoint in the user's app.
2. Call `POST /api/saveurl` with that endpoint URL.
3. Parse `incoming_message` and `auction_wining` events.
4. Match callbacks to local orders by `order_id` first, then by `number` and `service`.

## Error Handling Guidance

- Treat `status: error` as a failed operation and display `message` to the user.
- Treat `status: info` as a decision state, not a final failure. `Price_Change_Required` and `Premium_Available` require user confirmation.
- Handle HTTP 429 by backing off until the rate limit reset time or retry-after interval.
- Store and use `order_id` whenever possible because service names and numbers are less reliable identifiers.

## Code Generation Notes

- Generate clients from the OpenAPI JSON, not by scraping the HTML docs.
- The server URL in OpenAPI is `https://nonvoipusnumber.com/manager`; combine it with path names such as `/api/products`.
- Prefer JSON request examples in generated code.
- Include user-facing confirmation screens for price changes and premium bids.
- Use UTC for displayed timestamps, or explicitly convert to the user's timezone in the application UI.