Import Sync

Comprobar si un lote importado ya está disponible para segmentar

Endpoint servicio-a-servicio consumido por el reconciliador de importaciones de nev-api. No acepta JWT de usuario.

Demuestra, usuario a usuario y campo a campo, que los datos aceptados por una importación han llegado al mart que lee la segmentación. Un recuento de filas o una ventana temporal no lo demuestran: los satisface igualmente un dato que nunca cambió.

Para cada entrada se compara la huella que nev-api calcula desde el documento ACTUAL de origen con la que BigQuery calcula desde la fila del mart, usando la misma codificación canónica (n: si el valor es nulo o ausente, s: + el valor en caso contrario; SHA-256 sobre bytes UTF-8 en hexadecimal minúscula).

Lo que se demuestra en campos personalizados es la proyección que el consumidor lee: property_name, data_type y typed_value no nulos, y la huella de typed_value igual a la esperada. raw_value no es prueba: coincide en casos que el selector no puede mostrar (un valor LIST cuya extracción escalar deja typed_value nulo), y darlo por bueno certificaba campos que la segmentación no puede usar.

Contrato opcional v2 (contractVersion: 2): prueba histórica de un candidato fijo, identificado por candidateRevision. Exige versión exacta y la misma imagen en users/user_tenants, valores tipados y marcadores de campos personalizados, y presencia o ausencia de cada etiqueta del ámbito por fila. No certifica escrituras futuras. Una imagen posterior devuelve candidate_superseded, nunca READY automático. La respuesta devuelve proofs para TODOS los candidatos y su revisión recibida. Finalizar requiere lote vacío, bumpCatalogVersionOnReady: true y finalizationId estable por job/época; un replay reutiliza el recibo de catálogo transaccional.

Reglas que no admiten atajo:

  • Una edición posterior no exime la prueba: nev-api recalcula la expectativa, así que la edición cambia lo que hay que demostrar.
  • Un valor marcado como ambiguo por la vista resuelta queda pendiente aunque coincida.
  • Un valor presente pero inutilizable (metadatos o typed_value nulos) queda pendiente con field:cf:<id>:unusable; nunca READY.
  • La ausencia también es una expectativa: si el origen no tiene valor (huella de n:) y el mart no tiene fila, está consumido. Si el mart conserva un valor que el origen ya borró, queda pendiente con field:cf:<id>:stale.
  • Un borrado de usuario sí es terminal: si el mart marca el usuario como borrado no queda nada que demostrar sobre sus campos.

El lote está listo cuando pending es 0. missing devuelve una entrada por cada prueba fallida, de modo que un mismo usuario puede aparecer varias veces.

post/import-sync/readiness

Request

  • Base URL: http://localhost:8081
  • URL: http://localhost:8081/import-sync/readiness
  • Auth: HTTP bearer

Headers

x-service'nev-api' required

Identifica qué servicio interno llama

x-tenant-idstring required

Tenant sobre el que se comprueba (nunca se lee del body)

Request body

contractVersion2

Opcional; su ausencia conserva el contrato legacy.

finalizationIdstring

Identidad estable job/época para finalizar v2 de forma idempotente.

jobIdstring required

Job de importación al que pertenece el lote. Obligatorio y no vacío: junto con chunkIndex es lo que permite rastrear la respuesta hasta su lote en Cloud Logging. Se rechaza con 400 si falta o no es una cadena con contenido.

chunkIndexinteger required

Índice del lote dentro del manifiesto. Obligatorio, entero y no negativo (0 es el primer lote). Se rechaza con 400 en cualquier otro caso.

importLabelIdstring nullable

Etiqueta aplicada por la importación; si viene, se exige pertenencia

bumpCatalogVersionOnReadyboolean

Incrementa la versión de catálogo del tenant si el lote está listo. La invalidación es un paso de job completo, no de lote: llega una sola vez, con entries vacío, cuando todos los lotes están READY.

Example request

{
  "jobId": "68a1b2c3d4e5f60718293a4b",
  "importLabelId": "68b2c3d4e5f60718293a4b5c",
  "entries": [
    {
      "userId": "68388013e2226d79536e4ae2",
      "sourceVersion": 1789034400000,
      "fields": {
        "std:email": "4d7ef18d30405721f3e8abef5d9b4c027327b3db72aea730ff57f2f9e3db1ab9",
        "cf:68c1d2e3f40718293a4b5c6d": "5e5d3600c93ced8f8898c77693ce725b10015d89c1b57c6df8bb386dd06707bb"
      }
    }
  ]
}

Response

Comprobación realizada

successboolean
timestampstring date-time

Example response

{
  "success": true,
  "data": {
    "consumed": 998,
    "pending": 2,
    "missing": [
      {
        "userId": "68388013e2226d79536e4ae2",
        "reason": "field:cf:68c1d2e3f40718293a4b5c6d"
      }
    ],
    "source": "legacy"
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.