Frequently asked questions

What is darvis/snelstart?

A PHP package with a client for the SnelStart B2B API v2, the API of the Dutch accounting software SnelStart. It fetches and keeps the access token and sends your calls; it has no models, no synchronisation and no webhooks, and it returns the arrays SnelStart answers with.

How do I connect a Laravel application to the SnelStart API?

Run composer require darvis/snelstart, set SNELSTART_CLIENT_KEY and SNELSTART_SUBSCRIPTION_KEY in .env and check with php artisan snelstart:test. Then resolve Darvis\Snelstart\Services\SnelstartAPI from the container and call getRelaties(), getArtikelen(), createRelatie(), createVerkooporder(), or get(), post(), put() and delete() for any other endpoint.

What do I need to use darvis/snelstart, and what does it cost?

PHP 8.2 or higher, Laravel 11, 12 or 13, and a client key and a subscription key for the B2B API, both issued by SnelStart. The package itself is free and MIT licensed.

How does darvis/snelstart authenticate with SnelStart, and where is the access token kept?

It posts grant_type=clientkey and your client key as a form to the token endpoint and sends the token it gets in the Authorization header, with the subscription key in the Ocp-Apim-Subscription-Key header. The Laravel client keeps the token in memory and, encrypted with the application key, in Laravel’s cache until sixty seconds before it expires; SNELSTART_TOKEN_CACHE=false keeps it in memory only.

What happens when a SnelStart call fails, and how do I get the HTTP status?

The client throws Darvis\Snelstart\Exceptions\SnelstartException, which extends RuntimeException, with a message such as Snelstart API call failed. HTTP status: 429. Response: .... $e->status() gives the HTTP status, and 0 when there was no response. A timeout in the Laravel client is an Illuminate\Http\Client\ConnectionException instead.

Does darvis/snelstart retry a failed call?

Only once, and only for a 401 on a token it already had: it fetches a new token and repeats the call. A 429, a 5xx and a timeout are not retried, so make such calls from a queued job with a backoff. A request gives up after 30 seconds, 10 to connect (SNELSTART_TIMEOUT, SNELSTART_CONNECT_TIMEOUT).

Is darvis/snelstart safe with my SnelStart keys?

The client key goes in the body of the token request and the subscription key and the token go in headers, never in a URL. The package replaces all three with [redacted] in its exception messages, log lines and command output, and it only stores the token in the cache encrypted. The rest of an error response can hold data of the administration, so protect your logs.

Can I use darvis/snelstart without Laravel?

Yes. Darvis\Snelstart\Standalone\SnelstartAPI takes its settings as an array, or from the environment with fromEnv(), and uses the PHP cURL extension. It has the same methods, the same exception and the same timeouts, and keeps the token in memory only.

How do I test code that uses darvis/snelstart without calling SnelStart?

Use Http::fake() for auth.snelstart.nl/* (return an access_token) and for b2bapi.snelstart.nl/*, set snelstart.client_key to any value and call Http::preventStrayRequests(). Run the tests on the array cache store or set SNELSTART_TOKEN_CACHE=false, so a cached token does not travel from one test to the next.

Which Laravel and PHP versions does darvis/snelstart support?

PHP 8.2 and higher with Laravel 11, 12 or 13. The test suite runs on every combination, on the lowest and the latest dependencies.