first

2026-06-18 14:49:29 +02:00
parent 6529893f38
commit 28596fe772
5 changed files with 573 additions and 5 deletions
@@ -0,0 +1,134 @@
+# 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")
+```