README

Official PHP client for Urbaniqo Transit — the channel that lets your customers buy your tickets, passes and subscriptions through the Urbaniqo app.

Looking for the JavaScript / Node SDK? It lives in a separate repository: regnatech/urbaniqo-sdk-js.

Wire-level spec for both SDKs: docs/protocol.md.

Install

composer require regna/urbaniqo-sdk guzzlehttp/guzzle

guzzlehttp/guzzle is the recommended PSR-18 implementation. Bring your own if you already have a different one.

Quick start

use GuzzleHttp\Client as Guzzle;
use GuzzleHttp\Psr7\HttpFactory;
use Regna\UrbaniqoSdk\Client;

$factory = new HttpFactory();
$urbaniqo = new Client(
    agencyId:       $_ENV['URBANIQO_AGENCY_ID'],
    keyId:          $_ENV['URBANIQO_KEY_ID'],
    secret:         $_ENV['URBANIQO_SECRET'],
    httpClient:     new Guzzle(),
    requestFactory: $factory,
    streamFactory:  $factory,
    // baseUrl defaults to https://urbaniqo.com/api/transit/v1
);

$urbaniqo->upsertTariffs([
    [
        'id' => 'AMT-110',
        'name' => ['en' => 'Single ride 110\'', 'it' => 'Corsa singola 110 minuti'],
        'kind' => 'single_ride',
        'fare_cents' => 200,
        'currency' => 'EUR',
        'default_validity_seconds' => 110 * 60,
        'is_active' => true,
    ],
]);

What the SDK gives you

• HMAC-SHA256 request signing (Authorization header in canonical-request form)
• Idempotent retries with exponential backoff for safe verbs (PUT, GET, idempotent POSTs)
• Webhooks\Verifier for inbound webhook signature checking — pass the raw request body
• Typed exceptions: UrbaniqoApiException, UrbaniqoTransportException, UrbaniqoWebhookException

Webhook handler (Laravel example)

A complete drop-in lives at examples/php-laravel-webhook/routes-snippet.php.

Docs

• docs/protocol.md — wire-level spec
• docs/getting-started.md — onboarding walkthrough
• docs/webhooks.md — webhook events + payload shapes
• docs/error-codes.md — full error code reference
• docs/barcode-formats.md — supported ticket formats
• docs/changelog.md

License

MIT — see LICENSE.