raynet/documentation/raynet-connector.md

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é entity

Pro každou z těchto entit existuje plné CRUD se strukturou objektu i odpovědí viditelnou ve Swaggeru (request modely, povinná pole, validace):

Cesta	Entita	Povinná pole
/company	Firma / klient	name, rating, state, role
/person	Kontaktní osoba	lastName
/lead	Lead / poptávka	topic, priority
/businessCase	Obchodní případ	name, company
/offer	Nabídka	name, company, businessCase
/salesOrder	Objednávka	name, company, businessCase
/invoice	Faktura	company, currency, dueDate, issueDate, invoiceType, paymentType, taxableSupplyDate
/product	Produkt	code, name
/priceList	Ceník	name, code, currency, validFrom
/project	Projekt	name, company
/task	Úkol	title, priority, owner, resolver, deadline
/email	E-mail (aktivita)	title, priority, owner
/event	Událost	title, priority, owner
/meeting	Schůzka	title, priority, owner
/phoneCall	Telefonát	title, priority, owner
/letter	Dopis	title, priority, owner
/webhook	Webhook	url, events

Operace u každé entity:

Metoda	Cesta	Popis
POST	/{entita}	Vytvoří záznam (validovaný objekt)
GET	/{entita}	Seznam (offset, limit, fulltext + libovolné RAYNET filtry)
GET	/{entita}/{id}	Detail
PUT	/{entita}/{id}	Částečná úprava (všechna pole volitelná)
DELETE	/{entita}/{id}	Smazání

Enumy firmy: rating = A/B/C; state = A_POTENTIAL/B_ACTUAL/C_DEFERRED/D_UNATTRACTIVE; role = A_SUBSCRIBER/B_PARTNER/C_SUPPLIER/D_RIVAL; taxPayer = YES/NO.

Pole jsou v camelCase (tak je očekává RAYNET). Nevyjmenovaná pole jsou povolená (extra="allow"), takže lze poslat i pole, která model neuvádí.

Generický průchod na zbytek API

Pro entity bez typovaného modelu – zejména uživatelé (userAccount), soubory (file), DMS dokumenty/složky, GDPR, hromadné e-maly a všechny číselníky (currency, legalForm, paymentTerm, taxRate, territory, contactSource, companyCategory, productCategory, leadPhase, businessCasePhase, offerStatus, salesOrderStatus, projectStatus, maritalStatus, employeesNumber, economyActivity, klasifikace 1/2/3, …):

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}/

Vnořené zdroje a speciální akce

Pro kolekce a akce nad záznamem (sub = zbytek cesty, přesně dle RAYNET vč. koncového lomítka u kolekcí):

Metoda	Cesta	Příklad cíle
GET	/api/{resource}/{id}/{sub}	/invoice/{id}/pdfExport, /company/{id}/relationship/
POST	/api/{resource}/{id}/{sub}	/invoice/{id}/cancel, /company/{id}/lock, /company/{id}/merge/{srcId}/
PUT	/api/{resource}/{id}/{sub}	/company/{id}/address/, /invoice/{id}/payment/, /offer/{id}/item/
DELETE	/api/{resource}/{id}/{sub}	/company/{id}/address/5/

Raw – 100 % pokrytí

Pro jakoukoli cestu / metodu (i netypické, např. PUT /invoice/creditNote):

POST /raw
{ "method": "PUT", "path": "/invoice/creditNote", "params": {...}, "data": {...} }

Tvar odpovědí

• Create → { "success": true, "id": 123, "data": {...} }
• Detail → { "success": true, "data": { ...objekt vč. id, rowInfo } }
• Seznam → { "success": true, "totalCount": N, "data": [ ... ] }
• Update / Delete → { "success": true }

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.