{ "components": { "headers": { "X-Face-Auth-Event-Id": { "description": "ID unico do evento entregue.", "schema": { "type": "string" } }, "X-Face-Auth-Event-Type": { "description": "Tipo do evento entregue.", "schema": { "enum": [ "transaction.created", "terms_accepted", "location_captured", "handoff_created", "handoff_opened", "handoff_completed", "handoff_expired", "liveness_session_created", "liveness_passed", "liveness_failed", "document_uploaded", "document_passed", "document_failed", "manual_review_required", "approved", "rejected", "expired" ], "type": "string" } }, "X-Face-Auth-Signature": { "description": "Assinatura HMAC SHA-256 no formato sha256= sobre timestamp + '.' + body bruto em bytes, antes de parsear JSON.", "schema": { "pattern": "^sha256=[a-f0-9]{64}$", "type": "string" } }, "X-Face-Auth-Timestamp": { "description": "Unix timestamp usado na assinatura.", "schema": { "type": "string" } } }, "parameters": { "IdempotencyKeyHeader": { "description": "Chave opcional para repetir o mesmo POST sem duplicar a transacao.", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 180, "minLength": 1, "type": "string" } }, "WebhookEventIdHeader": { "description": "ID unico do evento entregue.", "in": "header", "name": "X-Face-Auth-Event-Id", "required": true, "schema": { "type": "string" } }, "WebhookEventTypeHeader": { "description": "Tipo do evento entregue.", "in": "header", "name": "X-Face-Auth-Event-Type", "required": true, "schema": { "enum": [ "transaction.created", "terms_accepted", "location_captured", "handoff_created", "handoff_opened", "handoff_completed", "handoff_expired", "liveness_session_created", "liveness_passed", "liveness_failed", "document_uploaded", "document_passed", "document_failed", "manual_review_required", "approved", "rejected", "expired" ], "type": "string" } }, "WebhookSignatureHeader": { "description": "Assinatura HMAC SHA-256 no formato sha256= sobre timestamp + '.' + body bruto em bytes, antes de parsear JSON.", "in": "header", "name": "X-Face-Auth-Signature", "required": true, "schema": { "pattern": "^sha256=[a-f0-9]{64}$", "type": "string" } }, "WebhookTimestampHeader": { "description": "Unix timestamp usado na assinatura.", "in": "header", "name": "X-Face-Auth-Timestamp", "required": true, "schema": { "type": "string" } } }, "responses": { "ForbiddenExternalAccess": { "content": { "application/json": { "examples": { "api_key_scope_not_allowed": { "value": { "detail": { "code": "api_key_scope_not_allowed", "message": "api key is not allowed for scope document_download" } } }, "tenant_ip_not_authorized": { "value": { "detail": { "code": "tenant_ip_not_authorized", "message": "client IP is not authorized for this tenant environment" } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "API key sem permissao ou IP fora da allowlist do escopo." }, "IdempotencyConflict": { "content": { "application/json": { "examples": { "idempotency_conflict": { "value": { "detail": { "code": "idempotency_conflict", "message": "Idempotency-Key was already used with a different payload" } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Mesma Idempotency-Key usada com payload diferente." }, "InvalidApiKey": { "content": { "application/json": { "examples": { "invalid_api_key": { "value": { "detail": { "code": "invalid_api_key", "message": "invalid api key" } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "X-API-Key ausente, invalida, revogada ou fora do ambiente." }, "TenantEnvironmentDisabled": { "content": { "application/json": { "examples": { "tenant_environment_disabled": { "value": { "detail": { "code": "tenant_environment_disabled", "message": "tenant environment is disabled" } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Tenant ou ambiente pausado/desabilitado." }, "TransactionNotFound": { "content": { "application/json": { "examples": { "transaction_not_found": { "value": { "detail": { "code": "transaction_not_found", "message": "transaction not found" } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Transacao inexistente ou fora do tenant/ambiente da key." }, "ValidationError": { "content": { "application/json": { "examples": { "validation_error": { "value": { "detail": { "code": "validation_error", "message": "request validation failed" } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Payload invalido ou regra de negocio violada." } }, "schemas": { "BiometricAsset": { "properties": { "asset_id": { "type": "string" }, "asset_kind": { "enum": [ "liveness_reference", "document_front", "document_back", "document_full" ], "type": "string" }, "content_type": { "nullable": true, "type": "string" }, "created_at": { "format": "date-time", "type": "string" }, "download_url": { "description": "Use /v1/face-auth/transactions/{transaction_id}/assets/{asset_id}/content.", "type": "string" }, "size_bytes": { "nullable": true, "type": "integer" }, "tenant_id": { "type": "string" }, "transaction_id": { "nullable": true, "type": "string" } }, "required": [ "asset_id", "tenant_id", "transaction_id", "asset_kind", "content_type", "created_at" ], "type": "object" }, "BlacklistSearchAttemptSummary": { "properties": { "best_similarity": { "nullable": true, "type": "number" }, "blacklist_search_attempt_id": { "type": "string" }, "created_at": { "format": "date-time", "type": "string" }, "environment": { "enum": [ "hml", "prod" ], "type": "string" }, "kind": { "enum": [ "identity", "face" ], "type": "string" }, "status": { "enum": [ "skipped", "no_match", "matched", "failed" ], "type": "string" }, "tenant_id": { "type": "string" }, "threshold": { "nullable": true, "type": "number" }, "transaction_id": { "type": "string" } }, "required": [ "blacklist_search_attempt_id", "tenant_id", "transaction_id", "environment", "kind", "status", "created_at" ], "type": "object" }, "DocumentExtractionSummary": { "description": "Resumo operacional tenant-safe da extracao documental, sem OCR bruto, provider, payloads ou identificadores forenses.", "properties": { "created_at": { "format": "date-time", "type": "string" }, "declared_document_type": { "nullable": true, "type": "string" }, "detected_document_type": { "nullable": true, "type": "string" }, "document_capture_id": { "type": "string" }, "document_expiration_status": { "nullable": true, "type": "string" }, "document_expires_at": { "format": "date-time", "nullable": true, "type": "string" }, "document_side": { "enum": [ "front", "back", "combined" ], "nullable": true, "type": "string" }, "document_type_confidence": { "nullable": true, "type": "number" }, "document_type_evidence_status": { "nullable": true, "type": "string" }, "environment": { "enum": [ "hml", "prod" ], "type": "string" }, "tenant_id": { "type": "string" }, "transaction_id": { "type": "string" } }, "required": [ "document_capture_id", "transaction_id", "tenant_id", "environment", "created_at" ], "type": "object" }, "DocumentRequirement": { "properties": { "reason": { "type": "string" }, "required": { "type": "boolean" }, "trusted_document_id": { "nullable": true, "type": "string" }, "trusted_identity_backing_id": { "nullable": true, "type": "string" }, "valid_until": { "format": "date-time", "nullable": true, "type": "string" } }, "type": "object" }, "ErrorDetail": { "properties": { "code": { "enum": [ "validation_error", "invalid_api_key", "tenant_environment_disabled", "transaction_not_found", "idempotency_conflict", "tenant_ip_not_authorized", "api_key_scope_not_allowed", "evidence_access_restricted" ], "type": "string" }, "errors": { "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "ErrorResponse": { "properties": { "detail": { "$ref": "#/components/schemas/ErrorDetail" } }, "required": [ "detail" ], "type": "object" }, "ManualReviewSummary": { "properties": { "case_id": { "type": "string" }, "created_at": { "format": "date-time", "type": "string" }, "decided_at": { "format": "date-time", "nullable": true, "type": "string" }, "decision": { "enum": [ "pending", "approved", "rejected" ], "type": "string" }, "decision_reason": { "nullable": true, "type": "string" }, "reason": { "type": "string" }, "status": { "enum": [ "pending", "approved", "rejected", "expired" ], "type": "string" }, "updated_at": { "format": "date-time", "type": "string" } }, "required": [ "case_id", "status", "reason", "decision", "created_at", "updated_at" ], "type": "object" }, "Subject": { "properties": { "email": { "maxLength": 254, "nullable": true, "type": "string" }, "identity": { "$ref": "#/components/schemas/SubjectIdentity" }, "name": { "maxLength": 160, "nullable": true, "type": "string" }, "phone": { "maxLength": 40, "nullable": true, "type": "string" }, "tenant_subject_id": { "description": "ID persistente do cliente dentro do tenant.", "maxLength": 128, "nullable": true, "type": "string" } }, "required": [ "identity" ], "type": "object" }, "SubjectIdentity": { "properties": { "country": { "enum": [ "AR", "BO", "BR", "CL", "CO", "CR", "CU", "DO", "EC", "SV", "GT", "HT", "HN", "MX", "NI", "PA", "PE", "PY", "UY", "US", "VE" ], "type": "string" }, "number": { "maxLength": 80, "minLength": 1, "type": "string" }, "type": { "example": "CPF", "maxLength": 40, "minLength": 1, "type": "string" } }, "required": [ "type", "number", "country" ], "type": "object" }, "TenantTransactionConfigurationSnapshot": { "properties": { "captured_at": { "format": "date-time", "type": "string" }, "default_transaction_ttl_minutes": { "type": "integer" }, "docmatch_threshold": { "type": "number" }, "document_capture_max_attempts": { "type": "integer" }, "document_expiration_policy": { "enum": [ "reject_expired", "allow_expired" ], "type": "string" }, "environment": { "enum": [ "hml", "prod" ], "type": "string" }, "liveness_max_attempts": { "type": "integer" }, "liveness_threshold": { "type": "number" }, "location_capture_mode": { "enum": [ "disabled", "optional", "required" ], "type": "string" }, "manual_review_ttl_hours": { "type": "integer" }, "snapshot_quality": { "type": "string" } }, "type": "object" }, "TenantTransactionLinks": { "properties": { "short_url": { "format": "uri", "nullable": true, "type": "string" }, "webview_url": { "format": "uri", "nullable": true, "type": "string" } }, "type": "object" }, "TenantTransactionResponse": { "description": "Resposta tenant-safe da transacao para integracao diaria.", "properties": { "accepted_evidence_documents": { "items": { "type": "string" }, "type": "array" }, "canonical_url": { "format": "uri", "nullable": true, "type": "string" }, "configuration_snapshot": { "oneOf": [ { "$ref": "#/components/schemas/TenantTransactionConfigurationSnapshot" }, { "type": "null" } ] }, "country_code": { "enum": [ "AR", "BO", "BR", "CL", "CO", "CR", "CU", "DO", "EC", "SV", "GT", "HT", "HN", "MX", "NI", "PA", "PE", "PY", "UY", "US", "VE" ], "type": "string" }, "created_at": { "format": "date-time", "type": "string" }, "created_by": { "nullable": true, "type": "string" }, "created_by_type": { "enum": [ "api_key", "tenant_user", "internal_admin", "system" ], "type": "string" }, "current_step": { "enum": [ "terms", "liveness", "document", "done" ], "type": "string" }, "decision": { "enum": [ "pending", "approved", "rejected" ], "type": "string" }, "decision_reason": { "nullable": true, "type": "string" }, "document_required": { "type": "boolean" }, "document_requirement": { "$ref": "#/components/schemas/DocumentRequirement" }, "environment": { "enum": [ "hml", "prod" ], "type": "string" }, "expires_at": { "format": "date-time", "type": "string" }, "external_id": { "nullable": true, "type": "string" }, "links": { "$ref": "#/components/schemas/TenantTransactionLinks" }, "locale": { "enum": [ "pt-BR", "es", "es-AR", "es-BO", "es-CL", "es-CO", "es-CR", "es-CU", "es-DO", "es-EC", "es-SV", "es-GT", "es-HN", "es-MX", "es-NI", "es-PA", "es-PE", "es-PY", "es-UY", "es-VE", "fr-HT", "en-US" ], "type": "string" }, "location_captured_at": { "format": "date-time", "nullable": true, "type": "string" }, "manual_review": { "description": "Resumo tenant-safe quando a transacao foi enviada para mesa manual.", "oneOf": [ { "$ref": "#/components/schemas/ManualReviewSummary" }, { "type": "null" } ] }, "metadata": { "additionalProperties": true, "type": "object" }, "origin": { "enum": [ "api", "tenant_portal", "internal_admin" ], "type": "string" }, "result": { "$ref": "#/components/schemas/TenantTransactionResult" }, "short_code": { "nullable": true, "type": "string" }, "short_url": { "format": "uri", "nullable": true, "type": "string" }, "source": { "$ref": "#/components/schemas/TransactionSource" }, "status": { "enum": [ "created", "terms_accepted", "liveness_pending", "liveness_passed", "document_pending", "document_passed", "manual_review_pending", "approved", "rejected", "expired" ], "type": "string" }, "subject": { "$ref": "#/components/schemas/TenantTransactionSubject" }, "tenant_id": { "description": "Tenant resolvido pela API key.", "type": "string" }, "tenant_subject_id": { "nullable": true, "type": "string" }, "terms_accepted_at": { "format": "date-time", "nullable": true, "type": "string" }, "terms_version": { "type": "string" }, "transaction_id": { "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "webhook_delivery": { "$ref": "#/components/schemas/TenantWebhookDeliveryStatus" }, "webhook_events": { "items": { "$ref": "#/components/schemas/TenantWebhookEvent" }, "type": "array" }, "webview_url": { "format": "uri", "nullable": true, "type": "string" } }, "required": [ "transaction_id", "tenant_id", "environment", "country_code", "locale", "origin", "source", "subject", "links", "status", "current_step", "decision", "terms_version", "metadata", "document_required", "document_requirement", "accepted_evidence_documents", "created_at", "updated_at", "expires_at", "result", "webhook_delivery", "webhook_events" ], "type": "object" }, "TenantTransactionResult": { "properties": { "document_expiration_status": { "enum": [ "unknown", "not_extracted", "valid", "expired" ], "nullable": true, "type": "string" }, "document_match_similarity": { "nullable": true, "type": "number" }, "document_match_status": { "type": "string" }, "evidence_document_type": { "nullable": true, "type": "string" }, "liveness_score": { "nullable": true, "type": "number" }, "liveness_status": { "type": "string" }, "trusted_identity_backing_created": { "type": "boolean" } }, "type": "object" }, "TenantTransactionSubject": { "properties": { "email": { "nullable": true, "type": "string" }, "identity": { "oneOf": [ { "$ref": "#/components/schemas/SubjectIdentity" }, { "type": "null" } ] }, "name": { "nullable": true, "type": "string" }, "phone": { "nullable": true, "type": "string" }, "tenant_subject_id": { "nullable": true, "type": "string" } }, "type": "object" }, "TenantWebhookDeliveryStatus": { "properties": { "attempts": { "type": "integer" }, "last_error": { "nullable": true, "type": "string" }, "last_event_id": { "nullable": true, "type": "string" }, "last_event_type": { "nullable": true, "type": "string" }, "status": { "type": "string" }, "updated_at": { "format": "date-time", "nullable": true, "type": "string" } }, "type": "object" }, "TenantWebhookEvent": { "properties": { "attempts": { "type": "integer" }, "callback_configured": { "type": "boolean" }, "created_at": { "format": "date-time", "type": "string" }, "delivered_at": { "format": "date-time", "nullable": true, "type": "string" }, "event_id": { "type": "string" }, "event_type": { "enum": [ "transaction.created", "terms_accepted", "location_captured", "handoff_created", "handoff_opened", "handoff_completed", "handoff_expired", "liveness_session_created", "liveness_passed", "liveness_failed", "document_uploaded", "document_passed", "document_failed", "manual_review_required", "approved", "rejected", "expired" ], "type": "string" }, "failed_at": { "format": "date-time", "nullable": true, "type": "string" }, "last_error": { "nullable": true, "type": "string" }, "last_http_status": { "nullable": true, "type": "integer" }, "max_attempts": { "type": "integer" }, "published_at": { "format": "date-time", "nullable": true, "type": "string" }, "status": { "enum": [ "pending", "queued", "delivering", "delivered", "retry_pending", "failed", "skipped_no_callback" ], "type": "string" }, "transaction_id": { "type": "string" }, "updated_at": { "format": "date-time", "type": "string" } }, "type": "object" }, "TransactionAssetsResponse": { "properties": { "assets": { "items": { "$ref": "#/components/schemas/BiometricAsset" }, "type": "array" }, "blacklist_search_attempts": { "items": { "$ref": "#/components/schemas/BlacklistSearchAttemptSummary" }, "type": "array" }, "document_captures": { "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, "document_extractions": { "items": { "$ref": "#/components/schemas/DocumentExtractionSummary" }, "type": "array" }, "face_search_attempts": { "items": { "type": "object" }, "type": "array" }, "liveness_sessions": { "items": { "type": "object" }, "type": "array" }, "location_capture_events": { "items": { "type": "object" }, "type": "array" } }, "required": [ "assets", "document_captures" ], "type": "object" }, "TransactionCreate": { "properties": { "callback_url": { "description": "Webhook especifico da transacao. Se ausente, usa o webhook configurado no tenant.", "format": "uri", "nullable": true, "type": "string" }, "country_code": { "default": "BR", "enum": [ "AR", "BO", "BR", "CL", "CO", "CR", "CU", "DO", "EC", "SV", "GT", "HT", "HN", "MX", "NI", "PA", "PE", "PY", "UY", "US", "VE" ], "type": "string" }, "expires_in_minutes": { "description": "TTL customizado; ausente usa o padrao do tenant.", "maximum": 129600, "minimum": 5, "nullable": true, "type": "integer" }, "external_id": { "description": "ID do processo no sistema do tenant.", "maxLength": 128, "type": "string" }, "locale": { "enum": [ "pt-BR", "es", "es-AR", "es-BO", "es-CL", "es-CO", "es-CR", "es-CU", "es-DO", "es-EC", "es-SV", "es-GT", "es-HN", "es-MX", "es-NI", "es-PA", "es-PE", "es-PY", "es-UY", "es-VE", "fr-HT", "en-US" ], "nullable": true, "type": "string" }, "metadata": { "additionalProperties": true, "default": {}, "description": "JSON livre tenant-safe, maximo 8KB.", "type": "object" }, "source": { "$ref": "#/components/schemas/TransactionSource" }, "subject": { "$ref": "#/components/schemas/Subject" } }, "required": [ "country_code", "subject" ], "type": "object" }, "TransactionSource": { "properties": { "channel": { "maxLength": 80, "nullable": true, "type": "string" }, "integration": { "maxLength": 120, "nullable": true, "type": "string" }, "system": { "maxLength": 80, "nullable": true, "type": "string" } }, "type": "object" }, "WebhookPayload": { "description": "Payload enviado ao callback_url da transacao ou webhook do tenant. Validar usando X-Face-Auth-Timestamp e X-Face-Auth-Signature.", "properties": { "api_version": { "const": "v1", "type": "string" }, "created_at": { "format": "date-time", "type": "string" }, "event_id": { "type": "string" }, "event_type": { "enum": [ "transaction.created", "terms_accepted", "location_captured", "handoff_created", "handoff_opened", "handoff_completed", "handoff_expired", "liveness_session_created", "liveness_passed", "liveness_failed", "document_uploaded", "document_passed", "document_failed", "manual_review_required", "approved", "rejected", "expired" ], "type": "string" }, "transaction": { "$ref": "#/components/schemas/TenantTransactionResponse" } }, "required": [ "api_version", "event_id", "event_type", "created_at", "transaction" ], "type": "object" } }, "securitySchemes": { "ApiKeyAuth": { "description": "API key do tenant, escopada por ambiente. Exemplos: fa_hml_... ou fa_prod_...", "in": "header", "name": "X-API-Key", "type": "apiKey" } } }, "info": { "description": "Contrato publico para tenants criarem transacoes de Face Auth, consultarem o status e validarem webhooks assinados. Expoe somente o contrato externo tenant-safe.", "title": "Face Auth Tenant API", "version": "1.0.0" }, "openapi": "3.1.0", "paths": { "/v1/face-auth/transactions": { "post": { "description": "Cria uma transacao no tenant e ambiente resolvidos pela API key. Envie somente os campos documentados nesta especificacao. Use Idempotency-Key para repetir a mesma criacao sem duplicar a transacao.", "operationId": "createFaceAuthTransaction", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKeyHeader" } ], "requestBody": { "content": { "application/json": { "examples": { "complete": { "summary": "Payload completo", "value": { "callback_url": "https://customer.example.invalid/webhooks/kyc", "country_code": "BR", "expires_in_minutes": 10080, "external_id": "docs-example-0001", "locale": "pt-BR", "metadata": { "branch": "SAO-01", "order_id": "pedido-123" }, "source": { "channel": "callcenter", "integration": "onboarding-digital", "system": "CRM" }, "subject": { "email": "person@example.invalid", "identity": { "country": "BR", "number": "00000000000", "type": "CPF" }, "name": "Pessoa de exemplo / Example person", "phone": "+5500000000000", "tenant_subject_id": "subject_docs_example" } } }, "minimal": { "summary": "Payload minimo", "value": { "country_code": "BR", "external_id": "docs-example-0001", "locale": "pt-BR", "subject": { "identity": { "country": "BR", "number": "00000000000", "type": "CPF" } } } } }, "schema": { "$ref": "#/components/schemas/TransactionCreate" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "examples": { "approved": { "summary": "Fluxo aprovado", "value": { "accepted_evidence_documents": [ "CIN", "CNH", "RG" ], "canonical_url": "https://journey.example.invalid/demo/0001", "configuration_snapshot": { "captured_at": "2026-06-18T12:00:00Z", "default_transaction_ttl_minutes": 10080, "docmatch_threshold": 85, "document_capture_max_attempts": 3, "document_expiration_policy": "reject_expired", "environment": "prod", "liveness_max_attempts": 10, "liveness_threshold": 80, "location_capture_mode": "required", "manual_review_ttl_hours": 720, "snapshot_quality": "complete" }, "country_code": "BR", "created_at": "2026-06-18T12:00:00Z", "created_by": null, "created_by_type": "api_key", "current_step": "done", "decision": "approved", "decision_reason": "document_match_and_identity_backing_passed", "document_required": true, "document_requirement": { "reason": "missing_trusted_identity_backing", "required": true, "trusted_document_id": null, "trusted_identity_backing_id": null, "valid_until": null }, "environment": "prod", "expires_at": "2026-06-25T12:00:00Z", "external_id": "docs-example-0001", "links": { "short_url": "https://short.example.invalid/demo0001", "webview_url": "https://journey.example.invalid/demo/0001" }, "locale": "pt-BR", "location_captured_at": null, "metadata": { "branch": "SAO-01", "order_id": "pedido-123" }, "origin": "api", "result": { "document_expiration_status": "unknown", "document_match_similarity": 96.7, "document_match_status": "passed", "evidence_document_type": null, "liveness_score": 98.4, "liveness_status": "passed", "trusted_identity_backing_created": false }, "short_code": "demo0001", "short_url": "https://short.example.invalid/demo0001", "source": { "channel": "callcenter", "integration": "onboarding-digital", "system": "CRM" }, "status": "approved", "subject": { "email": "person@example.invalid", "identity": { "country": "BR", "number": "00000000000", "type": "CPF" }, "name": "Pessoa de exemplo / Example person", "phone": "+5500000000000", "tenant_subject_id": "subject_docs_example" }, "tenant_id": "tenant_docs_example", "tenant_subject_id": "subject_docs_example", "terms_accepted_at": null, "terms_version": "BR-pt-BR-v1", "transaction_id": "00000000-0000-4000-8000-000000000001", "updated_at": "2026-06-18T12:10:22Z", "webhook_delivery": { "attempts": 0, "last_error": null, "last_event_id": "evt_docs_9b7a4a04ceacc0f2", "last_event_type": "approved", "status": "pending", "updated_at": "2026-06-18T12:10:22Z" }, "webhook_events": [ { "attempts": 0, "callback_configured": true, "created_at": "2026-06-18T12:00:00Z", "delivered_at": null, "event_id": "evt_docs_9b7a4a04ceacc0f2", "event_type": "approved", "failed_at": null, "last_error": null, "last_http_status": null, "max_attempts": 5, "published_at": null, "status": "pending", "transaction_id": "00000000-0000-4000-8000-000000000001", "updated_at": "2026-06-18T12:10:22Z" } ], "webview_url": "https://journey.example.invalid/demo/0001" } }, "created": { "summary": "Transacao criada", "value": { "accepted_evidence_documents": [ "CIN", "CNH", "RG" ], "canonical_url": "https://journey.example.invalid/demo/0001", "configuration_snapshot": { "captured_at": "2026-06-18T12:00:00Z", "default_transaction_ttl_minutes": 10080, "docmatch_threshold": 85, "document_capture_max_attempts": 3, "document_expiration_policy": "reject_expired", "environment": "prod", "liveness_max_attempts": 10, "liveness_threshold": 80, "location_capture_mode": "required", "manual_review_ttl_hours": 720, "snapshot_quality": "complete" }, "country_code": "BR", "created_at": "2026-06-18T12:00:00Z", "created_by": null, "created_by_type": "api_key", "current_step": "terms", "decision": "pending", "decision_reason": null, "document_required": true, "document_requirement": { "reason": "missing_trusted_identity_backing", "required": true, "trusted_document_id": null, "trusted_identity_backing_id": null, "valid_until": null }, "environment": "prod", "expires_at": "2026-06-25T12:00:00Z", "external_id": "docs-example-0001", "links": { "short_url": "https://short.example.invalid/demo0001", "webview_url": "https://journey.example.invalid/demo/0001" }, "locale": "pt-BR", "location_captured_at": null, "metadata": { "branch": "SAO-01", "order_id": "pedido-123" }, "origin": "api", "result": { "document_expiration_status": "unknown", "document_match_similarity": null, "document_match_status": "not_started", "evidence_document_type": null, "liveness_score": null, "liveness_status": "not_started", "trusted_identity_backing_created": false }, "short_code": "demo0001", "short_url": "https://short.example.invalid/demo0001", "source": { "channel": "callcenter", "integration": "onboarding-digital", "system": "CRM" }, "status": "created", "subject": { "email": "person@example.invalid", "identity": { "country": "BR", "number": "00000000000", "type": "CPF" }, "name": "Pessoa de exemplo / Example person", "phone": "+5500000000000", "tenant_subject_id": "subject_docs_example" }, "tenant_id": "tenant_docs_example", "tenant_subject_id": "subject_docs_example", "terms_accepted_at": null, "terms_version": "BR-pt-BR-v1", "transaction_id": "00000000-0000-4000-8000-000000000001", "updated_at": "2026-06-18T12:00:00Z", "webhook_delivery": { "attempts": 0, "last_error": null, "last_event_id": "evt_docs_9b7a4a04ceacc0f2", "last_event_type": "transaction.created", "status": "pending", "updated_at": "2026-06-18T12:00:00Z" }, "webhook_events": [ { "attempts": 0, "callback_configured": true, "created_at": "2026-06-18T12:00:00Z", "delivered_at": null, "event_id": "evt_docs_9b7a4a04ceacc0f2", "event_type": "transaction.created", "failed_at": null, "last_error": null, "last_http_status": null, "max_attempts": 5, "published_at": null, "status": "pending", "transaction_id": "00000000-0000-4000-8000-000000000001", "updated_at": "2026-06-18T12:00:00Z" } ], "webview_url": "https://journey.example.invalid/demo/0001" } } }, "schema": { "$ref": "#/components/schemas/TenantTransactionResponse" } } }, "description": "Transacao criada ou recuperada por idempotencia." }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/InvalidApiKey" }, "403": { "$ref": "#/components/responses/TenantEnvironmentDisabled" }, "409": { "$ref": "#/components/responses/IdempotencyConflict" } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Criar transacao", "tags": [ "Transactions" ] } }, "/v1/face-auth/transactions/{transaction_id}": { "get": { "description": "Retorna a visao tenant-safe da transacao. A API key precisa pertencer ao mesmo tenant e ao mesmo ambiente da transacao.", "operationId": "getFaceAuthTransaction", "parameters": [ { "description": "Identificador oficial retornado no POST.", "in": "path", "name": "transaction_id", "required": true, "schema": { "maxLength": 128, "minLength": 1, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "approved": { "summary": "Fluxo aprovado", "value": { "accepted_evidence_documents": [ "CIN", "CNH", "RG" ], "canonical_url": "https://journey.example.invalid/demo/0001", "configuration_snapshot": { "captured_at": "2026-06-18T12:00:00Z", "default_transaction_ttl_minutes": 10080, "docmatch_threshold": 85, "document_capture_max_attempts": 3, "document_expiration_policy": "reject_expired", "environment": "prod", "liveness_max_attempts": 10, "liveness_threshold": 80, "location_capture_mode": "required", "manual_review_ttl_hours": 720, "snapshot_quality": "complete" }, "country_code": "BR", "created_at": "2026-06-18T12:00:00Z", "created_by": null, "created_by_type": "api_key", "current_step": "done", "decision": "approved", "decision_reason": "document_match_and_identity_backing_passed", "document_required": true, "document_requirement": { "reason": "missing_trusted_identity_backing", "required": true, "trusted_document_id": null, "trusted_identity_backing_id": null, "valid_until": null }, "environment": "prod", "expires_at": "2026-06-25T12:00:00Z", "external_id": "docs-example-0001", "links": { "short_url": "https://short.example.invalid/demo0001", "webview_url": "https://journey.example.invalid/demo/0001" }, "locale": "pt-BR", "location_captured_at": null, "metadata": { "branch": "SAO-01", "order_id": "pedido-123" }, "origin": "api", "result": { "document_expiration_status": "unknown", "document_match_similarity": 96.7, "document_match_status": "passed", "evidence_document_type": null, "liveness_score": 98.4, "liveness_status": "passed", "trusted_identity_backing_created": false }, "short_code": "demo0001", "short_url": "https://short.example.invalid/demo0001", "source": { "channel": "callcenter", "integration": "onboarding-digital", "system": "CRM" }, "status": "approved", "subject": { "email": "person@example.invalid", "identity": { "country": "BR", "number": "00000000000", "type": "CPF" }, "name": "Pessoa de exemplo / Example person", "phone": "+5500000000000", "tenant_subject_id": "subject_docs_example" }, "tenant_id": "tenant_docs_example", "tenant_subject_id": "subject_docs_example", "terms_accepted_at": null, "terms_version": "BR-pt-BR-v1", "transaction_id": "00000000-0000-4000-8000-000000000001", "updated_at": "2026-06-18T12:10:22Z", "webhook_delivery": { "attempts": 0, "last_error": null, "last_event_id": "evt_docs_9b7a4a04ceacc0f2", "last_event_type": "approved", "status": "pending", "updated_at": "2026-06-18T12:10:22Z" }, "webhook_events": [ { "attempts": 0, "callback_configured": true, "created_at": "2026-06-18T12:00:00Z", "delivered_at": null, "event_id": "evt_docs_9b7a4a04ceacc0f2", "event_type": "approved", "failed_at": null, "last_error": null, "last_http_status": null, "max_attempts": 5, "published_at": null, "status": "pending", "transaction_id": "00000000-0000-4000-8000-000000000001", "updated_at": "2026-06-18T12:10:22Z" } ], "webview_url": "https://journey.example.invalid/demo/0001" } }, "pending": { "summary": "Fluxo pendente", "value": { "accepted_evidence_documents": [ "CIN", "CNH", "RG" ], "canonical_url": "https://journey.example.invalid/demo/0001", "configuration_snapshot": { "captured_at": "2026-06-18T12:00:00Z", "default_transaction_ttl_minutes": 10080, "docmatch_threshold": 85, "document_capture_max_attempts": 3, "document_expiration_policy": "reject_expired", "environment": "prod", "liveness_max_attempts": 10, "liveness_threshold": 80, "location_capture_mode": "required", "manual_review_ttl_hours": 720, "snapshot_quality": "complete" }, "country_code": "BR", "created_at": "2026-06-18T12:00:00Z", "created_by": null, "created_by_type": "api_key", "current_step": "terms", "decision": "pending", "decision_reason": null, "document_required": true, "document_requirement": { "reason": "missing_trusted_identity_backing", "required": true, "trusted_document_id": null, "trusted_identity_backing_id": null, "valid_until": null }, "environment": "prod", "expires_at": "2026-06-25T12:00:00Z", "external_id": "docs-example-0001", "links": { "short_url": "https://short.example.invalid/demo0001", "webview_url": "https://journey.example.invalid/demo/0001" }, "locale": "pt-BR", "location_captured_at": null, "metadata": { "branch": "SAO-01", "order_id": "pedido-123" }, "origin": "api", "result": { "document_expiration_status": "unknown", "document_match_similarity": null, "document_match_status": "not_started", "evidence_document_type": null, "liveness_score": null, "liveness_status": "not_started", "trusted_identity_backing_created": false }, "short_code": "demo0001", "short_url": "https://short.example.invalid/demo0001", "source": { "channel": "callcenter", "integration": "onboarding-digital", "system": "CRM" }, "status": "created", "subject": { "email": "person@example.invalid", "identity": { "country": "BR", "number": "00000000000", "type": "CPF" }, "name": "Pessoa de exemplo / Example person", "phone": "+5500000000000", "tenant_subject_id": "subject_docs_example" }, "tenant_id": "tenant_docs_example", "tenant_subject_id": "subject_docs_example", "terms_accepted_at": null, "terms_version": "BR-pt-BR-v1", "transaction_id": "00000000-0000-4000-8000-000000000001", "updated_at": "2026-06-18T12:00:00Z", "webhook_delivery": { "attempts": 0, "last_error": null, "last_event_id": "evt_docs_9b7a4a04ceacc0f2", "last_event_type": "transaction.created", "status": "pending", "updated_at": "2026-06-18T12:00:00Z" }, "webhook_events": [ { "attempts": 0, "callback_configured": true, "created_at": "2026-06-18T12:00:00Z", "delivered_at": null, "event_id": "evt_docs_9b7a4a04ceacc0f2", "event_type": "transaction.created", "failed_at": null, "last_error": null, "last_http_status": null, "max_attempts": 5, "published_at": null, "status": "pending", "transaction_id": "00000000-0000-4000-8000-000000000001", "updated_at": "2026-06-18T12:00:00Z" } ], "webview_url": "https://journey.example.invalid/demo/0001" } } }, "schema": { "$ref": "#/components/schemas/TenantTransactionResponse" } } }, "description": "Transacao encontrada." }, "401": { "$ref": "#/components/responses/InvalidApiKey" }, "403": { "$ref": "#/components/responses/TenantEnvironmentDisabled" }, "404": { "$ref": "#/components/responses/TransactionNotFound" } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Consultar transacao", "tags": [ "Transactions" ] } }, "/v1/face-auth/transactions/{transaction_id}/assets": { "get": { "description": "Lista assets operacionais tenant-safe: liveness_reference, document_front, document_back e document_full. Exige API key com permissao document_download e IP autorizado para document_download.", "operationId": "listFaceAuthTransactionAssets", "parameters": [ { "in": "path", "name": "transaction_id", "required": true, "schema": { "maxLength": 128, "minLength": 1, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionAssetsResponse" } } }, "description": "Assets encontrados." }, "401": { "$ref": "#/components/responses/InvalidApiKey" }, "403": { "$ref": "#/components/responses/ForbiddenExternalAccess" }, "404": { "$ref": "#/components/responses/TransactionNotFound" } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Listar assets da transacao", "tags": [ "Documents" ] } }, "/v1/face-auth/transactions/{transaction_id}/assets/{asset_id}/content": { "get": { "description": "Baixa o conteudo binario de um asset operacional tenant-safe. Exige API key e IP com permissao document_download.", "operationId": "downloadFaceAuthTransactionAsset", "parameters": [ { "in": "path", "name": "transaction_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "asset_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/octet-stream": { "schema": { "format": "binary", "type": "string" } } }, "description": "Conteudo binario do asset." }, "401": { "$ref": "#/components/responses/InvalidApiKey" }, "403": { "$ref": "#/components/responses/ForbiddenExternalAccess" }, "404": { "$ref": "#/components/responses/TransactionNotFound" } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Baixar asset da transacao", "tags": [ "Documents" ] } }, "/v1/face-auth/transactions/{transaction_id}/documents/download": { "get": { "description": "Esta rota não disponibiliza ZIP/PDF para integrações Tenant. Mesmo com chave válida, escopo document_download e IP autorizado, retorna HTTP 403 evidence_access_restricted. Não solicite permissões adicionais nem repita a chamada para tentar liberar a evidência. A existência da rota não concede acesso a evidências internas.", "operationId": "downloadFaceAuthTransactionDocuments", "parameters": [ { "in": "path", "name": "transaction_id", "required": true, "schema": { "type": "string" } } ], "responses": { "401": { "$ref": "#/components/responses/InvalidApiKey" }, "403": { "content": { "application/json": { "example": { "detail": { "code": "evidence_access_restricted", "message": "evidence access is restricted to internal admin" } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Evidence access is restricted to internal admin, including for authorized Tenant API keys." }, "404": { "$ref": "#/components/responses/TransactionNotFound" } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Evidência restrita ao Admin interno — indisponível na API Tenant", "tags": [ "Documents" ], "x-availability": "restricted" } }, "/v1/face-auth/transactions/{transaction_id}/evidence.pdf": { "get": { "description": "Esta rota não disponibiliza ZIP/PDF para integrações Tenant. Mesmo com chave válida, escopo document_download e IP autorizado, retorna HTTP 403 evidence_access_restricted. Não solicite permissões adicionais nem repita a chamada para tentar liberar a evidência. A existência da rota não concede acesso a evidências internas.", "operationId": "downloadFaceAuthTransactionEvidencePdf", "parameters": [ { "in": "path", "name": "transaction_id", "required": true, "schema": { "type": "string" } } ], "responses": { "401": { "$ref": "#/components/responses/InvalidApiKey" }, "403": { "content": { "application/json": { "example": { "detail": { "code": "evidence_access_restricted", "message": "evidence access is restricted to internal admin" } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Evidence access is restricted to internal admin, including for authorized Tenant API keys." }, "404": { "$ref": "#/components/responses/TransactionNotFound" } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Evidência restrita ao Admin interno — indisponível na API Tenant", "tags": [ "Documents" ], "x-availability": "restricted" } } }, "servers": [ { "description": "Placeholder only. Obtain the authorized environment base URL from your Tenant Portal.", "url": "https://api.example.invalid" } ], "tags": [ { "description": "Criacao e consulta de transacoes tenant-safe.", "name": "Transactions" }, { "description": "Downloads server-to-server de documentos, evidencias e assets.", "name": "Documents" }, { "description": "Payload entregue ao callback do tenant e headers HMAC.", "name": "Webhooks" } ], "webhooks": { "faceAuthTransactionEvent": { "post": { "description": "Contrato de saida enviado ao callback_url da transacao ou, se ausente, ao webhook configurado para o tenant no ambiente. O evento approved e o sinal assincrono recomendado para integracoes automaticas; use GET /v1/face-auth/transactions/{transaction_id} para reconciliacao. Libere no firewall/WAF os IPs de origem publicados no portal Face Auth; o hostname de origem e uma referencia operacional.", "operationId": "receiveFaceAuthTransactionEvent", "parameters": [ { "$ref": "#/components/parameters/WebhookEventIdHeader" }, { "$ref": "#/components/parameters/WebhookEventTypeHeader" }, { "$ref": "#/components/parameters/WebhookTimestampHeader" }, { "$ref": "#/components/parameters/WebhookSignatureHeader" } ], "requestBody": { "content": { "application/json": { "examples": { "approved": { "summary": "approved", "value": { "api_version": "v1", "created_at": "2026-06-18T12:10:22Z", "event_id": "evt_docs_4fe051ecc8d3ce90", "event_type": "approved", "transaction": { "accepted_evidence_documents": [ "CIN", "CNH", "RG" ], "canonical_url": "https://journey.example.invalid/demo/0001", "configuration_snapshot": { "captured_at": "2026-06-18T12:00:00Z", "default_transaction_ttl_minutes": 10080, "docmatch_threshold": 85, "document_capture_max_attempts": 3, "document_expiration_policy": "reject_expired", "environment": "prod", "liveness_max_attempts": 10, "liveness_threshold": 80, "location_capture_mode": "required", "manual_review_ttl_hours": 720, "snapshot_quality": "complete" }, "country_code": "BR", "created_at": "2026-06-18T12:00:00Z", "created_by": null, "created_by_type": "api_key", "current_step": "done", "decision": "approved", "decision_reason": "document_match_and_identity_backing_passed", "document_required": true, "document_requirement": { "reason": "missing_trusted_identity_backing", "required": true, "trusted_document_id": null, "trusted_identity_backing_id": null, "valid_until": null }, "environment": "prod", "expires_at": "2026-06-25T12:00:00Z", "external_id": "docs-example-0001", "links": { "short_url": "https://short.example.invalid/demo0001", "webview_url": "https://journey.example.invalid/demo/0001" }, "locale": "pt-BR", "location_captured_at": null, "metadata": { "branch": "SAO-01", "order_id": "pedido-123" }, "origin": "api", "result": { "document_expiration_status": "unknown", "document_match_similarity": 96.7, "document_match_status": "passed", "evidence_document_type": null, "liveness_score": 98.4, "liveness_status": "passed", "trusted_identity_backing_created": false }, "short_code": "demo0001", "short_url": "https://short.example.invalid/demo0001", "source": { "channel": "callcenter", "integration": "onboarding-digital", "system": "CRM" }, "status": "approved", "subject": { "email": "person@example.invalid", "identity": { "country": "BR", "number": "00000000000", "type": "CPF" }, "name": "Pessoa de exemplo / Example person", "phone": "+5500000000000", "tenant_subject_id": "subject_docs_example" }, "tenant_id": "tenant_docs_example", "tenant_subject_id": "subject_docs_example", "terms_accepted_at": null, "terms_version": "BR-pt-BR-v1", "transaction_id": "00000000-0000-4000-8000-000000000001", "updated_at": "2026-06-18T12:10:22Z", "webhook_delivery": { "attempts": 0, "last_error": null, "last_event_id": "evt_docs_9b7a4a04ceacc0f2", "last_event_type": "approved", "status": "pending", "updated_at": "2026-06-18T12:10:22Z" }, "webhook_events": [ { "attempts": 0, "callback_configured": true, "created_at": "2026-06-18T12:00:00Z", "delivered_at": null, "event_id": "evt_docs_9b7a4a04ceacc0f2", "event_type": "approved", "failed_at": null, "last_error": null, "last_http_status": null, "max_attempts": 5, "published_at": null, "status": "pending", "transaction_id": "00000000-0000-4000-8000-000000000001", "updated_at": "2026-06-18T12:10:22Z" } ], "webview_url": "https://journey.example.invalid/demo/0001" } } }, "document_passed": { "summary": "document_passed", "value": { "api_version": "v1", "created_at": "2026-06-18T12:09:45Z", "event_id": "evt_docs_ad1d23bb16175ca3", "event_type": "document_passed", "transaction": { "accepted_evidence_documents": [ "CIN", "CNH", "RG" ], "canonical_url": "https://journey.example.invalid/demo/0001", "configuration_snapshot": { "captured_at": "2026-06-18T12:00:00Z", "default_transaction_ttl_minutes": 10080, "docmatch_threshold": 85, "document_capture_max_attempts": 3, "document_expiration_policy": "reject_expired", "environment": "prod", "liveness_max_attempts": 10, "liveness_threshold": 80, "location_capture_mode": "required", "manual_review_ttl_hours": 720, "snapshot_quality": "complete" }, "country_code": "BR", "created_at": "2026-06-18T12:00:00Z", "created_by": null, "created_by_type": "api_key", "current_step": "done", "decision": "pending", "decision_reason": "document_match_passed_pending_identity_extraction", "document_required": true, "document_requirement": { "reason": "missing_trusted_identity_backing", "required": true, "trusted_document_id": null, "trusted_identity_backing_id": null, "valid_until": null }, "environment": "prod", "expires_at": "2026-06-25T12:00:00Z", "external_id": "docs-example-0001", "links": { "short_url": "https://short.example.invalid/demo0001", "webview_url": "https://journey.example.invalid/demo/0001" }, "locale": "pt-BR", "location_captured_at": null, "metadata": { "branch": "SAO-01", "order_id": "pedido-123" }, "origin": "api", "result": { "document_expiration_status": "unknown", "document_match_similarity": 96.7, "document_match_status": "passed", "evidence_document_type": null, "liveness_score": 98.4, "liveness_status": "passed", "trusted_identity_backing_created": false }, "short_code": "demo0001", "short_url": "https://short.example.invalid/demo0001", "source": { "channel": "callcenter", "integration": "onboarding-digital", "system": "CRM" }, "status": "document_passed", "subject": { "email": "person@example.invalid", "identity": { "country": "BR", "number": "00000000000", "type": "CPF" }, "name": "Pessoa de exemplo / Example person", "phone": "+5500000000000", "tenant_subject_id": "subject_docs_example" }, "tenant_id": "tenant_docs_example", "tenant_subject_id": "subject_docs_example", "terms_accepted_at": null, "terms_version": "BR-pt-BR-v1", "transaction_id": "00000000-0000-4000-8000-000000000001", "updated_at": "2026-06-18T12:10:22Z", "webhook_delivery": { "attempts": 0, "last_error": null, "last_event_id": "evt_docs_9b7a4a04ceacc0f2", "last_event_type": "document_passed", "status": "pending", "updated_at": "2026-06-18T12:10:22Z" }, "webhook_events": [ { "attempts": 0, "callback_configured": true, "created_at": "2026-06-18T12:00:00Z", "delivered_at": null, "event_id": "evt_docs_9b7a4a04ceacc0f2", "event_type": "document_passed", "failed_at": null, "last_error": null, "last_http_status": null, "max_attempts": 5, "published_at": null, "status": "pending", "transaction_id": "00000000-0000-4000-8000-000000000001", "updated_at": "2026-06-18T12:10:22Z" } ], "webview_url": "https://journey.example.invalid/demo/0001" } } }, "expired": { "summary": "expired", "value": { "api_version": "v1", "created_at": "2026-06-25T12:00:00Z", "event_id": "evt_docs_548035fc9b349acc", "event_type": "expired", "transaction": { "accepted_evidence_documents": [ "CIN", "CNH", "RG" ], "canonical_url": "https://journey.example.invalid/demo/0001", "configuration_snapshot": { "captured_at": "2026-06-18T12:00:00Z", "default_transaction_ttl_minutes": 10080, "docmatch_threshold": 85, "document_capture_max_attempts": 3, "document_expiration_policy": "reject_expired", "environment": "prod", "liveness_max_attempts": 10, "liveness_threshold": 80, "location_capture_mode": "required", "manual_review_ttl_hours": 720, "snapshot_quality": "complete" }, "country_code": "BR", "created_at": "2026-06-18T12:00:00Z", "created_by": null, "created_by_type": "api_key", "current_step": "done", "decision": "pending", "decision_reason": "transaction_expired", "document_required": true, "document_requirement": { "reason": "missing_trusted_identity_backing", "required": true, "trusted_document_id": null, "trusted_identity_backing_id": null, "valid_until": null }, "environment": "prod", "expires_at": "2026-06-25T12:00:00Z", "external_id": "docs-example-0001", "links": { "short_url": "https://short.example.invalid/demo0001", "webview_url": "https://journey.example.invalid/demo/0001" }, "locale": "pt-BR", "location_captured_at": null, "metadata": { "branch": "SAO-01", "order_id": "pedido-123" }, "origin": "api", "result": { "document_expiration_status": "unknown", "document_match_similarity": null, "document_match_status": "not_started", "evidence_document_type": null, "liveness_score": null, "liveness_status": "not_started", "trusted_identity_backing_created": false }, "short_code": "demo0001", "short_url": "https://short.example.invalid/demo0001", "source": { "channel": "callcenter", "integration": "onboarding-digital", "system": "CRM" }, "status": "expired", "subject": { "email": "person@example.invalid", "identity": { "country": "BR", "number": "00000000000", "type": "CPF" }, "name": "Pessoa de exemplo / Example person", "phone": "+5500000000000", "tenant_subject_id": "subject_docs_example" }, "tenant_id": "tenant_docs_example", "tenant_subject_id": "subject_docs_example", "terms_accepted_at": null, "terms_version": "BR-pt-BR-v1", "transaction_id": "00000000-0000-4000-8000-000000000001", "updated_at": "2026-06-18T12:10:22Z", "webhook_delivery": { "attempts": 0, "last_error": null, "last_event_id": "evt_docs_9b7a4a04ceacc0f2", "last_event_type": "expired", "status": "pending", "updated_at": "2026-06-18T12:10:22Z" }, "webhook_events": [ { "attempts": 0, "callback_configured": true, "created_at": "2026-06-18T12:00:00Z", "delivered_at": null, "event_id": "evt_docs_9b7a4a04ceacc0f2", "event_type": "expired", "failed_at": null, "last_error": null, "last_http_status": null, "max_attempts": 5, "published_at": null, "status": "pending", "transaction_id": "00000000-0000-4000-8000-000000000001", "updated_at": "2026-06-18T12:10:22Z" } ], "webview_url": "https://journey.example.invalid/demo/0001" } } }, "liveness_passed": { "summary": "liveness_passed", "value": { "api_version": "v1", "created_at": "2026-06-18T12:05:15Z", "event_id": "evt_docs_df225f4b7c45f908", "event_type": "liveness_passed", "transaction": { "accepted_evidence_documents": [ "CIN", "CNH", "RG" ], "canonical_url": "https://journey.example.invalid/demo/0001", "configuration_snapshot": { "captured_at": "2026-06-18T12:00:00Z", "default_transaction_ttl_minutes": 10080, "docmatch_threshold": 85, "document_capture_max_attempts": 3, "document_expiration_policy": "reject_expired", "environment": "prod", "liveness_max_attempts": 10, "liveness_threshold": 80, "location_capture_mode": "required", "manual_review_ttl_hours": 720, "snapshot_quality": "complete" }, "country_code": "BR", "created_at": "2026-06-18T12:00:00Z", "created_by": null, "created_by_type": "api_key", "current_step": "document", "decision": "pending", "decision_reason": null, "document_required": true, "document_requirement": { "reason": "missing_trusted_identity_backing", "required": true, "trusted_document_id": null, "trusted_identity_backing_id": null, "valid_until": null }, "environment": "prod", "expires_at": "2026-06-25T12:00:00Z", "external_id": "docs-example-0001", "links": { "short_url": "https://short.example.invalid/demo0001", "webview_url": "https://journey.example.invalid/demo/0001" }, "locale": "pt-BR", "location_captured_at": null, "metadata": { "branch": "SAO-01", "order_id": "pedido-123" }, "origin": "api", "result": { "document_expiration_status": "unknown", "document_match_similarity": null, "document_match_status": "not_started", "evidence_document_type": null, "liveness_score": 98.4, "liveness_status": "passed", "trusted_identity_backing_created": false }, "short_code": "demo0001", "short_url": "https://short.example.invalid/demo0001", "source": { "channel": "callcenter", "integration": "onboarding-digital", "system": "CRM" }, "status": "liveness_passed", "subject": { "email": "person@example.invalid", "identity": { "country": "BR", "number": "00000000000", "type": "CPF" }, "name": "Pessoa de exemplo / Example person", "phone": "+5500000000000", "tenant_subject_id": "subject_docs_example" }, "tenant_id": "tenant_docs_example", "tenant_subject_id": "subject_docs_example", "terms_accepted_at": null, "terms_version": "BR-pt-BR-v1", "transaction_id": "00000000-0000-4000-8000-000000000001", "updated_at": "2026-06-18T12:10:22Z", "webhook_delivery": { "attempts": 0, "last_error": null, "last_event_id": "evt_docs_9b7a4a04ceacc0f2", "last_event_type": "liveness_passed", "status": "pending", "updated_at": "2026-06-18T12:10:22Z" }, "webhook_events": [ { "attempts": 0, "callback_configured": true, "created_at": "2026-06-18T12:00:00Z", "delivered_at": null, "event_id": "evt_docs_9b7a4a04ceacc0f2", "event_type": "liveness_passed", "failed_at": null, "last_error": null, "last_http_status": null, "max_attempts": 5, "published_at": null, "status": "pending", "transaction_id": "00000000-0000-4000-8000-000000000001", "updated_at": "2026-06-18T12:10:22Z" } ], "webview_url": "https://journey.example.invalid/demo/0001" } } }, "rejected": { "summary": "rejected", "value": { "api_version": "v1", "created_at": "2026-06-18T12:11:03Z", "event_id": "evt_docs_fa565ae6c5d1446d", "event_type": "rejected", "transaction": { "accepted_evidence_documents": [ "CIN", "CNH", "RG" ], "canonical_url": "https://journey.example.invalid/demo/0001", "configuration_snapshot": { "captured_at": "2026-06-18T12:00:00Z", "default_transaction_ttl_minutes": 10080, "docmatch_threshold": 85, "document_capture_max_attempts": 3, "document_expiration_policy": "reject_expired", "environment": "prod", "liveness_max_attempts": 10, "liveness_threshold": 80, "location_capture_mode": "required", "manual_review_ttl_hours": 720, "snapshot_quality": "complete" }, "country_code": "BR", "created_at": "2026-06-18T12:00:00Z", "created_by": null, "created_by_type": "api_key", "current_step": "done", "decision": "rejected", "decision_reason": "document_match_failed", "document_required": true, "document_requirement": { "reason": "missing_trusted_identity_backing", "required": true, "trusted_document_id": null, "trusted_identity_backing_id": null, "valid_until": null }, "environment": "prod", "expires_at": "2026-06-25T12:00:00Z", "external_id": "docs-example-0001", "links": { "short_url": "https://short.example.invalid/demo0001", "webview_url": "https://journey.example.invalid/demo/0001" }, "locale": "pt-BR", "location_captured_at": null, "metadata": { "branch": "SAO-01", "order_id": "pedido-123" }, "origin": "api", "result": { "document_expiration_status": "unknown", "document_match_similarity": 42.1, "document_match_status": "failed", "evidence_document_type": null, "liveness_score": 98.4, "liveness_status": "passed", "trusted_identity_backing_created": false }, "short_code": "demo0001", "short_url": "https://short.example.invalid/demo0001", "source": { "channel": "callcenter", "integration": "onboarding-digital", "system": "CRM" }, "status": "rejected", "subject": { "email": "person@example.invalid", "identity": { "country": "BR", "number": "00000000000", "type": "CPF" }, "name": "Pessoa de exemplo / Example person", "phone": "+5500000000000", "tenant_subject_id": "subject_docs_example" }, "tenant_id": "tenant_docs_example", "tenant_subject_id": "subject_docs_example", "terms_accepted_at": null, "terms_version": "BR-pt-BR-v1", "transaction_id": "00000000-0000-4000-8000-000000000001", "updated_at": "2026-06-18T12:10:22Z", "webhook_delivery": { "attempts": 0, "last_error": null, "last_event_id": "evt_docs_9b7a4a04ceacc0f2", "last_event_type": "rejected", "status": "pending", "updated_at": "2026-06-18T12:10:22Z" }, "webhook_events": [ { "attempts": 0, "callback_configured": true, "created_at": "2026-06-18T12:00:00Z", "delivered_at": null, "event_id": "evt_docs_9b7a4a04ceacc0f2", "event_type": "rejected", "failed_at": null, "last_error": null, "last_http_status": null, "max_attempts": 5, "published_at": null, "status": "pending", "transaction_id": "00000000-0000-4000-8000-000000000001", "updated_at": "2026-06-18T12:10:22Z" } ], "webview_url": "https://journey.example.invalid/demo/0001" } } }, "transaction_created": { "summary": "transaction.created", "value": { "api_version": "v1", "created_at": "2026-06-18T12:00:00Z", "event_id": "evt_docs_9b7a4a04ceacc0f2", "event_type": "transaction.created", "transaction": { "accepted_evidence_documents": [ "CIN", "CNH", "RG" ], "canonical_url": "https://journey.example.invalid/demo/0001", "configuration_snapshot": { "captured_at": "2026-06-18T12:00:00Z", "default_transaction_ttl_minutes": 10080, "docmatch_threshold": 85, "document_capture_max_attempts": 3, "document_expiration_policy": "reject_expired", "environment": "prod", "liveness_max_attempts": 10, "liveness_threshold": 80, "location_capture_mode": "required", "manual_review_ttl_hours": 720, "snapshot_quality": "complete" }, "country_code": "BR", "created_at": "2026-06-18T12:00:00Z", "created_by": null, "created_by_type": "api_key", "current_step": "terms", "decision": "pending", "decision_reason": null, "document_required": true, "document_requirement": { "reason": "missing_trusted_identity_backing", "required": true, "trusted_document_id": null, "trusted_identity_backing_id": null, "valid_until": null }, "environment": "prod", "expires_at": "2026-06-25T12:00:00Z", "external_id": "docs-example-0001", "links": { "short_url": "https://short.example.invalid/demo0001", "webview_url": "https://journey.example.invalid/demo/0001" }, "locale": "pt-BR", "location_captured_at": null, "metadata": { "branch": "SAO-01", "order_id": "pedido-123" }, "origin": "api", "result": { "document_expiration_status": "unknown", "document_match_similarity": null, "document_match_status": "not_started", "evidence_document_type": null, "liveness_score": null, "liveness_status": "not_started", "trusted_identity_backing_created": false }, "short_code": "demo0001", "short_url": "https://short.example.invalid/demo0001", "source": { "channel": "callcenter", "integration": "onboarding-digital", "system": "CRM" }, "status": "created", "subject": { "email": "person@example.invalid", "identity": { "country": "BR", "number": "00000000000", "type": "CPF" }, "name": "Pessoa de exemplo / Example person", "phone": "+5500000000000", "tenant_subject_id": "subject_docs_example" }, "tenant_id": "tenant_docs_example", "tenant_subject_id": "subject_docs_example", "terms_accepted_at": null, "terms_version": "BR-pt-BR-v1", "transaction_id": "00000000-0000-4000-8000-000000000001", "updated_at": "2026-06-18T12:10:22Z", "webhook_delivery": { "attempts": 0, "last_error": null, "last_event_id": "evt_docs_9b7a4a04ceacc0f2", "last_event_type": "transaction.created", "status": "pending", "updated_at": "2026-06-18T12:10:22Z" }, "webhook_events": [ { "attempts": 0, "callback_configured": true, "created_at": "2026-06-18T12:00:00Z", "delivered_at": null, "event_id": "evt_docs_9b7a4a04ceacc0f2", "event_type": "transaction.created", "failed_at": null, "last_error": null, "last_http_status": null, "max_attempts": 5, "published_at": null, "status": "pending", "transaction_id": "00000000-0000-4000-8000-000000000001", "updated_at": "2026-06-18T12:10:22Z" } ], "webview_url": "https://journey.example.invalid/demo/0001" } } } }, "schema": { "$ref": "#/components/schemas/WebhookPayload" } } }, "required": true }, "responses": { "2XX": { "description": "Confirma recebimento. Responda em ate 10 segundos; respostas fora de 2xx ou timeout entram em retry_pending." } }, "summary": "Receber evento de transacao", "tags": [ "Webhooks" ] } } }, "x-webhook": { "description": "Contratos de webhook para receptores do tenant.", "headers": { "X-Face-Auth-Event-Id": { "$ref": "#/components/headers/X-Face-Auth-Event-Id" }, "X-Face-Auth-Event-Type": { "$ref": "#/components/headers/X-Face-Auth-Event-Type" }, "X-Face-Auth-Signature": { "$ref": "#/components/headers/X-Face-Auth-Signature" }, "X-Face-Auth-Timestamp": { "$ref": "#/components/headers/X-Face-Auth-Timestamp" } }, "outbound_source": "Consulte o portal Face Auth para hostname de referencia e IPs oficiais de origem por ambiente.", "payload_schema": { "$ref": "#/components/schemas/WebhookPayload" }, "retries": "Eventos com falha ficam retry_pending ate max_attempts; depois ficam failed para reconciliacao/DLQ.", "signature_algorithm": "HMAC-SHA256", "signature_base": "timestamp + '.' + raw_body" } }