Prepara un envío postal de un PDF con Python y la API de IRIS

Prepara los datos de entrada

Necesitas Python 3.10 o posterior, una cuenta de desarrollador de IRIS verificada y una clave del lado del servidor con los permisos account:read, documents:write y mailings:read. El ejemplo utiliza únicamente la biblioteca estándar de Python. Proporciona IRIS_API_KEY mediante tu entorno en lugar de incluirla en el script.

Guarda un PDF terminado de tamaño carta de EE. UU. como letter.pdf. Crea mailing-input.json con los datos de la solicitud de carta de la guía de inicio rápido de IRIS, con tu remitente, destinatario y opciones de impresión reales. El script reemplaza primaryDocumentId después de registrar el archivo. Usa recipient, primaryLine, city, state y zipCode dentro de cada dirección; no los sustituyas por nombres de campos específicos de otros proveedores.

• Documentación de la API de IRIS y límites actuales
• Contrato OpenAPI de IRIS

Carga y registra el PDF y obtén una cotización

Guarda esto como prepare_mail.py y ejecuta python prepare_mail.py desde un directorio de trabajo privado. Crea un archivo de revisión que contiene direcciones postales, así que mantén ese archivo fuera del control de versiones. La preparación de cargas y cotizaciones utiliza tu cuenta y almacenamiento privado, pero este script no crea un pedido.

import json
import os
from pathlib import Path
from urllib.error import HTTPError
from urllib.request import Request, urlopen

BASE = "https://api.irispostalforms.com"
KEY = os.environ["IRIS_API_KEY"]

def api(path, payload):
    request = Request(
        BASE + path,
        data=json.dumps(payload).encode("utf-8"),
        headers={"Authorization": "Bearer " + KEY,
                 "Content-Type": "application/json"},
        method="POST",
    )
    try:
        with urlopen(request, timeout=60) as response:
            return json.load(response)["data"]
    except HTTPError as error:
        raise RuntimeError(f"IRIS returned HTTP {error.code}; stop and inspect the request.") from error

pdf = Path("letter.pdf").read_bytes()
if not 0 < len(pdf) <= 26 * 1024 * 1024:
    raise ValueError("The PDF must be between 1 byte and 26 MiB.")

mailing = json.loads(Path("mailing-input.json").read_text(encoding="utf-8"))
if mailing.get("product") != "letter":
    raise ValueError("This example prepares letters only.")

upload = api("/v1/uploads/presign", {
    "fileName": "letter.pdf", "sizeBytes": len(pdf), "kind": "letter"
})
put = Request(upload["uploadUrl"], data=pdf,
              headers=upload["uploadHeaders"], method="PUT")
with urlopen(put, timeout=60) as response:
    if not 200 <= response.status < 300:
        raise RuntimeError("PDF upload did not complete.")

document = api("/v1/documents", {
    "key": upload["key"], "fileName": "letter.pdf", "kind": "letter"
})
mailing["primaryDocumentId"] = document["id"]
quote = api("/v1/mailings/quote", mailing)
review = {"mailing": mailing, "document": document, "quote": quote}
with Path("mailing-review.json").open("x", encoding="utf-8") as output:
    json.dump(review, output, indent=2)
print(f"Quoted total: USD {quote['priceCents'] / 100:.2f}")
print("Review letter.pdf and mailing-review.json. No mailing was submitted.")

Comprende el resultado antes de enviar

El archivo de revisión contiene tres objetos: mailing son los datos de la solicitud destinados a la cotización y al envío; document incluye la identidad y los metadatos del PDF registrado; quote contiene priceCents y su desglose. El script utiliza la creación exclusiva de archivos para no sobrescribir silenciosamente un archivo de revisión anterior. Crea un nuevo directorio de trabajo privado para una nueva intención de envío.

Las dos llamadas POST autenticadas posteriores a la carga utilizan la misma clave de cuenta. La solicitud PUT al almacenamiento utiliza únicamente los uploadHeaders devueltos; no adjuntes tu clave de portador de IRIS al host de almacenamiento. La URL de carga caduca después de diez minutos. Si caduca, solicita una nueva carga y repite la preparación antes de pedir la aprobación.

Añade un comando de envío separado y sujeto a revisión

Después de que una persona haya revisado el PDF, las direcciones, las opciones, el precio y la autorización para enviar, tu componente de envío de confianza puede enviar el objeto mailing mediante POST a /v1/mailings. No envíes todo el objeto contenedor de revisión. El envío requiere mailings:write, suficientes créditos prepagados y una Idempotency-Key guardada una sola vez para esta intención de envío.

Usa el ejemplo de envío de la guía de inicio rápido de IRIS como siguiente paso y mantén ese comando separado de este script de preparación. Guarda el orderId devuelto y luego usa GET /v1/mailings/{id} para consultar el estado. Antes de realizar envíos reales, prueba tu cliente con respuestas simuladas para 401, 402, 409, 429 y una respuesta interrumpida. Este tutorial no es una prueba de envío postal real ni un servicio de entorno de pruebas.

• Guía de inicio rápido de IRIS para envíos con revisión previa
• Diseña reintentos idempotentes