Werken met de Gripp API

  1. home
  2. API & Koppelingen
  3. Werken met de Gripp API

Met een API kunnen andere softwareontwikkelaars op eenvoudige wijze gegevens in Gripp opvragen, toevoegen of wijzigen. Lees verder voor enkele voorbeelden, inclusief code.

Hoe maak ik een API-key en een API-rol aan?

Om gebruik te maken van de API dien je eerst een API-rol en een API-key aan te maken. Een API-rol bevat de rechten die het script heeft, dat gebruik maakt van de API-key. Zo kun je bijvoorbeeld instellen dat deze API-key alleen lees-rechten heeft tot het onderdeel relaties. De rollen kun je aanmaken via de instellingen > API-rollen > API-rol toevoegen. Wanneer de API-rol is aangemaakt, kun je via instellingen > tabblad API Keys je API-keys aanmaken.

Om de API te gebruiken heb je request packs nodig. Meer informatie vind je hier.

Online API-documentatie met test-mogelijkheid

Voor programmeurs zijn er de API-docs. Bekijk de API-documentatie online. Je kunt ook direct naar je eigen API-docs online omgeving, waarna je bij het invullen van een geldige key direct API-calls kunt testen op je eigen omgeving. Ga hiervoor naar https://MIJNDOMEIN.gripp.com/public/api3.php.

Connector class voor PHP

De Gripp API is een low-level API voor de meest voorkomende CRUD operaties, en is daarmee uitermate krachtig in hetgeen je kunt realiseren. Om het werken met de API nét even iets gemakkelijker te maken, kun je een API-connector downloaden (PhP). Met de connector wordt het uitvoeren van calls, en de afhandeling van de responses gedeeltelijk uit handen genomen, zonder al te veel in te boeten op flexibiliteit.

Voorbeeld 1: Een terugbel-taak aanmaken

Op je website heb je een "Bel mij terug" formulier gemaakt. Graag wil je dat er automatisch een taak wordt aangemaakt in Gripp, welke toegewezen wordt aan de salesmedewerker. Met een enkele API-call is de taak aan te maken in Gripp!
Download voorbeeldcode (PHP) (let op: de connector class api.class.php dien je apart te downloaden. Zie hierboven).
            <?php
require_once('api.class.php');
print '<pre>';

// Initialisatie API connector
$apikey = '[hier API-sleutel invullen]';
$api = new com_gripp_API($apikey);

// Variabelen; in de praktijk zijn deze afkomstig van een webformulier
$date = date('Y-m-d');
$telnr = '06 12345678';
$bedrijfsnaam = 'Uw Warme Bakker';
$naam = 'Dirk de Jong';

// Enkele velden die afhankelijk zijn van de instellingen in Gripp
// De juiste ID's kunnen in de instellingen afgelezen worden bij het overzicht met Taaktypes en Taakfases.
$taakfase = 1;
$taaktype = 1;

// Terugbeltaak maken
$fields = array(
    'company' => 95585,
    'type' => $taaktype,
    'content' => "Terugbelafspraak: $bedrijfsnaam, $naam", //onderwerpregel
    'description' => "$telnr, $bedrijfsnaam, $naam",
    'phase' => $taakfase,
    'date' => $date
);
$responses = $api->task_create($fields);
$response = $responses[0]['result'];

print_r($response);
?>

Voorbeeld 2: Automatisch een offerte verzenden

Je runt een website waarop mensen een offerte kunnen aanvragen voor een partij tegels. In dit voorbeeld laten we zien dat je op eenvoudige wijze direct een offerte in Gripp kunt plaatsen, en de geïntereseerde vervolgens automatisch een e-mail met offerte kunt terugsturen.
Download voorbeeldcode (PHP) (let op: de connector class api.class.php dien je apart te downloaden. Zie hierboven).
            <?php
require_once('api.class.php');
print '<pre>';

// Initialisatie API connector
$apikey = '[hier API-sleutel invullen]';
$api = new com_gripp_API($apikey);

// Variabelen; in de praktijk zijn deze afkomstig van een webformulier waarmee
// men een offerte aanvraagt voor de levering van een x aantal terrastegels
$company = "Bakker Van De Akker";
$email = "mail@example.com";
$aantalTegels = 50;

// Enkele velden die afhankelijk zijn van de instellingen in Gripp
// De juiste ID's kunnen in de instellingen afgelezen worden bij het overzicht met Taaktypes en Taakfases.
$fase_id = 1;
$sjabloon_id = 10;
$productnummer = 20030; //Het productnummer kan worden gevonden in het overzicht met producten.

// We gaan er in dit voorbeeld vanuit dat het bedrijf
// nog niet bij ons bekend is en we het aan moeten maken
// Als alternatief zou een relatie opgezocht kunnen worden op het klantnummer.
$fields = array(
    "companyname" => "$company",
    "email" => "$email",
    "relationtype" => "COMPANY",
    "invoicesendby" => "EMAIL", //verplicht
    "invoiceemail" => "$email", //verplicht
);
$responses = $api->company_create($fields);
$response = $responses[0]['result'];
$company_id = $response["recordid"];


// Voor het opstellen van de offerte moeten we de
// inkoopprijs, verkoopprijs en product_id van een terrastegel (productnummer 20030) weten
$filters = array();
$filters[] = array(
    "field" => "product.number",
    "operator" => "equals",
    "value" => $productnummer //dit is het nummer van terrastegels
);
$responses = $api->product_getone($filters);
$response = $responses[0]['result'];
$product_id = $response['rows'][0]['id'];
$sellingprice = $response['rows'][0]['sellingprice'];
$byingprice = $response['rows'][0]['buyingprice'];

// Offerte maken
$fields = array(
    "company" => $company_id,
    "template" => $sjabloon_id,
    "name" => "Terrastegels",
    "offerlines" => array(
        array(
            "product" => $product_id,
            "amount" => $aantalTegels,
            "vat" => 27,
            "invoicebasis" => "FIXED",
            "sellingprice" => $sellingprice,
            "discount" => 0,
            "buyingprice" => $byingprice
        )
    ),
    "phase" => $fase_id
);
$responses = $api->offer_create($fields);
$response = $responses[0]['result'];
$offer_id = $response["recordid"];

// Offerte verzenden per e-mail

// URL opvragen
$filters = array();
$filters[] = array(
    "field" => "offer.id",
    "operator" => "equals",
    "value" => $offer_id
);
$responses = $api->offer_getone($filters);
$response = $responses[0]['result'];
$offer_url = $response['rows'][0]['viewonlineurl'];

// E-mail verzenden
$to = $email;
$subject = 'Offerte van Ons Bedrijf';
$message = "De door u aangevraagde offerte kunt u bekijken via de volgende link: \r\n $offer_url";
$headers = 'From: service@onsbedrijf.nl' . "\r\n";
mail($to, $subject, $message, $headers);
// [foutafhandeling]

// Status offerte wijzigen als e-mail succesvol is verstuurd
$fields = array(
    "status" => "SENT"
);
$responses = $api->offer_update($offer_id, $fields);
$response = $responses[0]['result'];

echo "Done!";
?>

Voorbeeld 3: Overzicht van openstaande facturen

Stel, je hebt een webshop gekoppeld aan Gripp, en je wilt je klant een online overzicht geven van de betaalde en onbetaalde facturen. Met slechts 2 API-calls is alle informatie uit Gripp te halen, inclusief zaken als sortering, filtering en paginering!
Download voorbeeldcode (PHP) (let op: de connector class api.class.php dien je apart te downloaden. Zie hierboven).
            <?php
require_once('api.class.php');
print '<pre>';

// Initialisatie API connector
$apikey = '[hier API-sleutel invullen]';
$api = new com_gripp_API($apikey);

$customernumber = 105559; // Bakker Van De Akker. Het klantnummer kan gevonden worden in het overzicht met relaties.

// Eerst moeten we het ID van de relatie achterhalen
$filters = array();
$filters[] = array(
    "field" => "company.customernumber",
    "operator" => "equals",
    "value" => $customernumber
);

// Pagineer en sorteer op verloopdatum
$options = array();

// Verzenden en resultaat verwerken
$responses = $api->company_getone($filters, $options);
$response = $responses[0]['result'];
$customer = $response['rows'][0];
if ($response['count'] == 0) {
    die('Geen relatie gevonden met nummer ' . $customernumber);
}
$customer_id = $customer['id'];


// Filter op openstaande facturen van Gripp B.V.
$filters = array();
$filters[] = array(
    "field" => "company.id",
    "operator" => "equals",
    "value" => $customer_id
);
$filters[] = array(
    "field" => "invoice.totalopeninclvat",
    "operator" => "notequals",
    "value" => "0"
);

// Pagineer en sorteer op verloopdatum
$options = array(
    "paging" => array(
        "firstresult" => 0, //begin bij zoekresultaat 0
        "maxresults" => 10  //toon maximaal 10 zoekresultaten
    ),
    "orderings" => array(
        array(
            "field" => "invoice.expirydate",
            "direction" => "asc"
        )
    )
);

// Verzenden en resultaat verwerken
$responses = $api->invoice_get($filters, $options);
$response = $responses[0]['result'];


echo '
<h1>Openstaande facturen</h1>
<table style="border: 1px solid grey;">
    <thead style="font-weight: bold;">
        <td width="70px">Status</td>
        <td width="100px">Nummer</td>
        <td width="100px">Datum</td>
        <td width="140px">Factuurbedrag</td>
        <td width="140px">Nog open</td>
        <td width="140px">Bekijk online</td>
    </thead>

';

//print_r($response['rows']);

foreach ($response['rows'] as $row) {
    $dateobj = $row['date'] ? new \DateTime($row['date']['date']) : null;

    echo '
        <tr>
            <td><div style="background-color: #cc0000; padding: 2px; border-radius: 5px; color: white;">Open</div></td>
            <td>' . $row['number'] . '</td>
            <td>' . (is_object($dateobj) ? $dateobj->format('d-m-Y') : '') . '</td>
            <td>' . $row['totalincldiscountinclvat'] . '</td>
            <td>' . $row['totalopeninclvat'] . '</td>
            <td><a target="_blank" href="' . $row['viewonlineurl'] . '">Openen</a></td>
        </tr>
    ';
}

echo '</table>';


// Filter op betaalde facturen van Gripp B.V.
$filters = array();
$filters[] = array(
    "field" => "company.id",
    "operator" => "equals",
    "value" => $customer_id
);
$filters[] = array(
    "field" => "invoice.totalopeninclvat",
    "operator" => "equals",
    "value" => "0"
);

// Verzenden en resultaat verwerken
$responses = $api->invoice_getone($filters, $options); // we gebruiken dezelfde opties ($options) voor paginering en sortering
$response = $responses[0]['result'];

echo '
<h1>Betaalde facturen</h1>
<table style="border: 1px solid grey;">
    <thead style="font-weight: bold;">
        <td width="70px">Status</td>
        <td width="100px">Nummer</td>
        <td width="100px">Datum</td>
        <td width="140px">Factuurbedrag</td>
        <td width="140px">Nog open</td>
        <td width="140px">Bekijk online</td>
    </thead>

';

//print_r($response);

foreach ($response['rows'] as $row) {
    $dateobj = $row['date'] ? new \DateTime($row['date']['date']) : null;

    echo '
        <tr>
            <td><div style="background-color: #39c39b; padding: 2px; border-radius: 5px; color: white;">Voldaan</div></td>
            <td>' . $row['number'] . '</td>
            <td>' . (is_object($dateobj) ? $dateobj->format('d-m-Y') : '') . '</td>
            <td>' . $row['totalincldiscountinclvat'] . '</td>
            <td>' . $row['totalopeninclvat'] . '</td>
            <td><a target="_blank" href="' . $row['viewonlineurl'] . '">Openen</a></td>
        </tr>
    ';
}

echo '</table>';
?>

Voorbeeld 4: Een opdracht aanmaken

In dit uitgebreide voorbeeld kun je zien hoe je middels de API een nieuwe opdracht aanmaakt in Gripp.
Download voorbeeldcode (PHP) (let op: de connector class api.class.php dien je apart te downloaden. Zie hierboven).
            <?php
require_once('api.class.php');
print '<pre>';

// Initialisatie API connector
$apikey = '[hier API-sleutel invullen]';
$api = new com_gripp_API($apikey);

//Dit zijn de teammembers. Ook al is het er maar 1, deze moet wel meegegeven worden als een array.
//Voor de duidelijkheid is het handig om de varialenaam in een meervoudsvorm te kiezen.
$werknemers = array(
    100 //medewerker_id
);

//Het zelfde geldt voor de tags:
$tags = array(
    4, 5 //tags met id 4 en 5
);


//De opdracht heeft een of meerdere projectlines. Deze zitten in een array.
$projectlines = array();

//Per opdrachtregel voeg je een projectline toe aan de array met projectlines.
//Het is een associatieve array met keys en values.
$projectlines[] = array(
    //De volgorde in de database. Dit bepaald de sortering van de opdrachtregels.
    '_ordering' => 10,

    //Het regeltype. 1=groepregel, 2=normale regel
    'rowtype' => 1,

    //Dit is alleen van toepassing voor groepregels. Op normale regels heeft dit geen invloed. Geeft aan of de onderliggende regels van een groep verborgen of getoond worden.
    'hidedetails' => true,

    //Het aantal
    'amount' => 1.23,

    //De ID van de eenheid. Deze kun je in de instellingen vinden op het tabblad 'Eenheden'.
    'unit' => 3,

    //De verkoopprijs per stuk
    'sellingprice' => 2.34,

    //Het kortingspercentage
    'discount' => 5,

    //Het veld 'Hoe te facturen. Je hebt hier de keuze uit FIXED | COSTING | BUDGETED | NONBILLABLE
    'invoicebasis' => "FIXED",

    //Het ID van het product. Het product ID is een intern ID en is niet direct in de applicatie af te lezen. Je kunt eenmalig een lijstje ophalen en afdrukken via de 2e voorbeeldfunctie hieronder.
    'product' => 42,

    //Het veldje 'toevoeging onderwerp'
    'additionalsubject' => "testtest",

    //Omschrijving
    'description' => 'Dit is de omschrijving',

    //BTW-id. Deze is af te lezen in de instellingen > BTW-tarieven
    'vat' => 27,

    //Dit veld is een verwijzing naar de bovenliggende opdracht. Dit is alleen van toepassing als je de offerprojectline_create() functie aanroep. In dit voorbeeld is het niet nodig omdat we de regels direct meegegeven met een opdracht.
    //'offerprojectbase' = 12345

    //De inkoopprijs
    'buyingprice' => 1.23
);


//Opstellen van de data voor een opdracht
$project = array(
    //Het sjabloonset. Dit verwijst naar het gekozen sjabloonset en is af te lezen in de instellingen
    'templateset' => 1,

    //De onderstaande velden spreken voor zich
    'name' => "name",
    'phase' => 1,
    'deadline' => "2016-11-11",
    'company' => 95595,
    'startdate' => "2016-11-11",
    'deliverydate' => "2016-11-11",
    'enddate' => "2016-11-11",
    'addhoursspecification' => true,
    'description' => "De omschrijving van de opdracht",
    'clientreference' => "Referentie van de klant",
    'archived' => false,
    'archivedon' => null, //alleen setten als het gearchiveer is. Bijv: "2016-11-14",

    //Dit zijn arrays die we hierboven hebben opgebouwd
    'tags' => $tags,
    'employees' => $werknemers,
    'projectlines' => $projectlines
);

//Na het aanroepen wordt de $response gevuld.
$response = $API->project_create($project);
print '<pre>';
print_r($response);

//Het ID van het aangemaakte project is nu op te halen middels
echo "Nieuwe opdracht aangemaakt met ID = ".$response[0]['result']['recordid'];


//===============================================
//Producten ophalen:

//we gaan de producten niet filteren, maar er moet wel altijd een 'filters' parameter meegegeven worden.
//in dit geval is de array leeg aangezien we geen filtering toepassen.
$filters = array();

//sinds v2 van de API is de $options['paging'] verplicht.
$options = array(
    'paging' => array(
        'firstresult' => 0,
        'maxresults' => '10'
    )
);

//Het lijstje met producten en hun ID's zijn op te vragen met:
$response = $API->project_get($filters, $options);

//De lijst met producten
print_r($response);

$watchdog = 5; //Een watchdog om te voorkomen dat de while loop hieronder maximaal 5 keer wordt aangeroepen.

//Wanneer er meer dan 100 producten zijn, dan moet de call nogmaals gemaakt worden. In het resultaat krijg je of er nog meer items in de opgevraagde collectie zitten. Dit kun je zien aan het veld more_items_in_collection.

while ($response[0]['result']['more_items_in_collection'] && $watchdog){
    $options = array(
        'paging' => array(
            'firstresult' => $response[0]['result']['next_start'], //hier stellen we de volgende in.
            'maxresults' => '10'
        )
    );
    $response = $API->project_get($filters, $options);
    print_r($response);

    $watchdog--;
}

//Het is aan te raden deze productenlijst 1x te maken, en in het vervolg de ID's te gebruiken van de producten die je in de opdracht wilt gebruiken.
?>