Lotes de patentes por API: aceptación parcial y reproceso seguro
Un lote mixto no debería ocultarse detrás de un único éxito o fracaso. Cada ítem necesita identidad, estado y evidencia para reintentar sólo lo rechazado.
Por Marco Ferreiro ·
Un archivo con mil patentes puede contener novecientas noventa filas válidas, cinco duplicadas y cinco mal formadas. Rechazar todo obliga a repetir trabajo correcto. Aceptar todo y guardar errores en un log impide saber qué se procesó.
La aceptación parcial funciona cuando cada patente tiene identidad, resultado y una ruta segura de reproceso. Sin esos tres elementos, “parcial” se convierte en incertidumbre.
Separar el sobre de los ítems
El lote tiene propiedades globales:
batchId;- empresa o tenant;
- versión de contrato;
- cantidad declarada;
- instante de creación;
- digest opcional del artefacto;
- formato.
Cada ítem tiene itemKey, tipo de consulta, el dominio normalizado y metadatos permitidos. La clave se elige en origen y permanece estable entre reintentos.
Si el JSON raíz no puede parsearse o la versión no existe, falla el sobre completo. Si el sobre es válido, la API evalúa cada fila por separado.
Identidad por ítem antes que número de fila
La posición no es una identidad durable. Al quitar una patente rechazada, todas las filas siguientes cambian de número. Usá una clave de negocio o un UUID generado por el cliente y único dentro de su ámbito.
El servidor almacena la combinación de tenant, operación e itemKey. Así, la misma patente enviada por otra empresa no colisiona y un reintento puede reconocer el efecto anterior.
La clave no debe incluir la patente en texto legible. Puede ser opaca y resolverse sólo en el sistema autorizado.
Estados por fila
Un manifiesto útil distingue:
accepted: validado y persistido;rejected: no produjo efecto y puede corregirse;duplicate: ya aceptado en un intento previo;pending: recibido, pero aún no terminó;failed: hubo un fallo operativo y la política de reintento está indicada.
No usamos success: false para todos. Cada estado tiene reglas sobre si se puede reenviar y qué evidencia conserva.
Un mensaje humano ayuda, pero el cliente decide con códigos estables y campos estructurados, no analizando texto.
El status HTTP describe el intercambio, no cada fila
RFC 9110 define la semántica de respuestas HTTP. En un lote mixto, el status representa el tratamiento del recurso o comando global según el contrato. No existe un código mágico que modele cada resultado interno.
Podemos responder un 2xx cuando el lote fue recibido y evaluado, acompañado por estado global partially_accepted. Si el procesamiento es asincrónico, una aceptación inicial no debe fingir que todas las patentes ya se consultaron.
OpenAPI documenta los posibles status, el esquema global y la enumeración por ítem. Los ejemplos incluyen lote completo, mixto y rechazado.
Manifiesto de errores
La respuesta incluye totales y un arreglo por ítem. Para rechazados guardamos:
itemKey;- código estable;
- puntero al campo;
- detalle corregible;
- posibilidad de reintento;
- correlación;
- versión de validación.
RFC 9457 ofrece application/problem+json para detalles de problemas, pero advierte que problemas heterogéneos no siempre encajan bien en una única respuesta genérica. Por eso el contrato del lote define explícitamente su colección de resultados y puede reutilizar conceptos de Problem Details por fila.
No exponemos trazas internas, SQL ni actas de otro tenant en detail.
Un lote sintético
Enviamos seis ítems:
- tres válidos;
- uno con dominio mal formado;
- uno repetido dentro del lote;
- uno cuya
itemKeyya fue aceptada ayer.
La API persiste los tres válidos, rechaza el formato, identifica el duplicado interno y reconoce el ítem previo sin repetir la consulta de esa patente. La respuesta totaliza tres aceptados, un rechazado y dos duplicados.
Después corregimos sólo el rechazado y lo reenviamos con la misma itemKey. Nace un nuevo intento; el historial conserva el error anterior y la aceptación actual.
Reproceso seguro
El cliente construye un lote de reparación que referencia parentBatchId. Incluye únicamente las patentes cuyo estado permite reintento.
El servidor aplica estas reglas:
- misma
itemKeyy mismo contenido ya aceptado: devuelve el resultado previo; - misma clave rechazada con contenido corregido: nuevo intento permitido;
- misma clave aceptada con contenido distinto: conflicto;
- clave desconocida: se trata según el endpoint documentado.
El conflicto no se resuelve sobrescribiendo. El cliente debe usar una operación de corrección explícita o una nueva identidad, según el dominio.
Cuándo persistir
La API no debe responder accepted antes de guardar de forma durable la decisión y la clave idempotente. Si confirma y cae antes de persistir, el reintento puede duplicar efectos.
En una transacción se almacenan identidad, estado y referencia de trabajo. La consulta a la jurisdicción puede ejecutarse después, pero entonces el estado inicial es pending, no un resultado final.
Los workers reclaman tareas con exclusión y actualizan por transición válida. Dos procesos no deben consultar la misma patente porque leyeron el mismo lote.
Integridad del archivo de entrada
Cuando el lote llega como archivo, tamaño y digest ayudan a confirmar que el contenido recibido coincide con el manifiesto. RFC 9530 define campos de digest para mensajes y representaciones HTTP.
El digest no sustituye la validación de filas. Un CSV íntegro puede contener dominios inválidos. Tampoco reemplaza la idempotencia: el mismo archivo puede enviarse dos veces.
Guardamos el hash sin registrar contenido sensible en logs.
Reconciliar al final
El cliente no considera terminado el lote hasta que cada patente llega a un estado terminal o queda explícitamente pendiente. Compara cantidad declarada, resultados y claves únicas.
Una exportación de conciliación incluye itemKey, último intento, estado, código y referencia, sin exponer titulares ni actas a equipos que no los necesitan.
Las métricas cuentan aceptados, rechazados, duplicados, tiempo de resolución y reintentos. No usan patentes como etiquetas.
Errores de seguridad y aislamiento
El manifiesto nunca revela si esa patente ya fue consultada por otro tenant. La comprobación se hace dentro del ámbito autenticado. Un conflicto devuelve una referencia propia, no el resultado ajeno.
Los límites se aplican por empresa y tamaño. Un lote de diez mil patentes no debe monopolizar workers ni permitir saltarse cuotas diseñadas para consultas individuales.
Los archivos rechazados se retienen sólo el tiempo necesario y con cifrado y acceso restringido.
Contrato verificable
La documentación debe responder antes de integrar:
- qué invalida todo el sobre;
- qué se acepta por fila;
- cuándo hay persistencia durable;
- qué status global se devuelve;
- cómo se consulta progreso;
- qué estados permiten reintento;
- cómo funciona la idempotencia;
- cuánto se retiene cada resultado.
Sin esas respuestas, el consumidor termina reenviando el lote completo “por las dudas”. Con identidad y manifiesto, puede corregir cinco filas sin volver a consultar las novecientas noventa y cinco patentes que ya tuvieron una decisión.
Metodología
- Alcance
- Prueba sintética de un lote con filas válidas, duplicadas e inválidas, seguida por un reproceso exclusivo de rechazos.
- Unidad de análisis
- Un ítem identificado de forma estable dentro de un lote y asociado a cada intento y resultado.
- Cobertura
- OpenAPI 3.1.1, HTTP, Problem Details y Digest Fields consultados el 14 de agosto de 2026.
Limitaciones
- HTTP no impone un único modelo de aceptación parcial; la semántica debe definirse en el contrato de dominio.
- La idempotencia evita efectos repetidos, pero no corrige datos válidos que fueron enviados con significado equivocado.
Fuentes
- OpenAPI Specification 3.1.1 — OpenAPI Initiative (consultada el )
- RFC 9110 — HTTP Semantics — RFC Editor (consultada el )
- RFC 9457 — Problem Details for HTTP APIs — RFC Editor (consultada el )
- RFC 9530 — Digest Fields — RFC Editor (consultada el )
Preguntas frecuentes
¿La API debe devolver 200 si algunas filas fallan?
El contrato debe documentar la semántica elegida. El status del sobre no alcanza; el cuerpo necesita resultado inequívoco por ítem y un estado global.
¿Se puede reenviar el lote completo después de corregir una fila?
Sólo si la idempotencia por ítem garantiza que los aceptados no repitan efectos. Es más claro reintentar exclusivamente los rechazados con sus mismas identidades.
¿RFC 9457 define un formato completo para cualquier lote mixto?
No. Define detalles de problemas y advierte sobre mezclar problemas heterogéneos. El contrato del lote debe especificar su manifiesto por ítem.
Notas relacionadas
Webhooks de nuevas multas: idempotencia, reintentos y trazabilidad
Un webhook confiable puede llegar más de una vez, demorarse o fallar después de ser procesado. El diseño debe deduplicar eventos, reintentar con límites y conservar evidencia de punta a punta.
Cursores estables para paginar resultados que pueden cambiar mientras se leen
Si una colección cambia entre la primera y la última página, el offset puede repetir u omitir resultados. Un cursor ligado a una revisión conserva un corte auditable.
Null, campo ausente o cero: tres respuestas distintas en un contrato de infracciones
Un monto cero es un número, null es un valor explícito y un campo ausente no fue enviado. Si el contrato los mezcla, un cliente puede informar que no hay deuda cuando sólo falta un dato.