RAYNET konektor

Stateless proxy nad RAYNET CRM API v2. 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`

{
  "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

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í

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.

5.8 KiB Raw Blame History Unescape Escape