AsentioCRM — REST/JSON API

Wersja API: 1.1 · Format: JSON · Uwierzytelnianie: klucz API

Dokumentacja publiczna interfejsu programistycznego AsentioCRM. Opisuje zasoby, endpointy, format odpowiedzi, filtrowanie i przykłady wywołań. Adres bazowy w przykładach zapisujemy jako — podstaw własną domenę instancji.

1. Przegląd

API wystawia zasoby CRM jako REST/JSON nad istniejącym frameworkiem (routing /controller/action). Jeden kontroler api, rejestr zasobów, generyczny CRUD. Uwierzytelnianie kluczem API (tabela api_keys, zarządzana w panelu /users/apikeys). Każdy odczyt/zapis ograniczony do firm_id klucza (multi-tenant).

Baza URL: https:///api

2. Uwierzytelnianie

Klucz w nagłówku (preferowane):

X-API-Key:

lub

Authorization: Bearer

Fallback (tylko testy, mniej bezpieczny): ?api_key= w query stringu.

Klucz generuje się w panelu Users → Klucze API (/users/apikeys). Pokazywany raz przy tworzeniu.
W bazie trzymany jako SHA-256 (nie da się odzyskać jawnego).
Uprawnienia klucza: read (GET), write (POST, PUT), delete (DELETE) — dowolna kombinacja.
Opcjonalnie: data wygaśnięcia (expires_at) i whitelist IP (ip_whitelist).
Każde użycie stempluje last_used_at.

3. Zasoby

Zasób	Ścieżka	Odczyt	Zapis	Firm-scoped	Uwagi
customers	`/api/customers`	✅	✅	✅	klienci
contacts	`/api/contacts`	✅	✅	✅	osoby kontaktowe
products	`/api/products`	✅	✅	✅	produkty
tasks	`/api/tasks`	✅	✅	✅	zadania
sales	`/api/sales`	✅	✅	✅	`sales_costs`
invoices	`/api/invoices`	✅	✅	✅	faktury
offers	`/api/offers`	✅	✅	✅	oferty
documents	`/api/documents`	✅	✅	✅	dokumenty
users	`/api/users`	✅	❌	✅	read-only; `pass`/`ip` nigdy nie wychodzą
firms	`/api/firms`	✅	❌	✅	read-only; tylko własna firma

3.1 Lookupy / słowniki (read-only — do rozwiązywania ID → nazwa)

Encje główne trzymają odwołania jako ID (region, country, status, category_id, title_id…). Poniższe endpointy pozwalają rozwiązać te ID na nazwy.

Zasób	Ścieżka	Firm-scoped	Uwagi
dict	`/api/dict`	✅ + globalne	słownik polimorficzny; filtruj `?type=` (np. `customer_group`, `acquisition_method`, `customer_ruck`). Pokazuje wpisy firmy oraz globalne (`firm_id=0`).
countries	`/api/countries`	❌ global	`id, name, code` (ISO)
regions	`/api/regions`	❌ global	województwa
product-categories	`/api/product-categories`	✅	kategorie produktów
document-categories	`/api/document-categories`	✅	kategorie dokumentów

# rozwiąż kraje / regiony
curl -H "X-API-Key: $KEY" "$BASE/countries"
curl -H "X-API-Key: $KEY" "$BASE/regions"
# słownik: metody pozyskania klienta
curl -H "X-API-Key: $KEY" "$BASE/dict?type=acquisition_method"

4. Endpointy (na zasób)

Metoda	Ścieżka	Akcja
GET	`/api/`	lista (filtry/paginacja)
GET	`/api//`	jeden rekord
POST	`/api/`	utwórz (body JSON)
PUT	`/api//`	aktualizuj — PARTIAL (tylko przesłane pola)
DELETE	`/api//`	usuń

GET /api → indeks: wersja, uprawnienia klucza, lista zasobów. GET /api/openapi → spec OpenAPI 3.0.3 generowany dynamicznie z żywego schematu (nie rozjedzie się z kodem). Import do Swagger UI / Postman / codegen. Wymaga ważnego klucza. Można też użyć X-HTTP-Method-Override: PUT|DELETE na POST (dla klientów bez PUT/DELETE).

5. Format odpowiedzi

Sukces (jeden / utworzenie / aktualizacja):

{ "ok": true, "data": { "id": 271, "fullname": "...", "firm_id": 1, ... } }

Sukces (lista):

{ "ok": true,
  "data": [ { ... }, { ... } ],
  "meta": { "count": 2, "total": 188, "limit": 50, "offset": 0 } }

Błąd:

{ "ok": false, "error": { "code": "not_found", "message": "Rekord 999 nie istnieje." } }

Kody błędów / HTTP

HTTP	code	znaczenie
400	`bad_json` / `missing_id`	złe ciało / brak id
401	`no_key` / `invalid_key`	brak / zły klucz
403	`key_disabled` / `key_expired` / `ip_denied` / `insufficient_perms` / `readonly`	odmowa
404	`not_found` / `unknown_resource`	brak rekordu / zasobu
405	`method_not_allowed`	zła metoda
422	`no_fields`	brak dozwolonych pól do zapisu

6. Lista — filtry i paginacja

?limit= (domyślnie 50, max 200), ?offset=
?order=&dir=asc|desc (domyślnie PK malejąco)
?= — dokładne dopasowanie (tylko realne kolumny tabeli)
?q= — LIKE po wszystkich kolumnach tekstowych zasobu

Przykład: GET /api/customers?status=1&order=fullname&dir=asc&limit=20&q=studio

7. Przykłady (curl)

KEY="twoj_klucz"
BASE="https:///api"

# lista klientów (2 szt.)
curl -H "X-API-Key: $KEY" "$BASE/customers?limit=2"

# jeden klient
curl -H "X-API-Key: $KEY" "$BASE/customers/270"

# utwórz
curl -X POST -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
     -d '{"fullname":"Nowa Firma Sp.","city":"Kraków","status":"1"}' "$BASE/customers"

# aktualizuj TYLKO notatkę (reszta pól nietknięta)
curl -X PUT -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
     -d '{"note":"kontakt 2026"}' "$BASE/customers/271"

# usuń
curl -X DELETE -H "X-API-Key: $KEY" "$BASE/customers/271"

MafiaAI / t8.pl — AsentioCRM to nasz system CRM. Pytania o integrację i wdrożenie: t8.pl

api crm dokumentacja