smart-dato / correos-sdk

0.2.0 2026-09-24 07:08 UTC

Requires

• php: ^8.2|^8.5
• ext-soap: *
• illuminate/contracts: ^10.0||^11.0||^12.0||^13.0
• spatie/laravel-package-tools: ^1.16

Requires (Dev)

• larastan/larastan: ^2.9||^3.0
• laravel/pint: ^1.14
• nunomaduro/collision: ^8.1.1||^7.10.0
• orchestra/testbench: ^10.0.0||^9.0.0||^8.22.0
• pestphp/pest: ^3.0
• pestphp/pest-plugin-arch: ^3.0
• pestphp/pest-plugin-laravel: ^3.0
• phpstan/extension-installer: ^1.3||^2.0
• phpstan/phpstan-deprecation-rules: ^1.1||^2.0
• phpstan/phpstan-phpunit: ^1.3||^2.0
• spatie/laravel-ray: ^1.35

MIT

• SmartDato

• laravel
• SmartDato
• correos-sdk

Published on Packagist.org on 2026-09-24 07:08 UTC

README

A small Laravel package for pre-registering Correos (Spanish postal service) shipments over SOAP and fetching their tracking events.

For labels, customs documents and a fuller API surface, see smart-dato/correos-shipping-sdk.

Requirements

• PHP 8.2+
• Laravel 10 – 13
• The soap PHP extension

Installation

composer require smart-dato/correos-sdk

Publish the config file:

php artisan vendor:publish --tag="correos-sdk-config"

CORREOS_SDK_BASE_URL=https://your-correos-host
CORREOS_SDK_USERNAME=your-username
CORREOS_SDK_PASSWORD=your-password

SOAP calls go to {base_url}/preregistroenvios.

Usage

The CorreosSdk facade and container binding use the configured credentials:

use SmartDato\CorreosSdk\Facades\CorreosSdk;

$correos = CorreosSdk::getFacadeRoot();

Or construct the client yourself:

use SmartDato\CorreosSdk\CorreosSdk;

$correos = new CorreosSdk(
    baseUrl: 'https://your-correos-host',
    username: 'your-username',
    password: 'your-password',
);

Pre-register a shipment

Calls the PreRegistroMultibulto SOAP operation.

use SmartDato\CorreosSdk\Enums\DeliveryModeEnum;
use SmartDato\CorreosSdk\Enums\LabelModeEnum;
use SmartDato\CorreosSdk\Enums\PostageTypeEnum;
use SmartDato\CorreosSdk\Payloads\AddressPayload;
use SmartDato\CorreosSdk\Payloads\ParcelPayload;
use SmartDato\CorreosSdk\Payloads\ShipmentPayload;
use SmartDato\CorreosSdk\Payloads\ShippingPartyPayload;

$result = $correos->createShipment(new ShipmentPayload(
    date: '...',                // sent as FechaOperacion
    parcelCount: 1,
    senderInfo: new ShippingPartyPayload(
        name: 'Sender S.L.',
        address: new AddressPayload(address: 'Calle Mayor 1', city: 'Madrid'),
        zipcode: '28013',
        phone: '910000000',
        email: '[e-mail]',
    ),
    receiverInfo: new ShippingPartyPayload(
        name: 'Jane Doe',
        address: new AddressPayload(address: 'Avinguda Diagonal 100', city: 'Barcelona'),
        zipcode: '08019',
        phone: '930000000',
        email: '[e-mail]',
    ),
    parcels: [
        new ParcelPayload(parcelNumber: 1, weight: 1.5, length: 30, height: 20, width: 10),
    ],
    totalWeight: 1.5,
    labelCode: 'your-labeler-code', // CodEtiquetador, issued by Correos
    productCode: 'your-product-code', // CodProducto
    postageType: PostageTypeEnum::POSTAGE_PAID,   // TipoFranqueo
    deliveryMode: DeliveryModeEnum::STANDARD,     // ModalidadEntrega
    modDevLabel: (int) LabelModeEnum::PDF->value,
));

$result['request'];  // raw SOAP request XML
$result['response']; // raw SOAP response XML

createShipment() returns the raw SOAP request and response rather than a parsed object, and throws SoapFault on transport errors.

Values such as the operation date and weights are passed to Correos unchanged — the SDK does not enforce a date format or weight unit, so use whatever your Correos contract specifies.

postageType and deliveryMode default to POSTAGE_PAID and STANDARD.

Track a shipment

$events = $correos->getTracking('your-shipment-code');

Returns the decoded JSON from Correos's eventos_envio_servicio_auth endpoint, or an empty array when the body is not JSON.

The underlying HTTP exchange of the last call stays available for logging:

$correos->lastRequest();  // ?Illuminate\Http\Client\Request, also set when the connection failed
$correos->lastResponse(); // ?Illuminate\Http\Client\Response

Enums

Enum	Cases
DeliveryModeEnum	STANDARD (ST), IN_SELECTED_BRANCH (LS), IN_REFERENCE_BRANCH (OR), CITYPAQ (CP)
PostageTypeEnum	POSTAGE_PAID (FP), MACHINE_FRANKING (FM), CASH (ES), ONLINE_PAYMENT (ON)
LabelModeEnum	XML (1), PDF (2), ZPL (3)
WeightTypeEnum	REAL (R), VOLUMETRIC (V)

Testing

composer test

Changelog

Please see CHANGELOG for more information on what has changed recently.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

• SmartDato
• All Contributors

License

The MIT License (MIT). Please see License File for more information.