mandae-sdk-php

PHP SDK for the Mandaê API — rates, orders, tracking, and webhooks.

---

Requirements

• PHP 8.1+
• A PSR-18 HTTP client (e.g. Guzzle)
• A PSR-17 HTTP factory (e.g. guzzlehttp/psr7)

Installation

composer require rafaelcgstz/mandae-sdk-php

Quick start

use GuzzleHttp\Client;
use GuzzleHttp\Psr7\HttpFactory;
use Mandae\Enums\Environment;
use Mandae\MandaeClient;

$factory = new HttpFactory();

$client = new MandaeClient(
    token:          'your-api-token',        // request at ti@mandae.com.br
    httpClient:     new Client(),
    requestFactory: $factory,
    streamFactory:  $factory,
    environment:    Environment::Production, // default: Sandbox
);

---

Features

Get shipping rates

use Mandae\Requests\GetRatesRequest;

$response = $client->getRates(new GetRatesRequest(
    postalCode:    '01310100',
    weight:        1.5,     // kg
    height:        10,      // cm
    width:         15,      // cm
    length:        20,      // cm
    declaredValue: 150.00,
));

foreach ($response->shippingOptions as $option) {
    echo "R$ {$option->price} — {$option->days} business days\n";
}

$cheapest = $response->cheapest();
$fastest  = $response->fastest();

Create a collection order

use Mandae\Enums\Vehicle;
use Mandae\Models\{Address, Dimensions, Item, Recipient, Sender};
use Mandae\Requests\CreateOrderRequest;

$address = new Address(
    postalCode: '01310100',
    street:     'Av. Paulista',
    number:     '1000',
    city:       'São Paulo',
    state:      'SP',
);

$response = $client->createOrder(new CreateOrderRequest(
    customerId: 'your-customer-id',
    vehicle:    Vehicle::Motorcycle,
    sender:     new Sender('My Store', $address),
    items: [
        new Item(
            recipient:  new Recipient('Jane Doe', $address, phone: '11999990000'),
            dimensions: new Dimensions(height: 10, width: 15, length: 20, weight: 1.5),
        ),
    ],
));

echo "Order ID: {$response->id}";

Track a shipment

$tracking = $client->getTracking('VTR0001184271');

echo "Carrier: {$tracking->carrierName}\n";

foreach ($tracking->events as $event) {
    echo "[{$event->date->format('d/m/Y H:i')}] {$event->name}\n";
}

Webhooks

Parse incoming webhook payloads with the provided models:

use Mandae\Webhooks\{OrderPickupPayload, ProcessedItemPayload};

// Order pickup status
$pickup = OrderPickupPayload::fromJson($request->getBody());

// Item processed (tracking code assigned)
$item = ProcessedItemPayload::fromJson($request->getBody());
echo $item->trackingCode;

V1 API (experimental)

The V1 API is non-public and may change without notice. It requires separate email/password authentication.

use Mandae\Enums\SearchMethod;
use Mandae\Requests\V1\SearchOrdersRequest;

$v1 = $client->v1();
$v1->authenticate('you@example.com', 'password');

$result = $v1->searchOrders(new SearchOrdersRequest(
    method: SearchMethod::TrackingCode,
    value:  'VTR0001184271',
));

foreach ($result->orders as $order) {
    echo "{$order->trackingCode} — {$order->situationCode}\n";
}

---

Environment

Constant	Base URL
Environment::Sandbox	https://sandbox.api.mandae.com.br/v2/
Environment::Production	https://api.mandae.com.br/v2/

Each environment uses a different API token. Request your credentials at ti@mandae.com.br.

---

Running tests

composer install
./vendor/bin/phpunit

---

License

MIT © Rafael Corrêa Gomes