Integración de la API de envíos: Guía de inicio rápido para desarrolladores
La integración de una API de envío conecta su sistema directamente con los proveedores de servicios de paquetería mediante una interfaz REST o middleware, lo que permite el acceso inmediato a la creación de etiquetas, el seguimiento y el procesamiento de devoluciones. Para la mayoría de los minoristas medianos y grandes, se recomienda una plataforma multienvío en lugar de una única conexión directa, ya que consolida la autenticación, el control de versiones y la facturación en un solo lugar.
Tres pasos para empezar:
- Cree una cuenta de cliente empresarial y obtenga acceso a la API con el operador o middleware elegido.
- Active el entorno de pruebas e introduzca los datos de prueba.
- Envía la primera solicitud de etiqueta a través de un punto final de prueba y verifica la respuesta.
Hallazgos importantes
Una integración funcional de la API de envíos requiere pruebas en un entorno aislado (sandbox), autenticación OAuth2, webhooks en lugar de sondeo y una decisión consciente entre la conexión directa y el middleware.
| Tema | Detalles |
|---|---|
| Primera prueba | Configure el acceso al entorno de pruebas y los tokens de prueba antes de cada conexión a producción. |
| autenticación | Utilice OAuth2 en lugar de autenticación básica para las nuevas integraciones. |
| Actualizaciones de estado | Utilice webhooks en lugar de sondeos para reducir la latencia y la carga de la API. |
| Elección de operador | Verifique los límites de volumen y las condiciones del contrato antes de conectarse. |
| Opción de implementación | Paket International combina múltiples transportistas y procesos aduaneros en una única interfaz. |
Contenido
- ¿Qué capacidades técnicas ofrece una API de envío?
- ¿Qué funciones determinan el esfuerzo de integración?
- ¿Qué servicios de entrega de paquetes se pueden conectar mediante API?
- ¿Cómo conseguir tu primera consulta de una discográfica en 60 minutos?
- ¿Qué requisitos de seguridad y protección de datos se aplican?
- Conexión directa con el operador o middleware: ¿Cuál es la mejor opción?
- ¿Cuáles son las mejores prácticas que garantizan un funcionamiento fluido en la vida cotidiana?
- ¿Cómo simplifica Paket International la conexión técnica?
- ¿Por qué el paquete internacional es una opción de implementación que vale la pena?
- ¿Dónde pueden encontrar los desarrolladores más documentación?
- Mar de fondo
¿Qué capacidades técnicas ofrece una API de envío?
Una API de envío proporciona puntos de acceso para los pasos clave del proceso de envío: creación de etiquetas, seguimiento, devoluciones, registro de recogida, cálculo de costes de envío, validación de direcciones y documentación aduanera. La mayoría de los proveedores utilizan REST con datos JSON, documentados mediante OpenAPI o Swagger. La API de E-POSTBUSINESS, por ejemplo, utiliza precisamente este patrón para el procesamiento automatizado de correo con envíos masivos.
Una solicitud de etiquetado típica se vería así de forma simplificada:
POST /orders
{
"shipper": {...},
"receiver": {...},
"weight": 2.5,
"product": "V01PAK"
}
El proceso consta de tres pasos:
- Validar direcciones y datos del paquete.
- Enviar objeto de pedido vía POST.
- Recuperar e imprimir la URL de la etiqueta de la respuesta.
Consejo profesional: Pruebe siempre cada nueva versión de la API con una carga útil de ejemplo de la documentación oficial antes de añadir sus propios campos.
Los puntos finales clave como /orders, /labels y /manifests constituyen la base de casi todas las API de operadores. El paso del manifiesto, en definitiva, es uno de los... fuentes de error más comunes en operación de producción.
¿Qué funciones determinan el esfuerzo de integración?
No todas las API son igual de complejas de integrar. Varios detalles técnicos son cruciales e influyen directamente en el esfuerzo requerido:
- Método de autenticación: OAuth2 ahorra trabajo de migración a largo plazo en comparación con la autenticación básica.
- Entorno de pruebas con datos de prueba realistas y su propio punto final.
- Límites de velocidad y su documentación para evitar la limitación de velocidad en operaciones por lotes.
- Clave de idempotencia para solicitudes POST para evitar la creación de etiquetas duplicadas.
- Webhooks para actualizaciones de estado y seguimiento en lugar de sondeos.
- Los formatos de etiquetas compatibles (PDF, ZPL) y el flujo de retorno se gestionan como un punto final independiente.
- API para documentos aduaneros y de exportación para envíos internacionales.
Los SDK y los ejemplos de código predefinidos suelen acortar la implementación inicial en varios días. También conviene revisar los acuerdos de nivel de servicio y los canales de soporte antes de tomar una decisión, ya que un proveedor con tiempos de respuesta poco fiables se convierte rápidamente en un riesgo en caso de problemas.
Consejo profesional: No evalúe la documentación por su extensión, sino por si contiene consultas de ejemplo completas y funcionales, y no solo listas de campos.
¿Qué servicios de entrega de paquetes se pueden conectar mediante API?
Para el mercado alemán, DHL, Deutsche Post, DPD, Hermes y GLS son las principales opciones a nivel nacional, mientras que UPS, FedEx y DB Schenker complementan la cobertura internacional. Cada transportista tiene sus propios requisitos: condiciones contractuales, números de facturación y, en ocasiones, umbrales de volumen fijos.
La API de envíos de DHL Parcel DE, por ejemplo, suele estar dirigida a clientes empresariales con más de 200 envíos al año y requiere un contrato de cliente empresarial que incluye acceso al portal de clientes empresariales. Quienes no alcancen este umbral, o quienes deseen conectar varios transportistas simultáneamente, prácticamente acaban utilizando una plataforma centralizada.
A aclarar antes de la firma del contrato:
- ¿Qué direcciones de remitente y de destinatario deben configurarse?
- ¿Qué datos bancarios se requieren para el pago contra reembolso o para servicios adicionales?
- ¿Existe una cantidad mínima de envío al mes o al año?
¿Cómo conseguir tu primera consulta de una discográfica en 60 minutos?
Si se sigue la secuencia correcta, la primera solicitud que requiere trabajo puede implementarse en menos de una hora.
- Formalice un contrato con su empresa y reciba los datos de acceso al portal.
- Habilitar el acceso al entorno aislado, normalmente a través de un punto final separado como
api-sandbox.dhl.com. - Genera tokens de API o credenciales de cliente OAuth2.
- Envíe una solicitud de prueba a través de Postman Collection o la herramienta de línea de comandos (CLI).
- primero
POST /orders-Envía una solicitud con datos de prueba. - Recupera la etiqueta de la respuesta y compruébala visualmente.
- Simule el proceso de manifiesto (cierre al final del día) antes de la puesta en marcha.
Obstáculos típicos en el primer intento:
- Error 401: El token ha caducado o su alcance es incorrecto.
- Error 422: Falta un campo obligatorio o el formato de los datos de la dirección es incorrecto.
- URL de etiqueta vacía: El manifiesto aún no se ha activado.
Consejo profesional: Crea una colección de Postman con todos los casos de prueba y haz que se ejecute automáticamente en el entorno de pruebas con cada actualización de la API; esto ahorra mucho tiempo durante los cambios de versión.
| Enfoque | Primera prueba posible después |
|---|---|
| API directa del operador | Normalmente de 1 a 3 días (después de la aprobación del contrato). |
| Plataforma de middleware | a menudo en cuestión de horas |
¿Qué requisitos de seguridad y protección de datos se aplican?
OAuth2 se considera ahora el estándar para nuevas integraciones, y DHL lo recomienda explícitamente por encima de la variante anterior de autenticación básica. Las claves API siguen siendo comunes para conexiones más sencillas, pero deben cambiarse periódicamente.
En el tratamiento de datos del destinatario conforme al RGPD se aplican varios puntos fijos:
- Almacenaremos los datos personales únicamente durante el tiempo necesario para el proceso de envío.
- Mantenga registros de acceso (registros de auditoría) para cada cambio en los datos de envío.
- Cifrado TLS para todas las conexiones API sin excepción.
- La gestión de roles y alcances garantiza que no todos los sistemas tengan acceso a todos los puntos finales.
Consejo profesional: Los plazos de eliminación de documentos para el seguimiento de datos están estipulados contractualmente con la compañía operadora, no solo internamente; esto evita disputas durante las auditorías.
Los webhooks no solo reducen la carga del servidor, sino que también... También reducen la latencia. en comparación con las consultas repetidas para detectar cambios de estado, un aspecto que se evalúa cada vez más en las auditorías de seguridad.
Conexión directa con el operador o middleware: ¿Cuál es la mejor opción?
Una conexión directa con un único transportista permite un control total sobre sus funciones especializadas y puede ofrecer mejores tarifas para grandes volúmenes. El inconveniente: cada servicio de paquetería adicional implica un nuevo conjunto de lógica de autenticación, control de versiones y facturación.
El middleware consolida todo esto en una única interfaz. En lugar de mantener cinco integraciones con operadores, te comunicas con un solo sistema que gestiona la traducción.
Sin software intermedio, los procesos de autenticación, el control de versiones y la gestión de la facturación se multiplican con cada operador adicional, un esfuerzo que a menudo se subestima en las conexiones directas.
Principales ventajas y desventajas de un vistazo:
- Conexión directa: mayor control, pero esfuerzo repetido por cada operador.
- Middleware: un Plataforma centralpero dependencia de su conjunto de características.
- Con el middleware, el riesgo del SLA se traslada a un único proveedor, lo que cambia el poder de negociación en caso de fallos.
Consejo profesional: Calcule el costo total de propiedad (TCO) durante tres años, no solo durante el primer año de integración; los costos de mantenimiento por operador se acumulan más rápido de lo esperado con las conexiones directas.
¿Cuáles son las mejores prácticas que garantizan un funcionamiento fluido en la vida cotidiana?
Un entorno de pruebas y un entorno de producción estrictamente separados impiden que los pedidos de prueba generen cargos de etiquetado reales. Las recopilaciones de Postman con pruebas automatizadas deben ejecutarse con cada implementación, no solo con el lanzamiento inicial.
- Utilice webhooks en lugar de sondeos para el seguimiento y el estado del manifiesto.
- Claves de idempotencia en cada
POST /ordersEnvíe una solicitud para evitar etiquetas duplicadas. - Implementar estrategias de reintento con retroceso exponencial en lugar de reintentos inmediatos.
- Implementar la verificación de firmas y la protección contra repetición para los eventos de webhook entrantes.
- Mantenga un panel de control de SLA con la tasa de errores, el tiempo de actividad y los errores de etiquetado por operador.
La monitorización resulta especialmente beneficiosa al final del día: el paso del manifiesto sigue siendo una de las fuentes de error más frecuentes, por lo que debe tratarse como una tarea independiente y monitorizada, en lugar de como un efecto secundario del último pedido del día.
¿Cómo simplifica Paket International la conexión técnica?
Paket International combina el acceso a múltiples transportistas, la documentación aduanera automatizada y el seguimiento en tiempo real en una única interfaz. En lugar de conectar DHL, DPD, UPS y FedEx por separado, un solo sistema accede a todos ellos, incluyendo el cálculo transparente de costes antes de la impresión de las etiquetas.
El proceso de incorporación sigue un patrón claro:
- Configura el acceso al entorno de pruebas.
- Genere etiquetas de prueba utilizando formatos de soporte reales.
- Active la cuenta de producción y conecte los procesos de pedidos existentes.
- Migre los datos de envío existentes sin interrumpir los envíos en curso.
Las señales de confianza, como la conformidad con la norma ISO 27001, el procesamiento de datos que cumple con el RGPD, los SDK y los acuerdos de nivel de servicio (SLA) documentados de muestra, facilitan aún más la aprobación interna por parte de los equipos de seguridad y cumplimiento.
¿Por qué el paquete internacional es una opción de implementación que vale la pena?
En lugar de mantener una nueva conexión directa para cada transportista adicional, Paket International cubre DHL, UPS, FedEx, DPD y DB Schenker a través de una única API, incluyendo el despacho de aduanas automático sin formularios manuales.
Esto ahorra tiempo, especialmente con los envíos internacionales: documentos de aduana, Facturas pro forma El cálculo del costo de entrega se realiza en el mismo proceso que la creación de etiquetas, no como un paso posterior independiente. Quienes ya tengan transportistas individuales conectados directamente pueden migrar gradualmente su lógica existente al software central de envío multicarrier sin interrumpir los envíos en curso. Para mercancías con requisitos especiales, como... Electrónica o en MueblesLa plataforma también proporciona directamente perfiles de envío adecuados.
El siguiente paso: solicitar acceso al entorno de pruebas, generar etiquetas de prueba y ejecutar el proceso de pedidos existente con la API de Paket International antes de que comience la transición a producción.
¿Dónde pueden encontrar los desarrolladores más documentación?
- API de envíos de DHL Parcel DE: Referencia para puntos finales, entorno de pruebas y migración de autenticación.
- Portal para desarrolladores de API grupales: Una colección de API de envío, devoluciones y seguimiento con un entorno de prueba.
- API de E-POSTBUSINESS: Referencia para el envío automatizado de correo a través de REST/Swagger.
- Webhooks frente a sondeo de API: una comparación de patrones arquitectónicos para actualizaciones de estado.
Mar de fondo
- Envíos DHL Parcel DE (Correos y Paquetería Alemania)
- Webhooks frente a sondeo de API — Recursos de Svix