Expand description
§usps_v3_api
SDK en Rust idiomático, fuertemente tipado, asíncrono y listo para producción para interactuar con el ecosistema de APIs REST v3 del Servicio Postal de los Estados Unidos (USPS - United States Postal Service).
§Características Principales
- Arquitectura Modular en Capas: Separación limpia entre infraestructura transversal (
core) y catálogo de servicios de negocio (services). - Gestión Inteligente de Autenticación OAuth 2.0: Manejo automático del ciclo de vida del token
Bearer (
POST /oauth2/v3/token), con almacenamiento seguro en memoria mediantetokio::sync::RwLock, renovación transparente con margen de expiración y patrón double-checked lock. - Seguridad en Producción: Protección de credenciales confidenciales (
client_secret) contra fugas accidentales en logs de depuración ([REDACTED]). - Servicio de Direcciones (
Addresses v3): Estandarización de direcciones, validación de entrega DPV, búsqueda de códigos postales (ZIP Lookup) y resolución de ciudad/estado. - Servicio de Seguimiento (
Tracking v3): Consulta individual y por lotes (hasta 35 paquetes) de envíos en tránsito, detalle de eventos históricos, estados y fechas estimadas de entrega. - Servicio de Precios y Tarifas (
Prices v3): Cotización de tarifas postales nacionales e internacionales por peso, dimensiones y clases postales (Priority Mail,USPS Ground Advantage,Global Express Guaranteed, etc.). - Servicio de Estándares de Entrega (
Service Standards v3): Cálculo de compromisos de entrega, fechas estimadas (Expected Delivery Date - EDD) y días de tránsito entre códigos postales origen y destino. - Servicio de Etiquetas (
Labels v3): Emisión y cancelación de etiquetas postales con código de barras en formatos PDF, PNG, TIFF, SVG o Base64 (POST /labels/v3/label,DELETE /labels/v3/label/{id}). - Servicio de Manifiestos (
Manifests v3): Consolidación de envíos masivos en un Formulario SCAN Form (PS Form 5630) con código de barras maestro (POST /manifests/v3/manifest,GET /manifests/v3/manifest/{id}). - Servicio de Recolección (
Pickup v3): Verificación de disponibilidad, programación y cancelación de recolección de paquetes por cartero a domicilio (Carrier Pickup). - Servicio de Ubicaciones (
Locations v3): Búsqueda de oficinas postales, buzones de depósito y quioscos por código postal o geocordenadas, consulta de horarios semanales y servicios (pasaportes, casilleros). - Servicio de Webhooks (
Subscriptions v3): Registro, consulta y cancelación de callbacks HTTP en tiempo real para eventos de rastreo y entrega (POST /subscriptions/v3/subscription,DELETE /subscriptions/v3/subscription/{id}). - Servicio de Pagos EPS (
Payments v3): Consulta de saldos y autorizaciones en el Enterprise Payment System de USPS. - Declaraciones Aduaneras (
Customs v3): Modelado de formularios CN22 y CP72, partidas arancelarias HTS y exenciones AES/ITN. - Resiliencia y Reintentos: Política de backoff exponencial con jitter (
RetryPolicy) ante respuestas transitorias HTTP 429 (Rate Limit), 500, 502, 503 y 504. - Manejo Exhaustivo de Errores: Jerarquía fuertemente tipada con
UspsErrory deserialización de errores estructurados devueltos por la pasarela de USPS.
§Ejemplo de Uso Rápido
use usps_v3_api::{
UspsClient, UspsEnvironment,
AddressStandardizationRequest, TrackingExpand,
};
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
// 1. Inicializar el cliente SDK
let client = UspsClient::builder()
.credentials("TU_CLIENT_ID", "TU_CLIENT_SECRET")
.environment(UspsEnvironment::Sandbox)
.build()?;
// 2. Estandarizar una dirección postal
let address_req = AddressStandardizationRequest::new("475 L'Enfant Plaza SW")
.city_state("Washington", "DC")
.zip_code("20260");
let address_info = client.addresses().standardize(&address_req).await?;
println!("Dirección estandarizada: {:?}", address_info.address);
// 3. Rastrear un paquete
let tracking = client.tracking().track("9400100000000000000000").await?;
println!("Estado del paquete: {:?}", tracking.status);
Ok(())
}Re-exports§
pub use core::ApiErrorDetail;pub use core::OAuthTokenResponse;pub use core::Result;pub use core::RetryPolicy;pub use core::TokenManager;pub use core::USPS_CAT_BASE_URL;pub use core::USPS_PROD_BASE_URL;pub use core::UspsApiErrorResponse;pub use core::UspsClient;pub use core::UspsClientBuilder;pub use core::UspsConfig;pub use core::UspsEnvironment;pub use core::UspsError;pub use core::UspsErrorCode;pub use services::AccountBalanceResponse;pub use services::AddressResponse;pub use services::AddressStandardizationRequest;pub use services::AddressesService;pub use services::CancelLabelResponse;pub use services::CancelPickupResponse;pub use services::CityStateResponse;pub use services::CreateLabelRequest;pub use services::CreateLabelResponse;pub use services::CreateManifestRequest;pub use services::CreateManifestResponse;pub use services::CreateSubscriptionRequest;pub use services::CustomsContentType;pub use services::CustomsDeclaration;pub use services::CustomsItem;pub use services::DailyHours;pub use services::DeleteSubscriptionResponse;pub use services::DomesticRateRequest;pub use services::DomesticRateResponse;pub use services::ExtraServiceRateItem;pub use services::ExtraServiceType;pub use services::ExtraServicesRateRequest;pub use services::ExtraServicesRateResponse;pub use services::ImageInfo;pub use services::InternationalMailClass;pub use services::InternationalRateRequest;pub use services::InternationalRateResponse;pub use services::LabelBrokerRequest;pub use services::LabelBrokerResponse;pub use services::LabelImageType;pub use services::LabelPartyAddress;pub use services::LabelSize;pub use services::LabelsService;pub use services::LocationFacility;pub use services::LocationSearchRequest;pub use services::LocationSearchResponse;pub use services::LocationServiceType;pub use services::LocationsService;pub use services::MailClass;pub use services::ManifestsService;pub use services::NonDeliveryOption;pub use services::PackageDescription;pub use services::PackageLocation;pub use services::PaymentAccountType;pub use services::PaymentAuthorizationRequest;pub use services::PaymentAuthorizationResponse;pub use services::PaymentsService;pub use services::PickupAvailabilityResponse;pub use services::PickupContactAddress;pub use services::PickupPackageCount;pub use services::PickupService;pub use services::PricesService;pub use services::ProcessingCategory;pub use services::ProofOfDeliveryFormat;pub use services::ProofOfDeliveryRequest;pub use services::ProofOfDeliveryResponse;pub use services::RateItem;pub use services::SchedulePickupRequest;pub use services::SchedulePickupResponse;pub use services::ServiceStandardEstimate;pub use services::ServiceStandardRequest;pub use services::ServiceStandardResponse;pub use services::ServiceStandardsService;pub use services::StandardizedAddress;pub use services::SubscriptionEventType;pub use services::SubscriptionResponse;pub use services::TrackingEvent;pub use services::TrackingExpand;pub use services::TrackingResponse;pub use services::TrackingService;pub use services::WebhooksService;pub use services::ZipCodeLookupRequest;pub use core::auth;pub use core::client;pub use core::config;pub use core::error;pub use core::retry;pub use services::addresses;pub use services::customs;pub use services::labels;pub use services::locations;pub use services::manifests;pub use services::payments;pub use services::pickup;pub use services::prices;pub use services::standards;pub use services::tracking;pub use services::webhooks;