Envía una postal personalizada con la API REST de IRIS

Elige el tamaño de la tarjeta postal antes de exportar los PDF

A diferencia de un PDF de carta, una tarjeta postal no es un documento de varias páginas que se envía a una imprenta para que lo organice. IRIS acepta caras de impresión ya renderizadas. Cada PDF de tarjeta postal registrado debe tener exactamente una página en orientación horizontal, coincidir con el tipo de documento y las dimensiones del tamaño seleccionado con una tolerancia de 1 pt y abrirse sin contraseña. La API no convierte texto ni una URL de imagen en un diseño listo para imprimir.

Estas son las dimensiones de los archivos de impresión de los proveedores de IRIS, incluido el sangrado para los tamaños de Lob. USPS distingue entre las dimensiones de las tarjetas postales First-Class para clientes minoristas y comerciales, así que usa la cotización de IRIS calculada por el servidor para conocer el precio, en lugar del precio de una estampilla.

• Dimensiones de PDF y cargas útiles de tarjetas postales de IRIS
• USPS: reglas de tamaño y seguimiento de tarjetas postales First-Class Mail

Coloca el mensaje y el espacio para la dirección en la cara correcta

Para las tarjetas de Lob de 4 × 6 o 6 × 9, prepara dos PDF distintos de una página del mismo tipo de tarjeta postal: primaryDocumentId identifica el frente; secondaryDocumentId identifica el reverso. No repitas el mismo ID para ambas caras. Small es la excepción: coloca el diseño y el mensaje en su única cara personalizada, dentro de un borde blanco de un cuarto de pulgada; el proveedor genera la cara de la dirección, así que no subas un segundo archivo.

Para Pro, el archivo principal contiene el diseño principal y el archivo secundario corresponde a la cara del mensaje y la dirección. Reserva las 3.75 pulgadas (270 pt) del extremo derecho de esa cara para el área de la dirección del proveedor. Ambos archivos deben usar las dimensiones de postcard_pro. Small y Pro dependen del proveedor LetterStream en su entorno de pruebas; actualmente, las solicitudes enviadas a LetterStream permanecen retenidas en modo de prueba en lugar de imprimirse y enviarse por correo. Si se selecciona un tamaño correspondiente al otro proveedor activo, la solicitud se rechaza antes de cobrar.

Inspecciona una representación renderizada de cada PDF, especialmente los bordes, el sangrado, la orientación de lectura, la ubicación del mensaje y el espacio libre para la dirección. Los campos options.layout (banner, poster, minimal), options.font (editorial, modern, handwritten) y options.artwork describen tus PDF terminados; artwork: { type: "upload" } no los sube ni los renderiza.

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

Obtén una URL prefirmada, realiza un PUT y registra cada cara

Mantén en tu servidor una clave bearer vinculada a la cuenta, nunca en el JavaScript del navegador. Para cada cara, realiza un POST a /v1/uploads/presign con fileName, el valor exacto de sizeBytes y el kind seleccionado. Sube los bytes mediante PUT a uploadUrl antes de que venza su plazo de diez minutos, con todos los valores de uploadHeaders devueltos, incluido If-None-Match cuando se proporcione. No reenvíes la clave bearer al almacenamiento de objetos. Una URL prefirmada por sí sola no constituye una carga completada.

Después de un PUT exitoso, realiza un POST a /v1/documents con la clave de almacenamiento devuelta, el mismo fileName y kind. Guarda data.id del documento inmutable registrado; la clave de almacenamiento no es un ID de documento. Si una cara cambia, debes volver a subirla y registrarla. Cada PDF tiene un límite de 26 MiB. Una tarjeta postal puede leerse durante el tránsito, así que no incluyas números de Seguro Social, Medicare ni otras identificaciones gubernamentales; esa información debe ir en una carta sellada de IRIS.

• Detalles de carga y registro de IRIS

Prepara una tarjeta postal de 4 × 6 y solicita una cotización, no un envío

Este ejemplo para el servidor con Node.js 22+ requiere front.pdf y back.pdf como archivos PDF separados de una página de 450 × 306 pt. Guarda el JSON que aparece a continuación como addresses.json con las direcciones reales del remitente y del destinatario en Estados Unidos, previamente revisadas; el script rechaza los marcadores de posición del ejemplo. Tanto sender.recipient como recipient.recipient son nombres de personas o empresas obligatorios, no etiquetas opcionales. Cada dirección también necesita primaryLine, city, state de dos letras y zipCode.

Proporciona IRIS_API_KEY en el entorno del servidor con los permisos documents:write y mailings:read. Este ejemplo nunca llama a POST /v1/mailings. Guarda la carga útil exacta de la cotización y el precio para que una persona los revise, pero no verifica el saldo de créditos ni crea un envío. El proveedor activo debe admitir 4x6; si, en cambio, admite el entorno de pruebas de LetterStream, usa los tipos de PDF y la cantidad de caras de Small o Pro indicados arriba, en lugar de limitarte a cambiar la cadena del tamaño.

{
  "sender": {
    "recipient": "REPLACE WITH SENDER NAME",
    "primaryLine": "REPLACE WITH SENDER STREET",
    "city": "Boston", "state": "MA", "zipCode": "02108"
  },
  "recipient": {
    "recipient": "REPLACE WITH RECIPIENT NAME",
    "primaryLine": "REPLACE WITH RECIPIENT STREET",
    "city": "Boston", "state": "MA", "zipCode": "02109"
  }
}

• Esquema de solicitud de tarjetas postales y permisos de IRIS

Ejecuta el script privado de preparación

Guarda este código como prepare-postcard.mjs junto a tus dos PDF y addresses.json. Configura IRIS_API_KEY únicamente en el entorno de tu servidor de confianza y luego ejecuta node prepare-postcard.mjs. Mantén postcard-review.json privado: incluye direcciones y los ID de los documentos registrados. Si la preparación falla, detente e inspecciona el error; una cotización no es una aprobación ni un pedido.

import { readFile, writeFile } from 'node:fs/promises';

const base = 'https://api.irispostalforms.com';
const key = process.env.IRIS_API_KEY;
if (!key || !key.startsWith('irk_')) throw new Error('Set a server-side IRIS_API_KEY.');

async function api(path, body) {
  const response = await fetch(base + path, {
    method: 'POST',
    headers: { Authorization: 'Bearer ' + key, 'Content-Type': 'application/json' },
    body: JSON.stringify(body)
  });
  const result = await response.json();
  if (!response.ok) throw new Error(response.status + ' ' + JSON.stringify(result.error));
  return result.data;
}

async function register(fileName) {
  const pdf = await readFile(fileName);
  const kind = 'postcard_4x6';
  const upload = await api('/v1/uploads/presign', {
    fileName, sizeBytes: pdf.byteLength, kind
  });
  const put = await fetch(upload.uploadUrl, {
    method: 'PUT', headers: upload.uploadHeaders, body: pdf
  });
  if (!put.ok) throw new Error(fileName + ' upload failed: HTTP ' + put.status);
  const document = await api('/v1/documents', {
    key: upload.key, fileName, kind
  });
  return document.id;
}

const addresses = JSON.parse(await readFile('addresses.json', 'utf8'));
if (JSON.stringify(addresses).includes('REPLACE')) {
  throw new Error('Replace every sample address placeholder first.');
}
const primaryDocumentId = await register('front.pdf');
const secondaryDocumentId = await register('back.pdf');
const mailing = {
  product: 'postcard', primaryDocumentId, secondaryDocumentId,
  sender: addresses.sender, recipient: addresses.recipient,
  options: { size: '4x6', layout: 'minimal', font: 'modern',
             artwork: { type: 'upload' } }
};
const quote = await api('/v1/mailings/quote', mailing);
await writeFile('postcard-review.json',
  JSON.stringify({ mailing, quote }, null, 2), { flag: 'wx' });
console.log('Quote in US cents:', quote.priceCents);
console.log('STOP: inspect both PDFs, addresses, options, and price. No order was created.');

Revisa, aprueba, solicita el envío una sola vez y luego consulta el estado

POST /v1/mailings/quote devuelve priceCents y un desglose. No descuenta créditos, no reserva un precio ni solicita el envío de la tarjeta postal. Cada envío corresponde a una tarjeta postal con una dirección individual dentro de Estados Unidos; ¿planeas enviar a una lista grande? Cuéntanos en /contact?topic=volume. Si cambian los PDF o los detalles del envío, registra archivos nuevos según sea necesario, solicita otra cotización y obtén una nueva aprobación.

Solo después de que una persona vea ambas caras reales (o la única cara personalizada de Small), las direcciones completas del remitente y del destinatario, la cotización actual, el propósito y la autorización para enviar, el código de un servidor de confianza debe realizar un POST del objeto de envío revisado —no del objeto contenedor completo de la revisión— a /v1/mailings con una Idempotency-Key persistente. Esta llamada vuelve a calcular el precio, descuenta los créditos prepagados y da curso al procesamiento del pedido. Guarda una clave única con esa carga útil aprobada; si la respuesta es incierta, vuelve a intentarlo con la misma carga útil sin cambios y la misma clave. Una clave nueva puede crear otro pedido de pago.

Guarda data.orderId del resultado de creación 201 (o de la repetición completada 200). El estado paid confirma el pedido. Realiza un GET a /v1/mailings/{id} con ese ID de pedido para consultar el estado actual; trackingNumber y expectedDeliveryDate pueden ser null, y es posible que se omitan etapas. Las tarjetas postales First-Class comunes no incluyen USPS Tracking. IRIS imprime la tarjeta y la entrega a USPS First-Class Mail; USPS indica un plazo de 1–5 días hábiles una vez que está en el correo.

• Instrucciones de IRIS para solicitar un envío revisado y consultar su estado
• Cómo manejar un envío con resultado incierto sin duplicar el pedido
• Planifica tarjetas postales individuales de seguimiento a clientes
• Habla con nosotros sobre envíos de tarjetas postales en grandes volúmenes