Naar de hoofdinhoud

CRM Public API: personen, bedrijven, deals, taken en activiteiten

H
Geschreven door Hayko

CRM Public API: personen, bedrijven, deals, taken en activiteiten

Met de CRM Public API kan je eigen systeem het CRM van je QrX-organisatie lezen en wijzigen: personen, bedrijven, deals, pijplijnen, taken, de tijdlijn met activiteit en notities. Dit artikel is voor ontwikkelaars. De basis-URL is https://api.qr-x.net. Elke aanroep vereist Authorization: Bearer <accessToken>. Voor het toegangstoken, zie "Snelstart voor ontwikkelaars: QrX Public API en webhooks".

Wat je nodig hebt

  • Een QrX CRM-abonnement dat de publieke API bevat. De publieke API maakt deel uit van Business en Enterprise. Zonder dat wordt een aanroep met een sleutel met de CRM-scopes geweigerd met 402, en een sleutel zonder de CRM-scopes krijgt eerst 403 CRM_SCOPE_MISSING.

  • Een API-sleutel (sleutel van een verkoopkanaal) waarbij de CRM-scopes zijn aangevinkt, zie "Een API-sleutel met scopes aanmaken" hieronder.

  • Voor de taken-endpoints is ook de functie Taken nodig, en voor de endpoints voor deals en pijplijnen de functie Deals in je abonnement.

Een API-sleutel met scopes aanmaken

CRM-toegang wordt nooit standaard verleend. Een sleutel zonder beperking (Volledige toegang) heeft geen CRM-toegang. Je moet de sleutel beperken en de CRM-scopes zelf aanvinken.

  1. Ga naar Instellingen > Zakelijk > Handelaarskanalen en open het verkoopkanaal waarvan je de sleutel wilt gebruiken.

  2. Open het tabblad Instellingen. Het blok API-toegang staat onder het veld API-sleutel. Je hebt het recht Kanalen beheren nodig om het te wijzigen.

  3. Zet Deze sleutel beperken aan.

  4. Vink onder CRM CRM-personen, bedrijven, deals en pijplijnen lezen aan (scope crm.read) en, als je systeem moet schrijven, CRM-personen, bedrijven, deals en notities aanmaken en wijzigen (scope crm.write).

  5. Klik op API-toegang opslaan, controleer de lijst onder Stopt met werken en klik op De sleutel beperken. Een wijziging kan tot 30 seconden duren voordat ze wordt toegepast.

Let op: een sleutel beperken schakelt ook elk onderdeel uit dat je niet aanvinkt, voor integraties die nu werken. Als deze sleutel ook transacties aanmaakt, blijven die werken, maar de scopes voor retouren, inkomend, voorraad, inkoop, fulfilment en taken moeten opnieuw worden aangevinkt als de sleutel ze gebruikt. Zie "Een API-sleutel beperken (API-toegang)".

Scopes

  • crm.read: alle GET-aanroepen (pijplijnen, personen, bedrijven, deals, taken, activiteiten).

  • crm.write: alle POST- en PUT-aanroepen (personen, bedrijven, deals, taken en notities aanmaken en wijzigen, een deal verplaatsen, een taak afronden). Een schrijfscope omvat niet het lezen: vink beide aan als je beide nodig hebt.

Een ontbrekende scope antwoordt met 403 CRM_SCOPE_MISSING.

Een toegangstoken ophalen

Stuur POST /api/v1/auth/token met de header QrX-MerchantChannel-API-Key ingesteld op je sleutel. Gebruik het toegangstoken uit het antwoord als bearer-token bij elke CRM-aanroep. Stuur de API-sleutel zelf nooit naar de CRM-endpoints.

Endpoints

Alle paden beginnen met /api/v1/crm.

  • Pijplijnen: GET /pipelines (pijplijnen met hun fases: id, naam, soort en kans).

  • Personen: GET /people, GET /people/{id}, POST /people, PUT /people/{id}.

  • Bedrijven: GET /companies, GET /companies/{id}, POST /companies, PUT /companies/{id}.

  • Deals: GET /deals, GET /deals/{id}, POST /deals, PUT /deals/{id}, POST /deals/{id}/move.

  • Taken: GET /tasks, GET /tasks/{id}, POST /tasks, PUT /tasks/{id}, POST /tasks/{id}/complete.

  • Activiteiten: GET /activities?recordType=person&recordId={id}. recordType is person, company of deal.

  • Notities: POST /notes.

Er is geen verwijderaanroep. Records verwijderen, samenvoegen en wissen gebeurt in PortalX.

Lijsten lezen

Lijsten geven items, nextCursor en hasMore terug. Geef nextCursor mee als cursor voor de volgende pagina en stop wanneer hasMore false is. limit is 1 tot 100 en is standaard 40.

  • Personen: de meest recent actieve eerst. q zoekt in namen, e-mailadressen en telefoonnummers. De lijst toont alleen het primaire e-mailadres en de primaire telefoon. GET /people/{id} geeft alle contactpunten, tags en aangepaste velden terug.

  • Bedrijven: de meest recent actieve eerst. q zoekt in namen en domeinen.

  • Deals: de meest recent bijgewerkte eerst. Filters: pipelineId, stageId, status (open, won of lost) en q.

  • Taken: de nieuwste eerst. Filters: state (open of done), assigneeUserId, personId, companyId en dealId.

Records aanmaken en wijzigen

  • Idempotency-Key: elke aanroep om iets aan te maken (POST voor personen, bedrijven, deals, taken en notities) vereist de header Idempotency-Key met 8 tot 80 tekens: letters, cijfers en . _ : -. Stuur dezelfde sleutel opnieuw om het nog eens te proberen en je krijgt het eerste resultaat terug in plaats van een tweede record. Gebruik een nieuwe sleutel voor elk nieuw record. Zonder geldige sleutel antwoordt de aanroep met 400 IDEMPOTENCY_KEY_REQUIRED.

  • version: elk record heeft een version. Een PUT, het verplaatsen van een deal en het afronden van een taak moeten de version meesturen die je hebt gelezen. Als iemand het record ondertussen heeft gewijzigd, krijg je 409 CRM_CONFLICT: lees het record opnieuw en probeer het met de nieuwe version.

  • Persoon: velden zijn onder meer firstName, lastName, jobTitle, companyId, lifecycleStageId, ownerUserId, language, country, emails, phones, tagIds en customFields. Een persoon waarvan het e-mailadres of telefoonnummer al bestaat, antwoordt met 409. Personen aanmaken telt mee voor de limiet voor personen van je abonnement.

  • Bedrijf: name, domains, vatNumber, chamberNumber, adresvelden, industry, sizeBand, website, ownerUserId, lifecycleStageId, tagIds en customFields.

  • Deal: title, pipelineId, stageId, value, currency, expectedCloseOn, probability, ownerUserId, primaryPersonId, personIds, companyId, source, tagIds en customFields. Zonder pijplijn en fase komt de deal in de standaardpijplijn. Een PUT kan de fase niet wijzigen: gebruik POST /deals/{id}/move met toStageId, version en, voor een fase Verloren, lostReasonId (en eventueel lostNote) als de pijplijn redenen van verlies heeft.

  • Notitie: POST /notes met recordType (person, company of deal), recordId en text. De tekst is platte tekst en wordt opgeslagen als een alinea.

Taken

Maak een taak aan met een title en een assigneeUserId van een gebruiker in je organisatie die het CRM kan gebruiken. Zonder toegewezen gebruiker mislukt de aanroep. Andere velden: description, type, priority, dueAt, timeZoneId, reminderAt, recurrence, en de koppelingen personId, companyId en dealId. Het afronden van een terugkerende taak geeft de afgeronde taak terug in task en de volgende in next.

Activiteiten en wat nooit wordt teruggegeven

De lijst met activiteiten toont de tijdlijn van één record. Notities bevatten hun gezuiverde HTML. Gesprekken, conversaties, bestellingen en retouren verschijnen alleen als metagegevens en zijn gemarkeerd als restricted. Privéberichten, betaalgegevens en links naar gespreksopnames zitten nooit in de API. De API geeft ook nooit deals van merchants, bestelstatistieken, toestemmingsgegevens of redenen van de leadscore terug.

Records die je via de API aanmaakt, hebben geen eigenaar tot je ownerUserId instelt.

Limieten voor aanvragen

Lezen (GET) is beperkt tot 1200 aanvragen per minuut en schrijven (POST en PUT) tot 300 aanvragen per minuut. Als je daaroverheen gaat, antwoordt de API met 429 en een header Retry-After. Wacht zoveel seconden voordat je het opnieuw probeert.

Fouten

Fouten gebruiken hetzelfde probleemformaat als de rest van de Public API: code, detail en een requestId.

  • 400 IDEMPOTENCY_KEY_REQUIRED: de header Idempotency-Key ontbreekt of heeft de verkeerde vorm.

  • 401 UNAUTHORIZED: geen geldig toegangstoken.

  • 402: je abonnement bevat de publieke API of de functie niet, of CRM_PLAN_LIMIT_REACHED: een abonnementslimiet zoals het aantal personen is bereikt. Upgrade het abonnement in PortalX.

  • 403 CRM_SCOPE_MISSING: de sleutel heeft crm.read of crm.write niet. Vink de scope aan en wacht 30 seconden.

  • 404 CRM_NOT_FOUND: het record bestaat niet in je organisatie.

  • 409 CRM_CONFLICT: de version is verouderd (record_changed) of de persoon bestaat al (duplicate). Lees het record opnieuw.

  • 422 VALIDATION_FAILED: een veld is ongeldig, bijvoorbeeld een ontbrekende version, een ongeldige cursor of een taak zonder toegewezen gebruiker. De detail zegt welke.

Webhook-gebeurtenissen voor het CRM

QrX kan je systeem ook laten weten wanneer er iets verandert in het CRM. Maak een webhook aan onder Instellingen > Geavanceerd > Webhooks (zie "Webhooks en API-sleutels in PortalX") en vink de CRM-gebeurtenissen aan die je wilt:

  • crm/person_created

  • crm/deal_created

  • crm/deal_moved

  • crm/deal_won

  • crm/deal_lost

  • crm/task_completed

  • crm/automation_triggered: verstuurd door de automatiseringsactie Een webhook-gebeurtenis versturen.

CRM-gebeurtenissen gaan naar elke actieve webhook van je organisatie waarbij de gebeurtenis is aangevinkt, ongeacht het verkoopkanaal. De payload bevat alleen id's en zakelijke feiten (bijvoorbeeld personId, dealId, title, pipelineId, stageId, value, currency, ownerUserId), nooit e-mailadressen, telefoonnummers, notities of berichtteksten. Elke gebeurtenis heeft een eventId die hetzelfde blijft wanneer QrX hem opnieuw aflevert, dus negeer een gebeurtenis waarvan je de eventId al hebt verwerkt. Gebeurtenissen ouder dan 24 uur worden niet verstuurd. Een deal die wordt gewonnen of verloren, stuurt ook crm/deal_moved. Leveringen zijn ondertekend met X-QrX-Signature, zie het artikel over webhooks.

Postman en OpenAPI

De Postman-collectie van de QrX Public API heeft de mappen CRM-taken en CRM-activiteiten. De API-documentatie staat op qrx.eu/api.

Veelvoorkomende problemen

  • 403 bij elke CRM-aanroep. De sleutel heeft volledige toegang of mist de scope. Beperk de sleutel en vink de CRM-scopes aan.

  • 402 bij elke CRM-aanroep. Je abonnement bevat de publieke CRM-API niet. Hij maakt deel uit van Business en Enterprise.

  • 409 bij bijwerken. Lees het record opnieuw en stuur de actuele version mee.

  • Taak aanmaken geweigerd. Controleer of assigneeUserId bij je organisatie hoort en of de gebruiker het CRM kan gebruiken.

  • Dubbele records na een nieuwe poging. Gebruik dezelfde Idempotency-Key opnieuw voor een nieuwe poging van hetzelfde record.

Wanneer je ons supportteam moet contacteren

Neem contact op met QrX support via [email protected] als een aangevinkte scope meer dan een minuut na het opslaan nog steeds wordt geweigerd, of bij incidenten in productie. Vermeld de request-ID, het endpoint en het tijdstip, nooit je API-sleutel of toegangstoken.

Gerelateerde artikelen
Was dit een antwoord op uw vraag?