Feedback — acción del cliente y resultado

En producción · modo shadow

Después de una evaluación, su backend puede informar lo que ocurrió cuando su credencial activa tiene las capacidades requeridas. El feedback usa la ruta S2S autenticada de forma independiente y registra juntos un hecho, un comprobante inmutable y la auditoría. Nunca ejecuta una acción en su producto.

Ruta	Capacidad	Hecho
`POST /v1/assessments/{assessment_id}/customer-actions`	`action:write`	La acción que su producto ejecutó realmente
`POST /v1/assessments/{assessment_id}/outcomes`	`outcome:write`	Verdad/evidencia observada posteriormente, o una corrección del resultado actual

Son distintas de assessment:write: solicítelas con el permiso Avaliações, ações e resultados al crear la credencial de servidor en la consola, y confirme con FingerTrackID que están activas. Un contrato publicado o una credencial de evaluación, por sí solos, no habilitan el feedback.

Contratos públicos exactos

Conserve assessment.v1.yaml junto al OpenAPI de feedback por sus referencias compartidas. Las anotaciones históricas de implementación y el servidor de ejemplo no son configuraciones de runtime emitidas. Valide los esquemas cerrados y las reglas normativas de entrada sin procesar y entre campos; un JSON Schema por sí solo no rechaza claves duplicadas tras la decodificación, NUL ni todas las violaciones de número sin pérdida.

Firmar la llamada de feedback

Use el mismo firmador de referencia. La ruta canónica incluye el assessment_id exacto de la evaluación síncrona original, sin cadena de consulta ni barra final. La sexta línea firmada es assessment_id:<id> y X-FTID-Assessment-Id debe coincidir con la ruta. No envíe en su lugar el encabezado de evento externo de la ruta de evaluación.

secret proviene solo del gestor de secretos de su backend. Los cuerpos de solicitud tienen como máximo 16384 bytes; las respuestas, como máximo 65536 bytes. Mantenga los bytes originales exactos y la clave de idempotencia en todos los reintentos, y cree un ID de solicitud UUIDv7, una marca de tiempo y una firma nuevos en cada intento.

// Validate once, then preserve these exact bytes for the logical feedback operation.
const body = Buffer.from(JSON.stringify(customerActionRequest), 'utf8')
const path = `/v1/assessments/${assessmentId}/customer-actions`
// Each transport attempt receives a new request ID, timestamp and signature.
const attempt = prepareAttempt({ secret, keyId, path, body })
const result = await postAttempt(apiOrigin, attempt, 2000)
// Validate the exact receipt or feedback Problem before accepting the result.

Acción del cliente (`customer-action.v1`)

Los siete campos son obligatorios: schema_version, external_action_id, idempotency_key, action, basis, occurred_at y reason_code.

Acciones: ALLOWED, CHALLENGED, HELD, REVIEWED, BLOCKED, CANCELLED.
Base: ASSESSMENT, CLIENT_POLICY, FALLBACK, MANUAL_REVIEW.
El motivo debe corresponder a su base según el esquema. ASSESSMENT requiere FOLLOWED_FTID_RECOMMENDATION y una acción alineada con la recomendación almacenada.
occurred_at es el momento real de la acción en su backend, no una marca de tiempo elegida por el navegador. No puede ser anterior al evento original ni superar la ventana futura permitida por el servidor.

FingerTrackID deriva recommendation_alignment; nunca lo incluya en la solicitud. CANCELLED es NOT_COMPARABLE. Coincidir con una recomendación no prueba causalidad ni fraude. El comprobante confirma la acción registrada, no un bloqueo recién ejecutado.

Cuerpo de la solicitud
SDK de servidor

{
  "schema_version": "customer-action.v1",
  "external_action_id": "action:synthetic-001",
  "idempotency_key": "synthetic-action-001",
  "action": "ALLOWED",
  "basis": "ASSESSMENT",
  "occurred_at": "2026-09-05T12:00:00.123456789+03:00",
  "reason_code": "FOLLOWED_FTID_RECOMMENDATION"
}

await ftid?.recordCustomerAction(assessmentId, {
  action: 'ALLOWED',
  basis: 'CLIENT_POLICY',
  reasonCode: 'CLIENT_POLICY_RULE',
})

El cuerpo de la solicitud es un vector de canonicalización publicado.

Resultado (`customer-outcome.v1`)

Todos los campos, incluidos los que admiten nulo, son obligatorios: schema_version, external_outcome_id, idempotency_key, truth_status, label_maturity, fraud_type, evidence_source, evidence_reference, evidence_confidence, observed_at, reason_code y corrects_external_outcome_id.

La verdad es PENDING, INSUFFICIENT_EVIDENCE, LEGITIMATE o FRAUD_CONFIRMED. La madurez es PROVISIONAL o MATURE; PENDING debe seguir siendo provisional. Una verdad concluyente requiere la tríada de evidencia completa, y FRAUD_CONFIRMED requiere además la entrada activa del catálogo de tipos de fraude. Nunca ponga PII ni material secreto en una referencia de evidencia.

La observación inicial lleva INITIAL_OBSERVATION y un predecesor nulo. Una corrección debe referenciar el external_outcome_id de la hoja actual, usar un ID de resultado nuevo y el motivo que corresponda al cambio real. Un predecesor desactualizado, un sucesor en competencia o una segunda raíz es un conflicto. Las correcciones añaden hechos; no sobrescriben el registro original ni la recomendación. La madurez o la evidencia enviadas no hacen, por sí mismas, que el rótulo sea apto para la calibración de detectores. Los resultados de fraude confirmado también alimentan el ítem de la consola Contas vizinhas com fraude confirmada pela empresa (cuentas vecinas con fraude confirmado por su empresa) en Contexto do acesso; sin resultados, muestra Sem dado: a empresa não envia resultados.

Cuerpo de la solicitud
SDK de servidor

{
  "schema_version": "customer-outcome.v1",
  "external_outcome_id": "outcome:synthetic-001",
  "idempotency_key": "synthetic-outcome-001",
  "truth_status": "PENDING",
  "label_maturity": "PROVISIONAL",
  "fraud_type": null,
  "evidence_source": null,
  "evidence_reference": null,
  "evidence_confidence": null,
  "observed_at": "2026-09-05T12:00Z",
  "reason_code": "INITIAL_OBSERVATION",
  "corrects_external_outcome_id": null
}

await ftid?.recordOutcome(assessmentId, {
  truthStatus: 'PENDING',
  labelMaturity: 'PROVISIONAL',
  reasonCode: 'INITIAL_OBSERVATION',
})

Comprobantes, reintento y resultados no disponibles

201 confirma un hecho nuevo registrado; 200 confirma el mismo hecho lógico sin un segundo efecto. Una reutilización divergente devuelve 409. Un tiempo de espera agotado o una confirmación perdida es indeterminado: concilie con el mismo POST y el mismo cuerpo en un intento firmado nuevo, sujeto al campo retryable del Problem efectivamente recibido y a un backoff acotado. 429/503 usan Retry-After.

El catálogo de Problems de feedback pertenece al OpenAPI de feedback; no suponga que todo Problem de evaluación es una respuesta de feedback. La ausencia del destino y un destino fuera del ámbito autenticado comparten 404. No se ofrece consulta de comprobantes sin autenticación ni GET de evaluación.