Groweo-kontaktien tuominen Pipedriveen GET API-rajapinnalla

Groweon GET-rajapinnan avulla voit hakea Groweo® Contactsiin tallennettuja kontakteja Pipedriveen ilman manuaalista tiedonsiirtoa.

Integraatio hakee kontaktit Groweosta API-tokenilla ja luo tai päivittää niitä vastaavat henkilöt Pipedrivessa. Pipedriven API-kontakteja kutsutaan nimellä Persons.

Groweon rajapinta on tarkoitettu kontaktien lukemiseen. Sen kautta ei voi lisätä, muokata tai poistaa Groweon kontakteja. Groweo ei myöskään työnnä kontaktidataa automaattisesti Pipedriveen, vaan integraatio hakee tiedot Groweosta ja tallentaa ne Pipedriveen.

Tässä ohjeessa toteutus tehdään erillisellä integraatiolla, joka yhdistää Groweon GET API Pipedriven REST APIin.

Huomaathan, että Groweo ei suunnittele tai toteuta integraatiota, vaan tarjoaa GET API -rajapinnan avaimineen integraatiota varten. Artikkeli sisältää ohjeet ja esimerkin rajapinnan käyttöön – integraation suunnittelu ja toteutus ovat sinun tai kumppanisi vastuulla.

Ennen kuin aloitat

Tarvitset:

Groweo API-tokenin
Pipedrive API-tokenin tai OAuth-yhteyden
oikeudet luoda Pipedriveen omia Person-kenttiä
Groweon ja Pipedriven välisen kenttämappauksen
ympäristön, jossa integraatiokoodi suoritetaan ja voidaan ajastaa.

1. Hanki Groweo API-token

Saat Groweo API-tokenin omalta Groweo-asiakasvastaavaltasi tai Groweon asiakaspalvelusta.

Groweon kontaktirajapinnan osoite on:

GET https://engine.groweo.com/engine/api/client-api/contacts

Esimerkiksi ensimmäinen 50 kontaktin sivu voidaan hakea parametreilla:

?page=1&limit=50&populateModuleData=true

API-token välitetään HTTP-headerissa:

x-client-api-token: <API_TOKEN>

Kokonainen kutsu näyttää esimerkiksi tältä:

GET https://engine.groweo.com/engine/api/client-api/contacts?page=1&limit=50&populateModuleData=true

Testaa kutsu ensin esimerkiksi Postmanilla. Näin näet oman Groweo-ympäristösi palauttaman JSON-rakenteen ja voit määrittää sen perusteella Pipedriveen siirrettävät tiedot.

2. Valitse Pipedriven autentikointitapa

Pipedrive tukee API-tokeniin ja OAuth 2.0 perustuvaa autentikointia.

Yhden yrityksen omaan integraatioon voidaan käyttää Pipedrive API-tokenia. Pipedriven nykyisessä API token välitetään x-api-token-headerissa:

x-api-token: <PIPEDRIVE_API_TOKEN>

API-token on sidottu tiettyyn Pipedrive-käyttäjään ja yritykseen, joten sitä pitää käsitellä salaisuutena.

Integraatioympäristössä tarvitaan tällöin kaksi tunnistetta:

GROWEO_API_TOKEN
PIPEDRIVE_API_TOKEN

Älä kirjoita tokeneita suoraan lähdekoodiin, vaan säilytä ne integraatioympäristön secrets- tai environment variables -asetuksissa.

Jos rakennat sovelluksen useiden Pipedrive-asiakkaiden käyttöön, käytä OAuth 2.0 -autentikointia. Pipedriven Marketplace-sovellukset käyttävät OAuth 2.0.

3. Luo Pipedriveen Groweo ID -kenttä

Kontaktit tallennetaan Pipedrivessa Person-tietueiksi.

Integraatiota varten kannattaa luoda Personille oma custom field:

Groweo ID

Tekstimuotoisen kentän API-tyyppi on:

varchar

Kentän voi luoda Pipedriven käyttöliittymässä tai API v2 kautta:

POST /api/v2/personFields

Groweo ID avulla integraatio voi tunnistaa, mikä Pipedrive Person vastaa mitäkin Groweo-kontaktia.

Periaate on:

Groweo contact ID
        ↓
Pipedrive Person
        ↓
custom field: Groweo ID

Jos Groweon API tarjoaa kontaktille pysyvän yksilöllisen tunnisteen, käytä sitä ensisijaisena integraatioavaimena sähköpostiosoitteen sijaan.

Huomio: varmista ensin Groweon todellisesta API-vastauksesta, että käytettävissä on tähän tarkoitukseen sopiva pysyvä kontaktitunniste.

4. Selvitä Groweo ID -kentän API-tunniste

Pipedriven custom fieldit tunnistetaan API omilla kenttäkoodeillaan.

Person-kentät voidaan hakea endpointista:

GET /api/v2/personFields

Pipedrive palauttaa jokaiselle kentälle sen API käytettävän field_code-arvon.

Custom fieldin tunniste on Pipedriven generoima merkkijono. Älä siis rakenna integraatiota käyttöliittymässä näkyvän Groweo ID -nimen varaan, vaan käytä oman Pipedrive-ympäristösi palauttamaa kenttäkoodia.

5. Hae kontaktit Groweosta

Integraatiopalvelu tekee GET-kutsun Groweon kontaktirajapintaan.

Esimerkiksi JavaScriptillä:

const response = await fetch(
  'https://engine.groweo.com/engine/api/client-api/contacts' +
  '?page=1&limit=50&populateModuleData=true',
  {
    method: 'GET',
    headers: {
      'x-client-api-token': process.env.GROWEO_API_TOKEN
    }
  }
);

if (!response.ok) {
  throw new Error(`Groweo API returned ${response.status}`);
}

const data = await response.json();

Ensimmäisessä testissä kannattaa tarkistaa Groweon palauttama JSON-rakenne ennen Pipedrive-mappauksen rakentamista.

Groweon API koko kontaktivastauksen rakennetta ei ole määritelty tässä ohjeessa. Kenttämappaus pitää siksi tehdä oman Groweo-ympäristösi todellisen API-vastauksen perusteella.

6. Määritä kenttämappaus

Seuraavaksi määritetään, mitkä Groweon tiedot tallennetaan Pipedriveen.

Mappaus voi sisältää esimerkiksi seuraavat:

Groweon tieto	Pipedrive Person
kontaktin yksilöllinen tunniste	Groweo ID
nimi	Name
sähköposti	Email
puhelinnumero	Phone
yrityksen nimi	Organization
muut tarvittavat Groweo-tiedot	omat Person custom fieldit

Taulukko kuvaa mahdollista kenttämappausta, ei Groweon API:n dokumentoitua response-skeemaa.

Jos populateModuleData=true palauttaa integraatiossa tarvittavaa moduulikohtaista dataa, sille voidaan luoda omat Person-kentät Pipedriveen.

7. Tarkista, löytyykö kontakti jo Pipedrivesta

Pipedriven Persons API ei ole suoraa upsert-endpointia, joka tekisi tässä tarvittavan haun ja luonnin tai päivityksen yhdellä pyynnöllä.

Integraation pitää siksi ensin selvittää, löytyykö Groweo-kontaktia vastaava Person jo Pipedrivesta.

Pipedriven API v2 tukee henkilöiden hakemista myös tietyntyyppisistä custom fieldeistä. varchar-tyyppinen Groweo ID -kenttä on haettavissa.

Haku voidaan tehdä endpointilla:

GET /api/v2/persons/search

ja esimerkiksi parametreilla:

term=<GROWEO_ID>
fields=custom_fields
exact_match=true

Integraatiologiikka on:

Groweo contact
        ↓
etsi Pipedrivesta Groweo ID:llä
        ↓
      löytyi?
     ↙       ↘
  kyllä       ei
    ↓          ↓
 PATCH        POST
 Person       Person

Tarkista hakutuloksesta myös, että löytynyt tietue todella vastaa käytettyä Groweo IDä.

8. Luo uusi Person Pipedriveen

Jos Groweo IDä vastaavaa henkilöä ei löydy, integraatio luo uuden Person-tietueen endpointilla:

POST /api/v2/persons

Periaatteellinen request-rakenne voi olla:

{
  "name": "Matti Meikäläinen",
  "emails": [
    {
      "value": "matti@example.com",
      "primary": true
    }
  ],
  "phones": [
    {
      "value": "+358401234567",
      "primary": true
    }
  ],
  "custom_fields": {
    "GROWEO_ID_FIELD_CODE": "groweo-contact-id"
  }
}

Korvaa GROWEO_ID_FIELD_CODE oman Pipedrive-ympäristösi Groweo ID -kentän tunnisteella.

Esimerkin henkilötiedot ja kentät ovat havainnollistavia eivätkä kuvaa Groweon dokumentoitua API-vastausta.

9. Päivitä olemassa oleva Person

Jos Groweo IDä vastaava Person löytyy, integraatio käyttää löydetyn henkilön Pipedrive IDä päivitykseen.

Endpoint on:

PATCH /api/v2/persons/{id}

Päivityksessä lähetetään vain ne tiedot, jotka integraation halutaan päivittävän.

Näin esimerkiksi sähköpostiosoite voi muuttua ilman, että Pipedriveen syntyy uusi Person-tietue.

10. Huomioi Organizations-tietueet

Pipedrivessa yritykset tallennetaan erillisinä Organization-tietueina, joihin Person voidaan liittää.

Jos integraatiossa halutaan synkronoida myös yritykset, pitää erikseen määrittää, miten Groweon yritystieto yhdistetään olemassa olevaan Pipedrive Organizationiin tai milloin uusi Organization luodaan.

Pelkkää yrityksen nimeä ei kannata automaattisesti käyttää pysyvänä integraatioavaimena, koska samannimisiä yrityksiä voi olla useita.

Jos Groweon API-vastaus sisältää yritykselle luotettavan yksilöllisen tunnisteen, sitä voidaan hyödyntää yritysten yhdistämisessä.

Jos yritystietojen synkronointia ei tarvita, Organization-logiikan voi jättää integraatiosta pois.

11. Huomioi Groweon sivutus

Groweon API käyttää sivutusta. Esimerkiksi:

?page=1&limit=50

Jos kontakteja on enemmän kuin yhdelle sivulle mahtuu, integraation pitää hakea myös seuraavat sivut.

Esimerkiksi:

page = 1
    ↓
GET Groweo
    ↓
käsittele kontaktit
    ↓
page = 2
    ↓
GET Groweo
    ↓
käsittele kontaktit
    ↓
...

Tarkka tapa viimeisen sivun tunnistamiseen pitää määrittää Groweon todellisen API-vastauksen perusteella.

12. Ajasta synkronointi

Koska Groweon rajapinta on GET-rajapinta eikä Groweo työnnä muutoksia Pipedriveen, integraatio voidaan ajaa ajastetusti esimerkiksi kerran tunnissa tai kerran vuorokaudessa.

Integraation voi suorittaa esimerkiksi pilvifunktiossa, omalla palvelimella tai muussa ajastettavassa integraatioympäristössä.

Tietovirta on toteutustavasta riippumatta:

Ajastus
    ↓
Groweo GET API
    ↓
kontaktien käsittely
    ↓
Pipedrive Persons API
    ↓
create / update

Valitse synkronointiväli todellisen käyttötarpeen ja käsiteltävän kontaktimäärän perusteella.

13. Huomioi Pipedriven API-rajoitukset

Pipedrive käyttää API token-pohjaista käyttörajoitusta. Jokaisella endpointilla on oma token-kustannuksensa, ja API-kutsut kuluttavat yrityksen yhteistä päivittäistä token-budjettia.

Päivittäisen budjetin lisäksi Pipedrive käyttää lyhyen aikavälin burst-rajoituksia.

API v2 -endpointeja kannattaa käyttää aina, kun tarvittava toiminto on saatavilla niiden kautta. Ne on optimoitu muun muassa suorituskyvyn ja token-kulutuksen kannalta.

Tässä integraatiossa yksi Groweo-kontakti voi tavallisessa toteutuksessa aiheuttaa vähintään:

1 Person search
+
1 Person create tai update

Jos kontakteja synkronoidaan paljon ja usein, API-kutsujen määrä kasvaa nopeasti.

Kun Pipedriven käyttöraja ylittyy, API voi palauttaa:

429 Too Many Requests

Integraation pitää huomioida Pipedriven palauttamat rate limit -tiedot ja käsitellä 429-vastaukset hallitusti.

14. Vältä tarpeettomia päivityksiä

Jos Groweon API-vastaus sisältää luotettavan tiedon kontaktin viimeisimmästä muokkauksesta, sitä voidaan hyödyntää muuttuneiden kontaktien tunnistamiseen.

Jos tällaista tietoa ei ole saatavilla, integraatio voi esimerkiksi verrata olennaisia Groweo- ja Pipedrive-kenttiä ennen PATCH-pyynnön tekemistä.

Älä rakenna muutosten tunnistamista tietyn Groweo-kentän varaan ennen kuin olet varmistanut sen saatavuuden API-vastauksesta.

Tarpeettomien päivitysten välttäminen vähentää Pipedrive API token-kulutusta.

15. Lisää virheenkäsittely

Tuotantointegraation pitää käsitellä ainakin:

Groweo API -virheet
Pipedrive API -virheet
Pipedriven 429-vastaukset
puuttuvat tai virheelliset tiedot
yksittäisen kontaktin synkronoinnin epäonnistuminen.

Yhden virheellisen kontaktin ei pitäisi pysäyttää koko synkronointia.

Kirjaa lokiin riittävät tiedot virheen selvittämiseksi, mutta älä tallenna lokiin API-tokeneita tai tarpeettomia henkilötietoja.

16. API-token vai OAuth?

Yhden yrityksen omassa integraatiossa Pipedrive API-tokenia voidaan käyttää autentikointiin.

Tällöin integraatiolla on esimerkiksi:

Groweo API token
+
Pipedrive API token

Jos integraatio rakennetaan sovellukseksi, jonka useat asiakkaat yhdistävät omiin Pipedrive-tileihinsä, käytä OAuth 2.0 -autentikointia.

OAuthissa Pipedrive-käyttäjä antaa sovellukselle määritellyt käyttöoikeudet, minkä jälkeen integraatio käyttää access tokenia API-kutsuihin ja refresh tokenia yhteyden uusimiseen.

Yksinkertaistettuna:

Yhden yrityksen oma integraatio
→ API-token mahdollinen

Useiden asiakkaiden sovellus
→ OAuth 2.0

Integraation rakenne lyhyesti

                  GROWEO®
                     │
                     │ GET
                     ▼
               Contacts API
                     │
           x-client-api-token
                     │
                     ▼
             Integraatiopalvelu
                     │
               kenttämappaus
                     │
              Groweo ID -haku
                     │
                     ▼
           Pipedrive Persons API
                ↙           ↘
             POST           PATCH
               │              │
               └──────┬───────┘
                      ▼
                  PIPEDRIVE

Groweo toimii integraatiossa kontaktidatan lähteenä. Integraatio hakee tiedot Groweosta ja luo tai päivittää niitä vastaavat Person-tietueet Pipedrivessa.

Mitä tarvitset integraatiota varten?

Tarvitset:

Groweo API-tokenin
Pipedrive API-tokenin tai OAuth-yhteyden
Groweo ID -custom fieldin tai muun sovitun yksilöintitavan Pipedrive Personille
Groweo- ja Pipedrive-kenttien mappauksen
integraatiopalvelun, joka hakee Groweo-kontaktit
logiikan olemassa olevan Personin tunnistamiseen
kontaktien luonti- ja päivityslogiikan
Groweon sivutuksen käsittelyn
ajastuksen ja virheenkäsittelyn.

Aloita yhdellä kontaktisivulla

Ennen varsinaisen synkronoinnin rakentamista hae Groweosta yksi sivu:

page=1
limit=50
populateModuleData=true

Tarkista palautuvan JSON-datan rakenne ja määritä sen perusteella Groweon ja Pipedriven välinen kenttämappaus.

Testaa sen jälkeen yhdellä kontaktilla:

Groweo contact
        ↓
Groweo ID
        ↓
Pipedrive search
        ↓
create tai update

Näin integraation kentät ja tunnistuslogiikka voidaan varmistaa ennen kaikkien kontaktien synkronointia.

Näin tuot Groweo® -kontaktisi GET-APIn avulla Pipedriveen