Completar un briefing de integración con un informe

Describa una integración mediante un flujo completo antes de comparar ofertas. «El portal necesita una conexión API» deja sin definir qué datos se transfieren, cuándo termina el trabajo y quién gestiona un fallo. Un briefing completo permite debatir esas decisiones.

Definir un flujo para la primera entrega

En este proyecto ficticio, un portal solicita un informe PDF mensual a un servicio documental. Todos los nombres, campos y respuestas son ejemplos propios, no la API de un proveedor.

Así también se ven las peticiones adicionales: una futura función de correo sería un paso aparte con su propia gestión de errores. No queda oculta dentro de la palabra «conexión».

Indicar los valores y el significado de las entradas

Se acuerda este contenido de ejemplo para POST /report-jobs:

{"requestId":"R-52","projectId":"P-18","templateId":"monthly-v2","period":"2026-10"}

El identificador de solicitud representa esta petición de creación. Proyecto y plantilla son referencias estables; el periodo es aquí un mes natural en formato año–mes. Los nombres visibles o un periodo en texto libre no sustituyen esos valores. El portal debe acordar con el servicio documental qué plantillas están aprobadas.

El acceso al trabajo, al estado y al archivo se limita al proyecto autorizado. Conocer un enlace no permite por sí solo descargar. El briefing especifica roles y método de acceso; los tokens y contraseñas reales quedan fuera del documento.

Describir por separado la aceptación y el resultado

Tras registrar la solicitud de forma duradera, el servicio de ejemplo responde con HTTP 202 y Location: /report-jobs/J-52:

{"jobId":"J-52","status":"queued"}

MDN describe 202 como la aceptación de un procesamiento aún no completado. Nuestro contrato incluye por ello los estados queued (en cola), running (en curso), succeeded (completado correctamente) y failed (fallido). El trabajo solo tiene éxito cuando el archivo está creado y, al completarse, puede recuperarse con autorización. Microsoft describe una consulta de estado separada para el trabajo asíncrono; los nombres concretos de estos estados son una decisión nuestra.

El mismo identificador de solicitud con contenido idéntico y dentro del mismo ámbito autorizado remite al mismo trabajo. Para un contenido distinto, el ejemplo acuerda HTTP 409. Esta regla de repetición debe implementarse y comprobarse; el nombre del campo no crea idempotencia.

Completar cuatro casos de aceptación antes de implementar

En el último caso, el equipo de plataforma revisa la plantilla. Una nueva solicitud corregida recibe otro identificador; el trabajo fallido sigue siendo trazable. Si solo falla la consulta de estado, el portal indica que se desconoce el estado actual, sin afirmar éxito ni fallo.

Resolver las preguntas operativas antes de comprometerse

Complete el volumen esperado de trabajos, el tamaño habitual de archivo, la espera admisible, el intervalo de consulta y la conservación de archivos y estados según el uso real. Estos valores quedan abiertos en el ejemplo y deben aclararse antes de un compromiso fiable. Una duración estimada no se adopta como una propiedad medida.

Una descripción OpenAPI puede precisar operaciones, entradas y respuestas esperadas. También deben establecerse la definición de negocio del resultado y las responsabilidades de los equipos. Con los casos completados, los equipos de portal y plataforma pueden evaluar la misma entrega.

Fuentes

• MDN: 202 Accepted

• Microsoft: Asynchronous Request-Reply pattern

• OpenAPI Specification 3.1.1: Operation and Responses