API ja integraatiot (CRM, Make, n8n)

Liitä CRM tai ERP Sattotaliin API-avaimilla: synkronoi asiakkaat ja toimittajat automaattisesti ja turvallisesti

Sattotalin API:n avulla toinen ohjelma — CRM, ERP, Make, n8n, Zapier tai oma skriptisi — voi lukea ja luoda asiakkaita ja toimittajia organisaatiossasi ilman, että kenenkään pitää tuoda CSV-tiedostoa käsin. Sitä hallitaan API-avaimilla, jotka ylläpitäjä luo kohdassa Asetukset → API; jokaisella on oma nimi ja oikeudet resurssikohtaisesti, ja ne voi perua milloin tahansa. Tässä käydään läpi, mitä API tekee, miten avain luodaan, miten API:a kutsutaan ja miten Make-synkronointi rakennetaan vaihe vaiheelta.

Liitä CRM ja automaatiosi

Mikä tahansa työkalu, joka osaa tehdä HTTP-pyynnön (Make, n8n, Zapier, oma CRM tai ERP), voi lukea, luoda ja päivittää asiakkaita ja toimittajia.

Nimetyt avaimet omilla oikeuksilla

Yksi avain integraatiota kohden, ja jokaisen avaimen sisällä yksi oikeus resurssia kohden: voit antaa toimittajien lukuoikeuden antamatta asiakkaiden kirjoitusoikeutta. Enintään 10 aktiivista avainta organisaatiota kohden.

Vaiheittainen synkronointi

actualizadoDesde-parametrilla haetaan vain ne asiakkaat tai toimittajat, jotka ovat muuttuneet edellisen ajon jälkeen: ihanteellinen skenaariolle, joka pyörii muutaman minuutin välein.

Turvallinen lähtökohtaisesti

Avain näytetään vain kerran ja tallennetaan salattuna niin, ettei sitä voi palauttaa. Jokainen avain pääsee vain oman organisaationsa tietoihin, ja sen voi perua välittömästi.

Kuka voi käyttää sitä

Avaimet luovat ja peruvat organisaation ylläpitäjät. API sisältyy maksullisiin suunnitelmiin (Basic, Pro ja Enterprise) ja kokeilujaksoon; ilmaisessa suunnitelmassa näkymässä on lukko ja mahdollisuus vaihtaa suunnitelmaa. Avain toimii aina organisaation nimissä, ei henkilön: se ei peri minkään teknikon oikeuksia eikä näy käyttäjänä tiimissä.

Näin luot avaimen

Siirry kohtaan Asetukset → API

Sivuvalikosta Asetukset ja sieltä kortti ”API”. Näet organisaatiosi avainten luettelon (aktiiviset ja perutut) sekä kortin ”Näin yhdistät”, jossa on perus-URL ja esimerkki.

Paina ”Uusi avain”

Anna sille nimi, josta tunnistat integraation (”Liikkeen CRM”, ”Make”, ”n8n”). Jos joskus joudut perumaan sen, tiedät mikä se on.

Valitse oikeudet

Valitse resurssit, joita integraatio tarvitsee — Asiakkaat, Toimittajat tai molemmat — ja valitse kullekin ”Vain luku” (hakeminen) tai ”Luku ja kirjoitus” (hakeminen, luominen, päivittäminen ja arkistointi). Valitsematta jätetty resurssi on resurssi, johon avain ei yllä. Valitse pienin, jonka integraatio tarvitsee.

Kopioi avain ja tallenna se työkaluusi

Koko avain (alkaa sat_) näytetään vain kerran. Kopioi se painikkeella ja liitä se Makeen, n8n:ään tai CRM:ään. Jos se katoaa, sitä ei voi palauttaa: peru se ja luo uusi.

Asetukset → API: avainluettelo ja juuri luotu avain

CRM Make

sat_Ab3k…x9Zq

Asiakkaat · Luku ja kirjoitusToimittajat · Vain lukuKäytetty viimeksi: 3 minuuttia sittenPeru

n8n

sat_Qm7t…p2Lk

Peruttu

Avain luotu

sat_Ab3k9Zq2Xv8Lp1Mn4Rt7Wy0Cd5Fg6Hj3Kl8Sx9ZqKopioi

Näet koko avaimen vain tämän kerran. Jos se katoaa, peru se ja luo uusi.

Avaimen oikeudet

Vain luku

Voi listata ja hakea kyseistä resurssia. Jokainen yritys luoda, muokata tai arkistoida saa 403-virheen koodilla PERMISO_DENEGADO sekä tiedon puuttuvasta oikeudesta.

Luku ja kirjoitus

Hakemisen lisäksi voi luoda, päivittää ja arkistoida kyseisessä resurssissa. Tätä oikeutta kaksisuuntainen synkronointi tarvitsee.

Oikeudet ovat resurssikohtaisia

Oikeudet ovat resurssikohtaisia, ja se on jo näkynyt: kun toimittajat lisättiin, olemassa olleet avaimet — kaikki asiakkaita varten — EIVÄT saaneet niihin pääsyä. Ne piti valita erikseen. Sama pätee jokaiseen myöhemmin lisättävään resurssiin: integraatio ei koskaan näe enempää kuin mitä sille annoit.

Näin todennat

Lähetä avain jokaisessa pyynnössä, palvelimelta palvelimelle, otsakkeessa Authorization: Bearer sat_…. Jos työkalusi ei salli valtuutusotsakkeita, avain hyväksytään myös otsakkeessa x-api-key. Perus-URL on oman Sattotalisi osoite ja sen perässä /api/v1 (se on valmiina kopioitavaksi näkymässä Asetukset → API).

GET /api/v1/me
Authorization: Bearer sat_Ab3k9…x9Zq

API:ssa ei ole tarkoituksella CORS-tukea: se on tehty palvelimille ja automaatiotyökaluille, ei verkkosivuille tai sovelluksille, jotka toimivat asiakkaidesi selaimessa. Avain ei saa koskaan päätyä selaimeen.

Mitä voit tehdä (päätepisteet)

Kaikki vastaukset ovat muotoa success + data (ja listauksissa lisäksi pagination). Asiakkaan voit hakea joko id:llä tai koodilla (CLI-0007); toimittajan vain id:llä.

Menetelmä	Polku	Mitä se tekee	Oikeus
GET	/me	Palauttaa organisaatiosi ja avaimen, jolla kutsut. Käytä sitä ”yhteyden testaamiseen” Makessa tai n8n:ssä.	Mikä tahansa
GET	/clientes	Sivutettu asiakasluettelo. Suodattimet: busqueda, tipo, activo ja actualizadoDesde. Ilman activo-parametria palautetaan myös arkistoidut.	Luku
POST	/clientes	Luo asiakkaan samoilla säännöillä kuin lomake (maasi mukainen verotunniste, ei kahta samaa verotunnistetta tai sähköpostia).	Kirjoitus
GET	/clientes/{id}	Palauttaa yhden asiakkaan id:n tai koodin perusteella.	Luku
PATCH	/clientes/{id}	Päivittää vain lähetetyt kentät. PUT hyväksytään synonyymina.	Kirjoitus
DELETE	/clientes/{id}	Arkistoi asiakkaan (activo = false). Mitään ei poisteta, ja kutsun voi toistaa ilman virhettä.	Kirjoitus
GET	/proveedores	Sivutettu toimittajaluettelo. Suodattimet: busqueda, activo, tipoProveedor, codigo ja actualizadoDesde. Ilman activo-parametria palautetaan myös arkistoidut.	Luku
POST	/proveedores	Luo toimittajan. Vain nimi on pakollinen. Jos samalla verotunnisteella tai samalla nimellä on jo toimittaja, vastaus on 409 ja siinä on olemassa olevan id.	Kirjoitus
GET	/proveedores/{id}	Palauttaa toimittajan sen id:n perusteella. Koodi EI kelpaa tässä: katso alla oleva huomautus.	Luku
PATCH	/proveedores/{id}	Päivittää vain lähetetyt kentät. Yhteyshenkilöiden luettelo korvataan kokonaan. PUT hyväksytään synonyymina.	Kirjoitus
DELETE	/proveedores/{id}	Arkistoi toimittajan (activo = false). Mitään ei poisteta, ja kutsun voi toistaa ilman virhettä.	Kirjoitus
GET	/reparaciones	Sivutettu luettelo tilauksista, uusin vastaanotto ensin. Suodattimet: cliente, estado, entradaDesde, entradaHasta ja actualizadoDesde.	Luku
GET	/reparaciones/{id}	Palauttaa yhden tilauksen id:n tai tilausnumeron perusteella.	Luku
GET	/clientes/{id}/reparaciones	Asiakkaan tilaukset (asiakkaan id:n tai koodin perusteella) samoilla suodattimilla.	Luku
GET	/clientes/{id}/resumen	Asiakkaan toimintayhteenveto: montako korjausta asiakkaalla on (yhteensä, avoimina ja tiloittain), paljonko hänelle on annettu kustannusarvioita ja milloin hän kävi viimeksi.	Luku

Asiakkaan kentät

Kentät ovat samat kuin asiakaskortissa: nombre ja tipo (particular tai empresa) ovat pakollisia; nif_cif, apellidos, razonSocial, email, telefono, telefonoSecundario, direccion (calle, numero, piso, codigoPostal, localidad, provincia, pais) ja notas ovat valinnaisia. Verotunniste tallennetaan isoilla kirjaimilla ja sähköposti pienillä. Vastauksessa kaikki avaimet ovat aina mukana, arvona null kun arvoa ei ole, jotta kenttien yhdistäminen työkalussasi ei hajoa. Huomaa nimi: nombre on etunimi (yrityksellä toiminimi), ja sukunimi annetaan erikseen kentässä apellidos, monikossa.

Kentät, joita API ei tunnista

Jos pyynnön rungossa on avain, jota ei ole olemassa (esimerkiksi firstName nimen nombre sijaan tai yksikkömuotoinen apellido kentän apellidos sijaan), pyyntöä ei hylätä, mutta arvoa ei tallenneta. Jotta tämä ei jää huomaamatta, asiakkaan luonnin ja muokkauksen vastauksessa on avisos.camposIgnorados, jossa nämä avaimet luetellaan; osoitteen kentät näkyvät polkuineen, esimerkiksi direccion.ciudad. Jos näet sen, tarkista integraatiosi kenttämäppäys. API:n itse palauttamat kentät (id, codigo, createdAt…) eivät koskaan aiheuta varoitusta, joten voit lukea asiakkaan, muuttaa sitä ja lähettää sen kokonaan takaisin.

POST /api/v1/clientes
{ "firstName": "Daniel", "nombre": "Florea", "tipo": "particular" }

201 Created
{
  "success": true,
  "data": { "nombre": "Florea", "apellidos": null, … },
  "avisos": { "camposIgnorados": ["firstName"] }
}

Esimerkki: asiakkaan luominen

Pyyntö

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

Vastaus (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"
  }
}

Toimittajat

Asiakkaiden lisäksi API tarjoaa toimittajarekisterin: samat viisi päätepistettä, samat virhekoodit ja saman lisäävän synkronoinnin. Kyse on vain rekisteristä: ostot ja ostolaskut pysyvät siellä, missä ne jo ovat, ERP:ssäsi tai Sattotalissa.

Toimittajan kentät

Vain nombre on pakollinen. Valinnaisia ovat codigo, cif, email, telefono, telefonoSecundario, web, direccion (yhdellä rivillä, ei objekti kuten asiakkailla), ciudad, provincia, codigoPostal, pais, contactos, tipoProveedor (general, producto, servicio, logistica tai otro), formaPago, plazoPago (päivinä; 0 tarkoittaa heti maksettavaa), cuentaCliente ja notas. Jokaisessa yhteyshenkilössä on nombre — pakollinen — sekä cargo, telefono, email ja notas; yhteyshenkilöillä ei ole omaa tunnistetta.

Näin yhteyshenkilöt päivittyvät

Lähettämäsi luettelo KORVAA aiemman. Jos lähetät tyhjän luettelon, kaikki yhteyshenkilöt poistetaan; jos et lähetä avainta lainkaan (tai lähetät null), ne jäävät ennalleen. Juuri tämän ansiosta voit lukea toimittajan, muuttaa siitä yhden kentän ja lähettää koko objektin takaisin ilman outoja sivuvaikutuksia.

Pyyntö

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" }
  ]
}

Vastaus (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"
  }
}

Pankkitiedot eivät kulje API:n kautta

Toimittajan IBAN-tilinumeroa ja pankkitilejä ei palauteta eikä oteta vastaan, ja se on tarkoituksellista: jos avain vuotaisi, sillä ei voisi tehdä tilinumeron vaihtoon perustuvaa petosta, joka on toimittajien kohdalla yleisin. cuentaCliente sen sijaan palautetaan, sillä se on SINUN asiakasnumerosi kyseisellä toimittajalla, ja sen avulla ERP täsmäyttää ostonsa.

Tasauslisä on vain luettavissa

Kenttä excluidoRecargoEquivalencia palautetaan, ja voit lähettää sen takaisin samalla arvolla (jotta koko objektin voi palauttaa), mutta sen muuttaminen API:n kautta tuottaa 400-virheen: se ratkaisee, lisätäänkö kyseiseltä toimittajalta tekemiisi ostoihin tasauslisä (”recargo de equivalencia”), eli se siirtää ostolaskujesi veron perustetta. Sitä muutetaan toimittajan kortilla. Espanjan ulkopuolella sillä ei ole mitään vaikutusta.

Toimittajan koodi ei yksilöi

Toisin kuin asiakkaan, toimittajan koodi (PROV-004) ei ole yksilöivä: se voi toistua jopa oman korjaamosi sisällä. Siksi GET /proveedores/{id} hyväksyy vain id:n. Jos ERP:si tallentaa vain koodin, käytä listauksen suodatinta: GET /proveedores?codigo=PROV-004 palauttaa kaikki osumat, ja sinä päätät, mikä niistä on oikea.

Korjaustilaukset (vain luku)

API:n kautta voi lukea myös korjaustilaukset: tilausnumeron, tilan, päivämäärät, laitteen (tyyppi, merkki, malli, sarjanumero, IMEI) ja kustannusarvion. Vain luku: tilaukset luodaan ja niiden tila vaihdetaan edelleen Sattotalissa, jossa myös vastaanottokuitti ja luovutus allekirjoitetaan. Avaimella on oltava resurssi Korjaukset valittuna; asiakkaiden tai toimittajien avaimet eivät pääse niihin.

Tilauksen kentät

Jokainen tilaus sisältää kentät numeroFicha, estado, prioridad, ubicacion, averiaDeclarada, diagnostico, vaiheiden päivämäärät (vastaanotto, vianmäärityksen ja korjauksen alku ja loppu, ilmoitus asiakkaalle, luovutus sekä ultimoCambioEstado eli milloin tilaus siirtyi nykyiseen tilaansa), asiakkaan tiivistelmän (id, codigo, codigoVisible, nombre, apellidos, razonSocial), laitteen (id, codigo, tipo, marca, modelo, numeroSerie, imei, color), kustannusarvion (numero, total, estado, fechaEnvio ja fechaRespuesta, tai null jos sitä ei ole), tilaukselle määritetyn teknikon (vain nimen) sekä plazoEntregaEstimado eli toimitusajan, joka asiakkaalle ilmoitettiin vastaanottokuitissa. Sisäisiä muistiinpanoja, allekirjoituksia, kuvia, asiakirjoja tai laitteen salasanoja ei palauteta koskaan.

Pyyntö

GET /api/v1/clientes/CLI-0042/reparaciones?estado=reparado
Authorization: Bearer sat_Ab3k9…x9Zq

Vastaus (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 }
}

Asiakkaan haku soittajan numerolla

Jos CRM tai puhelinvaihde avaa asiakaskortin, kun puhelu tulee sisään, käytä GET /clientes?telefono=<numero>. Haku kohdistuu sekä ensisijaiseen että toissijaiseen puhelinnumeroon, eikä numeron kirjoitustavalla ole väliä: välilyönnit, väliviivat, maatunnus (+358 tai 00358) ja alun 0 jätetään huomiotta. Näin ”040 123 4567” löytää asiakkaan, joka on tallennettu muodossa ”+358 40-123-4567”. Hakuun tarvitaan vähintään 6 numeroa.

Asiakasyhteenveto CRM:ääsi varten

GET /clientes/{id}/resumen palauttaa yhdellä kutsulla sen, mitä CRM yleensä näyttää asiakaskortissa: totalReparaciones, reparacionesAbiertas (laite on yhä korjaamolla), porEstado, totalPresupuestado ja totalPresupuestosAprobados (korjaamon valuutassa, joka kerrotaan kentässä moneda), primeraReparacion, ultimaReparacion ja ultimaActividad (viimeisin muutos missä tahansa asiakkaan tilauksessa). Tilausten tapaan se vaatii resurssin Korjaukset.

Pyyntö

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",
    …
  }
}

Synkronoi vain muuttuneet

Kaikkea ei tarvitse hakea jokaisella ajolla. Tallenna työkaluusi edellisen ajon päivämäärä ja aika ja pyydä actualizadoDesde-parametrilla vain sen jälkeen muuttuneet asiakkaat tai toimittajat. Vastaus on järjestetty muokkauspäivän mukaan nousevasti ja tasatilanteet ratkaistaan vakaasti, joten voit sivuttaa sen ohittamatta tietueita. Myös arkistoidut tietueet näkyvät (activo = false), jotta CRM voi huomioida arkistoinnin.

GET /api/v1/clientes?actualizadoDesde=2026-09-18T10:00:00Z&limit=100&page=1
Authorization: Bearer sat_Ab3k9…x9Zq

Ensimmäinen ajo

Käy läpi GET /clientes arvoilla limit=100 ja page=1, 2, 3… kunnes totalPages on käyty loppuun. Tallenna aloitusaika.

Seuraavat ajot

Pyydä GET /clientes?actualizadoDesde=<tallennettu aika> ja käsittele vain se, mitä tulee. Tallenna tämän ajon aloitusaika uudelleen.

Yhdistä, älä monista

Tallenna Sattotalin id CRM:n tietueen yhteyteen. Jos saat luodessa 409 DUPLICADO, vastauksessa on existenteId: yhdistä se sen sijaan, että loisit uuden.

Sivutus ja haku

Listaukset hyväksyvät parametrit page (alkaen 1) ja limit (oletus 25, enintään 100; suurempi pyyntö leikataan sataan). Kenttä busqueda hakee nimestä, sukunimestä, toiminimestä, verotunnisteesta, sähköpostista, koodista ja puhelinnumerosta.

Virhekoodit ja mitä tehdä

Kaikissa virhevastauksissa on success: false, selittävä teksti ja pysyvä code, jonka perusteella ohjelma voi tehdä päätöksiä. Näitä voit saada:

NO_AUTORIZADO

Avain puuttuu, sen muoto ei ole meidän tai sitä ei ole olemassa. Tarkista Authorization-otsake.

CLAVE_REVOCADA

Avain oli voimassa, mutta ylläpitäjä perui sen. Luo uusi kohdassa Asetukset → API ja päivitä se työkaluusi.

PLAN_REQUERIDO

Organisaatio on ilmaisessa suunnitelmassa. API toimii taas, kun vaihdat maksulliseen suunnitelmaan.

PERMISO_DENEGADO

Avaimella ei ole tähän toimintoon tarvittavaa oikeutta. Vastaus kertoo kentässä ambitoRequerido, mikä puuttuu: luo avain, jolla on se oikeus.

NO_ENCONTRADO

Organisaatiossasi ei ole asiakasta eikä toimittajaa tuolla id:llä. Muiden organisaatioiden tietueet eivät näy koskaan, eikä ”ei ole olemassa” eroa vastauksessa siitä, että ”ei ole sinun”.

DUPLICADO

Tietue tuolla tiedolla on jo olemassa: asiakkailla verotunniste tai sähköposti; toimittajilla verotunniste, nimi tai koodi. Vastauksessa on campo ja existenteId, jotta voit yhdistää sen sen sijaan, että loisit uuden.

VALIDACION

Jokin kenttä ei läpäise tarkistusta (tai JSON on virheellinen). Kohdassa details on kenttä ja syy, aivan kuten lomakkeessa.

IDENTIFICADOR_FISCAL_REQUERIDO

Tämä asiakas tarvitsee verotunnisteen: maassasi se on pakollinen lähetetylle asiakastyypille (esimerkiksi aina yrityksille).

RATE_LIMIT

Liian monta pyyntöä. Odota Retry-After-otsakkeen ilmoittamat sekunnit ja yritä uudelleen.

API_DESACTIVADA

API on tilapäisesti pois käytöstä huollon vuoksi. Yritä myöhemmin uudelleen.

Rajat

120 pyyntöä minuutissa avainta kohden (reilusti säännölliseen synkronointiin; pysäyttää vahingossa syntyneen silmukan). 10 aktiivista avainta organisaatiota kohden. Listaukset palauttavat enintään 100 tietuetta sivua kohden. Jos organisaatio on ilmaisessa suunnitelmassa ja kuukausikiintiö on täynnä, asiakkaiden luominen estyy samoin kuin sovelluksessa.

Vaihe vaiheelta: asiakkaiden synkronointi Maken kanssa

Tyypillinen skenaario: 15 minuutin välein tuodaan CRM:ään Sattotalissa uudet tai muuttuneet asiakkaat ja toimittajat. n8n:ssä vastaava tehdään HTTP Request- ja Schedule-solmuilla.

Luo avain Sattotalissa

Asetukset → API → Uusi avain; oikeus ”Vain luku”, jos vain luet, ”Luku ja kirjoitus”, jos luot asiakkaita myös CRM:stä. Kopioi avain.

HTTP-moduuli ”Make a request”

URL: perus-URL + /clientes. Menetelmä GET. Authorization-otsake, jonka arvona on Bearer ja avaimesi. Valitse ”Parse response”, jotta voit käsitellä JSONia.

Testaa yhteys

Aja ensin kertaalleen pyyntö osoitteeseen /me: jos se palauttaa organisaatiosi ja avaimen nimen, todennus on kunnossa.

Lisää vaiheittainen suodatin

Tallenna edellisen ajon päivämäärä Data storeen tai muuttujaan ja välitä se URL:ssa parametrina actualizadoDesde. Ajasta skenaario 15 minuutin välein.

Yhdistä kentät CRM:ään

Käy läpi data[] ja yhdistä id, codigo, nombre, apellidos, email, telefono, nif_cif ja direccion. Tallenna Sattotalin id CRM:ään, jotta päivität etkä monista.

Asiakkaiden luomiseen CRM:stä lisää toinen HTTP-moduuli menetelmällä POST osoitteeseen /clientes ja asiakkaan JSON-runko. Jos saat 409, yhdistä existenteId-arvolla.

Hyvät tietoturvakäytännöt

Yksi avain integraatiota kohden

Näin voit perua yhden rikkomatta muita, ja luettelosta näet, milloin kutakin on viimeksi käytetty.

Ei koskaan selaimeen eikä julkiseen koodivarastoon

Tallenna se työkalusi tunnistetietojen säilöön (Maken yhteydet, n8n:n tunnistetiedot, ympäristömuuttujat). Jos se päätyy koodivarastoon tai verkkosivulle, pidä sitä vuotaneena.

Jos avain vuotaa, peru se ja luo uusi

Peruminen tapahtuu heti: vanha avain alkaa saada 401 CLAVE_REVOCADA. Päivitä uusi työkaluusi, ja valmista tuli.

API-määrittely

Täydellinen tekninen viite (polut, parametrit, skeemat ja virhekoodit) on julkaistu avoimessa muodossa osoitteessa /api/v1/openapi.json ilman avainta. Oletuksena se on espanjaksi; lisää ?lang= ja kielesi koodi, niin saat sen käännettynä (esimerkiksi ?lang=fi tai /api/v1/openapi.json?lang=en). Voit tuoda sen Postmaniin, Insomniaan, Makeen tai n8n:ään, niin kaikki kutsut ovat valmiina.

Usein kysyttyä

Hukkasin avaimen, voinko nähdä sen uudelleen?

Et. Se näytetään vain luotaessa ja tallennetaan sen jälkeen palauttamattomasti. Peru se kohdassa Asetukset → API ja luo uusi.

Onko webhookeja, joilla Sattotal ilmoittaa CRM:lle, kun jokin muuttuu?

Ei vielä. Suositeltu tapa on kysellä säännöllisesti actualizadoDesde-parametrilla, joka palauttaa vain muuttuneet.

Mitä tietoja API tarjoaa?

Asiakkaat ja toimittajat: listaus, luominen, hakeminen, päivittäminen ja arkistointi. Oikeudet ovat resurssikohtaisia, joten ennen toimittajien tuloa luotu avain ei ylety niihin, ennen kuin ylläpitäjä valitsee sen sille. Lisäksi korjaustilaukset vain luku -tilassa (tila, päivämäärät, laite ja kustannusarvio) omalla oikeudellaan.

Voinko poistaa asiakkaan API:n kautta?

Et, vain arkistoida (activo = false), samoin kuin sovelluksessa. Tämä koskee sekä asiakkaita että toimittajia. Arkistoitu tietue näkyy edelleen synkronoinnissa, jotta CRM voi huomioida sen.

Sisältyykö API ilmaiseen suunnitelmaan?

Ei. Se sisältyy Basic-, Pro- ja Enterprise-suunnitelmiin sekä kokeilujaksoon. Ilmaisessa suunnitelmassa voit silti nähdä ja perua luomasi avaimet.

Asiakkaasta tulee perille vain sukunimi. Miksi etunimeä ei tallenneta?

Syy on lähes aina kenttämäppäys: etunimi kuuluu kenttään nombre ja sukunimi kenttään apellidos. Jos työkalusi lähettää etunimen toisella avaimella (firstName, name, apellido…), API hylkää sen ja kertoo siitä vastauksen kohdassa avisos.camposIgnorados. Korjaa mäppäys ja lähetä asiakas uudelleen PATCH-pyynnöllä.

Voinko löytää asiakkaan numerolla, josta minulle soitetaan?

Kyllä. Tee pyyntö GET /api/v1/clientes?telefono= numerolla sellaisenaan kuin se tulee: ei ole väliä, onko siinä maatunnus, välilyöntejä tai väliviivoja, ja haku kohdistuu myös toissijaiseen puhelinnumeroon. Asiakkaan id:llä voit sen jälkeen hakea hänen tilauksensa (/clientes/{id}/reparaciones) ja yhteenvetonsa (/clientes/{id}/resumen).

Edellinen

Haluatko kokeilla itse?

Kokeile Sattotalia ilmaiseksi esimerkkitiedoilla, ilman luottokorttia.