workflows

API por lotes: cuándo HTTP 200 no confirma cada operación

El 200 global puede ocultar fallos individuales. Consulta el contrato, relaciona cada respuesta con su ID y decide qué acciones liberar.

Un HTTP 200 para un lote puede confirmar la solicitud global sin demostrar que cada operación interna se completó. Antes de actualizar el CRM, enviar un aviso o cerrar una tarea, consulta el contrato del proveedor y los resultados individuales cuando existan.

Respuesta breve

En los lotes JSON de Microsoft Graph, un 200 externo no prueba que todas las solicitudes internas hayan funcionado. Cada respuesta tiene su propio id y status, y el orden de las respuestas puede diferir del orden de envío. En cambio, spreadsheets.batchUpdate de Google Sheets aplica las solicitudes de forma atómica: una solicitud no válida hace fallar el lote entero. Sigue las reglas del endpoint concreto, relaciona los resultados por ID y libera el siguiente paso solo para resultados confirmados.

Ficha de liberación por elemento

Campo Qué anotar sin datos sensibles
ID enviado Clave para relacionar solicitud y resultado
Estado individual Correcto, error que exige corrección, candidato a reintento o incierto
Efecto confirmado Estado comprobado en la fuente de referencia cuando haga falta
Próxima acción Liberar, corregir, consultar el estado o repetir solo un elemento seguro
Responsable Persona que resuelve estados inciertos

Regla original de Pulse: si un elemento esencial carece de respuesta identificable o su efecto es incierto, el trabajo agregado queda pendiente de conciliación. El 200 global no elimina esa condición. No guardes credenciales ni cargas completas de clientes en la ficha.

Comprueba el lote antes de repetirlo

  1. Lee la semántica del endpoint. ¿Es atómico, admite éxito parcial o inicia un proceso asíncrono? Graph documenta éxito parcial y Sheets documenta un batchUpdate atómico. Este contraste es útil para equipos de España y de Hispanoamérica que integran Microsoft 365 o una API por lotes similar; no supone una regla nacional ni que todos los proveedores funcionen igual.
  2. Relaciona cada resultado con su ID. Graph advierte que las respuestas pueden llegar en otro orden. Comparar solo la posición de la lista puede asignar un fallo al registro equivocado. Utiliza el campo de correlación documentado.
  3. Separa los estados antes del reintento. Distingue éxitos confirmados, permisos insuficientes, límites de solicitudes y resultados desconocidos. Corrige el acceso antes de repetir un error de permiso. Para un límite, sigue la indicación del proveedor. Si el efecto es incierto, consulta el estado actual antes de reenviar.
  4. Decide qué continúa. Si el proceso necesita todos los elementos, detén el siguiente paso agregado. Si admite un resultado parcial, registra qué IDs avanzaron y cuáles siguen pendientes.

Ejemplo ilustrativo, sin integración probada

Un pequeño equipo comercial en España envía tres operaciones a Microsoft Graph, identificadas como A, B y C. El lote responde 200; A y C salen bien y B indica falta de permiso. El equipo no marca las tres como completadas. Registra A y C, corrige el permiso de B y evalúa solo B para un nuevo intento. Si el siguiente mensaje al cliente depende de las tres operaciones, espera. Los IDs y resultados son ficticios; Pulse no ejecutó este flujo.

Cuándo detenerse

Detén la automatización si no puedes relacionar solicitud y respuesta, si un tiempo de espera deja incierto el efecto sin consulta de estado, o si repetir puede duplicar un correo, cargo o registro. Define primero la fuente de referencia y una salida manual.

Esta guía trata el resultado del lote. Si faltan registros de origen, comprueba la paginación. Si un elemento recibió un límite, gestiona el 429. Si se repite una acción tras recibir el evento otra vez, controla duplicados.

Fuentes