Authorization: Bearer $RETAILGRID_API_KEY. Las escrituras requieren un UUID en Idempotency-Key. Reutilícelo con la misma solicitud si se pierde la respuesta. Cambiar el contenido con la misma clave, actor y operación devuelve 409.
Leer antes de decidir
ConsulteGET /v1/matching/matches para obtener match_id, version, review.revision y review.evidence. Estos valores protegen contra cambios simultáneos. No sustituya automáticamente los valores después de un conflicto.
Rechazar o actualizar revisiones
POST /v1/matching/matches:batch-decide acepta decisions, una lista de 1 a 500 identificadores únicos, con las acciones approve, reject, reopen o rematch.
review.status = rejected y el actor del propietario de la clave API. Deja de alimentar las cuadrículas en su próxima actualización. Para corregir la clasificación, apruebe con relation: "direct" o "substitute". Para sustituir un enlace, use rematch y replacement: {rg_item_id, competitor_product_id, relation}. Reabra una coincidencia rechazada antes de aprobarla o sustituirla.
Eliminar coincidencias
POST /v1/matching/matches:batch-remove requiere una versión positiva para cada uno de los 1 a 500 identificadores únicos:
200, external_org_id, request_id, results ordenados y changed_item_ids. Cada resultado contiene index, match_id, outcome, y opcionalmente result_match_id y code. Los resultados son decided, removed, already_removed o error. Los identificadores desconocidos y de otras organizaciones devuelven el mismo código resource_unavailable; las versiones o evidencias obsoletas, match_version_conflict. Los elementos válidos se procesan de forma independiente. Un reintento exacto reproduce todos los resultados originales, incluidos los errores. Una interrupción del servicio o de la base de datos revierte la transacción.
Los duplicados, versiones ausentes, solicitudes mal formadas o listas de más de 500 elementos devuelven 422 antes de escribir. Una clave API ausente o inválida devuelve 401; la ausencia de Idempotency-Key, 422. Tras corregir un conflicto intencionalmente, use una clave nueva.
Crear enlaces y buscar productos de competidores
GET /v1/matching/competitor-products admite query, competitor, availability y cursor. Siga next_cursor mientras has_more sea verdadero. Utilice el competitor_product_id devuelto; un SKU o URL no lo sustituye.
POST /v1/matching/matches:batch-add acepta de 1 a 500 pares únicos:
direct o substitute. Los resultados son created, restored o unchanged. La adición conserva el contrato atómico: un recurso no disponible o un conflicto de relación rechaza todo el lote. Para cambiar una relación existente, utilice una decisión de revisión.
