appfactory/raynet
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

2

Browse Source
This commit is contained in:
JiriUhlir
2026-06-18 15:11:49 +02:00
parent 28596fe772
commit a5795fe344
5 changed files with 405 additions and 200 deletions
Download Patch File Download Diff File Expand all files Collapse all files
documentation/raynet-company.md
-134
View File
@@ -1,134 +0,0 @@
# 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")
```
documentation/raynet-connector.md
+152
View File
@@ -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`.
```