JiriUhlir
135 lines
4.0 KiB
Markdown
135 lines
4.0 KiB
Markdown
# 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")
|
||
```
|