Desarrollador PHP en Zaragoza

Cómo conecto las APIs de Correos y DHL Express a una aplicación Symfony o Laravel: adaptadores, reintentos sin etiquetas duplicadas, colas y pruebas.

Desarrollador PHP

Mi lugar en la comunidad WordPress

  • Tengo cuenta en wordpress.org desde 2006.
  • He contribuido al núcleo de WordPress en las versiones 7.0 y 7.1.
  • Mantengo 30 plugins en wordpress.org.
  • Organizo WordCamps y hablo en ellos como ponente.
  • He asistido a todas las WordCamp Europe de 2017 a 2026.
  • Meetup local de WordPress: WordPress Zaragoza

Mi perfil en WordPress.org

#Etiquetas y seguimiento desde tu propia aplicación

Zaragoza vive de mover mercancía. Aragón Plataforma Logística presenta PLAZA como un complejo logístico y de transporte intermodal con aeropuerto, terminal ferroviaria y red de carreteras (plazalogistica.com, consultada el 15 de noviembre de 2026). Si tu empresa vende o fabrica en la zona, probablemente envías paquetes cada día, y alguien de tu equipo copia direcciones de un pedido a la web de un transportista.

Esa tarea se automatiza con las APIs que los transportistas publican para clientes con contrato. En esta página cuento cómo lo hago en una aplicación Symfony o Laravel, qué documentan hoy Correos y DHL Express y dónde se rompen la mayoría de estas integraciones: en los reintentos, no en la primera llamada que sale bien.

Trabajo solo, en remoto y por escrito. No hago diseño gráfico: si la integración necesita una pantalla de envíos, el esquema de elementos lo aportas tú y yo lo implemento.

Estación de Delicias, Zaragoza

Foto: Diego Delso, CC BY-SA 3.0, Wikimedia Commons.

#Qué publican Correos y DHL Express

Antes de diseñar nada leo lo que el transportista documenta, y solo trabajo con lo que tu contrato te permite usar.

CorreosDHL Express (MyDHL API)
RequisitoContrato de transporte, Correos ID y alta en el portal de desarrolladoresCuenta de cliente DHL Express
AutenticaciónToken con OAuth 2.0Cabecera Authorization con Basic Auth enviada de forma preventiva
OperacionesPreregister, Labels, Requests (recogidas), Trackpub (trazabilidad)Rating, Product, Shipment, Pickup, Tracking, Address
PruebasSe solicita acceso a cada API en el portalEntorno de pruebas aparte, con 500 invocaciones diarias por credencial

Fuentes: Correos, integración API y MyDHL API.

De Correos conviene saber tres cosas. Preregister valida y preregistra los envíos de paquetes. Labels genera las etiquetas nacionales e internacionales y la documentación CN22, CN23, DCAF y DDP. Trackpub devuelve la trazabilidad a partir de una matriz estandarizada de eventos, así que tu aplicación debe traducir esos eventos a los estados que entiende tu negocio, y esa tabla de traducción merece un archivo propio y pruebas.

De DHL Express conviene saber el orden. Su documentación recomienda consultar primero el servicio Rating para ver productos y servicios de valor añadido disponibles, y pasar después el elegido al servicio Shipment. En el código eso significa dos llamadas con un dato intermedio que hay que guardar, no una sola.

Los límites del entorno de pruebas también cuentan. Con 500 invocaciones diarias, un bucle de pruebas mal escrito te deja sin margen a media mañana. Por eso casi todas las pruebas automáticas de esta integración no deben tocar al transportista, y más abajo explico cómo.

#Un adaptador por transportista detrás de una interfaz

El patrón es el mismo en Symfony y en Laravel. La aplicación habla con una interfaz propia, por ejemplo CarrierGateway, con las operaciones que tu negocio necesita: crear envío, obtener etiqueta, pedir recogida, consultar estado. Cada transportista es una clase que traduce esa interfaz a su API.

interface CarrierGateway
{
    public function createShipment(Shipment $shipment): CarrierLabel;
    public function track(string $trackingNumber): array;
}

Con esto, cambiar de transportista o añadir uno segundo no toca el pedido ni la cola. También permite escribir reglas de elección (peso, destino, Canarias, Ceuta y Melilla) en un solo sitio. Esas reglas dependen de tu contrato y de la documentación de cada servicio, y no las invento: las dejo por escrito antes de programarlas.

#En Symfony: cliente con ámbito, Messenger y reintentos

Symfony HttpClient permite declarar clientes con ámbito. Cada transportista tiene su cliente, con su dirección base, su tiempo máximo y sus cabeceras:

# config/packages/framework.yaml
framework:
    http_client:
        scoped_clients:
            dhl.client:
                base_uri: '%env(DHL_API_BASE)%'
                timeout: 10
                headers:
                    Accept: 'application/json'

El detalle que más importa está en los reintentos. Según la documentación de Symfony, la opción retry_failed reintenta por defecto hasta 3 veces, con espera exponencial (1 segundo en el primer reintento, 4 en el tercero), y solo para ciertos códigos: 423, 425, 429, 502 y 503 con cualquier método, y 500, 504, 507 y 510 únicamente con métodos idempotentes (HTTP Client, Symfony). Un POST que crea una etiqueta no es idempotente por naturaleza. Si el transportista responde 503 después de haberla registrado, un reintento automático puede crear la segunda. Por eso decido por operación qué se reintenta y qué no.

Para el trabajo asíncrono uso Messenger. Su estrategia de reintentos se configura por transporte (max_retries, delay, multiplier), y lanzar UnrecoverableMessageHandlingException marca un mensaje que no debe reintentarse nunca (Messenger, Symfony). Una dirección rechazada por el transportista es un caso así: repetirla mil veces no la corrige.

#[AsMessageHandler]
final class CreateShipmentHandler
{
    public function __construct(
        private ShipmentRepository $shipments,
        private CarrierGateway $carrier,
    ) {}

    public function __invoke(CreateShipment $message): void
    {
        $shipment = $this->shipments->get($message->shipmentId);
        if ($shipment->hasLabel()) {
            return; // ya hecho: un segundo mensaje no crea otra etiqueta
        }

        try {
            $label = $this->carrier->createShipment($shipment);
        } catch (InvalidAddressException $e) {
            throw new UnrecoverableMessageHandlingException($e->getMessage(), 0, $e);
        }

        $shipment->attachLabel($label);
        $this->shipments->save($shipment);
    }
}

#En Laravel: cliente Http, colas y trabajos únicos

El cliente Http de Laravel tiene un tiempo máximo de 30 segundos por defecto y otro de conexión de 10, y ambos se cambian con timeout() y connectTimeout(). Su método retry() repite la petición si hay un error de cliente o de servidor (HTTP Client, Laravel). Esa frase, aplicada a un POST de creación, tiene la misma consecuencia que en Symfony, así que separo lecturas y escrituras:

// Seguimiento: se puede repetir sin efectos
$estado = Http::withToken($token)->timeout(10)->retry(3, 200)->get($urlSeguimiento);

// Creación de etiqueta: sin reintento automático
$respuesta = Http::withToken($token)->timeout(20)->post($urlEtiqueta, $datos);

En la cola, la interfaz ShouldBeUnique evita que haya dos trabajos iguales esperando a la vez, y uniqueId() define qué es igual (Colas, Laravel):

final class CreateShipmentLabel implements ShouldQueue, ShouldBeUnique
{
    use Dispatchable, Queueable;

    public function __construct(public int $shipmentId) {}

    public function uniqueId(): string
    {
        return (string) $this->shipmentId;
    }
}

Eso protege la cola, no al transportista. Dos trabajos nunca simultáneos siguen pudiendo crear dos etiquetas si el primero se perdió a mitad de camino. La protección real está en la base de datos, y es el siguiente apartado.

#El fallo que más cuesta: la etiqueta duplicada

Un envío pasa por estados que guardo en tu base de datos: pendiente, enviado al transportista, con etiqueta, con error. El orden importa:

  1. Antes de llamar a la API, el envío pasa a “pendiente” con una referencia propia y única (un índice único en base de datos, no solo una comprobación en código).
  2. Se llama al transportista con esa referencia, si su API admite referencia del cliente. Lo compruebo en su documentación, no lo doy por hecho.
  3. Si llega una respuesta correcta, se guarda la etiqueta y el número de seguimiento en la misma transacción.
  4. Si la llamada expira sin respuesta, el envío queda en un estado propio, “incierto”, y no vuelve a “pendiente” solo.
  5. Desde “incierto”, un proceso consulta primero si el transportista ya conoce ese envío. Si la API no permite esa consulta, lo decide una persona.

El paso 4 es el que casi todo el mundo omite. Sin él, un tiempo máximo agotado se convierte en un segundo paquete etiquetado y, a veces, en dos recogidas.

#El token de Correos y su caché

Correos pide un token con OAuth 2.0 para acceder a sus APIs. No pido un token nuevo en cada llamada: lo guardo en la caché de la aplicación hasta poco antes de su caducidad y lo renuevo en un único punto, con un bloqueo para que dos procesos no lo pidan a la vez. En Laravel, la documentación del cliente Http incluye un patrón para renovar el token si el primer intento devuelve un error de autenticación, usando una función en retry() que cambia el token y devuelve true solo en ese caso. En Symfony uso un decorador del cliente con el componente Cache. Las credenciales (Client ID y secreto) van en variables de entorno o en el gestor de secretos, nunca en el repositorio.

#Pruebas sin llamar al transportista

Las pruebas automáticas no llaman a ninguna API real. En Symfony, MockHttpClient y MockResponse sustituyen al cliente en las pruebas, y como el código depende de HttpClientInterface, no cambia nada más. En Laravel, Http::fake() define respuestas por URL y Http::preventStrayRequests() hace que cualquier petición no simulada lance una excepción, de modo que una prueba olvidada no gasta tus 500 invocaciones ni crea una etiqueta de verdad.

Los casos que cubro con respuestas simuladas, aparte del caso feliz:

  • Tiempo máximo agotado en la creación, y que el envío quede “incierto”.
  • Dirección rechazada, y que no se reintente.
  • Token caducado a mitad de una cola de envíos.
  • Evento de seguimiento que tu tabla de estados no conoce.
  • El mismo mensaje procesado dos veces.

Una vez al final, y solo con credenciales de prueba, ejecuto una prueba real contra el entorno de pruebas del transportista con los tres o cuatro envíos de ejemplo que me des.

#Lista de comprobación antes de producción

  • Contrato y credenciales de producción del transportista, distintas de las de prueba.
  • Tiempos máximos explícitos en cada llamada, y distintos para leer y para escribir.
  • Reintentos solo en operaciones que se pueden repetir sin efecto.
  • Estados del envío en base de datos, con índice único sobre la referencia propia.
  • Registro de cada llamada con el identificador del envío, sin volcar direcciones ni teléfonos completos en los logs.
  • Alerta cuando un envío lleva demasiado tiempo en “incierto”.
  • Tabla de eventos de seguimiento con prueba para el caso desconocido.
  • Un transportista de reserva configurable, si tu contrato lo permite.

#Cómo trabajo

Empiezo con un resumen escrito de lo que me cuentes: transportistas con contrato, dónde nace el pedido (tu tienda, tu ERP, una aplicación propia) y qué hace hoy tu equipo a mano. Te devuelvo por escrito las preguntas que faltan y un alcance con supuestos. La integración se despliega primero en un entorno de pruebas tuyo, la aceptas allí con tus envíos de ejemplo, y después pasa a producción. Si quieres, queda un mantenimiento mensual aparte, con las horas del mes que no se acumulan.

Qué aportas tú: acceso al repositorio y al entorno, el contrato y las credenciales de cada transportista, y las reglas de elección de servicio que ya aplicas.

#Preguntas frecuentes

#¿Puedo integrar Correos sin ser cliente de Correos?

No para las APIs directas. Correos exige un contrato de transporte para integrarse con sus APIs, además de Correos ID y el alta en su portal de desarrolladores. Si todavía no tienes contrato, ese es el primer paso, antes de cualquier línea de código. Mientras tanto puedo dejar el adaptador preparado contra una respuesta simulada.

#¿Merece la pena una integración por API con pocos envíos al día?

Depende de qué te cuesta hoy cada envío manual. Correos recomienda la integración por API sobre todo para volúmenes diarios altos y logística muy automatizada. Con pocos envíos suele bastar el conector de tu tienda o ERP, y yo te lo diré así tras leer tu caso.

#¿Qué pasa si el transportista no responde cuando creo una etiqueta?

La aplicación no debe repetir la creación a ciegas, porque la primera petición pudo haberse registrado. Guardo el envío en estado pendiente antes de llamar, repito solo con una referencia propia y, si la API lo permite, consulto antes de crear de nuevo. Si no hay forma de comprobarlo, el envío pasa a revisión manual y no a un segundo intento.

#¿Symfony o Laravel para este tipo de integración?

Los dos sirven. Si ya tienes uno de los dos, me quedo en él: el adaptador por transportista es el mismo y solo cambian el cliente HTTP, la cola y las pruebas. No recomiendo migrar de framework por una integración de transportistas.

#¿Puedes integrar un transportista cuya documentación no es pública?

Sí, si el transportista te da acceso a su documentación y a un entorno de pruebas con tu contrato. Sin entorno de pruebas no entrego una integración que cree etiquetas reales para comprobar que funciona. Con DHL Express, por ejemplo, el acceso depende de tener una cuenta de cliente.

#¿Qué necesitas para empezar?

Los transportistas con los que tienes contrato, las credenciales de prueba, la aplicación donde nacen los pedidos y tres o cuatro envíos reales de ejemplo (nacional, internacional, con recogida en punto, con incidencia). Lo demás lo pregunto por escrito. El primer presupuesto escrito es gratuito.

#Escríbeme

Cuéntame por escrito en la página de contacto qué transportistas usas, qué aplicación genera los pedidos (Symfony, Laravel u otra), cuántos envíos distintos tienes que cubrir y para cuándo lo necesitas. Con eso preparo el primer presupuesto escrito, que es gratuito.

Fuentes consultadas el 15 de noviembre de 2026: Correos, integración API, MyDHL API, HTTP Client, Symfony, Messenger, Symfony, HTTP Client, Laravel, Colas, Laravel.

¿Buscas el servicio: Desarrollador PHP en Zaragoza?

Describe tu proyecto por e-mail. Respondo en 48 horas.

Describe tu proyecto

Explora otros servicios WordPress y base de conocimiento