2

2026-06-18 15:11:49 +02:00
parent 28596fe772
commit a5795fe344
5 changed files with 405 additions and 200 deletions
@@ -0,0 +1,152 @@
+# RAYNET konektor
+
+Stateless proxy nad [RAYNET CRM API v2](https://app.raynetcrm.com/api/doc/index-en.html).
+Pokrývá celé RAYNET API díky jednotným REST konvencím.
+
+## Přihlášení (společné pro celé připojení)
+
+RAYNET API používá HTTP Basic Auth (email + API klíč) a hlavičku s názvem
+instance. V této službě se předává **třemi hlavičkami u každého requestu**:
+
+| Hlavička              | Co to je          | Kde to vzít |
+|-----------------------|-------------------|-------------|
+| `X-Api-Key`           | API klíč (secret) | RAYNET CRM: **Nastavení → Klíč k API** |
+| `X-Raynet-Email`      | Email uživatele   | Přihlašovací email do RAYNET |
+| `X-Instance-Name`     | Název instance    | Identifikátor instance (subdoména účtu) |
+
+> `X-Api-Key` je secret – nikdy se neloguje, necommituje ani nevrací z endpointů
+> (viz AGENTS.md). Tyto údaje jsou zobrazené i nahoře ve Swaggeru (`/docs`).
+
+Base URL RAYNET: `https://app.raynet.cz/api/v2`.
+
+## REST konvence RAYNET (platí pro celé API)
+
+| Operace | RAYNET metoda + cesta        |
+|---------|------------------------------|
+| List    | `GET /{resource}/`           |
+| Detail  | `GET /{resource}/{id}/`      |
+| Create  | `PUT /{resource}/`           |
+| Update  | `POST /{resource}/{id}/`     |
+| Delete  | `DELETE /{resource}/{id}/`   |
+
+Příklady entit: `company`, `person`, `lead`, `businessCase`, `activity`,
+`product`, `offer`, `order`, `project`, …
+
+## Endpointy služby
+
+Veřejně přes AppFactory reverse proxy: `https://services.csbot.cz/apps/<app-id>/...`
+
+### Typované zkratky pro firmy
+
+| Metoda | Cesta                   | Popis                         |
+|--------|-------------------------|-------------------------------|
+| POST   | `/company`              | Vytvoří firmu (validace)      |
+| GET    | `/company`              | Seznam firem (offset/limit/fulltext) |
+| GET    | `/company/{id}`         | Detail firmy                  |
+| PUT    | `/company/{id}`         | Úprava firmy                  |
+| DELETE | `/company/{id}`         | Smazání firmy                 |
+
+### Generický průchod na celé API
+
+| Metoda | Cesta                       | Mapuje se na RAYNET           |
+|--------|-----------------------------|-------------------------------|
+| GET    | `/api/{resource}`           | `GET /{resource}/` (query params se předávají) |
+| GET    | `/api/{resource}/{id}`      | `GET /{resource}/{id}/`       |
+| POST   | `/api/{resource}`           | `PUT /{resource}/` (create)   |
+| PUT    | `/api/{resource}/{id}`      | `POST /{resource}/{id}/` (update) |
+| DELETE | `/api/{resource}/{id}`      | `DELETE /{resource}/{id}/`    |
+
+## Vytvoření firmy – povinná pole
+
+| 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á: `regNumber` (IČO), `taxNumber` (DIČ), `taxPayer` (`YES`/`NO`),
+`bankAccount`, `notice`, `owner`, `category`, `legalForm`, `paymentTerm`,
+`turnover`, `territory`, `addresses`, `tags`, `customFields` a další dle
+RAYNET `CompanyInsertDto`.
+
+### Příklad těla `POST /company`
+
+```json
+{
+  "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"]
+}
+```
+
+## Chybové stavy
+
+| HTTP | Kdy                                                       |
+|------|-----------------------------------------------------------|
+| 400  | RAYNET odmítl data (nevalidní vstup)                      |
+| 401  | chybný API klíč / email / instance (autentizace selhala) |
+| 422  | nevalidní vstup (FastAPI validace nebo chybí povinné pole)|
+| 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:
+    # pojmenovaná zkratka
+    company = client.create_company({
+        "name": "ACME s.r.o.", "rating": "A",
+        "state": "A_POTENTIAL", "role": "A_SUBSCRIBER",
+    })
+
+    # generické CRUD nad libovolnou entitou
+    leads = client.list_records("lead", {"limit": 50})
+    deal = client.get_record("businessCase", 123)
+    client.update_record("person", 42, {"lastName": "Novák"})
+
+    # speciální akce / vnořené zdroje
+    client.call("POST", f"/company/{company['id']}/lock")
+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
+```
+
+Ve Swagger UI ověř, že `Try it out` volá endpointy přes `/apps/<app-id>` a že
+jsou vyžadované hlavičky `X-Api-Key`, `X-Raynet-Email`, `X-Instance-Name`.
+```