Datadis client for Laravel

Laravel integration of lenorix/datadis-client, the client for Datadis (supplies, contracts, hourly and quarter-hourly consumption, maximum power, reactive energy). It wires the client to what your application already has:

• HTTP: every call goes through Laravel's Http handler stack, so Http::fake() and Http::assertSent() work.
• Cache: the login token and the 24 hour guard (Datadis refuses an identical query for 24 hours and counts the refused ones) live in a Laravel cache store shared by all workers. Recording a query is atomic (Cache::add()), so two workers never both send it.
• Configuration: one or more accounts in config/datadis-client.php, container binding, facade and an artisan command.

Installation

composer require lenorix/laravel-datadis-client
php artisan vendor:publish --tag="datadis-client-config"

Requires PHP 8.4 and Laravel 13 (lenorix/datadis-client needs Guzzle 8, which Laravel 11 and 12 do not allow yet). Datadis is a third-party service, so its credentials go in config/services.php, like any other:

'datadis' => [
    'username' => env('DATADIS_USERNAME'),
    'password' => env('DATADIS_PASSWORD'),
],

DATADIS_USERNAME=A00000000
DATADIS_PASSWORD=your-password

services.datadis also accepts the other account settings (api_version, timezone, timeout...) and wins over the account named default in config/datadis-client.php, which keeps the same DATADIS_* variables as a fallback and holds extra accounts.

Security

The calls do not go through Laravel's Http client unless you ask. The login request carries your Datadis password and its answer carries the token; Laravel's request events, global HTTP middleware and recorders (Telescope, Nightwatch, your own logging middleware) would see both. So, unset, datadis-client.http.stack is guzzle: plain Guzzle with the package's settings, where nothing of Laravel sees the calls.

The test environment (APP_ENV=testing) is the exception: it uses laravel so that Http::fake() works. To fake Datadis in another environment, set DATADIS_HTTP_STACK=laravel and keep in mind what the recorders there will see. The token is also kept in your cache store: protect that store like a password. Details in Logging and request recorders.

Usage

Inject the client, or use the facade, which forwards to the default account:

use Lenorix\DatadisClient\DatadisClient;
use Lenorix\DatadisClient\Time\Month;
use Lenorix\DatadisClient\Values\Cups;
use Lenorix\LaravelDatadisClient\Facades\LaravelDatadisClient as Datadis;

public function __invoke(DatadisClient $client)
{
    $supply = $client->findSupply(Cups::fromString('ES0000000000000000AA0A'));
    $result = $client->getConsumptionDataOf($supply, Month::of(2026, 7));
}

$supplies = Datadis::getSupplies();

See the client documentation for every call, the results and the errors.

Several accounts and holders

use Lenorix\DatadisClient\Values\Nif;

Datadis::account('other')->getSupplies();

$holder = Datadis::forHolder(Nif::fromString('00000000T')); // someone who authorized your account

Define each account under accounts in config/datadis-client.php, with the same keys as default:

'accounts' => [
    'default' => [/* ... */],
    'second' => [
        'username' => env('DATADIS_SECOND_USERNAME'),
        'password' => env('DATADIS_SECOND_PASSWORD'),
        'timezone' => 'Atlantic/Canary',
    ],
],

Only the account named default reads services.datadis.

Public open data

Aggregated consumption by region, tariff and sector. Datadis still asks for an account's token, which it shares with the private client:

use Lenorix\DatadisClient\PublicApiClient;

app(PublicApiClient::class)->apiSearch($query);   // or Datadis::publicApi('other')

Command

php artisan datadis:supplies [--account=other] [--holder=00000000T]

Logging and request recorders

With DATADIS_HTTP_STACK=laravel (the default only in the test environment), Laravel's request events, global HTTP middleware and recorders such as Telescope or Nightwatch see the login request (the password) and its answer (the token). Outside tests keep the default (guzzle), or exclude datadis.es from the recorders and from the request bodies they keep. With guzzle, Http::fake() does not apply to these calls: fake Datadis in tests, where the stack is laravel.

Operations that change data

The facade and the injected client are the full client, so they also offer the calls that change data on Datadis: newAuthorization() and cancelAuthorization() (give or take away a third party's access to your supplies) and partnerDeleteUser() (partner accounts). They are never retried, and Datadis documents the first two for API v1; their answers are not verified yet. If your code only reads, type-hint what you use and keep these out of reach, for example behind your own small service class.

Queued jobs

The client holds a password and cannot be serialised: resolve it in handle(), never keep it in a property.

Configuration

A repeated query fails with RepetitionWindowException before anything is sent.

Set DATADIS_LEDGER_KEY. Derived from APP_KEY, the secret changes whenever you rotate the application key, and the guard forgets the queries of the last 24 hours, so they can be sent (and counted) again.

Laravel Boost

The package ships Laravel Boost resources, so your coding agent learns the client and the Datadis rules (the 24 hour query rule, hour labels, errors) when you run php artisan boost:install or boost:update --discover:

• resources/boost/guidelines/core.blade.php: the conventions, always loaded.
• Skills, loaded on demand: datadis-development (calls, results, errors), datadis-sync (scheduled jobs and backfills) and datadis-testing (Http::fake()).

Testing

Http::preventStrayRequests();   // a URL that stops matching must fail, not reach Datadis
Http::fake([
    '*/nikola-auth/tokens/login' => Http::response($token, 200, ['Content-Type' => 'text/plain']),
    '*/api-private/api/get-supplies*' => Http::response(['supplies' => [...], 'distributorError' => []]),
]);

composer test

Credits

• Jesus Hernandez
• All Contributors

License

The MIT License (MIT). See License File.