# TheAPI — REST API v1 Reference

> Markdown reference for the **TheAPI REST API v1** — the REST interface of [theapi.ro](https://theapi.ro/).
> Interactive docs (Postman): <https://documenter.getpostman.com/view/54562521/2sBY4HUjLg>

---

## 1. Basics

- **Base URL:** `https://theapi.ro/api/vs1`
- **Formats:** every endpoint requires an explicit extension — `.json` or `.xml` (requests without one are rejected with `406 Not Acceptable`).
- **Methods:** standard HTTP verbs (`GET`, `POST`, `PUT`, `DELETE`).
- **Response envelope:**

```json
{
    "status": 200,
    "data": { ... },
    "total": 42
}
```

`total` is present on paginated lists. On errors the envelope carries `message` and/or `errors`:

| HTTP | Meaning |
|------|---------|
| 400 | Validation error (`message`, `errors` per field) |
| 401 | Missing/invalid credentials or JWT token |
| 406 | Missing `.json` / `.xml` extension |

- **Pagination & sorting** (list endpoints): `limit` (default 20, max 100 — GeoEntities up to 1000), `page`, `sort`, `direction`.
  Alternatively `format=list` returns a flat key/value map, configurable via `keyField` / `valueField`.
- **Usage** is subject to your subscription plan limits.

## 2. Authentication

1. [Create your free account](https://theapi.ro/register) and set up a **project** — each project has its own API credentials.
2. Exchange the credentials for a **JWT token** (valid **7 days**):

```bash
curl -X POST https://theapi.ro/api/vs1/admins/login.json \
  -H "Content-Type: application/json" \
  -d '{"email": "project@example.com", "password": "secret"}'
```

```json
{
    "status": 200,
    "data": {
        "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
        "expire": { "timestamp": 1720000000, "datetime": "...", "string": "+7 days" }
    }
}
```

3. Send the token on every request:

```bash
curl "https://theapi.ro/api/vs1/regcom-companies/view/36145517.json" \
  -H "Authorization: Bearer {{token}}"
```

All endpoints require authentication unless marked **public**.

---

## 3. Resources

### 3.1 Hello — public

| Endpoint | Verb | Description |
|----------|------|-------------|
| `/hello.json` | GET | Ping / status: version, PHP/CakePHP version, timestamp, supported auth & formats |

### 3.2 Account

| Endpoint | Verb | Description |
|----------|------|-------------|
| `/admins/login.json` | POST | Obtain JWT token (body: `email`, `password`) |
| `/admins/view.json` | GET | Current account details, incl. subscription |

### 3.3 Romanian companies

Company data from the ANAF / Trade Register (Reg.Com.), continuously synchronized.

| Endpoint | Verb | Description |
|----------|------|-------------|
| `/regcom-companies.json` | GET | Paginated list. Filters: `term` (name), `date_from`, `date_until` |
| `/regcom-companies/view/{cui}.json` | GET | Full company details by CUI/CIF. `?refresh=1` forces a live ANAF re-check (max once per day per CUI). Unknown CUIs are looked up live (ANAF, with fallback) |
| `/regcom-companies/search.json` | GET | Smart search: `term` = CUI/CIF **or** company name (full-text). Optional `is_fiscal_active=1`, `limit` (max 25) |

Both `view` and `search` return the same compact company shape: `cui`, `cif`, `name`, `reg_com`; VAT flags (`is_vat_payer`, `is_vat_on_collection`, `is_split_vat`); registration status (`status_int`, `status_string`, `status_date`); a formatted `address` plus a structured breakdown (`address_county`, `address_county_iso`, `address_locality`, `address_street`, `address_no`, `address_details`, `address_zip_code`); and `interogation_date` / `is_checked`.

### 3.4 Exchange rates (BNR)

Official National Bank of Romania rates, with history.

| Endpoint | Verb | Description |
|----------|------|-------------|
| `/currency-rates/get-rate.json` | GET | Latest rate set for a date: `date` (`Y-m-d`, default today — returns the most recent publication ≤ date), `currency_iso` (CSV filter, e.g. `EUR,USD`) |
| `/currencies.json` | GET | Active currencies with their latest value/multiplier |

### 3.5 Geography (Romania)

Counties, municipalities, towns, communes and villages (`adm1`/`adm2` hierarchy).

| Endpoint | Verb | Description |
|----------|------|-------------|
| `/geo-entities.json` | GET | Paginated list. Filters: `term` (full-text), `level` (`1` = counties, `2` = their direct children), `adm1`, `adm2`, `is_adm` |
| `/geo-entities/all.json` | GET | All counties with all their localities |
| `/geo-entities/view/{id}.json` | GET | Single entity (name, type, coordinates, population, timezone…) |

### 3.6 Countries & timezones

| Endpoint | Verb | Description |
|----------|------|-------------|
| `/countries.json` · `/countries/view/{id}.json` | GET | World countries: ISO/ISO3 codes, continent, currency, phone prefix, postal code format, EU flag |
| `/timezones.json` · `/timezones/view/{id}.json` | GET | Timezones with GMT/DST/raw offsets |

### 3.7 IP addresses

| Endpoint | Verb | Description |
|----------|------|-------------|
| `/ip-addresses/info/{ip}.json` | GET | Geolocation for an IP (also `?ip=`; defaults to the caller's IP): city, region, country, coordinates, organization, ASN, timezone, bogon flag |

### 3.8 IBAN

| Endpoint | Verb | Description |
|----------|------|-------------|
| `/ibans/verify.json?iban={iban}` | GET | Validates an IBAN. Valid → machine/human/obfuscated formats + parts (country, bank, account, SEPA/SWIFT flags). Invalid → `400` with checksum analysis and mistranscription suggestions |

---

*This is a concise v1 reference; endpoints will be documented in more detail over time. For request/response samples use the [Postman documentation](https://documenter.getpostman.com/view/54562521/2sBY4HUjLg).*