Introductie

Welkom bij de API documentatie van het Centraal Invorderings Bureau (CIB). Op deze pagina proberen wij zo duidelijk mogelijk de basis en principes van onze API uit te leggen.

Wat is er nodig om gebruik te maken van onze API?

  • Een CIB Account (Neem contact op met het CIB via www.cibincasso.nl)
  • Een unieke API-Key te verkrijgen via het CIB

Live en Test omgeving:

  • Wanneer in URL “app“ wordt vervangen door “test” komt men in onze test-omgeving.
  • De test omgeving is niet altijd extern toegankelijk, dit dienen wij eerst aan te zetten.
Dossier

Sample

Om een dossier toe te voegen dienen de velden ingevuld te worden die hiernaast in het zwart staan geformuleerd achter het “=” teken.

URL http://app.cibincasso.nl/api/v1/files
Client ID
Username

Verplichte velden:

request.username
request.key
debtor.type
debtor.street
debtor.house_number
debtor.city
debtor.country
invoice.number
invoice.amount

    $request = array();

    $request['username'] = 'your username';
    $request['key']      = 'your secret key';

    $debtor                       = array();
    $debtor['type']               = 'Private';
    $debtor['company']            = 'My company';
    $debtor['first_name']         = 'First name';
    $debtor['last_name']          = 'Last name';
    $debtor['initials']           = 'initials';
    $debtor['insertion']          = 'insertion';
    $debtor['birth_date']         = 'dd-mm-year';
    $debtor['gender']             = 'm';
    $debtor['street']             = 'street';
    $debtor['house_number']       = '1';
    $debtor['house_extension']    = 'a';
    $debtor['post_code']          = '1234AB';
    $debtor['city']               = 'Rotterdam';
    $debtor['country']            = 'NL';
    $debtor['phone']              = '3161234567';
    $debtor['mobile']             = '061234567';
    $debtor['email']              = 'my-email@example.org';
    $debtor['email2']             = 'my-email2@example.org';
    $debtor['kvk_number']         = '12345678';
    $debtor['bank_account']       = 'NL11ABC1234567890';
    $debtor['automatic_workflow'] = 'no';
    $debtor['reference']          = 'some info about your order';
    $debtor['variable1']          = 'Variable 1';
    $debtor['variable2']          = 'Variable 2';
    $debtor['variable3']          = 'Variable 3';
    $debtor['variable4']          = 'Variable 4';
    $debtor['variable5']          = 'Variable 5';

    // assign as 'debtor' namespace
    $request['debtor'] = $debtor;

    // can be many invoices
    $invoice                        = array();
    $invoice['number']              = 'invoice number';
    $invoice['date']                = 'dd-mm-year';
    $invoice['expire_date']         = 'dd-mm-year';
    $invoice['amount']              = '10.01';

    // Invoice attachment (WIK,invoice, proposition) with content encoded in base64, max 3 attachments
    $invoice['invoice_attachment']             = array();
    $invoice['invoice_attachment']['name']     = 'test.txt';
    $invoice['invoice_attachment']['resource'] = base64_encode( get_file_content('/path/to/file/test.txt') );
    $invoice['invoice_attachments'][]          = $invoice['invoice_attachment'];

    $request['invoices'][] = $invoice;

    $payment                 = array();
    $payment['payment_date'] = 'dd-mm-year';
    $payment['description']  = 'description';
    $payment['amount']       = '12.21';

    $request['payments'][]   = $payment;

    // Log attachments with content encoded in base64, max 3 attachments
    $attachment             = array();
    $attachment['name']     = 'test.txt';
    $attachment['resource'] = base64_encode( get_file_content('/path/to/file/test.txt') );

    $request['attachments'][] = $attachment;
    

Code examples

Hiernaast een aantal voorbeelden van PHP code


    // prepare request
    custom_post_fields($request, $arrayRequest);

    // setup curl options
    $options = array(
        CURLOPT_URL            => 'https://app.cibincasso.nl/api/v1/files.json',
        CURLOPT_HEADER         => true,
        CURLOPT_FOLLOWLOCATION => true,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_FRESH_CONNECT  => true,
        CURLOPT_POST           => true,
        CURLOPT_POSTFIELDS     => $arrayRequest,
        CURLOPT_SSL_VERIFYPEER => false
    );

    // perform request
    $cUrl = curl_init();
    curl_setopt_array( $cUrl, $options );
    $response = curl_exec( $cUrl );

    // split into header and body
    $info            = curl_getinfo( $cUrl );
    $httpCode        = curl_getinfo($cUrl, CURLINFO_HTTP_CODE);
    $responseHeaders = substr( $response, 0, $info['header_size'] );
    $responseBody    = substr( $response, $info['header_size'] );
    curl_close($cUrl);

    if (in_array($httpCode, array(200, 201))) {
        $responseMessage = json_decode($responseBody, true);
        if ($responseMessage) {
            var_dump($responseMessage);
        }
    }

    

Response example

Het systeem kan het volgende antwoord geven:

  • Success response
  • Error response

In de PHP code is te zien waarom een error response wordt afgegeven. Rechts in het zwart is als voorbeeld een verkeerde gebruikersnaam/wachtwoord ingevuld.

Success response example:

    {
        "status": "OK",
        "file": 12345678
    }
                

Error response example:

    {
        "message": "Invalid username/key"
    }
                

Response codes

De codes die het systeem kan teruggeven met de betekenis erbij:

101 Abonnement of klant niet gevonden
400 Factuur aanmaak datum moet eerder zijn dan de factuur datum
403 Verkeerde gebruikersnaam/wachtwoord
Voortgang

Sample

Via deze API requests kan een voortgang opgevraagd worden. Hiernaast ziet u de code reeks van de request in PHP code.

URL http://app.cibincasso.nl/api/v2/file-log/
Client ID
Username

Verplichte velden:

request.username
request.key
request.number

    $request = array();

    $request['username'] = 'your username';
    $request['key']      = 'your secret key';

    $request['number']   = 'file id';
    

Response example

Als de gegevens zijn ingevuld kan het systeem de volgende antwoorden teruggeven:

  • Success response
  • Error response

In de PHP code is te zien waarom een error response wordt afgegeven. Rechts in het zwart is als voorbeeld een verkeerde gebruikersnaam/wachtwoord ingevuld.

Success response example:

    {
        "date":"2017-01-03 10:13:14",
        "type":"Opmerking",
        "description":"Status is gewijzigd naar: ingevoerd",
        "user":"Example User"
    },
    {
        "date":"2017-01-01 13:10:20",
        "type":"Opmerking",
        "description":"Status is gewijzigd naar: In behandeling",
        "user":"Example User"
    }
                

Error response example:

    {
        "message": "Invalid username/key"
    }
                
Betaling

Sample

Om een betaling te melden na overdracht dossier kunt u de volgende PHP code gebruiken in de kolom hiernaast.

URL http://app.cibincasso.nl/api/v1/payments
Client ID
Username

Verplichte velden:

request.username
request.key
request.file

    $request = array();

    $request['username'] = 'your username';
    $request['key']      = 'your secret key';
    $request['file']     = 'file number';

    $payment                 = array();
    $payment['payment_date'] = 'dd-mm-year';
    $payment['description']  = 'description';
    $payment['amount']       = '12.21';

    $request['payments'][]   = $payment;

    

Code examples

Hiernaast vindt u een aantal voorbeelden van PHP code.


    // prepare request
    $arrayRequest = http_build_query($request);

    // setup curl options
    $options = array(
        CURLOPT_URL            => 'https://app.cibincasso.nl/api/v1/payments.json',
        CURLOPT_HEADER         => true,
        CURLOPT_FOLLOWLOCATION => true,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_FRESH_CONNECT  => true,
        CURLOPT_POST           => true,
        CURLOPT_POSTFIELDS     => $arrayRequest,
        CURLOPT_SSL_VERIFYPEER => false
    );

    // perform request
    $cUrl = curl_init();
    curl_setopt_array( $cUrl, $options );
    $response = curl_exec( $cUrl );

    // split into header and body
    $info            = curl_getinfo( $cUrl );
    $httpCode        = curl_getinfo($cUrl, CURLINFO_HTTP_CODE);
    $responseHeaders = substr( $response, 0, $info['header_size'] );
    $responseBody    = substr( $response, $info['header_size'] );
    curl_close($cUrl);

    if (in_array($httpCode, array(200, 201))) {
        $responseMessage = json_decode($responseBody, true);
        if ($responseMessage) {
            var_dump($responseMessage);
        }
    }

    

Response example

Het systeem kan het volgende antwoord geven:

  • Success response
  • Error response

In de PHP code is te zien waarom een error response wordt afgegeven. Rechts in het zwart is als voorbeeld een verkeerde gebruikersnaam/wachtwoord ingevuld.

Success response example:

    {
        "status": "OK",
        "file": 12345678
    }
                

Error response example:

    {
        "message": "Invalid username/key"
    }
                

Response codes

De codes die het systeem kan teruggeven met de betekenis erbij:

101 Abonnement of klant niet gevonden
400 Validiteit fouten
403 Verkeerde gebruikersnaam/wachtwoord
Status

Sample

Als u de status van een dossier wilt opvragen kan dit door de gegevens in de velden te vullen die hiernaast in de zwarte kolom zijn geformuleerd achter het “=” teken.

URL http://app.cibincasso.nl/api/v1/statuses
Client ID
Username

Verplichte velden:

request.username
request.key
request.fileNumber

    $request = array();

    $request['username']    = 'your username';
    $request['key']         = 'your secret key';
    $request['fileNumber']  = 'file number';

    

Code examples

Hiernaast een aantal voorbeelden van PHP code


    // prepare request
    $arrayRequest = http_build_query($request);

    // setup curl options
    $options = array(
        CURLOPT_URL            => 'https://app.cibincasso.nl/api/v1/statuses.json',
        CURLOPT_HEADER         => true,
        CURLOPT_FOLLOWLOCATION => true,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_FRESH_CONNECT  => true,
        CURLOPT_POST           => true,
        CURLOPT_POSTFIELDS     => $arrayRequest,
        CURLOPT_SSL_VERIFYPEER => false
    );

    // perform request
    $cUrl = curl_init();
    curl_setopt_array( $cUrl, $options );
    $response = curl_exec( $cUrl );

    // split into header and body
    $info            = curl_getinfo( $cUrl );
    $httpCode        = curl_getinfo($cUrl, CURLINFO_HTTP_CODE);
    $responseHeaders = substr( $response, 0, $info['header_size'] );
    $responseBody    = substr( $response, $info['header_size'] );
    curl_close($cUrl);

    if (in_array($httpCode, array(200, 201))) {
        $responseMessage = json_decode($responseBody, true);
        if ($responseMessage) {
            var_dump($responseMessage);
        }
    }

    

Response example

Het systeem kan het volgende antwoord geven:

  • Success response
  • Error response

Bij een succes response wordt er in de PHP code aangegeven wat de status is van een dossier. In de PHP code is ook te zien waarom een error response wordt afgegeven. Rechts in het zwart is als voorbeeld een verkeerde gebruikersnaam/wachtwoord ingevuld.

Success response example:

    {
        "file_number": 90001234,
        "status": "Full_payment"
    }
                

Error response example:

    {
        "message": "Invalid username/key"
    }
                

Response codes

De codes die het systeem kan teruggeven met de betekenis erbij:

101 Abonnement of klant niet gevonden
400 Validiteit fouten
403 Verkeerde gebruikersnaam/wachtwoord
API Commentaar

Sample

Deze methode maakt het mogelijk om commentaar en bijlagen toevoegen aan opgegeven bestand

URL http://app.cibincasso.nl/api/v1/comments
Client ID
Username

Verplichte velden:

request.username
request.key
request.comment

    $arrayRequest = array();

    $arrayRequest['username']    = 'your username';
    $arrayRequest['key']         = 'your secret key';
    $arrayRequest['file_id']     = 'file id';
    $arrayRequest['comment']     = 'your comment';

    $attachment = array();
    $attachment['name'] = 'test.txt';
    $attachment['resource'] = base64_encode( file_get_contents ('/path/to/file/test.txt') );

    $arrayRequest['attachments'][] = $attachment;

                            

Code examples

Hiernaast een aantal voorbeelden van PHP code


    // setup curl options
    $options = array(
        CURLOPT_URL            => 'https://app.cibincasso.nl/api/v1/comments.json',
        CURLOPT_HEADER         => true,
        CURLOPT_FOLLOWLOCATION => true,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_FRESH_CONNECT  => true,
        CURLOPT_POST           => true,
        CURLOPT_POSTFIELDS     => $arrayRequest,
        CURLOPT_SSL_VERIFYPEER => false
    );

    // perform request
    $cUrl = curl_init();
    curl_setopt_array( $cUrl, $options );
    $response = curl_exec( $cUrl );

    // split into header and body
    $info            = curl_getinfo( $cUrl );
    $httpCode        = curl_getinfo($cUrl, CURLINFO_HTTP_CODE);
    $responseHeaders = substr( $response, 0, $info['header_size'] );
    $responseBody    = substr( $response, $info['header_size'] );
    curl_close($cUrl);

    if (in_array($httpCode, array(200, 201))) {
        $responseMessage = json_decode($responseBody, true);
        if ($responseMessage) {
            var_dump($responseMessage);
        }
    }

                            

Response example

Het systeem kan het volgende antwoord geven:

  • Success response
  • Error response

Bij een succes response wordt er in de PHP code aangegeven wat de status is van een dossier. In de PHP code is ook te zien waarom een error response wordt afgegeven. Rechts in het zwart is als voorbeeld een verkeerde gebruikersnaam/wachtwoord ingevuld.

Success response example:

    {
        "status": "OK"
    }
                

Error response example:

    {
        "message": "Invalid username/key"
    }
                

Response codes

De codes die het systeem kan teruggeven met de betekenis erbij:

400 Validiteit fouten
403 Verkeerde gebruikersnaam/wachtwoord
Webhook

Sample

Tevens is het ook mogelijk om alle status wijzigingen in een dossier automatisch te ontvangen door gebruik te maken van een "webhook" (push-notificaties). Dit kunt uw eenvoudig instellen op uw CIB inlog pagina. https://app.cibincasso.nl/webhook/

Options:

Naam Omschrijving
file_number Dossiernummer
mainStatus Main status
status Substatus
reference Product/Dienst
statusReasonClose Sluitcode/Reden
number Eerste factuurnummer
variable1 Var1

    {
        "file_number": "91234567"
        "fields": {
            "mainStatus": "Dossier gesloten",
            "status":"Volledig betaald",
            "statusReasonClose":"Volledig betaald",
            "reference":"4422321",
            "number":"1NR4569WI10",
            "variable1":"Var1",
        },
        "fields_before": {
            "mainStatus": "Betalingsregeling status",
            "status":"Herinnering betalingsregeling",
            "statusReasonClose":"",
            "reference":"",
            "number":"1NR4569WI",
            "variable1":"var_1",
        }
    }

    
XML Api

Sample

This method allows to add customers and files using XML string.

URL http://app.cibincasso.nl/api/xml
Client ID
Username

Verplichte velden:

request.username
request.key
request.inXml

    <Collection>
        <Cases>
            <Case Id="6401006416">
            <LegalOwner>AfterPay</LegalOwner>
            <Var1>shopA.nl</Var1>
            <Debtors>
                <Debtor Id="1800004602">
                    <Firstname>A</Firstname>>
                    <Lastname>jansen</Lastname>
                    <Birthday>1990-01-01T00:00:00</Birthday>
                    <Persontype>F</Persontype>
                    <CommercialRegister/>
                    <CommercialRegistrationNumber/>
                    <Addresses>
                        <Address>
                            <ZipCode>1234AJ</ZipCode>
                            <Street>Kerkstraat<</Street>
                            <Number>123</Number>
                            <Place>Rotterdam</Place>
                        </Address>
                    </Addresses>
                    <Communications>
                        <Communication>
                            <Type>E-Mail</Type>
                            <Value>test@test.nl<</Value>
                        </Communication>
                        <Communication>
                            <Type>Telefon</Type>
                            <Value>0612345678<</Value>
                        </Communication>
                    </Communications>
                </Debtor>
            </Debtors>
            <Invoices>
                <Invoice>
                    <Number>123456 ref</Number>
                    <InvoiceDate>2017-10-09T00:00:00</InvoiceDate>
                    <InvoiceDueDate>2017-10-23T00:00:00</InvoiceDueDate>
                    <Amount>80.57</Amount>
                </Invoice>
                <Invoice>
                    <Number>VERZENDKOSTEN::VERZENDKOSTEN</Number>
                    <InvoiceDate>2017-10-09T00:00:00</InvoiceDate>
                    <InvoiceDueDate>2017-10-23T00:00:00</InvoiceDueDate>
                    <Amount>4.95</Amount>
                </Invoice>
            </Invoices>
        </Case>
    </Collection>

    $arrayRequest = array();

    $arrayRequest['username']    = 'your username';
    $arrayRequest['key']         = 'your secret key';
    $arrayRequest['inXml']       = 'your xml string';

                            

Code examples

Hiernaast een aantal voorbeelden van PHP code


    // setup curl options
    $options = array(
        CURLOPT_URL            => 'https://app.cibincasso.nl/api/xml',
        CURLOPT_HEADER         => true,
        CURLOPT_FOLLOWLOCATION => true,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_FRESH_CONNECT  => true,
        CURLOPT_POST           => true,
        CURLOPT_POSTFIELDS     => $arrayRequest,
        CURLOPT_SSL_VERIFYPEER => false
    );

    // perform request
    $cUrl = curl_init();
    curl_setopt_array( $cUrl, $options );
    $response = curl_exec( $cUrl );

    // split into header and body
    $info            = curl_getinfo( $cUrl );
    $httpCode        = curl_getinfo($cUrl, CURLINFO_HTTP_CODE);
    $responseHeaders = substr( $response, 0, $info['header_size'] );
    $responseBody    = substr( $response, $info['header_size'] );
    curl_close($cUrl);

    if (in_array($httpCode, array(200, 201))) {
        $responseMessage = json_decode($responseBody, true);
        if ($responseMessage) {
            var_dump($responseMessage);
        }
    }

                            

Response example

Het systeem kan het volgende antwoord geven:

  • Success response
  • Error response

Bij een succes response wordt er in de PHP code aangegeven wat de status is van een dossier. In de PHP code is ook te zien waarom een error response wordt afgegeven. Rechts in het zwart is als voorbeeld een verkeerde gebruikersnaam/wachtwoord ingevuld.

Success response example:

    {
        "status": "OK",
        "key': 'customerApiKey",
        "username': 'customerUsername",
        "number": "customerNumber",
        "file": "fileNumber"
    }
                

Error response example:

    {
        "message": "A Token was not found in the TokenStorage."
    }
                

Response codes

De codes die het systeem kan teruggeven met de betekenis erbij:

400 Validiteit fouten
403 Verkeerde gebruikersnaam/wachtwoord