Skip to main content

Crate usps_v3_api

Crate usps_v3_api 

Source
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 mediante tokio::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 UspsError y 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;

Modules§

core
Primitivas centrales de configuración, autenticación OAuth 2.0, cliente HTTP y errores.
services
Catálogo de servicios de la API REST v3 de USPS.