API i integracje (CRM, Make, n8n)
Połącz swój CRM albo ERP z Sattotal za pomocą kluczy API: synchronizuj klientów i dostawców automatycznie i bezpiecznie
API Sattotal pozwala innemu programowi — Twojemu CRM-owi, Twojemu ERP, Make, n8n, Zapierowi albo własnemu skryptowi — odczytywać i tworzyć klientów i dostawców w Twojej organizacji, bez ręcznego importowania CSV. Steruje się nim kluczami API, które administrator tworzy w Ustawienia → API, każdy z własną nazwą i z uprawnieniami osobno dla każdego zasobu, i które można w każdej chwili unieważnić. Poniżej znajdziesz, co API robi, jak utworzyć klucz, jak wywoływać API i jak krok po kroku zbudować synchronizację z Make.
Połącz swój CRM i automatyzacje
Każde narzędzie, które potrafi wysłać żądanie HTTP (Make, n8n, Zapier, Twój własny CRM albo ERP), może odczytywać, tworzyć i aktualizować klientów oraz dostawców.
Klucze z nazwą i uprawnieniami
Jeden klucz na integrację, a w każdym kluczu osobne uprawnienie do każdego zasobu: możesz dać odczyt dostawców, nie dając zapisu klientów. Do 10 aktywnych kluczy na organizację.
Synchronizacja przyrostowa
Z parametrem actualizadoDesde pobierasz tylko tych klientów albo dostawców, którzy zmienili się od ostatniego przebiegu: idealne dla scenariusza uruchamianego co kilka minut.
Bezpieczne z założenia
Klucz jest pokazywany tylko raz i zapisywany w postaci nieodwracalnie zaszyfrowanej. Każdy klucz ma dostęp wyłącznie do danych swojej organizacji i można go natychmiast unieważnić.
Kto może z niego korzystać
Klucze tworzą i unieważniają administratorzy organizacji. API jest zawarte w planach płatnych (Basic, Pro i Enterprise) oraz w okresie próbnym; w planie darmowym ekran pokazuje kłódkę z możliwością zmiany planu. Klucz zawsze działa w imieniu organizacji, nie osoby: nie dziedziczy uprawnień żadnego technika i nie pojawia się jako użytkownik w zespole.
Jak utworzyć klucz
Wejdź w Ustawienia → API
Z menu bocznego: Ustawienia, karta „API”. Zobaczysz listę kluczy swojej organizacji (aktywnych i unieważnionych) oraz kartę „Jak się połączyć” z bazowym adresem URL i przykładem.
Kliknij „Nowy klucz”
Nadaj mu nazwę identyfikującą integrację („CRM sklepu”, „Make”, „n8n”). Dzięki temu, jeśli kiedyś trzeba będzie go unieważnić, będziesz wiedzieć który.
Wybierz uprawnienia
Zaznacz zasoby, których potrzebuje integracja — Klienci, Dostawcy albo oba — i dla każdego wybierz „Tylko odczyt” (podgląd) albo „Odczyt i zapis” (podgląd, tworzenie, aktualizacja i archiwizacja). Niezaznaczony zasób to zasób, do którego klucz nie sięga. Wybierz minimum, którego integracja potrzebuje.
Skopiuj klucz i zapisz go w swoim narzędziu
Pełny klucz (zaczyna się od sat_) jest pokazywany tylko raz. Skopiuj go przyciskiem i wklej w Make, n8n albo swoim CRM-ie. Jeśli go zgubisz, nie da się go odzyskać: unieważnia się go i tworzy nowy.
Ustawienia → API: lista kluczy i właśnie utworzony klucz
CRM Make
sat_Ab3k…x9Zq
n8n
sat_Qm7t…p2Lk
Klucz utworzony
sat_Ab3k9Zq2Xv8Lp1Mn4Rt7Wy0Cd5Fg6Hj3Kl8Sx9ZqKopiujTo jedyny raz, kiedy zobaczysz pełny klucz. Jeśli go zgubisz, unieważnij go i utwórz nowy.
Uprawnienia klucza
Tylko odczyt
Może listować i podglądać ten zasób. Każda próba utworzenia, zmiany albo archiwizacji kończy się błędem 403 z kodem PERMISO_DENEGADO i brakującym uprawnieniem.
Odczyt i zapis
Poza podglądem może w tym zasobie tworzyć, aktualizować i archiwizować. To uprawnienie, którego potrzebuje synchronizacja dwukierunkowa.
Uprawnienia są przypisane do zasobu
Uprawnienia są przypisane do zasobu i już to było widać: gdy doszli dostawcy, istniejące klucze — wszystkie dla klientów — NIE zyskały do nich dostępu. Trzeba było im to zaznaczyć. Tak samo będzie z każdym kolejnym zasobem: integracja nigdy nie widzi więcej, niż jej przyznano.
Jak się uwierzytelnić
Wysyłaj klucz w każdym żądaniu, z serwera do serwera, w nagłówku Authorization: Bearer sat_…. Jeśli Twoje narzędzie nie pozwala na nagłówki autoryzacji, klucz jest też przyjmowany w nagłówku x-api-key. Bazowy adres URL to adres Twojego Sattotal z dopiskiem /api/v1 (masz go gotowy do skopiowania na ekranie Ustawienia → API).
GET /api/v1/me Authorization: Bearer sat_Ab3k9…x9Zq
API celowo nie ma CORS: jest przeznaczone dla serwerów i narzędzi do automatyzacji, nie dla stron internetowych ani aplikacji działających w przeglądarce Twoich klientów. Klucz nigdy nie powinien trafić do przeglądarki.
Co można zrobić (endpointy)
Wszystkie odpowiedzi mają postać success + data (a listy dodatkowo pagination). Klienta możesz pobrać po jego id albo po kodzie (CLI-0007); dostawcę — wyłącznie po id.
| Metoda | Ścieżka | Co robi | Uprawnienie |
|---|---|---|---|
| GET | /me | Zwraca Twoją organizację i klucz, którym wywołujesz API. Użyj go, żeby „przetestować połączenie” w Make albo n8n. | Dowolne |
| GET | /clientes | Stronicowana lista klientów. Filtry: busqueda, tipo, activo i actualizadoDesde. Bez activo zwraca również zarchiwizowanych. | Odczyt |
| POST | /clientes | Tworzy klienta według tych samych reguł co formularz (identyfikator podatkowy zgodny z Twoim krajem, bez duplikatów identyfikatora podatkowego ani e-maila). | Zapis |
| GET | /clientes/{id} | Zwraca jednego klienta po id albo po kodzie. | Odczyt |
| PATCH | /clientes/{id} | Aktualizuje tylko przesłane pola. PUT jest przyjmowany jako synonim. | Zapis |
| DELETE | /clientes/{id} | Archiwizuje klienta (activo = false). Nic nie usuwa i można go powtarzać bez błędu. | Zapis |
| GET | /proveedores | Stronicowana lista dostawców. Filtry: busqueda, activo, tipoProveedor, codigo i actualizadoDesde. Bez activo zwraca również zarchiwizowanych. | Odczyt |
| POST | /proveedores | Tworzy dostawcę. Obowiązkowa jest tylko nazwa. Jeśli istnieje już dostawca z tym samym identyfikatorem podatkowym albo tą samą nazwą, odpowiedź to 409 z id istniejącego. | Zapis |
| GET | /proveedores/{id} | Zwraca dostawcę po jego id. Kod tutaj NIE zadziała: zobacz uwagę poniżej. | Odczyt |
| PATCH | /proveedores/{id} | Aktualizuje tylko przesłane pola. Lista kontaktów jest zastępowana w całości. PUT jest przyjmowany jako synonim. | Zapis |
| DELETE | /proveedores/{id} | Archiwizuje dostawcę (activo = false). Nic nie usuwa i można go powtarzać bez błędu. | Zapis |
| GET | /reparaciones | Stronicowana lista zleceń, od najnowszego przyjęcia. Filtry: cliente, estado, entradaDesde, entradaHasta i actualizadoDesde. | Odczyt |
| GET | /reparaciones/{id} | Zwraca jedno zlecenie po id lub numerze zlecenia. | Odczyt |
| GET | /clientes/{id}/reparaciones | Zlecenia klienta (po jego id lub kodzie), z tymi samymi filtrami. | Odczyt |
| GET | /clientes/{id}/resumen | Podsumowanie aktywności klienta: ile ma napraw (łącznie, otwartych i według statusu), na jaką kwotę dostał kosztorysy i kiedy był ostatnio. | Odczyt |
Pola klienta
Pola są takie same jak w karcie klienta: nombre i tipo (particular albo empresa) są obowiązkowe; nif_cif, apellidos, razonSocial, email, telefono, telefonoSecundario, direccion (calle, numero, piso, codigoPostal, localidad, provincia, pais) i notas są opcjonalne. Identyfikator podatkowy jest zapisywany wielkimi literami, a e-mail małymi. W odpowiedzi wszystkie klucze są zawsze obecne, z wartością null, gdy nie ma wartości, żeby mapowanie pól w Twoim narzędziu się nie rozsypało. Uwaga na imię: nombre to imię (w przypadku firmy jej nazwa handlowa), a nazwisko podaje się osobno w apellidos, w liczbie mnogiej.
Pola, których API nie rozpoznaje
Jeśli treść zawiera klucz, który nie istnieje (na przykład firstName zamiast nombre albo apellido w liczbie pojedynczej zamiast apellidos), żądanie nie zostaje odrzucone, ale ta wartość nie jest zapisywana. Żeby nie przeszło to niezauważone, odpowiedź przy tworzeniu i edycji klienta zawiera avisos.camposIgnorados z listą takich kluczy; pola adresu mają swoją ścieżkę, np. direccion.ciudad. Jeśli to widzisz, sprawdź mapowanie pól w swojej integracji. Pola zwracane przez samo API (id, codigo, createdAt…) nigdy nie wywołują ostrzeżenia, więc możesz odczytać klienta, zmienić go i odesłać w całości.
POST /api/v1/clientes
{ "firstName": "Daniel", "nombre": "Florea", "tipo": "particular" }
201 Created
{
"success": true,
"data": { "nombre": "Florea", "apellidos": null, … },
"avisos": { "camposIgnorados": ["firstName"] }
}Przykład: utworzenie klienta
Żądanie
POST /api/v1/clientes
Authorization: Bearer sat_Ab3k9…x9Zq
Content-Type: application/json
{
"nombre": "Daniel",
"apellidos": "Florea",
"tipo": "empresa",
"razonSocial": "Assista Tech SRL",
"nif_cif": "RO12345678",
"codigoPersonalizado": "801",
"email": "daniel@example.com",
"telefono": "+40 700 000 000",
"direccion": { "localidad": "București", "pais": "RO" }
}Odpowiedź (201)
{
"success": true,
"data": {
"id": "64b0…0001",
"codigo": "CLI-0042",
"codigoPersonalizado": "801",
"codigoVisible": "801",
"tipo": "empresa",
"nombre": "Daniel",
"apellidos": "Florea",
"razonSocial": "Assista Tech SRL",
"nif_cif": "RO12345678",
"email": "daniel@example.com",
"activo": true,
"createdAt": "2026-09-18T10:00:00.000Z",
"updatedAt": "2026-09-18T10:00:00.000Z"
}
}Dostawcy
Poza klientami API udostępnia katalog dostawców: te same pięć endpointów, te same kody błędów i tę samą synchronizację przyrostową. To wyłącznie katalog: zakupy i faktury zakupowe zostają tam, gdzie już są — w Twoim ERP albo w Sattotal.
Pola dostawcy
Obowiązkowe jest tylko nombre. Opcjonalne: codigo, cif, email, telefono, telefonoSecundario, web, direccion (w jednej linii, nie jest obiektem jak u klientów), ciudad, provincia, codigoPostal, pais, contactos, tipoProveedor (general, producto, servicio, logistica albo otro), formaPago, plazoPago (w dniach; 0 oznacza płatność natychmiastową), cuentaCliente i notas. Każdy kontakt ma nombre — obowiązkowe — oraz cargo, telefono, email i notas; kontakty nie mają własnego identyfikatora.
Jak aktualizują się kontakty
Lista, którą wysyłasz, ZASTĘPUJE tę, która była. Jeśli wyślesz pustą listę, wszystkie kontakty zostaną usunięte; jeśli nie wyślesz tego klucza (albo wyślesz null), zostaną bez zmian. Właśnie dzięki temu możesz odczytać dostawcę, zmienić w nim jedno pole i odesłać cały obiekt bez dziwnych skutków ubocznych.
Żądanie
POST /api/v1/proveedores
Authorization: Bearer sat_Ab3k9…x9Zq
Content-Type: application/json
{
"nombre": "Distribuciones Norte",
"cif": "B12345678",
"tipoProveedor": "producto",
"plazoPago": 30,
"cuentaCliente": "C-4471",
"contactos": [
{ "nombre": "Ana Ruiz", "cargo": "Ventas", "email": "ana@norte.es" }
]
}Odpowiedź (201)
{
"success": true,
"data": {
"id": "64b0…0009",
"codigo": "PROV-004",
"nombre": "Distribuciones Norte",
"cif": "B12345678",
"tipoProveedor": "producto",
"plazoPago": 30,
"cuentaCliente": "C-4471",
"contactos": [
{ "nombre": "Ana Ruiz", "cargo": "Ventas",
"telefono": null, "email": "ana@norte.es", "notas": null }
],
"excluidoRecargoEquivalencia": false,
"activo": true,
"createdAt": "2026-09-19T08:00:00.000Z",
"updatedAt": "2026-09-19T08:00:00.000Z"
}
}Dane bankowe nie wychodzą przez API
IBAN ani rachunki bankowe dostawcy nie są zwracane ani przyjmowane — i to celowo: gdyby klucz kiedyś wyciekł, nie przydałby się do oszustwa polegającego na podmianie numeru rachunku, czyli najczęstszego przy dostawcach. Zwracane jest natomiast cuentaCliente, czyli TWÓJ numer klienta u tego dostawcy, po którym ERP uzgadnia swoje zakupy.
Dopłata wyrównawcza jest tylko do odczytu
Pole excluidoRecargoEquivalencia jest zwracane i możesz odesłać je z tą samą wartością (żeby dało się odesłać cały obiekt), ale zmiana przez API kończy się błędem 400: to pole decyduje, czy do Twoich zakupów u tego dostawcy dolicza się dopłata wyrównawcza („recargo de equivalencia”), a więc przesuwa podstawę opodatkowania Twoich faktur zakupowych. Zmienia się je w karcie dostawcy. Poza Hiszpanią nie ma żadnego znaczenia.
Kod dostawcy nie wskazuje jednoznacznie
W odróżnieniu od kodu klienta kod dostawcy (PROV-004) nie jest unikalny: może się powtarzać nawet w obrębie Twojego własnego serwisu. Dlatego GET /proveedores/{id} przyjmuje wyłącznie id. Jeśli Twój ERP przechowuje tylko kod, skorzystaj z filtra na liście: GET /proveedores?codigo=PROV-004 zwróci wszystkie pasujące rekordy, a Ty zdecydujesz, o który chodzi.
Zlecenia naprawy (tylko odczyt)
API pozwala też odczytywać zlecenia naprawy: numer zlecenia, status, daty, urządzenie (typ, marka, model, numer seryjny, IMEI) i kosztorys. Tylko do odczytu: zlecenia nadal tworzy się i zmienia ich status w Sattotal, gdzie podpisuje się potwierdzenie przyjęcia i wydanie. Klucz musi mieć zaznaczony zasób Naprawy; klucze do klientów lub dostawców nie mają do nich dostępu.
Pola zlecenia
Każde zlecenie zawiera numeroFicha, estado, prioridad, ubicacion, averiaDeclarada, diagnostico, daty cyklu (przyjęcie, początek i koniec diagnozy i naprawy, powiadomienie klienta, wydanie oraz ultimoCambioEstado, czyli kiedy zlecenie przeszło do obecnego statusu), skrót danych klienta (id, codigo, codigoVisible, nombre, apellidos, razonSocial), urządzenie (id, codigo, tipo, marca, modelo, numeroSerie, imei, color), kosztorys (numero, total, estado, fechaEnvio i fechaRespuesta albo null, jeśli go nie ma), przypisanego serwisanta (tylko imię i nazwisko) oraz plazoEntregaEstimado, czyli termin realizacji podany klientowi w potwierdzeniu przyjęcia. Notatki wewnętrzne, podpisy, zdjęcia, dokumenty i hasła urządzenia nigdy nie są zwracane.
Żądanie
GET /api/v1/clientes/CLI-0042/reparaciones?estado=reparado Authorization: Bearer sat_Ab3k9…x9Zq
Odpowiedź (201)
{
"success": true,
"data": [{
"id": "64b0…0042",
"numeroFicha": "ORD-2026-0042",
"estado": "reparado",
"prioridad": "normal",
"averiaDeclarada": "No carga",
"diagnostico": "Conector de carga dañado",
"fechas": {
"entrada": "2026-09-20T09:00:00.000Z",
"finReparacion": "2026-09-22T17:30:00.000Z",
"entrega": null
},
"cliente": { "id": "64b0…0001", "codigoVisible": "801", "nombre": "Daniel" },
"dispositivo": {
"tipo": "movil", "marca": "Apple", "modelo": "iPhone 13",
"numeroSerie": "F2LXX0000", "imei": "356789012345678"
},
"presupuesto": { "numero": "PRES-2026-0010", "total": 89.9, "estado": "aprobado" },
"tecnico": { "nombre": "Andrei Popescu" },
"plazoEntregaEstimado": "3 días laborables"
}],
"pagination": { "total": 1, "page": 1, "limit": 25, "totalPages": 1 }
}Wyszukiwanie klienta po numerze, z którego dzwoni
Jeśli Twój CRM albo centrala telefoniczna otwiera kartę klienta przy połączeniu przychodzącym, użyj GET /clientes?telefono=<numer>. Wyszukiwanie obejmuje telefon główny i dodatkowy i nie zależy od zapisu numeru: spacje, myślniki i numer kierunkowy kraju (+48 lub 0048) są pomijane. Dzięki temu „512 345 678” znajdzie klienta zapisanego jako „+48 512-345-678”. Potrzeba co najmniej 6 cyfr.
Podsumowanie klienta dla Twojego CRM
GET /clientes/{id}/resumen zwraca w jednym wywołaniu to, co CRM zwykle pokazuje na karcie klienta: totalReparaciones, reparacionesAbiertas (urządzenie jest nadal w warsztacie), porEstado, totalPresupuestado i totalPresupuestosAprobados (w walucie warsztatu, podanej w moneda), primeraReparacion, ultimaReparacion i ultimaActividad (ostatnia zmiana w którymkolwiek z jego zleceń). Tak jak zlecenia, wymaga zasobu Naprawy.
Żądanie
GET /api/v1/clientes?telefono=0722 123 456
→ { "data": [{ "id": "64b0…0001", "codigoVisible": "801", "telefono": "+40 722 123 456", … }] }
GET /api/v1/clientes/801/resumen
{
"success": true,
"data": {
"cliente": { "id": "64b0…0001", "codigoVisible": "801" },
"moneda": "RON",
"totalReparaciones": 7,
"reparacionesAbiertas": 1,
"porEstado": { "entregado": 6, "en_reparacion": 1 },
"totalPresupuestosAprobados": 1240.5,
"ultimaReparacion": "2026-10-02T09:15:00.000Z",
"ultimaActividad": "2026-10-06T16:40:00.000Z",
…
}
}Synchronizuj tylko to, co się zmieniło
Nie trzeba pobierać wszystkiego przy każdym przebiegu. Zapisz w swoim narzędziu datę i godzinę ostatniego uruchomienia i proś tylko o klientów albo dostawców zmodyfikowanych od tego momentu, parametrem actualizadoDesde. Odpowiedź jest posortowana rosnąco po dacie modyfikacji, ze stabilnym rozstrzyganiem remisów, więc możesz ją stronicować bez pomijania rekordów. Zarchiwizowane rekordy też się pojawiają (z activo = false), żeby Twój CRM mógł odzwierciedlić archiwizację.
GET /api/v1/clientes?actualizadoDesde=2026-09-18T10:00:00Z&limit=100&page=1 Authorization: Bearer sat_Ab3k9…x9Zq
Pierwszy przebieg
Przejdź GET /clientes z limit=100 i page=1, 2, 3… aż wyczerpie się totalPages. Zapisz godzinę rozpoczęcia.
Kolejne przebiegi
Wywołaj GET /clientes?actualizadoDesde=<zapisana godzina> i przetwarzaj tylko to, co przyjdzie. Ponownie zapisz godzinę rozpoczęcia tego przebiegu.
Łącz, nie duplikuj
Zapisz id z Sattotal obok rekordu w swoim CRM-ie. Jeśli przy tworzeniu otrzymasz 409 DUPLICADO, odpowiedź zawiera existenteId: połącz z tym rekordem, zamiast tworzyć kolejny.
Stronicowanie i wyszukiwanie
Listy przyjmują page (od 1) i limit (domyślnie 25, maksymalnie 100; jeśli poprosisz o więcej, wartość jest przycinana do 100). Pole busqueda przeszukuje imię, nazwisko, nazwę firmy, identyfikator podatkowy, e-mail, kod i telefon.
Kody błędów i co robić
Każda odpowiedź z błędem zawiera success: false, orientacyjny komunikat oraz stabilny code, na podstawie którego program może podejmować decyzje. Oto te, które możesz otrzymać:
NO_AUTORIZADOBrakuje klucza, ma format inny niż nasz albo nie istnieje. Sprawdź nagłówek Authorization.
CLAVE_REVOCADAKlucz był poprawny, ale administrator go unieważnił. Utwórz nowy w Ustawienia → API i zaktualizuj go w swoim narzędziu.
PLAN_REQUERIDOOrganizacja jest w planie darmowym. API znów działa po przejściu na plan płatny.
PERMISO_DENEGADOKlucz nie ma uprawnienia wymaganego do tej operacji. Odpowiedź wskazuje w ambitoRequerido, którego brakuje: utwórz klucz z tym uprawnieniem.
NO_ENCONTRADOW Twojej organizacji nie ma klienta ani dostawcy o tym id. Rekordy innych organizacji nigdy nie są widoczne, a „nie istnieje” nie jest odróżniane od „nie należy do Ciebie”.
DUPLICADORekord z tą wartością już istnieje: identyfikator podatkowy albo e-mail u klientów; identyfikator podatkowy, nazwa albo kod u dostawców. Odpowiedź zawiera campo i existenteId, żeby można było go połączyć zamiast tworzyć kolejny.
VALIDACIONKtóreś pole nie przechodzi walidacji (albo JSON jest źle sformatowany). W details znajdziesz pole i powód, tak samo jak w formularzu.
IDENTIFICADOR_FISCAL_REQUERIDOTen klient potrzebuje identyfikatora podatkowego: w Twoim kraju jest obowiązkowy dla przesłanego typu klienta (na przykład zawsze dla firm).
RATE_LIMITZa dużo żądań. Odczekaj liczbę sekund podaną w nagłówku Retry-After i spróbuj ponownie.
API_DESACTIVADAAPI jest tymczasowo wyłączone z powodu konserwacji. Spróbuj ponownie później.
Limity
120 żądań na minutę na klucz (w zupełności wystarcza dla okresowej synchronizacji; hamuje przypadkową pętlę). 10 aktywnych kluczy na organizację. Listy zwracają maksymalnie 100 rekordów na stronę. Jeśli organizacja jest w planie darmowym z wyczerpanym miesięcznym limitem, dodawanie klientów zostaje wstrzymane tak samo jak w aplikacji.
Krok po kroku: synchronizacja klientów z Make
Typowy scenariusz: co 15 minut przenosić do CRM-u klientów i dostawców nowych albo zmodyfikowanych w Sattotal. W n8n robi się to analogicznie, węzłem HTTP Request i węzłem Schedule.
Utwórz klucz w Sattotal
Ustawienia → API → Nowy klucz, uprawnienie „Tylko odczyt”, jeśli będziesz tylko odczytywać, „Odczyt i zapis”, jeśli będziesz też tworzyć klientów z CRM-u. Skopiuj klucz.
Moduł HTTP „Make a request”
URL: Twój bazowy adres URL + /clientes. Metoda GET. Nagłówek Authorization o wartości Bearer i Twój klucz. Zaznacz „Parse response”, żeby pracować na JSON-ie.
Przetestuj połączenie
Na początek wykonaj raz żądanie do /me: jeśli zwróci Twoją organizację i nazwę klucza, uwierzytelnianie działa.
Dodaj filtr przyrostowy
Zapisz datę ostatniego uruchomienia w Data store albo w zmiennej i przekaż ją jako actualizadoDesde w adresie URL. Zaplanuj scenariusz co 15 minut.
Zmapuj pola do swojego CRM-u
Przejdź po data[] i zmapuj id, codigo, nombre, apellidos, email, telefono, nif_cif i direccion. Zapisz id z Sattotal w swoim CRM-ie, żeby aktualizować zamiast duplikować.
Aby tworzyć klientów z CRM-u, dodaj kolejny moduł HTTP z metodą POST do /clientes i treścią JSON klienta. Jeśli otrzymasz 409, użyj existenteId do połączenia.
Dobre praktyki bezpieczeństwa
Jeden klucz na integrację
Dzięki temu możesz unieważnić jeden, nie psując pozostałych, a na liście widzisz, kiedy każdy z nich był ostatnio użyty.
Nigdy w przeglądarce ani w publicznym repozytorium
Przechowuj go w magazynie poświadczeń swojego narzędzia (połączenia w Make, poświadczenia w n8n, zmienne środowiskowe). Jeśli trafi do repozytorium albo na stronę internetową, uznaj go za ujawniony.
Jeśli wycieknie, unieważnij i utwórz nowy
Unieważnienie działa natychmiast: stary klucz zaczyna otrzymywać 401 CLAVE_REVOCADA. Zaktualizuj nowy w swoim narzędziu i gotowe.
Specyfikacja API
Pełna dokumentacja techniczna (ścieżki, parametry, schematy i kody błędów) jest opublikowana w otwartym formacie pod adresem /api/v1/openapi.json, bez potrzeby użycia klucza. Domyślnie jest po hiszpańsku; dodaj ?lang= z kodem swojego języka, aby dostać ją przetłumaczoną (na przykład ?lang=pl albo /api/v1/openapi.json?lang=en). Możesz ją zaimportować do narzędzi Postman, Insomnia, Make albo n8n, żeby mieć wszystkie wywołania gotowe.
Najczęstsze pytania
Zgubiłem klucz, czy mogę go znów zobaczyć?
Nie. Jest pokazywany tylko przy tworzeniu, a potem zapisywany nieodwracalnie. Unieważnij go w Ustawienia → API i utwórz nowy.
Czy są webhooki, żeby Sattotal powiadamiał mój CRM, gdy coś się zmieni?
Jeszcze nie. Zalecany sposób to okresowe odpytywanie z parametrem actualizadoDesde, który zwraca tylko to, co się zmieniło.
Jakie dane udostępnia API?
Klientów i dostawców: listowanie, tworzenie, podgląd, aktualizację i archiwizację. Uprawnienia są przypisane do zasobu, więc klucz utworzony, zanim pojawili się dostawcy, nie ma do nich dostępu, dopóki administrator mu tego nie zaznaczy. Do tego zlecenia naprawy tylko do odczytu (status, daty, urządzenie i kosztorys), z osobnym uprawnieniem.
Czy mogę usunąć klienta przez API?
Nie, można go tylko zarchiwizować (activo = false), tak samo jak w aplikacji. Dotyczy to zarówno klientów, jak i dostawców. Zarchiwizowany rekord nadal pojawia się w synchronizacji, żeby Twój CRM mógł to odzwierciedlić.
Czy API jest w planie darmowym?
Nie. Jest zawarte w planach Basic, Pro i Enterprise oraz w okresie próbnym. W planie darmowym nadal możesz przeglądać i unieważniać klucze, które utworzyłeś.
Dociera tylko nazwisko klienta. Dlaczego imię się nie zapisuje?
Prawie zawsze chodzi o mapowanie pól: imię trafia do nombre, a nazwisko do apellidos. Jeśli Twoje narzędzie wysyła imię pod innym kluczem (firstName, name, apellido…), API je pomija i informuje o tym w avisos.camposIgnorados w odpowiedzi. Popraw mapowanie i wyślij klienta ponownie metodą PATCH.
Czy mogę znaleźć klienta po numerze, z którego do mnie dzwoni?
Tak. Wywołaj GET /api/v1/clientes?telefono= z numerem w takiej postaci, w jakiej do Ciebie dociera: nie ma znaczenia, czy zawiera numer kierunkowy kraju, spacje lub myślniki, a wyszukiwanie obejmuje też telefon dodatkowy. Mając id klienta, możesz potem pobrać jego zlecenia (/clientes/{id}/reparaciones) i podsumowanie (/clientes/{id}/resumen).