README

Symfony bundle for the Enviatodo Shipping API (V2) — quotes, orders, labels, pickups, addresses, packages, carriers and catalogs for shipping inside Mexico.

It wires sarissaops/enviatodo-php (framework-agnostic PSR-18 client) into Symfony: composer require and autowire the Enviatodo facade. The Symfony HTTP client (symfony/http-client) and Nyholm PSR-7 are installed automatically as dependencies — no manual client setup, no discovery surprises in production.

Requirements

• PHP 8.2 or higher
• Symfony 7.4 or higher
• An Enviatodo API token (sandbox tokens work against the sandbox endpoint below)

Installation

composer require sarissaops/enviatodo-bundle

Register the bundle (Flex does this automatically):

// config/bundles.php
SarissaOps\EnviatodoBundle\EnviatodoBundle::class => ['all' => true],

Configure the token (infrastructure config belongs in env, never in code):

# .env — never commit real tokens
ENVIATODO_TOKEN=your-sandbox-token
# ENVIATODO_ENDPOINT=  # optional override; confirm the production base URL in the official API docs

# config/packages/enviatodo.yaml (every key has a default; the token value must resolve non-empty at runtime)
enviatodo:
    token: '%env(ENVIATODO_TOKEN)%'

Usage

use SarissaOps\Enviatodo\Enviatodo;

final class ShippingService
{
    public function __construct(private readonly Enviatodo $client)
    {
    }

    public function balance(): float
    {
        return $this->client->balance()->show()->getBalance(); // MXN
    }

    public function quote(array $quotePayload): void
    {
        $quote = $this->client->quote()->all($quotePayload);

        // Keep the UUID — it feeds OrderApi::create().
        $order = $this->client->order()->create(
            uuid: $quote->getTransactionUuid(),
            providerId: '9',
            serviceId: '11',
            insurance: false,
        );

        foreach ($order->getGuides() as $guide) {
            echo $guide->getTrackingId() . PHP_EOL;
        }
    }
}

Every request carries Authorization: Bearer <token> plus x-api-key: enviatodo and x-enviatodo-app: custom automatically. The underlying SDK exposes all 10 domains — zipCode(), balance(), address(), package(), parcel(), quote(), order(), guide(), pickup(), catalog() — see the enviatodo-php docs for per-resource recipes.

Configuration reference

enviatodo:
    token: '%env(ENVIATODO_TOKEN)%'      # required value, never empty (a missing env var fails at runtime with a clear message)
    endpoint: '%env(ENVIATODO_ENDPOINT)%' # default: https://apiqav2.enviatodo.mx/index.php/ (sandbox)
    api_key: 'enviatodo'                 # → x-api-key header
    app_name: 'custom'                   # → x-enviatodo-app header
    timeout: null                        # idle seconds, applied to the Symfony backend (null = Symfony HttpClient default)
    debug: false                         # true replaces every request URI with the bare endpoint for traffic inspection

Response handling

All API methods return typed model objects; the Enviatodo envelope ({success, message, data, error, code}) is unwrapped for you — and error: true raises even on HTTP 200:

use SarissaOps\Enviatodo\Exception\EnviatodoException;
use SarissaOps\Enviatodo\Exception\HttpClientException;
use SarissaOps\Enviatodo\Exception\HttpServerException;

try {
    $quote = $client->quote()->all($quotePayload);
} catch (HttpClientException $e) {
    echo $e->getResponseCode();     // HTTP status
    print_r($e->getResponseBody()); // decoded envelope
} catch (HttpServerException | EnviatodoException $e) {
    echo $e->getMessage();
}

$client->getLastResponse(); // last raw PSR-7 response, for logging

Debugging

Set debug: true to replace every request URI with the bare endpoint for traffic inspection (e.g. pointing at a request bin). Warning: the API itself will not respond usefully while it is enabled — use only when dumping traffic, never in production.

Framework integration

The bundle has no shop-platform dependencies and stays that way: only Symfony components plus the framework-agnostic client, no shop types in services.

Contributing

TDD is mandatory: Red → Green → Refactor. New wiring ships with a container wiring test + a functional kernel test (mocked transport — never live).

git clone https://github.com/sarissaops/enviatodo-bundle.git
cd enviatodo-bundle
composer install
composer validate
composer test
vendor/bin/phpunit tests/Unit/EnviatodoBundleTest.php
vendor/bin/phpstan analyse --level=max src tests
vendor/bin/php-cs-fixer fix --dry-run --diff

Compatibility

Symfony 7.4 and PHP ^8.2. Forward-compatible with Symfony 8 by design (AbstractBundle, no deprecated extension APIs) — not yet covered by CI.

License

MIT — see LICENSE.

Support

Issues: github.com/sarissaops/enviatodo-bundle/issues. Changelog: CHANGELOG.md.