La respuesta breve
Una API de gestión de correspondencia conecta las tareas de correo físico con tu software. Para las cartas salientes, permite que un equipo remoto prepare un PDF, revise el destinatario y el precio, y luego solicite su impresión y envío sin una impresora de oficina. IRIS se encarga de ese paso de salida para cartas y postales de Estados Unidos; recibir y escanear la correspondencia entrante es tarea de un servicio de correo entrante.
¿Qué tipo de API de gestión de correspondencia necesitas?
Empieza por la tarea física. Recibir un sobre, entregar un paquete a un colega y enviar una carta nueva requieren servicios diferentes. Una integración que lee correspondencia entrante escaneada no necesariamente imprimirá tu PDF saliente.
Por ejemplo, PostScan Mail documenta el acceso a la correspondencia recibida y a los documentos escaneados. Parcel Tracker describe integraciones para la recepción de paquetes y las notificaciones a los destinatarios. IRIS proporciona el paso de impresión y envío de una carta o postal terminada. Comprueba el alcance actual de cada proveedor antes de basar tu desarrollo en él.
| Tu tarea | Lo que debe hacer el servicio |
|---|---|
| Recibir correspondencia comercial mientras trabajas de forma remota | Proporcionar una dirección para recibir correspondencia, escaneo y controles de acceso o reenvío. |
| Gestionar paquetes en una oficina o edificio con personal | Registrar la recepción, notificar al destinatario y registrar la entrega. |
| Enviar por correo un PDF terminado desde tu software empresarial | Aceptar el PDF y ambas direcciones, cotizar la impresión y el franqueo, y devolver un pedido de envío postal. Este es el flujo de trabajo de salida que se trata aquí. |
Define quién es responsable de una carta antes de elegir las herramientas
Los equipos distribuidos suelen tener una gestión de correspondencia informal: alguien recibe un PDF por chat, lo imprime en casa, busca un sobre y más tarde confirma que se envió. El punto débil suele ser el traspaso de responsabilidades. Un proceso más claro comienza con un responsable designado, un documento completo, una dirección actualizada y un estado de revisión visible.
Para envíos ocasionales, el sitio web de IRIS puede ser suficiente. Una integración mediante API resulta útil cuando tu software ya contiene los documentos y los registros empresariales, o cuando tu equipo copia repetidamente los mismos campos en una pantalla de envío postal. Empieza con el flujo de trabajo más sencillo que mantenga visible la responsabilidad.
Separa la preparación, la revisión y el seguimiento
Asigna estas responsabilidades dentro de tu propia aplicación o proceso documentado, que también contiene la cola compartida.
| Responsabilidad | Resultado práctico |
|---|---|
| Solicitante | Finalidad comercial, documento de origen y destinatario previsto. |
| Preparador | PDF final, direcciones completas y una cotización. |
| Revisor | Aprobación del documento exacto, las opciones, el precio y la autoridad para enviarlo. |
| Servicio de presentación | Una intención guardada de forma persistente y el orderId resultante. |
| Responsable de operaciones | Seguimiento del estado, disponibilidad de créditos y excepciones. |
Conecta tu cola de revisión con la API de envío postal
Piensa en un cliente que solicita una copia en papel de una confirmación de servicio. Tu aplicación genera el PDF y lo coloca en una cola de revisión. Un colega comprueba el documento, el destinatario, la dirección del remitente y el precio antes de que el servicio de presentación cree el envío postal.
Utiliza una cuenta de desarrollador verificada con créditos prepagados y guarda sus credenciales en tu servidor. Para la preparación, selecciona explícitamente documents:write y mailings:read; añade account:read si el servicio comprueba el saldo. Reserva mailings:write para el paso de presentación aprobado. Las claves recién creadas no son de solo lectura de forma predeterminada.
- Prepara el PDF final en tamaño US Letter y ambas direcciones completas de Estados Unidos. Tanto el remitente como el destinatario necesitan un nombre de persona o empresa, una dirección postal, una ciudad, un estado y un código ZIP.
- Realiza una solicitud POST /v1/uploads/presign y luego envía los bytes del PDF mediante PUT a la uploadUrl devuelta utilizando todos los uploadHeaders devueltos. No incluyas el token bearer de IRIS en esa carga al almacenamiento.
- Registra el archivo cargado con POST /v1/documents. Guarda el ID del documento y la huella digital devueltos junto con el registro empresarial de origen.
- Llama a POST /v1/mailings/quote con el documento, el remitente, el destinatario y las opciones de impresión. Muestra el precio en dólares a partir de su valor entero en centavos de dólar estadounidense. Una cotización no gasta créditos ni reserva el precio.
- Haz que el revisor apruebe el PDF final, ambos nombres y direcciones, las opciones, el precio y la finalidad. Guarda ese contenido de la solicitud aprobado y una Idempotency-Key antes de llamar a POST /v1/mailings. La presentación recalcula el precio, gasta créditos e inicia la ejecución del envío; no es un endpoint para guardar borradores.
- Guarda el orderId y el orderNumber legible devueltos. Utiliza GET /v1/mailings/{orderId} para consultar el estado actual del pedido y el seguimiento disponible; conserva el ID del documento y el número de seguimiento postal en sus propios campos.
Gestiona los tiempos de espera agotados y los datos faltantes sin enviar dos veces
Que se agote el tiempo de espera de la red no te indica si se creó un envío postal pagado. Conserva la solicitud aprobada y su clave de idempotencia en almacenamiento duradero para que otro proceso de trabajo pueda recuperar la misma intención.
Si la respuesta POST se pierde antes de que recibas un ID de pedido, repite POST /v1/mailings con la Idempotency-Key original y el contenido de la solicitud sin cambios. Una repetición completada devuelve el pedido original sin otro cargo. Una vez que tengas el ID, consulta su estado actual con GET. La confirmación de POST, incluida la de una repetición, no es un informe en tiempo real del estado de ejecución del envío.
| Qué ocurrió | Qué debe hacer tu flujo de trabajo |
|---|---|
| Se agotó el tiempo de espera de la presentación | Recupera la operación con la clave original y el contenido de la solicitud sin cambios. No generes una clave nueva solo para reintentar. |
| Un nombre, un campo de dirección o un documento no es válido | Muestra al preparador el error específico del campo, corrige los datos y obtén una nueva cotización y revisión antes de la presentación. |
| La API devuelve 402 insufficient_credits | Pide al titular de la cuenta que revise el saldo y añada créditos antes de reanudar el flujo de trabajo aprobado. |
| La API devuelve 409 o 429 | Investiga un conflicto de idempotencia en lugar de ir cambiando las claves. Si se trata de un límite de frecuencia, espera el intervalo Retry-After antes de reintentar. |
| El seguimiento está vacío o el pedido no ha avanzado | Conserva el pedido existente y comprueba su estado. La ausencia de un número de seguimiento no demuestra que no exista un pedido. Deriva a una persona los casos de ejecución del envío poco claros o fallidos. |
Compara el costo del flujo de trabajo completo
Una comparación de costos útil incluye el tiempo de gestión del personal, los suministros de impresión, el franqueo y el tiempo dedicado a corregir o rastrear un envío postal. Utiliza tu propio tiempo de gestión medido y tu estimación del costo laboral. Añade la cotización real de IRIS, más cualquier costo de mantenimiento de la integración, para comparar tareas equivalentes.
Por ejemplo, una hoja de cálculo puede registrar los minutos dedicados a preparar una carta manualmente y los minutos dedicados a revisar una preparada mediante API. Multiplica por el costo por hora que hayas elegido y compara los totales durante un período representativo. Identifica claramente las suposiciones. Evita prometer un porcentaje fijo de ahorro antes de que tu equipo haya medido su propio proceso.
Haz una prueba piloto con un tipo de documento
Elige un documento habitual, como esa confirmación de servicio en papel solicitada. Prueba la preparación y la gestión de errores localmente con datos de prueba antes de realizar un envío postal pagado y aprobado de forma deliberada. Un nombre de clave o un documento de prueba no convierte la presentación en producción en un entorno de pruebas.
Mantén la cola compartida, el historial de aprobaciones y las reglas de negocio en tu aplicación. Para cartas ocasionales, utiliza el sitio web de IRIS con la misma lista de comprobación para la revisión. ¿Vas a enviar correspondencia a una lista más amplia de forma programada? Cuéntanos el volumen y te responderemos con opciones.
Después de la prueba piloto, compara el tiempo de preparación, las correcciones de direcciones detectadas antes del pago y las excepciones que requieren seguimiento. Confirma que un colega pueda recuperarse de una respuesta perdida y encontrar el registro del pedido. Amplía el flujo de trabajo cuando esos pasos funcionen de manera fiable para tu equipo.
Fuentes y lecturas adicionales
- Documentación de la API de IRIS y límites actuales
- Contrato OpenAPI de IRIS
- PostScan Mail: API de correo entrante y escaneo
- Parcel Tracker: integraciones de aplicaciones de gestión de correspondencia
Publicado por IRIS Postal Forms, operado por Great Lakes Computing Office LLC. ¿Encontraste información desactualizada? Envía una corrección.