Pipedriven tekninen integraatio-opas
Pipedrive-ylläpitäjille, tietoturva-arvioijille ja IT:lle — miten Revial todentaa, mihin scopeihin ja oikeuksiin se tukeutuu, API-kulutus, virhetilanteet ja auditointi.
Tämä opas kuvaa, mitä Revial tekee Pipedrive-yrityksessäsi, jotta voit hyväksyä, määrittää ja myöhemmin auditoida integraation. Yhdistäminen ja B2B/B2C-rajaus: Yhdistetään Revial Pipedriveen. Jokainen luettava ja kirjoitettava kenttä: Mitä Revial synkronoi Pipedriven kanssa.
1. Mitä hyväksyt
Revial yhdistyy Pipedrive Marketplace OAuth -sovelluksena Pipedriven API:n kautta (v2-päätepisteet sekä v1 muistiinpanoille, diilien osallistujille ja käyttäjän tarkistukselle).
| Ominaisuus | Arvo |
|---|---|
| Pääsymalli | Delegoitu — Revial toimii valtuuttaneena Pipedrive-käyttäjänä |
| Protokolla | OAuth 2.0 -valtuutuskoodi |
| Scopet | Määritetty Marketplace-sovellukseen (katso Yhdistäminen, luku 4) |
| Pipedriven ylläpito-oikeudet | Revial ei vaadi; yrityksesi voi rajoittaa, kuka saa asentaa sovelluksia |
| Sovelluskohtainen pääsy | Ei ole |
Kaikkea, mitä Revial näkee ja kirjoittaa, rajoittavat valtuuttavan käyttäjän käyttöoikeusjoukko ja näkyvyysryhmät.
2. Mitä ylläpitäjäsi tarvitsee tehdä
| Tilanne | Mitä tehdä |
|---|---|
| Yrityksesi rajoittaa Marketplace-asennuksia | Asenna sovellus ylläpitäjänä tai salli valtuuttavan käyttäjän asentaa |
| Haluat erillisen integraatiokäyttäjän | Luo se sillä näkyvyydellä, joka Revialilla kuuluu olla, ja anna sen yhdistää |
| Haluat Revialin kirjoittavan kenttiin | Luo kentät Pipedriveen ja mäppää ne Revialissa |
| Kuluttaja- ja yritysdatalla on sama näkyvyys | Lue yhdistämisoppaan luku 2 ennen yhdistämistä |
3. Todennus ja tunnistemalli
| Ominaisuus | Arvo |
|---|---|
| Valtuutuspäätepiste | https://oauth.pipedrive.com/marketplace/oauth/authorize |
| Tunnistepäätepiste | https://oauth.pipedrive.com/oauth/token (asiakas todennetaan HTTP Basicilla) |
| Scope-parametri | Ei lähetetä — Pipedrive myöntää sovellukseen määritetyt scopet |
| PKCE | Ei käytössä |
| API-osoite | Pipedriven tunnisteen mukana palauttama api_domain, tallennetaan yhteyskohtaisesti |
| Tarkistus yhdistämisen jälkeen | GET /api/v1/users/me |
| Tunnisteen elinikä | Pipedriven ilmoittama (expires_in); päivitetään, kun jäljellä on alle 35 minuuttia |
State. Satunnainen kertakäyttöinen state, voimassa viisi minuuttia ja sidottu Revial-käyttäjään, joka aloitti kulun; paluukutsu tarkistaa käyttäjän ylläpitäjäroolin uudelleen.
Säilytys. Pääsy- ja päivitystunnisteet salataan levossa (AES-256-GCM). Revial tallentaa myös API-osoitteen, Pipedrive-yrityksen tunnuksen sekä valtuuttavan käyttäjän tunnuksen, nimen ja sähköpostin. Client secret pysyy Revialin palvelimilla.
Päivitys. Enintään kolme yritystä lyhyellä viiveellä. Jos Pipedrive palauttaa uuden päivitystunnisteen, se tallennetaan. 401 tai invalid_grant merkitsee yhteyden uudelleenvaltuutusta vaativaksi, ja organisaation ylläpitäjä saa sovelluksen sisäisen ilmoituksen; tunnin välein ajettava synkronointi ohittaa yhteyden. Jos kierrätettyä tunnistetta ei voida tallentaa, yhteys merkitään myös rikkinäiseksi sen sijaan, että jatkettaisiin kuolleella tunnisteella.
Kuka voi yhdistää Revialin puolella. Organisaation omistaja tai ylläpitäjä tilauksella, joka sisältää CRM-integraation; pyyntömäärää rajoitetaan. Yksi Pipedrive-yhteys organisaatiota kohden; muita CRM-järjestelmiä voi yhdistää rinnalle. Yhdistäminen nollaa yhteyden tallennetut asetukset.
4. Scopet ja niiden käyttö
| Revialin tarvitsee… | Scope |
|---|---|
| Lukea organisaatiot, henkilöt, diilit, osallistujat | organizations:read, persons:read, deals:read |
| Lukea pipelinet ja vaiheet | pipelines:read |
| Lukea aktiviteetit | activities:read |
| Tarkistaa valtuuttava käyttäjä | users:read (vain /users/me) |
| Luoda muistiinpanoja; päivittää mäpättyjä kenttiä | deals:write, persons:write, organizations:write |
| Mitään tuotteisiin liittyvää tai luoda aktiviteetteja | Ei käytössä |
Pipedrivessa ei ole kenttätason scopeja, joten kirjoitusscopet sallivat minkä tahansa käyttäjän muokattavissa olevan kentän päivittämisen. Revial kirjoittaa vain muistiinpanoja ja ylläpitäjiesi mäppäämiä kenttiä.
5. Mitä Revial lukee
Organisaatiot, henkilöt, diilit (osallistujineen), pipelinet ja vaiheet, kaikentyyppiset aktiviteetit sekä muistiinpanot. Valtuuttava käyttäjä tarkistetaan kerran yhdistettäessä, ja kenttämääritykset luetaan mäppäysnäkymää varten. Tiedot: Mitä Revial synkronoi Pipedriven kanssa.
Revial ei lue sähköpostien sisältöä, tiedostoja, tuotteita eikä käyttäjälistaasi.
6. Mitä Revial kirjoittaa
| Toiminto | Päätepiste | Tiedot |
|---|---|---|
| Tapaamisen yhteenveto | POST /api/v1/notes | Yksi muistiinpano kohdetta kohden, content ja yksi kentistä deal_id, person_id, org_id |
| Mäpätyt kentät | PATCH /api/v2/{persons,organizations,deals}/{id} | Vain ylläpitäjiesi mäppäämät kentät |
Ennen mäpättyä kirjoitusta Revial lukee tietueen (GET /api/v2/{entity}/{id}), jotta olemassa olevat arvot jätetään ennalleen. Revial ei koskaan poista mitään eikä luo diilejä, henkilöitä, organisaatioita tai aktiviteetteja.
7. Kenttien mäppäykset
Organisaation ylläpitäjät ja omistajat määrittävät ne kohdassa Organisaatio → CRM-asetukset → Ominaisuuksien yhdistäminen. Arvot muunnetaan Pipedrive-kentän tyypin mukaan (luvuiksi rahamäärä- ja lukukentissä, muuten tekstiksi), ja teksti rajataan 64 kilotavuun. Epäonnistunut eräpäivitys yritetään kenttä kerrallaan ja virheet raportoidaan.
Tunnetut ongelmat: organisaatiokenttien listassa näkyvät tällä hetkellä tiimikentät; ja Pipedriven v2-API saattaa odottaa mukautettuja kenttiä sisäkkäisessä rakenteessa, jota Revial ei vielä lähetä — jos mäpättyä mukautettua kenttää ei päivitetä, ota yhteyttä tukeen.
8. Synkronoinnin tahti ja API-kulutus
- Ensimmäinen synkronointi — jokaisen entiteetin täysi haku, 500 tietuetta sivulla, enintään 50 000 tietuetta päätepistettä kohden.
- Seuraavat synkronoinnit — noin tunnin välein,
updated_sinceedellisestä synkronoinnista, päivitysajan mukaan järjestettynä. - Järjestys — organisaatiot → henkilöt → vaiheet → diilit → aktiviteetit → muistiinpanot, kukin omana ajonaan.
Diilien osallistujat haetaan yhdellä pyynnöllä diiliä kohden sekä täysissä että inkrementaalisissa synkronoinneissa, joten suuri pipeline tarkoittaa monia kutsuja. Vaiheet haetaan pipelinekohtaisesti.
Rate limitit. Synkronointi ei hidasta eikä lue Pipedriven rate limit -otsakkeita: epäonnistunut pyyntö kaataa kyseisen vaiheen, jonka työjono yrittää uudelleen. Rate limit -vastaus osallistujien haussa kaataa diilivaiheen kyseisellä ajolla. Revialista tehdyt manuaaliset kirjoitukset yrittävät enintään kolme kertaa ja noudattavat Retry-After-otsaketta.
Aikakatkaisut. 30 sekuntia pyyntöä kohden.
Poistot. Poistetuiksi merkityt tietueet poistetaan inkrementaalisissa synkronoinneissa; täysi synkronointi ei suodata niitä pois.
Tietueraja. Jos päätepisteellä on yhdellä ajolla yli 50 000 muuttunutta tietuetta, loput ohitetaan eikä niitä haeta myöhemmin.
9. Tapaamisten yhdistäminen CRM-tietueisiin
Revial linkittää tapaamisen Pipedrive-tietueisiin tässä järjestyksessä, ensimmäinen osuma voittaa: tapaamisen suorat tunnukset; avoin diili, johon tapaaminen on jo linkitetty; osallistujien sähköpostit → henkilöt → heidän diilinsä (pisteytettyinä); organisaatio verkkosivun tai sähköpostin verkkotunnuksen perusteella; organisaatio nimen perusteella. Pisteytys suosii avoimia diilejä, osallistujaa diilin henkilönä, muita osallistujia diilissä, otsikon samankaltaisuutta, pidemmälle edenneitä vaiheita ja tuoreutta. Suljetut diilit jätetään pois, ja ilmaisten sähköpostipalveluiden verkkotunnukset ohitetaan organisaatiotunnistuksessa.
10. Tietoturva, rajat ja virhetilanteet
- Vähimmät oikeudet: vain delegoitu pääsy; valtuuttavan käyttäjän näkyvyys on ehdoton raja.
- Salaisuudet: tunnisteet salattu levossa; client secret vain palvelimella.
- Osittaiset virheet: virhe ensimmäisen pipelinen vaiheiden tai diilien osallistujien lukemisessa merkitsee synkronoinnin osittaiseksi sen sijaan, että se raportoitaisiin onnistuneeksi.
- Muistiinpanot kerran: tapaamisen yhteenveto kirjoitetaan kerran yhteyttä kohden.
- Datan säilytys: synkronoidut tietueet ja raa'at API-vastaukset tallennetaan Revialiin ja poistetaan, kun katkaiset yhteyden.
11. Auditointi ja yhteyden katkaiseminen
Pipedrivessa: asennetut Marketplace-sovellukset näyttävät Revialin; Revialin kirjoittamien muistiinpanojen tekijä on valtuuttava käyttäjä.
Yhteyden katkaiseminen:
- Revialissa — Katkaise yhteys Pipedrive-kortissa. Revial poistaa synkronoidun kopionsa, tunnisteet ja kenttien mäppäykset. Se ei tee peruutuskutsua Pipedriveen.
- Pipedrivessa — poista sovellus tai poista valtuuttava käyttäjä käytöstä. Revialin seuraava päivitys epäonnistuu, yhteys merkitään ja synkronointi pysähtyy.
Kumpikaan ei poista muistiinpanoja tai kenttien arvoja, jotka Revial on jo kirjoittanut.
12. Vianmääritys
| Oire | Todennäköinen syy | Korjaus |
|---|---|---|
| Kortissa odottamaton sähköpostiosoite | Toinen Pipedrive-tili oli kirjautuneena | Katkaise yhteys, kirjaudu ulos Pipedrivesta, yhdistä uudelleen |
| Diilejä puuttuu | Valtuuttavan käyttäjän näkyvyys | Muuta näkyvyysryhmiä tai yhdistä käyttäjällä, joka näkee ne |
| Synkronointi merkitty osittaiseksi | Vaiheita tai osallistujia ei voitu lukea | Tarkista käyttäjän oikeudet; seuraava synkronointi yrittää uudelleen |
| Mäpätty kenttä ei päivity | Tyyppiristiriita tai luvun 7 mukautettujen kenttien ongelma | Tarkista kenttäkohtainen virhe; ota yhteyttä tukeen |
| "CRM: Authentication expired" | Sovellus poistettu tai käyttäjä poistettu käytöstä | Yhdistä uudelleen |
| Runsas API-käyttö | Ensimmäinen synkronointi tai paljon diilejä (osallistujat diileittäin) | Odotettua; myöhemmät synkronoinnit seuraavat muutoksia |
Mitä Revial synkronoi Pipedriven kanssa
Pipedrive-ylläpitäjällesi ja sille, joka arvioi integraation tietojen käyttöoikeudet — jokainen Pipedrive-kenttä, jonka Revial lukee, kaikki mitä se kirjoittaa takaisin ja tunnetut puutteet.
Yhdistetään Revial Salesforceen
OAuth-kirjautuminen, tuotanto- ja sandbox-ympäristöt, yhdistetyn sovelluksen hyväksyminen ja mitä tehdä, kun yhteys on estetty.