# RAYNET konektor – vytvoření firmy

Stateless proxy nad [RAYNET CRM API v2](https://app.raynetcrm.com/api/doc/index-en.html).

## Autentizace RAYNET

RAYNET API používá:

- **HTTP Basic Auth**: username = email uživatele, password = **API klíč**
- hlavičku **`X-Instance-Name`** = název instance
- base URL: `https://app.raynet.cz/api/v2`

V této službě se **API klíč (secret) předává hlavičkou `X-Api-Key`**. Email a název
instance jsou běžné identifikátory a předávají se v těle požadavku.

> Secret se nikdy neloguje, necommituje ani nevrací z endpointů (viz AGENTS.md).

## Endpoint

```text
POST /company
```

Veřejně přes AppFactory reverse proxy:

```text
POST https://services.csbot.cz/apps/<app-id>/company
```

### Hlavičky

| Hlavička     | Povinná | Popis                         |
|--------------|---------|-------------------------------|
| `X-Api-Key`  | ano     | RAYNET API klíč (secret)      |

### Tělo požadavku

```json
{
  "email": "user@firma.cz",
  "instance_name": "moje-instance",
  "company": {
    "name": "ACME s.r.o.",
    "rating": "A",
    "state": "A_POTENTIAL",
    "role": "A_SUBSCRIBER",
    "regNumber": "12345678",
    "taxNumber": "CZ12345678",
    "taxPayer": "YES",
    "addresses": [
      {
        "address": {
          "name": "Sídlo klienta",
          "street": "Francouzská 6167/5",
          "city": "Ostrava",
          "province": "Morava",
          "zipCode": "708 00",
          "country": "CZ"
        },
        "contactInfo": {
          "email": "info@acme.cz",
          "tel1": "+420 553 401 520",
          "tel1Type": "recepce",
          "www": "www.acme.cz"
        }
      }
    ],
    "tags": ["import", "konektor"]
  }
}
```

#### Povinná pole firmy

| Pole     | Typ    | Hodnoty                                                        |
|----------|--------|---------------------------------------------------------------|
| `name`   | string | název firmy                                                   |
| `rating` | enum   | `A`, `B`, `C`                                                 |
| `state`  | enum   | `A_POTENTIAL`, `B_ACTUAL`, `C_DEFERRED`, `D_UNATTRACTIVE`     |
| `role`   | enum   | `A_SUBSCRIBER`, `B_PARTNER`, `C_SUPPLIER`, `D_RIVAL`          |

Volitelná pole: `regNumber` (IČO), `taxNumber` (DIČ), `taxPayer` (`YES`/`NO`),
`bankAccount`, `notice`, `owner`, `category`, `legalForm`, `paymentTerm`,
`turnover`, `territory`, `addresses`, `tags`, `customFields` a další dle
RAYNET `CompanyInsertDto`. Neuvedená/`null` pole se do RAYNET neposílají.

### Odpověď (200)

```json
{
  "id": 123456,
  "success": true,
  "raw": { "...": "surová odpověď RAYNET" }
}
```

### Chybové stavy

| HTTP | Kdy                                                        |
|------|------------------------------------------------------------|
| 400  | RAYNET odmítl data (nevalidní vstup)                       |
| 401  | chybný API klíč / email / instance (autentizace selhala)  |
| 422  | nevalidní tělo požadavku (FastAPI validace)               |
| 502  | RAYNET nedostupný / chyba serveru / timeout               |

## Použití konektoru přímo v Pythonu

```python
from app.raynet_client import RaynetClient, RaynetError

client = RaynetClient(api_key="...", email="user@firma.cz", instance_name="moje-instance")
try:
    company = client.create_company({
        "name": "ACME s.r.o.",
        "rating": "A",
        "state": "A_POTENTIAL",
        "role": "A_SUBSCRIBER",
    })
    print(company["id"])
except RaynetError as exc:
    print("Chyba:", exc.message, exc.status_code)
```

`RaynetClient` drží `requests.Session` (Basic Auth + `X-Instance-Name`),
automaticky opakuje přechodné chyby (síť, 429, 5xx) a vyhazuje typované
výjimky `RaynetAuthError` / `RaynetValidationError` / `RaynetError`.

## Ověření po nasazení

```text
GET  https://services.csbot.cz/apps/<app-id>/health
GET  https://services.csbot.cz/apps/<app-id>/docs
POST https://services.csbot.cz/apps/<app-id>/company   (Swagger „Try it out")
```