{ "components": { "schemas": { "ApiEnvironment": { "enum": [ "live", "test" ], "title": "ApiEnvironment", "type": "string" }, "ApplicantPII": { "description": "PII descifrada del applicant. Exponerla emite audit.event de acceso.", "properties": { "birthDate": { "anyOf": [ { "format": "date", "type": "string" }, { "type": "null" } ], "title": "Birthdate" }, "claveElector": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Claveelector" }, "curp": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Curp" }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Email" }, "fullName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Fullname" }, "nationality": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Nationality" }, "personId": { "anyOf": [ { "description": "Opaque person id.", "pattern": "^per_[0-9a-f]{32}$", "type": "string" }, { "type": "null" } ], "title": "Personid" }, "phone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Phone" }, "rfc": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Rfc" }, "sex": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Sex" }, "state": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "State" } }, "required": [ "personId", "fullName", "curp", "rfc", "claveElector", "email", "phone", "birthDate", "sex", "nationality", "state" ], "title": "ApplicantPII", "type": "object" }, "AuditChainSummary": { "description": "Subconjunto PII-free de `pii_audit.verify_chain` para el expediente -- sin `brokenAt`\n(ese detalle vive en `GET /v1/audit-logs/verify`, no en el reporte regulatorio).", "properties": { "count": { "title": "Count", "type": "integer" }, "valid": { "title": "Valid", "type": "boolean" } }, "required": [ "valid", "count" ], "title": "AuditChainSummary", "type": "object" }, "AuditChainVerification": { "description": "`GET /v1/audit-logs/verify` -- `pii_audit.verify_chain` expuesto tal cual (BEL-413).\n\nNOTA (BEL-445 follow-up, ver docstring del endpoint): esto detecta un INSERT directo con\ndatos manipulados (`entry_hash`/`prev_hash` no calzan), pero NO un truncamiento del SUFIJO de\nla cadena (borrar las últimas N filas) -- haría falta anclar `(count, head entry_hash)` fuera\nde banda para eso, deliberadamente fuera de scope aquí.", "properties": { "brokenAt": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Brokenat" }, "count": { "title": "Count", "type": "integer" }, "valid": { "title": "Valid", "type": "boolean" } }, "required": [ "valid", "count" ], "title": "AuditChainVerification", "type": "object" }, "AuditLogEntry": { "description": "Una fila de `idv.pii_access_event`, PII-free. `id` es el bigint identity crudo (usado\ntambién para el cursor, `id` como valor de orden Y desempate a la vez -- ver\n`app.services.pagination.paginate`, llamado con `sort_column=id_column=PiiAccessEvent.id`\nen `app/api/v1/audit_logs.py`).", "properties": { "actorId": { "title": "Actorid", "type": "string" }, "actorType": { "title": "Actortype", "type": "string" }, "applicationId": { "anyOf": [ { "description": "Opaque application id.", "pattern": "^app_[0-9a-f]{32}$", "type": "string" }, { "type": "null" } ], "title": "Applicationid" }, "channel": { "title": "Channel", "type": "string" }, "createdAt": { "format": "date-time", "title": "Createdat", "type": "string" }, "fields": { "items": { "type": "string" }, "title": "Fields", "type": "array" }, "id": { "title": "Id", "type": "integer" }, "object": { "const": "audit_log_entry", "default": "audit_log_entry", "title": "Object", "type": "string" }, "personCount": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Personcount" }, "personId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Personid" }, "purpose": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Purpose" }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Reason" }, "redaction": { "title": "Redaction", "type": "string" }, "requestId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Requestid" } }, "required": [ "id", "personId", "applicationId", "actorType", "actorId", "channel", "fields", "redaction", "purpose", "reason", "requestId", "createdAt" ], "title": "AuditLogEntry", "type": "object" }, "BatchDecryptErrorEntry": { "description": "Fila de `errors[]` -- `personId` es el string CRUDO tal cual lo mandó el caller (no\nnecesariamente un `per_` válido), para que pueda correlacionar el error con su request\naunque el id ni siquiera haya parseado.", "properties": { "error": { "$ref": "#/components/schemas/BatchDecryptErrorItem" }, "personId": { "title": "Personid", "type": "string" } }, "required": [ "personId", "error" ], "title": "BatchDecryptErrorEntry", "type": "object" }, "BatchDecryptErrorItem": { "properties": { "code": { "title": "Code", "type": "string" }, "reason": { "title": "Reason", "type": "string" } }, "required": [ "code", "reason" ], "title": "BatchDecryptErrorItem", "type": "object" }, "BatchDecryptItem": { "properties": { "fields": { "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "title": "Fields", "type": "object" }, "personId": { "title": "Personid", "type": "string" } }, "required": [ "personId", "fields" ], "title": "BatchDecryptItem", "type": "object" }, "BatchDecryptRequest": { "description": "`personIds` tope 100 -- validado a MANO en `vault_service.batch_decrypt` (413\n`batch_too_large`, no un `max_length` de Pydantic, que respondería 422 -- LOCKED: el\ncontrato es 413).", "properties": { "fields": { "items": { "type": "string" }, "minItems": 1, "title": "Fields", "type": "array" }, "personIds": { "items": { "type": "string" }, "minItems": 1, "title": "Personids", "type": "array" }, "purpose": { "title": "Purpose", "type": "string" }, "reason": { "maxLength": 2000, "minLength": 1, "title": "Reason", "type": "string" } }, "required": [ "personIds", "fields", "purpose", "reason" ], "title": "BatchDecryptRequest", "type": "object" }, "BatchDecryptResponse": { "properties": { "data": { "items": { "$ref": "#/components/schemas/BatchDecryptItem" }, "title": "Data", "type": "array" }, "errors": { "items": { "$ref": "#/components/schemas/BatchDecryptErrorEntry" }, "title": "Errors", "type": "array" }, "object": { "const": "list", "default": "list", "title": "Object", "type": "string" } }, "required": [ "data", "errors" ], "title": "BatchDecryptResponse", "type": "object" }, "BiometricCheckItem": { "description": "Un check biométrico ejecutado (idv.biometric_check).\n\nNO lleva `padLevel` ni `modelVersion`, y no es un olvido (⑤). Las columnas siguen en\n`idv.biometric_check`; lo que se retiró es su publicación.\n\n* **`padLevel`** — un nivel PAD ISO/IEC 30107-3 es un *resultado de laboratorio*, no un campo\n que un pipeline se autoasigne. Publicarlo —siempre nulo, porque nadie lo escribe— en una\n superficie de cumplimiento invita a leer una certificación que Belfort no tiene. Vuelve el día\n que exista una evaluación iBeta detrás, y entonces con su valor real.\n* **`modelVersion`** — ningún camino lo escribe y el idv-api ni siquiera expone el concepto:\n era un `null` permanente. `modelName` sí se queda: tiene escritor vivo.\n\nEl guard `tests/unit/test_biometric_check_writers.py` impide que vuelva a colarse un campo\ndeclarado y nunca producido.", "properties": { "checkType": { "title": "Checktype", "type": "string" }, "latencyMs": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Latencyms" }, "modelName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Modelname" }, "passed": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Passed" }, "score": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Score" }, "threshold": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Threshold" } }, "required": [ "checkType", "score", "threshold", "passed", "modelName", "latencyMs" ], "title": "BiometricCheckItem", "type": "object" }, "BiometricMatchSummary": { "description": "El resultado del cotejo facial, con su umbral y CONTRA QUÉ se cotejó.\n\nPOR QUÉ ESTE BLOQUE EXISTE APARTE DEL `trustScore`\n---------------------------------------------------\n`trustScore` es un score COMPUESTO: mezcla cotejo facial, prueba de vida, documento,\nanti-deepfake y consultas gubernamentales en un solo 0-1. Sirve para decidir, pero NO contesta\nla pregunta que hace un oficial de cumplimiento — que es sobre el cotejo facial concreto y su\numbral, no sobre una media ponderada.\n\nLa reforma a la CUB del 1-jul-2026 nombra un porcentaje mínimo de coincidencia biométrica. Un\nintegrador regulado necesita poder enseñar ESE número, no uno que lo contiene mezclado con\notras cuatro señales. Antes de este bloque, Belfort lo calculaba, lo guardaba en\n`idv.biometric_check`… y no lo dejaba salir.\n\n`matchedAgainst` NO ES DECORATIVO — LÉELO ANTES DE AFIRMAR CUMPLIMIENTO\n-----------------------------------------------------------------------\nDice contra qué se cotejó la selfie, y hoy la respuesta es `document_photo`: la fotografía del\ndocumento que la persona PRESENTÓ. Eso NO es lo mismo que una confronta contra el registro de\nuna autoridad (INE/SRE/SAT), que es lo que exige la CUB.\n\nEl campo existe precisamente para que esa diferencia sea imposible de pasar por alto: publicar\nel score sin decir contra qué se obtuvo invitaría a afirmar un cumplimiento que no se tiene, y\nen un producto de identidad una afirmación falsa es peor defecto que un campo faltante.", "properties": { "matchedAgainst": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Matchedagainst" }, "passed": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Passed" }, "score": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Score" }, "threshold": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Threshold" } }, "title": "BiometricMatchSummary", "type": "object" }, "BiometricScores": { "description": "Scores biométricos de la sesión (None si ese check no corrió). BEL-199.", "properties": { "deepfake": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Deepfake" }, "faceMatch": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Facematch" }, "imageQuality": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Imagequality" }, "liveness": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Liveness" } }, "title": "BiometricScores", "type": "object" }, "BreachNotificationRequest": { "description": "`POST /v1/compliance/breach-notifications` -- trigger admin, emit-only (sin tabla propia,\nLOCKED #1). `detected_at` opcional -- `None` -> `now()` (el caller no siempre sabe el\nmomento exacto de detección al reportar).", "properties": { "detectedAt": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Detectedat" }, "scope": { "title": "Scope", "type": "string" }, "severity": { "enum": [ "low", "medium", "high", "critical" ], "title": "Severity", "type": "string" }, "subprocessorsAffected": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Subprocessorsaffected" } }, "required": [ "severity", "scope" ], "title": "BreachNotificationRequest", "type": "object" }, "BreachNotificationResponse": { "properties": { "breachId": { "title": "Breachid", "type": "string" }, "detectedAt": { "format": "date-time", "title": "Detectedat", "type": "string" }, "object": { "const": "compliance.breach_notification", "default": "compliance.breach_notification", "title": "Object", "type": "string" }, "scope": { "title": "Scope", "type": "string" }, "severity": { "title": "Severity", "type": "string" } }, "required": [ "breachId", "detectedAt", "severity", "scope" ], "title": "BreachNotificationResponse", "type": "object" }, "CaptureAnalysis": { "description": "Señales de UNA captura para que la UI del integrador rutee en vivo (BEL-384). Espeja lo que\nhoy devuelve `allsign-idv-api /v1/verify/identity` (documentType/skipBack/requiresBackPage/\nextractedData) + liveness/face_match. Fail-closed: `status=\"error\"` NUNCA es un 500 — la media\nqueda almacenada y el veredicto final cae a REVIEW en el submit.", "properties": { "confidence": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Confidence" }, "documentType": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Documenttype" }, "errorCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Errorcode" }, "extractedData": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Extracteddata" }, "faceMatchScore": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Facematchscore" }, "issuingCountry": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Issuingcountry" }, "livenessScore": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Livenessscore" }, "qualityIssues": { "items": { "type": "string" }, "title": "Qualityissues", "type": "array" }, "requiresBackPage": { "default": false, "title": "Requiresbackpage", "type": "boolean" }, "retryHints": { "items": { "type": "string" }, "title": "Retryhints", "type": "array" }, "skipBack": { "default": false, "title": "Skipback", "type": "boolean" }, "status": { "enum": [ "ok", "error" ], "title": "Status", "type": "string" } }, "required": [ "status" ], "title": "CaptureAnalysis", "type": "object" }, "CaseEventItem": { "properties": { "actorType": { "title": "Actortype", "type": "string" }, "actorUserId": { "anyOf": [ { "description": "Opaque user id.", "pattern": "^usr_[0-9a-f]{32}$", "type": "string" }, { "type": "null" } ], "title": "Actoruserid" }, "body": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Body" }, "createdAt": { "format": "date-time", "title": "Createdat", "type": "string" }, "eventType": { "title": "Eventtype", "type": "string" } }, "required": [ "eventType", "actorType", "actorUserId", "body", "createdAt" ], "title": "CaseEventItem", "type": "object" }, "CasePriority": { "enum": [ "low", "medium", "high", "critical" ], "title": "CasePriority", "type": "string" }, "CaseStatus": { "enum": [ "open", "in_progress", "escalated", "resolved", "closed" ], "title": "CaseStatus", "type": "string" }, "CaseSummary": { "properties": { "assigneeApiKeyId": { "anyOf": [ { "description": "Opaque API key id.", "pattern": "^key_[0-9a-f]{32}$", "type": "string" }, { "type": "null" } ], "title": "Assigneeapikeyid" }, "assigneeUserId": { "anyOf": [ { "description": "Opaque user id.", "pattern": "^usr_[0-9a-f]{32}$", "type": "string" }, { "type": "null" } ], "title": "Assigneeuserid" }, "caseId": { "title": "Caseid", "type": "string" }, "caseNumber": { "title": "Casenumber", "type": "integer" }, "claimedAt": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Claimedat" }, "createdAt": { "format": "date-time", "title": "Createdat", "type": "string" }, "escalatedAt": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Escalatedat" }, "priority": { "$ref": "#/components/schemas/CasePriority" }, "publicId": { "title": "Publicid", "type": "string" }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Reason" }, "resolution": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Resolution" }, "slaDueAt": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Sladueat" }, "status": { "$ref": "#/components/schemas/CaseStatus" }, "tenantId": { "description": "Opaque tenant id.", "pattern": "^ten_[0-9a-f]{32}$", "title": "Tenantid", "type": "string" } }, "required": [ "caseId", "publicId", "caseNumber", "tenantId", "status", "priority", "reason", "assigneeUserId", "claimedAt", "slaDueAt", "escalatedAt", "resolution", "createdAt" ], "title": "CaseSummary", "type": "object" }, "CertificateBiometric": { "description": "Un check biométrico dentro de la constancia. Sin `latencyMs`: el tiempo que tardó no es un\nhecho del expediente, y variaría entre re-emisiones si algún día se recalculara.", "properties": { "checkType": { "title": "Checktype", "type": "string" }, "modelName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Modelname" }, "passed": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Passed" }, "score": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Score" }, "threshold": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Threshold" } }, "required": [ "checkType", "score", "threshold", "passed", "modelName" ], "title": "CertificateBiometric", "type": "object" }, "CertificateGov": { "description": "Una consulta gubernamental dentro de la constancia, con su folio y su sello de tiempo —\nque es lo que un auditor necesita para ir a la fuente.", "properties": { "provider": { "title": "Provider", "type": "string" }, "providerRequestId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Providerrequestid" }, "queriedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Queriedat" }, "result": { "title": "Result", "type": "string" } }, "required": [ "provider", "result", "queriedAt", "providerRequestId" ], "title": "CertificateGov", "type": "object" }, "CertificateMedia": { "description": "La media, por HASH y NUNCA por URL firmada.\n\nUna URL lleva `exp = now + ttl`: caduca y cambia en cada emisión, lo que haría imposible sellar\nel documento. El `sha256` identifica el archivo para siempre y se coteja contra el original\ncuando haga falta.", "properties": { "kind": { "title": "Kind", "type": "string" }, "sha256": { "title": "Sha256", "type": "string" } }, "required": [ "kind", "sha256" ], "title": "CertificateMedia", "type": "object" }, "CheckSelectionInput": { "description": "Selección de checks por sesión (BEL-235): qué checks corre el pipeline. Parcial (solo los\ncampos provistos ganan). Aplica a la cascada; con IDV_FUSION es advisory.", "properties": { "deepfake": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Deepfake" }, "document": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Document" }, "faceMatch": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Facematch" }, "liveness": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Liveness" } }, "title": "CheckSelectionInput", "type": "object" }, "ClaimResult": { "properties": { "assigneeApiKeyId": { "anyOf": [ { "description": "Opaque API key id.", "pattern": "^key_[0-9a-f]{32}$", "type": "string" }, { "type": "null" } ], "title": "Assigneeapikeyid" }, "assigneeUserId": { "anyOf": [ { "description": "Opaque user id.", "pattern": "^usr_[0-9a-f]{32}$", "type": "string" }, { "type": "null" } ], "title": "Assigneeuserid" }, "caseId": { "title": "Caseid", "type": "string" }, "claimedAt": { "format": "date-time", "title": "Claimedat", "type": "string" }, "status": { "$ref": "#/components/schemas/CaseStatus" } }, "required": [ "caseId", "claimedAt", "status" ], "title": "ClaimResult", "type": "object" }, "ClientTokenCreateRequest": { "description": "`ttlSeconds`: clamp server-side a `CLIENT_TOKEN_MAX_TTL_SECONDS` (≤15min, LOCKED #2) sin\nimportar lo que pida el caller. `purpose` opcional -- si viene, se valida contra `idv.purpose`\ny dispara el consent gate AL EMITIR (no al redimir).", "properties": { "fields": { "items": { "type": "string" }, "minItems": 1, "title": "Fields", "type": "array" }, "purpose": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Purpose" }, "reason": { "maxLength": 2000, "minLength": 1, "title": "Reason", "type": "string" }, "scope": { "const": "decrypt", "default": "decrypt", "title": "Scope", "type": "string" }, "ttlSeconds": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Ttlseconds" } }, "required": [ "fields", "reason" ], "title": "ClientTokenCreateRequest", "type": "object" }, "ClientTokenIssueResponse": { "description": "`token` (`ctok_`) se muestra UNA sola vez -- solo se persiste su hash.", "properties": { "createdAt": { "format": "date-time", "title": "Createdat", "type": "string" }, "expiresAt": { "format": "date-time", "title": "Expiresat", "type": "string" }, "fields": { "items": { "type": "string" }, "title": "Fields", "type": "array" }, "id": { "title": "Id", "type": "string" }, "object": { "const": "person.client_token", "default": "person.client_token", "title": "Object", "type": "string" }, "personId": { "title": "Personid", "type": "string" }, "purpose": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Purpose" }, "scope": { "title": "Scope", "type": "string" }, "token": { "title": "Token", "type": "string" } }, "required": [ "id", "token", "personId", "fields", "purpose", "scope", "expiresAt", "createdAt" ], "title": "ClientTokenIssueResponse", "type": "object" }, "ClientTokenRevokeResponse": { "properties": { "id": { "title": "Id", "type": "string" }, "object": { "const": "person.client_token", "default": "person.client_token", "title": "Object", "type": "string" }, "personId": { "title": "Personid", "type": "string" }, "revokedAt": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Revokedat" } }, "required": [ "id", "personId", "revokedAt" ], "title": "ClientTokenRevokeResponse", "type": "object" }, "CompanyCheckResponse": { "properties": { "checkType": { "title": "Checktype", "type": "string" }, "checkedAt": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Checkedat" }, "companyId": { "description": "Opaque company id.", "pattern": "^com_[0-9a-f]{32}$", "title": "Companyid", "type": "string" }, "createdAt": { "format": "date-time", "title": "Createdat", "type": "string" }, "id": { "description": "Opaque company check id.", "pattern": "^cck_[0-9a-f]{32}$", "title": "Id", "type": "string" }, "label": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Label" }, "result": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Result" }, "status": { "title": "Status", "type": "string" } }, "required": [ "id", "companyId", "checkType", "label", "status", "result", "checkedAt", "createdAt" ], "title": "CompanyCheckResponse", "type": "object" }, "CompanyClaimStatus": { "description": "Estado de verificación de la identidad de una empresa.", "enum": [ "unverified", "pending", "verified", "rejected" ], "title": "CompanyClaimStatus", "type": "string" }, "CompanyCreate": { "properties": { "country": { "default": "MX", "maxLength": 2, "minLength": 2, "title": "Country", "type": "string" }, "legalName": { "maxLength": 500, "minLength": 1, "title": "Legalname", "type": "string" }, "rfc": { "anyOf": [ { "maxLength": 13, "type": "string" }, { "type": "null" } ], "title": "Rfc" }, "subjectKind": { "default": "customer", "title": "Subjectkind", "type": "string" }, "tradeName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Tradename" } }, "required": [ "legalName" ], "title": "CompanyCreate", "type": "object" }, "CompanyDetail": { "description": "Detalle completo: company + grafo UBO + members + checks + documents + screening.", "properties": { "activity": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Activity" }, "checks": { "items": { "$ref": "#/components/schemas/CompanyCheckResponse" }, "title": "Checks", "type": "array" }, "claimStatus": { "title": "Claimstatus", "type": "string" }, "country": { "title": "Country", "type": "string" }, "createdAt": { "format": "date-time", "title": "Createdat", "type": "string" }, "documents": { "items": { "$ref": "#/components/schemas/CompanyDocumentResponse" }, "title": "Documents", "type": "array" }, "id": { "description": "Opaque company id.", "pattern": "^com_[0-9a-f]{32}$", "title": "Id", "type": "string" }, "incorporationDate": { "anyOf": [ { "format": "date", "type": "string" }, { "type": "null" } ], "title": "Incorporationdate" }, "industryCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Industrycode" }, "legalForm": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Legalform" }, "legalName": { "title": "Legalname", "type": "string" }, "members": { "items": { "$ref": "#/components/schemas/CompanyMemberResponse" }, "title": "Members", "type": "array" }, "networkCompanyId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Networkcompanyid" }, "registryAuthority": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Registryauthority" }, "registryId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Registryid" }, "registryStatus": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Registrystatus" }, "rfc": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Rfc" }, "riskLevel": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Risklevel" }, "riskScore": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Riskscore" }, "screeningHits": { "items": { "$ref": "#/components/schemas/ScreeningHitResponse" }, "title": "Screeninghits", "type": "array" }, "status": { "title": "Status", "type": "string" }, "subjectKind": { "title": "Subjectkind", "type": "string" }, "taxId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Taxid" }, "tenantId": { "description": "Opaque tenant id.", "pattern": "^ten_[0-9a-f]{32}$", "title": "Tenantid", "type": "string" }, "tradeName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Tradename" }, "uboNodes": { "items": { "$ref": "#/components/schemas/UboNodeResponse" }, "title": "Ubonodes", "type": "array" }, "updatedAt": { "format": "date-time", "title": "Updatedat", "type": "string" }, "verificationMethod": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Verificationmethod" }, "verifiedAt": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Verifiedat" } }, "required": [ "id", "tenantId", "legalName", "tradeName", "rfc", "country", "status", "claimStatus", "subjectKind", "riskLevel", "riskScore", "incorporationDate", "registryId", "registryAuthority", "activity", "legalForm", "industryCode", "registryStatus", "taxId", "networkCompanyId", "verifiedAt", "verificationMethod", "createdAt", "updatedAt" ], "title": "CompanyDetail", "type": "object" }, "CompanyDocumentCreate": { "description": "Registra un documento corporativo.\n\nEl binario NO se sube en este endpoint (BEL-218 scope); el cliente primero\nobtiene un presigned URL (media_storage), sube el archivo directamente y\nluego llama a este endpoint con `storageKey` + `sha256` + `kind`.", "properties": { "kind": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Kind" }, "sha256": { "anyOf": [ { "maxLength": 64, "type": "string" }, { "type": "null" } ], "title": "Sha256" }, "storageKey": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Storagekey" } }, "title": "CompanyDocumentCreate", "type": "object" }, "CompanyDocumentResponse": { "properties": { "companyId": { "description": "Opaque company id.", "pattern": "^com_[0-9a-f]{32}$", "title": "Companyid", "type": "string" }, "createdAt": { "format": "date-time", "title": "Createdat", "type": "string" }, "id": { "description": "Opaque company document id.", "pattern": "^cdc_[0-9a-f]{32}$", "title": "Id", "type": "string" }, "kind": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Kind" }, "sha256": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Sha256" }, "status": { "title": "Status", "type": "string" }, "storageKey": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Storagekey" }, "uploadedByUserId": { "anyOf": [ { "description": "Opaque user id.", "pattern": "^usr_[0-9a-f]{32}$", "type": "string" }, { "type": "null" } ], "title": "Uploadedbyuserid" } }, "required": [ "id", "companyId", "kind", "storageKey", "sha256", "status", "uploadedByUserId", "createdAt" ], "title": "CompanyDocumentResponse", "type": "object" }, "CompanyMemberCreate": { "properties": { "name": { "maxLength": 500, "minLength": 1, "title": "Name", "type": "string" }, "personId": { "anyOf": [ { "description": "Opaque person id.", "pattern": "^per_[0-9a-f]{32}$", "type": "string" }, { "type": "null" } ], "title": "Personid" }, "role": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Role" } }, "required": [ "name" ], "title": "CompanyMemberCreate", "type": "object" }, "CompanyMemberResponse": { "properties": { "companyId": { "description": "Opaque company id.", "pattern": "^com_[0-9a-f]{32}$", "title": "Companyid", "type": "string" }, "createdAt": { "format": "date-time", "title": "Createdat", "type": "string" }, "id": { "description": "Opaque company member id.", "pattern": "^cmb_[0-9a-f]{32}$", "title": "Id", "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name" }, "personId": { "anyOf": [ { "description": "Opaque person id.", "pattern": "^per_[0-9a-f]{32}$", "type": "string" }, { "type": "null" } ], "title": "Personid" }, "role": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Role" }, "verificationStatus": { "title": "Verificationstatus", "type": "string" } }, "required": [ "id", "companyId", "personId", "name", "role", "verificationStatus", "createdAt" ], "title": "CompanyMemberResponse", "type": "object" }, "CompanyResponse": { "properties": { "activity": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Activity" }, "claimStatus": { "title": "Claimstatus", "type": "string" }, "country": { "title": "Country", "type": "string" }, "createdAt": { "format": "date-time", "title": "Createdat", "type": "string" }, "id": { "description": "Opaque company id.", "pattern": "^com_[0-9a-f]{32}$", "title": "Id", "type": "string" }, "incorporationDate": { "anyOf": [ { "format": "date", "type": "string" }, { "type": "null" } ], "title": "Incorporationdate" }, "industryCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Industrycode" }, "legalForm": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Legalform" }, "legalName": { "title": "Legalname", "type": "string" }, "networkCompanyId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Networkcompanyid" }, "registryAuthority": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Registryauthority" }, "registryId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Registryid" }, "registryStatus": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Registrystatus" }, "rfc": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Rfc" }, "riskLevel": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Risklevel" }, "riskScore": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Riskscore" }, "status": { "title": "Status", "type": "string" }, "subjectKind": { "title": "Subjectkind", "type": "string" }, "taxId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Taxid" }, "tenantId": { "description": "Opaque tenant id.", "pattern": "^ten_[0-9a-f]{32}$", "title": "Tenantid", "type": "string" }, "tradeName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Tradename" }, "updatedAt": { "format": "date-time", "title": "Updatedat", "type": "string" }, "verificationMethod": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Verificationmethod" }, "verifiedAt": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Verifiedat" } }, "required": [ "id", "tenantId", "legalName", "tradeName", "rfc", "country", "status", "claimStatus", "subjectKind", "riskLevel", "riskScore", "incorporationDate", "registryId", "registryAuthority", "activity", "legalForm", "industryCode", "registryStatus", "taxId", "networkCompanyId", "verifiedAt", "verificationMethod", "createdAt", "updatedAt" ], "title": "CompanyResponse", "type": "object" }, "CompanyStatusResponse": { "properties": { "claimStatus": { "title": "Claimstatus", "type": "string" }, "id": { "description": "Opaque company id.", "pattern": "^com_[0-9a-f]{32}$", "title": "Id", "type": "string" }, "riskLevel": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Risklevel" }, "riskScore": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Riskscore" }, "status": { "title": "Status", "type": "string" } }, "required": [ "id", "claimStatus", "riskLevel", "riskScore", "status" ], "title": "CompanyStatusResponse", "type": "object" }, "CompanyVerifyResponse": { "properties": { "claimStatus": { "title": "Claimstatus", "type": "string" }, "id": { "description": "Opaque company id.", "pattern": "^com_[0-9a-f]{32}$", "title": "Id", "type": "string" }, "riskLevel": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Risklevel" }, "riskScore": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Riskscore" }, "status": { "title": "Status", "type": "string" }, "verifiedAt": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Verifiedat" } }, "required": [ "id", "claimStatus", "riskLevel", "riskScore", "status", "verifiedAt" ], "title": "CompanyVerifyResponse", "type": "object" }, "ComplianceReport": { "description": "`GET /v1/compliance/reports?type=nom024|cnbv` -- expediente MÍNIMO pero correcto (JSON\ninline). Un generador de PDF formal es follow-up (BEL-424 docstring del router).", "properties": { "auditChain": { "$ref": "#/components/schemas/AuditChainSummary" }, "datacenters": { "items": { "$ref": "#/components/schemas/DatacenterItem" }, "title": "Datacenters", "type": "array" }, "generatedAt": { "format": "date-time", "title": "Generatedat", "type": "string" }, "object": { "const": "compliance.report", "default": "compliance.report", "title": "Object", "type": "string" }, "retentionPolicies": { "items": { "$ref": "#/components/schemas/RetentionPolicyItem" }, "title": "Retentionpolicies", "type": "array" }, "subprocessors": { "items": { "$ref": "#/components/schemas/SubprocessorItem" }, "title": "Subprocessors", "type": "array" }, "type": { "enum": [ "nom024", "cnbv" ], "title": "Type", "type": "string" }, "verificationVolume": { "$ref": "#/components/schemas/VerificationVolumeSummary" } }, "required": [ "type", "generatedAt", "subprocessors", "datacenters", "retentionPolicies", "auditChain", "verificationVolume" ], "title": "ComplianceReport", "type": "object" }, "ConsentAttestedBy": { "description": "Quién atestigua un `idv.person_consent` — mismo vocabulario que el `attested_by` string\nde `app/services/consent.py` (evento `consent.granted` de la sesión), ahora materializado\ncomo catálogo TEXT+CHECK para la fila durable de `idv.person_consent`.", "enum": [ "applicant", "integrator" ], "title": "ConsentAttestedBy", "type": "string" }, "ConsentEvidenceInput": { "description": "Datos del TITULAR (no del server) reenviados por el integrador -- mismo criterio que\n`ConsentRequest` de `app/schemas/applicant.py` (BEL-382). Todos opcionales: solo lo\nefectivamente presente se cifra en `evidence_enc` (nunca se fabrica).", "properties": { "consentedAt": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Consentedat" }, "subjectIp": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Subjectip" }, "subjectUserAgent": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Subjectuseragent" } }, "title": "ConsentEvidenceInput", "type": "object" }, "ConsentGrantRequest": { "description": "`POST /v1/persons/{id}/consents`. `purpose` se valida contra `idv.purpose` (400\n`purpose_unknown` si no existe); `mechanism` es un `Literal` de Pydantic (422 si no calza).\n`attestedBy`: si no viene, el default lo resuelve el endpoint (`integrator` si\n`auth.actor_type == API_KEY`, `applicant` en cualquier otro caso -- LOCKED #7).\n\nSin `sessionId` (BEL-422 adversarial review, finding 3, removido a propósito): un grant\ndirecto por este endpoint SIEMPRE persiste `session_id=None` (`grant_consent`,\n`app/services/person_consent_service.py`) -- session-linked consents nacen SOLO del\ndual-write de `record_consent`/`project_structural_consent`. Aceptar un `sessionId`\nclient-supplied permitía pegarle al único parcial GLOBAL `uq_person_consent_session_purpose\n(session_id, purpose)` (500 sin capturar) e incluso colisionar entre tenants.", "properties": { "attestedBy": { "anyOf": [ { "$ref": "#/components/schemas/ConsentAttestedBy" }, { "type": "null" } ] }, "evidence": { "anyOf": [ { "$ref": "#/components/schemas/ConsentEvidenceInput" }, { "type": "null" } ] }, "expiresAt": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Expiresat" }, "mechanism": { "$ref": "#/components/schemas/ConsentMechanism" }, "policyVersion": { "maxLength": 32, "minLength": 1, "title": "Policyversion", "type": "string" }, "purpose": { "maxLength": 64, "minLength": 1, "title": "Purpose", "type": "string" } }, "required": [ "purpose", "mechanism", "policyVersion" ], "title": "ConsentGrantRequest", "type": "object" }, "ConsentItem": { "description": "Item de lectura -- `evidence` NUNCA se incluye (write-only, LOCKED #7).", "properties": { "attestedBy": { "title": "Attestedby", "type": "string" }, "createdAt": { "format": "date-time", "title": "Createdat", "type": "string" }, "expiresAt": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Expiresat" }, "grantedAt": { "format": "date-time", "title": "Grantedat", "type": "string" }, "id": { "title": "Id", "type": "string" }, "mechanism": { "title": "Mechanism", "type": "string" }, "object": { "const": "person.consent", "default": "person.consent", "title": "Object", "type": "string" }, "policyVersion": { "title": "Policyversion", "type": "string" }, "purpose": { "title": "Purpose", "type": "string" }, "revokedAt": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Revokedat" } }, "required": [ "id", "purpose", "mechanism", "attestedBy", "policyVersion", "grantedAt", "expiresAt", "revokedAt", "createdAt" ], "title": "ConsentItem", "type": "object" }, "ConsentMechanism": { "description": "Mecanismo de captura de un `idv.person_consent` (BEL-422, Persons Vault F1.4 — catálogo\nde finalidad/consentimiento, DESACOPLADO de `ConsentMethod` — ese es el mecanismo de REUSO\ncross-tenant de una identidad de red, passkey/biometric/otp; este es el mecanismo con el que\nla PERSONA otorgó un consentimiento concreto de acceso/tratamiento sobre su propio\nexpediente).", "enum": [ "firma_electronica", "autenticacion" ], "title": "ConsentMechanism", "type": "string" }, "ConsentRecord": { "description": "Registro de consentimiento LFPDPPP del solicitante (cuándo + versión aceptada). BEL-199.\n\nBEL-382: en el canal API-direct S2S, `attested_by=\"integrator\"` + los datos del TITULAR real\n(ip/ua/consentedAt) que el backend del integrador reenvió — para que el expediente NOM-151\nrefleje quién consintió, no el server de Belfort. En el canal del applicant son None.", "properties": { "attestedBy": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Attestedby" }, "consentedAt": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Consentedat" }, "grantedAt": { "format": "date-time", "title": "Grantedat", "type": "string" }, "policyVersion": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Policyversion" }, "subjectIpAddress": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Subjectipaddress" }, "subjectUserAgent": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Subjectuseragent" } }, "required": [ "grantedAt", "policyVersion" ], "title": "ConsentRecord", "type": "object" }, "ConsentRequest": { "properties": { "accepted": { "title": "Accepted", "type": "boolean" }, "consentedAt": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Consentedat" }, "policyVersion": { "default": "v1", "title": "Policyversion", "type": "string" }, "subjectIpAddress": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Subjectipaddress" }, "subjectUserAgent": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Subjectuseragent" } }, "required": [ "accepted" ], "title": "ConsentRequest", "type": "object" }, "ConsentResponse": { "properties": { "consentGiven": { "title": "Consentgiven", "type": "boolean" }, "recordedAt": { "format": "date-time", "title": "Recordedat", "type": "string" }, "status": { "title": "Status", "type": "string" } }, "required": [ "status", "consentGiven", "recordedAt" ], "title": "ConsentResponse", "type": "object" }, "ConsolidateMergeRef": { "description": "Una fuente encolada dentro de la consolidación (aún `pending` al responder el 202).", "properties": { "mergeId": { "title": "Mergeid", "type": "string" }, "mergedId": { "title": "Mergedid", "type": "string" } }, "required": [ "mergeId", "mergedId" ], "title": "ConsolidateMergeRef", "type": "object" }, "ConsolidateRequest": { "description": "`POST /v1/persons/{id}/consolidate` -- `{id}` es el survivor. Cada `sourcePersonIds[i]`\nse tombstonea (`status='merged'`) y sus hijos se re-apuntan al survivor (async, vía Temporal).\n`fieldResolutions` es opcional (default `{}`) -- se persiste como bitácora de la intención\ndeclarada, nunca se aplica a la PII del survivor (R2 LOCKED, el survivor conserva su propia\nPII tal cual).", "properties": { "fieldResolutions": { "additionalProperties": { "type": "string" }, "title": "Fieldresolutions", "type": "object" }, "sourcePersonIds": { "items": { "type": "string" }, "minItems": 1, "title": "Sourcepersonids", "type": "array" } }, "required": [ "sourcePersonIds" ], "title": "ConsolidateRequest", "type": "object" }, "ConsolidationEnvelope": { "description": "Respuesta `202` de `POST /v1/persons/{id}/consolidate` -- SIEMPRE `status='pending'` (el\nmerge real corre async vía `ConsolidateWorkflow`; el caller poll-ea\n`GET .../consolidations/{consolidationId}` para el resultado).", "properties": { "consolidationId": { "title": "Consolidationid", "type": "string" }, "merges": { "items": { "$ref": "#/components/schemas/ConsolidateMergeRef" }, "title": "Merges", "type": "array" }, "object": { "const": "person.consolidation", "default": "person.consolidation", "title": "Object", "type": "string" }, "status": { "title": "Status", "type": "string" }, "survivorId": { "title": "Survivorid", "type": "string" } }, "required": [ "consolidationId", "survivorId", "status", "merges" ], "title": "ConsolidationEnvelope", "type": "object" }, "ConsolidationMergeStatusItem": { "description": "Progreso de UNA fuente dentro de la consolidación (`idv.person_merge`, una fila).", "properties": { "completedAt": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Completedat" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error" }, "mergeId": { "title": "Mergeid", "type": "string" }, "mergedId": { "title": "Mergedid", "type": "string" }, "status": { "title": "Status", "type": "string" } }, "required": [ "mergeId", "mergedId", "status", "error", "completedAt" ], "title": "ConsolidationMergeStatusItem", "type": "object" }, "ConsolidationStatusResponse": { "description": "`GET /v1/persons/{id}/consolidations/{consolidationId}` -- `status` es el AGREGADO de\ntodas las filas (`done` solo si TODAS terminaron `done`; `failed` si alguna falló; si no,\n`processing`/`pending` -- ver `consolidate_service.aggregate_status`).", "properties": { "consolidationId": { "title": "Consolidationid", "type": "string" }, "createdAt": { "format": "date-time", "title": "Createdat", "type": "string" }, "merges": { "items": { "$ref": "#/components/schemas/ConsolidationMergeStatusItem" }, "title": "Merges", "type": "array" }, "object": { "const": "person.consolidation", "default": "person.consolidation", "title": "Object", "type": "string" }, "status": { "title": "Status", "type": "string" }, "survivorId": { "title": "Survivorid", "type": "string" } }, "required": [ "consolidationId", "survivorId", "status", "merges", "createdAt" ], "title": "ConsolidationStatusResponse", "type": "object" }, "DatacenterItem": { "properties": { "certifications": { "items": { "type": "string" }, "title": "Certifications", "type": "array" }, "country": { "title": "Country", "type": "string" }, "provider": { "title": "Provider", "type": "string" }, "region": { "title": "Region", "type": "string" } }, "required": [ "provider", "region", "country", "certifications" ], "title": "DatacenterItem", "type": "object" }, "DatacenterList": { "properties": { "data": { "items": { "$ref": "#/components/schemas/DatacenterItem" }, "title": "Data", "type": "array" }, "object": { "const": "list", "default": "list", "title": "Object", "type": "string" } }, "required": [ "data" ], "title": "DatacenterList", "type": "object" }, "DecisionItem": { "properties": { "decidedAt": { "format": "date-time", "title": "Decidedat", "type": "string" }, "decidedBy": { "title": "Decidedby", "type": "string" }, "decidedByUserId": { "anyOf": [ { "description": "Opaque user id.", "pattern": "^usr_[0-9a-f]{32}$", "type": "string" }, { "type": "null" } ], "title": "Decidedbyuserid" }, "isCurrent": { "title": "Iscurrent", "type": "boolean" }, "outcome": { "title": "Outcome", "type": "string" }, "reasonCodes": { "anyOf": [ { "items": {}, "type": "array" }, { "type": "null" } ], "title": "Reasoncodes" } }, "required": [ "outcome", "decidedBy", "decidedByUserId", "reasonCodes", "isCurrent", "decidedAt" ], "title": "DecisionItem", "type": "object" }, "DecisionOutcome": { "enum": [ "approved", "declined", "review" ], "title": "DecisionOutcome", "type": "string" }, "DecisionSummary": { "properties": { "outcome": { "$ref": "#/components/schemas/DecisionOutcome" }, "reasonCodes": { "items": { "type": "string" }, "title": "Reasoncodes", "type": "array" } }, "required": [ "outcome", "reasonCodes" ], "title": "DecisionSummary", "type": "object" }, "DecryptRequest": { "description": "`reason` es REQUERIDO (min_length=1, 422 si falta) -- deliberadamente más estricto que\n`expand=pii.` (donde `reason` solo aplica al canal API key), porque este es el reveal\nS2S EXPLÍCITO, no una vista de conveniencia del dashboard.", "properties": { "fields": { "items": { "type": "string" }, "minItems": 1, "title": "Fields", "type": "array" }, "purpose": { "title": "Purpose", "type": "string" }, "reason": { "maxLength": 2000, "minLength": 1, "title": "Reason", "type": "string" } }, "required": [ "fields", "purpose", "reason" ], "title": "DecryptRequest", "type": "object" }, "DecryptResponse": { "properties": { "fields": { "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "title": "Fields", "type": "object" }, "object": { "const": "person.decrypt", "default": "person.decrypt", "title": "Object", "type": "string" }, "personId": { "title": "Personid", "type": "string" } }, "required": [ "personId", "fields" ], "title": "DecryptResponse", "type": "object" }, "DecryptSlo": { "description": "SLO operativo del reveal S2S canónico -- meta interna, no un compromiso contractual.", "properties": { "description": { "title": "Description", "type": "string" }, "targetAvailability": { "title": "Targetavailability", "type": "number" }, "targetP95LatencyMs": { "title": "Targetp95Latencyms", "type": "integer" } }, "required": [ "targetAvailability", "targetP95LatencyMs", "description" ], "title": "DecryptSlo", "type": "object" }, "DeliveryStatus": { "enum": [ "pending", "sent", "failed" ], "title": "DeliveryStatus", "type": "string" }, "DeviceTrustSummary": { "description": "Sub-objeto `deviceTrust` del contrato saliente (BEL-490).\n\nProyección PII-free de las señales de confianza del dispositivo ya calculadas upstream\n(`idv.device_probe_check` + `idv.media_asset.capture_platform`). Aditivo: si la sesión no\nreportó probe ni plataforma de captura, el bloque puede ser `null`.", "properties": { "attested": { "default": false, "title": "Attested", "type": "boolean" }, "capturePlatform": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Captureplatform" }, "deviceRisk": { "default": 0, "maximum": 100, "minimum": 0, "title": "Devicerisk", "type": "integer" }, "hardFailReasons": { "items": { "type": "string" }, "title": "Hardfailreasons", "type": "array" } }, "title": "DeviceTrustSummary", "type": "object" }, "DocumentSummary": { "description": "Sub-objeto `document` del contrato saliente (BEL-doc-universal).\n\nFuente única: la fila `Document` de la sesión (`build_verification_report`, no recomputa).\n`type` es la FAMILIA canónica (`ine`/`passport`/`driver_license`/`national_id`/el coarse\n`Document.type` como fallback si `detected_type` aún no se clasificó); `issuing_country` el\npaís emisor si el idv lo reportó; `detected` si hubo clasificación. Presente en flows INE\n(`type=\"ine\"`, inofensivo) y en universal — mismo shape en `/verify` y el webhook.", "properties": { "detected": { "title": "Detected", "type": "boolean" }, "issuingCountry": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Issuingcountry" }, "type": { "title": "Type", "type": "string" } }, "required": [ "type", "detected" ], "title": "DocumentSummary", "type": "object" }, "DuplicateItem": { "description": "Un candidato a duplicado de la Person consultada (sugerencia, no fusión -- humano\nconfirma vía `POST .../consolidate`). `person` viaja masked (mismo contrato que\n`GET /v1/persons`, sin PII en claro).", "properties": { "matchReason": { "enum": [ "curp_match", "email_match" ], "title": "Matchreason", "type": "string" }, "person": { "$ref": "#/components/schemas/PersonListItem" } }, "required": [ "person", "matchReason" ], "title": "DuplicateItem", "type": "object" }, "DuplicatesResponse": { "properties": { "data": { "items": { "$ref": "#/components/schemas/DuplicateItem" }, "title": "Data", "type": "array" }, "object": { "const": "list", "default": "list", "title": "Object", "type": "string" } }, "required": [ "data" ], "title": "DuplicatesResponse", "type": "object" }, "EmbeddedBrowserSessionCreate": { "description": "Create client-side (Tier 1, publishable key): el browser monta `Belfort.mount({key, flow})`.\n\nFLOW-ONLY por seguridad: a diferencia de EmbeddedSessionCreateV2 NO admite policy/checks/\ntest_mode (eso bajaría umbrales o saltaría checks desde el cliente). `flow` es la KEY de un\nflow PUBLICADO del tenant; `allowedOrigins` es obligatorio (HTTPS, salvo localhost en dev).\n\n`flow` es opcional desde BEL-362: si la `Application` dueña de la key define\n`default_flow_id`, `Belfort.mount({key})` sin `flow` hereda ese default (ver\n`create_browser_embedded_session_endpoint`). Sin default configurado, `flow` sigue siendo\nobligatorio — mismo comportamiento que antes de este ticket (422 `flow_required`).", "properties": { "allowedOrigins": { "items": { "type": "string" }, "minItems": 1, "title": "Allowedorigins", "type": "array" }, "clientReference": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "title": "Clientreference" }, "country": { "default": "MX", "maxLength": 2, "minLength": 2, "title": "Country", "type": "string" }, "flow": { "anyOf": [ { "maxLength": 120, "minLength": 1, "type": "string" }, { "type": "null" } ], "title": "Flow" }, "locale": { "default": "es", "title": "Locale", "type": "string" } }, "required": [ "allowedOrigins" ], "title": "EmbeddedBrowserSessionCreate", "type": "object" }, "EmbeddedDecisionSummary": { "description": "Decisión resumida en la respuesta de verify.", "properties": { "outcome": { "$ref": "#/components/schemas/DecisionOutcome" }, "reasonCodes": { "items": { "type": "string" }, "title": "Reasoncodes", "type": "array" } }, "required": [ "outcome", "reasonCodes" ], "title": "EmbeddedDecisionSummary", "type": "object" }, "EmbeddedInitRequest": { "description": "Body del POST /v1/embedded/sessions/init (sin auth de API key — el secret es la auth).", "properties": { "clientSecret": { "minLength": 10, "title": "Clientsecret", "type": "string" }, "parentOrigin": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Parentorigin" } }, "required": [ "clientSecret" ], "title": "EmbeddedInitRequest", "type": "object" }, "EmbeddedInitResponse": { "description": "Respuesta del /init: el iframe recibe el applicant_token para operar la verificación.", "properties": { "allowedOrigins": { "items": { "type": "string" }, "title": "Allowedorigins", "type": "array" }, "applicantToken": { "title": "Applicanttoken", "type": "string" }, "expiresAt": { "format": "date-time", "title": "Expiresat", "type": "string" }, "requiresApp": { "default": false, "title": "Requiresapp", "type": "boolean" }, "sessionId": { "description": "Opaque embedded session id.", "pattern": "^ems_[0-9a-f]{32}$", "title": "Sessionid", "type": "string" }, "status": { "title": "Status", "type": "string" }, "verificationSessionId": { "title": "Verificationsessionid", "type": "string" } }, "required": [ "sessionId", "applicantToken", "status", "expiresAt", "verificationSessionId", "allowedOrigins" ], "title": "EmbeddedInitResponse", "type": "object" }, "EmbeddedPolicyResponse": { "description": "GET /v1/embedded/sessions/{id}/policy — CSP frame-ancestors dinámico.", "properties": { "allowedOrigins": { "items": { "type": "string" }, "title": "Allowedorigins", "type": "array" }, "frameAncestors": { "title": "Frameancestors", "type": "string" }, "sessionId": { "description": "Opaque embedded session id.", "pattern": "^ems_[0-9a-f]{32}$", "title": "Sessionid", "type": "string" } }, "required": [ "sessionId", "allowedOrigins", "frameAncestors" ], "title": "EmbeddedPolicyResponse", "type": "object" }, "EmbeddedSessionCreateResponse": { "description": "201 del POST /v1/embedded/sessions con API key. El client_secret se devuelve ONCE.", "properties": { "allowedOrigins": { "items": { "type": "string" }, "title": "Allowedorigins", "type": "array" }, "clientSecret": { "title": "Clientsecret", "type": "string" }, "expiresAt": { "format": "date-time", "title": "Expiresat", "type": "string" }, "id": { "description": "Opaque embedded session id.", "pattern": "^ems_[0-9a-f]{32}$", "title": "Id", "type": "string" }, "personId": { "anyOf": [ { "description": "Opaque person id.", "pattern": "^per_[0-9a-f]{32}$", "type": "string" }, { "type": "null" } ], "title": "Personid" }, "status": { "title": "Status", "type": "string" } }, "required": [ "id", "clientSecret", "expiresAt", "allowedOrigins", "status" ], "title": "EmbeddedSessionCreateResponse", "type": "object" }, "EmbeddedSessionCreateV2": { "description": "Crea una sesión embebida con API key (BEL-147).", "properties": { "allowedOrigins": { "items": { "type": "string" }, "title": "Allowedorigins", "type": "array" }, "callbackUrl": { "anyOf": [ { "format": "uri", "maxLength": 2083, "minLength": 1, "type": "string" }, { "type": "null" } ], "title": "Callbackurl" }, "checks": { "anyOf": [ { "$ref": "#/components/schemas/CheckSelectionInput" }, { "type": "null" } ] }, "clientReference": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "title": "Clientreference" }, "country": { "default": "MX", "maxLength": 2, "minLength": 2, "title": "Country", "type": "string" }, "flowId": { "anyOf": [ { "description": "Opaque flow id.", "pattern": "^flw_[0-9a-f]{32}$", "type": "string" }, { "type": "null" } ], "title": "Flowid" }, "locale": { "default": "es", "title": "Locale", "type": "string" }, "notificationsMode": { "default": "belfort_managed", "enum": [ "belfort_managed", "integrator_managed" ], "title": "Notificationsmode", "type": "string" }, "personId": { "anyOf": [ { "description": "Opaque person id.", "pattern": "^per_[0-9a-f]{32}$", "type": "string" }, { "type": "null" } ], "title": "Personid" }, "policy": { "anyOf": [ { "$ref": "#/components/schemas/PolicyOverrideInput" }, { "type": "null" } ] }, "testMode": { "default": false, "deprecated": true, "description": "DEPRECADO: el modo test/live lo fija el environment de la API key. Con una key live, test_mode=true devuelve 400.", "title": "Testmode", "type": "boolean" } }, "title": "EmbeddedSessionCreateV2", "type": "object" }, "EmbeddedVerifyResponse": { "description": "POST /v1/embedded/sessions/{id}/verify — estado final + resultado.\n\n`id` es el `ems_...` de la `EmbeddedSession` cuando existe (el consumidor correlaciona el\nwebhook por él: `module_data->>'belfort_session_id'`), o el `vrf_...` (STORED) de la\n`VerificationSession` para canales no-embebidos -- ver `verification_report.\nbuild_verification_report`. Nunca el UUID interno de ninguna de las dos (rule #5); el tipo es\n`str` liso porque el prefijo varía según el canal, no un solo `_schema()` fijo.", "properties": { "allowedOrigins": { "items": { "type": "string" }, "title": "Allowedorigins", "type": "array" }, "biometricMatch": { "anyOf": [ { "$ref": "#/components/schemas/BiometricMatchSummary" }, { "type": "null" } ] }, "clientReference": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Clientreference" }, "completedAt": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Completedat" }, "createdAt": { "format": "date-time", "title": "Createdat", "type": "string" }, "decision": { "anyOf": [ { "$ref": "#/components/schemas/EmbeddedDecisionSummary" }, { "type": "null" } ] }, "decisionMode": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decisionmode" }, "deviceTrust": { "anyOf": [ { "$ref": "#/components/schemas/DeviceTrustSummary" }, { "type": "null" } ] }, "document": { "anyOf": [ { "$ref": "#/components/schemas/DocumentSummary" }, { "type": "null" } ] }, "expiresAt": { "format": "date-time", "title": "Expiresat", "type": "string" }, "gov": { "items": { "$ref": "#/components/schemas/GovCheckWire" }, "title": "Gov", "type": "array" }, "humanReviewAvailable": { "default": false, "title": "Humanreviewavailable", "type": "boolean" }, "id": { "title": "Id", "type": "string" }, "isFinal": { "title": "Isfinal", "type": "boolean" }, "mountedAt": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Mountedat" }, "personId": { "anyOf": [ { "description": "Opaque person id.", "pattern": "^per_[0-9a-f]{32}$", "type": "string" }, { "type": "null" } ], "title": "Personid" }, "phase": { "$ref": "#/components/schemas/VerifyPhase" }, "reuse": { "anyOf": [ { "$ref": "#/components/schemas/ReuseSummary" }, { "type": "null" } ] }, "status": { "title": "Status", "type": "string" }, "trustScore": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Trustscore" }, "verificationStatus": { "title": "Verificationstatus", "type": "string" } }, "required": [ "id", "status", "verificationStatus", "phase", "isFinal", "createdAt", "mountedAt", "completedAt", "expiresAt", "allowedOrigins", "decision", "trustScore" ], "title": "EmbeddedVerifyResponse", "type": "object" }, "EvidenceBundle": { "description": "Bundle que AllSign consulta al cierre de una verificación para respaldar su firma NOM-151.\n\nReúne el veredicto (decisión + reason codes + trustScore), los scores biométricos, las refs de\nmedia firmadas, el registro de consentimiento y los checks gubernamentales (Lista Nominal).\nRead-only; tenant-scoped (API key sk_).", "properties": { "biometric": { "items": { "$ref": "#/components/schemas/BiometricCheckItem" }, "title": "Biometric", "type": "array" }, "completedAt": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Completedat" }, "consent": { "anyOf": [ { "$ref": "#/components/schemas/ConsentRecord" }, { "type": "null" } ] }, "createdAt": { "format": "date-time", "title": "Createdat", "type": "string" }, "decision": { "anyOf": [ { "$ref": "#/components/schemas/DecisionSummary" }, { "type": "null" } ] }, "document": { "anyOf": [ { "$ref": "#/components/schemas/DocumentSummary" }, { "type": "null" } ] }, "gov": { "items": { "$ref": "#/components/schemas/app__schemas__verification__GovLookupItem" }, "title": "Gov", "type": "array" }, "media": { "items": { "$ref": "#/components/schemas/MediaRef" }, "title": "Media", "type": "array" }, "reuse": { "anyOf": [ { "$ref": "#/components/schemas/ReuseSummary" }, { "type": "null" } ] }, "scores": { "$ref": "#/components/schemas/BiometricScores" }, "sessionId": { "title": "Sessionid", "type": "string" }, "trustScore": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Trustscore" }, "verificationStatus": { "$ref": "#/components/schemas/VerificationStatus" } }, "required": [ "sessionId", "verificationStatus", "decision", "trustScore", "scores", "media", "consent", "createdAt", "completedAt" ], "title": "EvidenceBundle", "type": "object" }, "ExportMediaItem": { "description": "Referencia firmada (TTL corto) a UN asset de media del titular -- mismo mecanismo que el\nevidence bundle (BEL-199, `media_signing.signed_media_url`), nunca los bytes crudos.", "properties": { "assetId": { "title": "Assetid", "type": "string" }, "contentType": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Contenttype" }, "createdAt": { "format": "date-time", "title": "Createdat", "type": "string" }, "kind": { "title": "Kind", "type": "string" }, "url": { "title": "Url", "type": "string" } }, "required": [ "assetId", "kind", "contentType", "createdAt", "url" ], "title": "ExportMediaItem", "type": "object" }, "ExportSessionItem": { "description": "Inventario de sesiones de verificación del titular (sin PII, solo metadatos).", "properties": { "createdAt": { "format": "date-time", "title": "Createdat", "type": "string" }, "environment": { "title": "Environment", "type": "string" }, "id": { "title": "Id", "type": "string" }, "publicId": { "title": "Publicid", "type": "string" }, "status": { "title": "Status", "type": "string" } }, "required": [ "id", "publicId", "status", "environment", "createdAt" ], "title": "ExportSessionItem", "type": "object" }, "GovCheckWire": { "description": "Una consulta a fuente GUBERNAMENTAL, en el contrato caliente (⑥). Dos campos, a propósito.\n\nEs deliberadamente MÁS POBRE que `GovLookupItem` (el del `/report` y el `EvidenceBundle`), que\nlleva `queriedAt`, `latencyMs`, `providerRequestId` y el `detail` curado. La diferencia no es\npereza: son dos preguntas distintas. Aquí se contesta *«¿dejo pasar a este cliente AHORA?»*, y\npara eso el folio de Nubarium no aporta nada — sólo peso en un endpoint que se consulta en\nbucle. El auditor que sí necesita el folio lo tiene en las otras dos superficies.\n\n`result` NO es un booleano: es el vocabulario completo de `GovLookupResult`\n(`match`/`no_match`/`not_found`/`error`/`pending`). Un integrador que quiera saber si la INE\nquedó validada busca `provider == \"ine_lista_nominal\"` y `result == \"match\"`; los otros cuatro\nvalores son situaciones distintas —el padrón no la encontró, el proveedor falló, aún no\ncorre— y colapsarlas a un `false` haría indistinguible \"no está vigente\" de \"no pudimos\npreguntar\".", "properties": { "provider": { "title": "Provider", "type": "string" }, "result": { "title": "Result", "type": "string" } }, "required": [ "provider", "result" ], "title": "GovCheckWire", "type": "object" }, "GrantCreateRequest": { "description": "`POST /v1/persons/{id}/grants` -- create-or-REPLACE por `(person, applicationId)`.\n`applicationId` se valida anti-IDOR (`assert_application_owned`); cada `allowedPurposes` debe\nexistir en `idv.purpose` (400 `purpose_unknown`).", "properties": { "allowedFields": { "items": { "type": "string" }, "minItems": 1, "title": "Allowedfields", "type": "array" }, "allowedPurposes": { "items": { "type": "string" }, "minItems": 1, "title": "Allowedpurposes", "type": "array" }, "applicationId": { "description": "Opaque application id.", "pattern": "^app_[0-9a-f]{32}$", "title": "Applicationid", "type": "string" }, "defaultRedaction": { "$ref": "#/components/schemas/GrantRedaction", "default": "masked" }, "expiresAt": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Expiresat" } }, "required": [ "applicationId", "allowedFields", "allowedPurposes" ], "title": "GrantCreateRequest", "type": "object" }, "GrantItem": { "properties": { "allowedFields": { "items": { "type": "string" }, "title": "Allowedfields", "type": "array" }, "allowedPurposes": { "items": { "type": "string" }, "title": "Allowedpurposes", "type": "array" }, "applicationId": { "description": "Opaque application id.", "pattern": "^app_[0-9a-f]{32}$", "title": "Applicationid", "type": "string" }, "createdAt": { "format": "date-time", "title": "Createdat", "type": "string" }, "createdVia": { "title": "Createdvia", "type": "string" }, "defaultRedaction": { "title": "Defaultredaction", "type": "string" }, "expiresAt": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Expiresat" }, "id": { "title": "Id", "type": "string" }, "object": { "const": "person.grant", "default": "person.grant", "title": "Object", "type": "string" }, "revokedAt": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Revokedat" } }, "required": [ "id", "applicationId", "allowedFields", "allowedPurposes", "defaultRedaction", "createdVia", "expiresAt", "revokedAt", "createdAt" ], "title": "GrantItem", "type": "object" }, "GrantRedaction": { "description": "Redacción DEFAULT de un `idv.person_grant` (BEL-423, ARCO-as-API + grants per Application).\n\nDistinto de `PiiRedaction` (2 valores, `plain`/`masked` -- lo que YA se sirvió/auditó en un\nacceso concreto): este es el default DECLARADO en el grant para el consumo cross-Application\nde un campo. `redacted` (tercer valor, sin equivalente en `PiiRedaction`) = el campo se OMITE\nenteramente del export -- nunca se revela, ni siquiera enmascarado; no genera fila de\nauditoría (no hay revelación que registrar).", "enum": [ "plain", "masked", "redacted" ], "title": "GrantRedaction", "type": "string" }, "IntegrityFieldResult": { "description": "`match`: el HMAC recomputado coincide con el provisto. `present`: la Person tiene ese\ncampo (si `present=False`, `match` es SIEMPRE `False` -- no hay nada que comparar).", "properties": { "match": { "title": "Match", "type": "boolean" }, "present": { "title": "Present", "type": "boolean" } }, "required": [ "match", "present" ], "title": "IntegrityFieldResult", "type": "object" }, "IntegrityRequest": { "description": "`POST /v1/persons/{id}/integrity`. `fields`: `{campo camelCase: hmac hex esperado}` --\nlas KEYS del dict NO pasan por el alias generator de pydantic (solo los nombres de campo del\nmodelo lo hacen), así que viajan tal cual las mandó el integrador (`\"claveElector\"`, no\n`\"clave_elector\"`). `reason` (opcional, LOCKED #1): motivo de negocio del chequeo -- si no\nviene, el evento de auditoría usa `\"integrity_check\"` por default.", "properties": { "fields": { "additionalProperties": { "type": "string" }, "title": "Fields", "type": "object" }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Reason" }, "signingKey": { "maxLength": 256, "minLength": 1, "title": "Signingkey", "type": "string" } }, "required": [ "signingKey", "fields" ], "title": "IntegrityRequest", "type": "object" }, "IntegrityResponse": { "properties": { "id": { "title": "Id", "type": "string" }, "object": { "const": "person.integrity", "default": "person.integrity", "title": "Object", "type": "string" }, "results": { "additionalProperties": { "$ref": "#/components/schemas/IntegrityFieldResult" }, "title": "Results", "type": "object" } }, "required": [ "id", "results" ], "title": "IntegrityResponse", "type": "object" }, "LegalHoldItem": { "description": "Una fila de `idv.person_legal_hold`. `action` distingue `set`/`release` -- el item MÁS\nRECIENTE (primero de `GET .../legal-holds`, orden desc por `createdAt`) indica el estado\nvigente: `action='set'` sin una fila `release` posterior => `Person.legal_hold=true`.", "properties": { "action": { "title": "Action", "type": "string" }, "createdAt": { "format": "date-time", "title": "Createdat", "type": "string" }, "expiresAt": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Expiresat" }, "id": { "title": "Id", "type": "string" }, "legalBasis": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Legalbasis" }, "object": { "const": "person.legal_hold", "default": "person.legal_hold", "title": "Object", "type": "string" }, "personId": { "title": "Personid", "type": "string" }, "reason": { "title": "Reason", "type": "string" } }, "required": [ "id", "personId", "action", "reason", "legalBasis", "expiresAt", "createdAt" ], "title": "LegalHoldItem", "type": "object" }, "LegalHoldReleaseRequest": { "description": "`POST /v1/persons/{id}/legal-hold/release`. `reason` OBLIGATORIO (422 si falta o viene\nvacío) -- por qué se levanta el hold. `legalBasis` opcional (no siempre aplica una base\nlegal concreta para LEVANTAR un hold, p.ej. \"litigio resuelto\").", "properties": { "legalBasis": { "anyOf": [ { "maxLength": 256, "type": "string" }, { "type": "null" } ], "title": "Legalbasis" }, "reason": { "maxLength": 2000, "minLength": 1, "title": "Reason", "type": "string" } }, "required": [ "reason" ], "title": "LegalHoldReleaseRequest", "type": "object" }, "LegalHoldSetRequest": { "description": "`POST /v1/persons/{id}/legal-hold`. `reason`/`legalBasis` OBLIGATORIOS (422 si faltan o\nvienen vacíos) -- un legal hold sin motivo ni base legal documentada no es defendible ante\nuna auditoría/disputa. `expiresAt` opcional (hold indefinido, hasta un `release` explícito,\nsi no viene).", "properties": { "expiresAt": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Expiresat" }, "legalBasis": { "maxLength": 256, "minLength": 1, "title": "Legalbasis", "type": "string" }, "reason": { "maxLength": 2000, "minLength": 1, "title": "Reason", "type": "string" } }, "required": [ "reason", "legalBasis" ], "title": "LegalHoldSetRequest", "type": "object" }, "ListEnvelope_AuditLogEntry_": { "properties": { "data": { "items": { "$ref": "#/components/schemas/AuditLogEntry" }, "title": "Data", "type": "array" }, "hasMore": { "description": "`true` si quedan resultados después de esta página.", "title": "Hasmore", "type": "boolean" }, "limit": { "description": "El límite realmente aplicado (puede ser menor al pedido).", "title": "Limit", "type": "integer" }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Pásalo como `startingAfter` para la siguiente página.", "title": "Nextcursor" }, "object": { "const": "list", "default": "list", "title": "Object", "type": "string" }, "previousCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Pásalo como `endingBefore` para la página anterior.", "title": "Previouscursor" }, "totalCount": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Total de coincidencias. Solo se calcula si pides `includeTotal=true` — es un `COUNT(*)` sobre el filtro entero y no se cobra a quien no lo necesita.", "title": "Totalcount" } }, "required": [ "data", "hasMore", "limit" ], "title": "ListEnvelope[AuditLogEntry]", "type": "object" }, "ListEnvelope_CompanyResponse_": { "properties": { "data": { "items": { "$ref": "#/components/schemas/CompanyResponse" }, "title": "Data", "type": "array" }, "hasMore": { "description": "`true` si quedan resultados después de esta página.", "title": "Hasmore", "type": "boolean" }, "limit": { "description": "El límite realmente aplicado (puede ser menor al pedido).", "title": "Limit", "type": "integer" }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Pásalo como `startingAfter` para la siguiente página.", "title": "Nextcursor" }, "object": { "const": "list", "default": "list", "title": "Object", "type": "string" }, "previousCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Pásalo como `endingBefore` para la página anterior.", "title": "Previouscursor" }, "totalCount": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Total de coincidencias. Solo se calcula si pides `includeTotal=true` — es un `COUNT(*)` sobre el filtro entero y no se cobra a quien no lo necesita.", "title": "Totalcount" } }, "required": [ "data", "hasMore", "limit" ], "title": "ListEnvelope[CompanyResponse]", "type": "object" }, "ListEnvelope_ConsentItem_": { "properties": { "data": { "items": { "$ref": "#/components/schemas/ConsentItem" }, "title": "Data", "type": "array" }, "hasMore": { "description": "`true` si quedan resultados después de esta página.", "title": "Hasmore", "type": "boolean" }, "limit": { "description": "El límite realmente aplicado (puede ser menor al pedido).", "title": "Limit", "type": "integer" }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Pásalo como `startingAfter` para la siguiente página.", "title": "Nextcursor" }, "object": { "const": "list", "default": "list", "title": "Object", "type": "string" }, "previousCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Pásalo como `endingBefore` para la página anterior.", "title": "Previouscursor" }, "totalCount": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Total de coincidencias. Solo se calcula si pides `includeTotal=true` — es un `COUNT(*)` sobre el filtro entero y no se cobra a quien no lo necesita.", "title": "Totalcount" } }, "required": [ "data", "hasMore", "limit" ], "title": "ListEnvelope[ConsentItem]", "type": "object" }, "ListEnvelope_GrantItem_": { "properties": { "data": { "items": { "$ref": "#/components/schemas/GrantItem" }, "title": "Data", "type": "array" }, "hasMore": { "description": "`true` si quedan resultados después de esta página.", "title": "Hasmore", "type": "boolean" }, "limit": { "description": "El límite realmente aplicado (puede ser menor al pedido).", "title": "Limit", "type": "integer" }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Pásalo como `startingAfter` para la siguiente página.", "title": "Nextcursor" }, "object": { "const": "list", "default": "list", "title": "Object", "type": "string" }, "previousCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Pásalo como `endingBefore` para la página anterior.", "title": "Previouscursor" }, "totalCount": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Total de coincidencias. Solo se calcula si pides `includeTotal=true` — es un `COUNT(*)` sobre el filtro entero y no se cobra a quien no lo necesita.", "title": "Totalcount" } }, "required": [ "data", "hasMore", "limit" ], "title": "ListEnvelope[GrantItem]", "type": "object" }, "ListEnvelope_LegalHoldItem_": { "properties": { "data": { "items": { "$ref": "#/components/schemas/LegalHoldItem" }, "title": "Data", "type": "array" }, "hasMore": { "description": "`true` si quedan resultados después de esta página.", "title": "Hasmore", "type": "boolean" }, "limit": { "description": "El límite realmente aplicado (puede ser menor al pedido).", "title": "Limit", "type": "integer" }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Pásalo como `startingAfter` para la siguiente página.", "title": "Nextcursor" }, "object": { "const": "list", "default": "list", "title": "Object", "type": "string" }, "previousCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Pásalo como `endingBefore` para la página anterior.", "title": "Previouscursor" }, "totalCount": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Total de coincidencias. Solo se calcula si pides `includeTotal=true` — es un `COUNT(*)` sobre el filtro entero y no se cobra a quien no lo necesita.", "title": "Totalcount" } }, "required": [ "data", "hasMore", "limit" ], "title": "ListEnvelope[LegalHoldItem]", "type": "object" }, "ListEnvelope_MediaAssetLegalHoldItem_": { "properties": { "data": { "items": { "$ref": "#/components/schemas/MediaAssetLegalHoldItem" }, "title": "Data", "type": "array" }, "hasMore": { "description": "`true` si quedan resultados después de esta página.", "title": "Hasmore", "type": "boolean" }, "limit": { "description": "El límite realmente aplicado (puede ser menor al pedido).", "title": "Limit", "type": "integer" }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Pásalo como `startingAfter` para la siguiente página.", "title": "Nextcursor" }, "object": { "const": "list", "default": "list", "title": "Object", "type": "string" }, "previousCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Pásalo como `endingBefore` para la página anterior.", "title": "Previouscursor" }, "totalCount": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Total de coincidencias. Solo se calcula si pides `includeTotal=true` — es un `COUNT(*)` sobre el filtro entero y no se cobra a quien no lo necesita.", "title": "Totalcount" } }, "required": [ "data", "hasMore", "limit" ], "title": "ListEnvelope[MediaAssetLegalHoldItem]", "type": "object" }, "ListEnvelope_PersonDocumentItem_": { "properties": { "data": { "items": { "$ref": "#/components/schemas/PersonDocumentItem" }, "title": "Data", "type": "array" }, "hasMore": { "description": "`true` si quedan resultados después de esta página.", "title": "Hasmore", "type": "boolean" }, "limit": { "description": "El límite realmente aplicado (puede ser menor al pedido).", "title": "Limit", "type": "integer" }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Pásalo como `startingAfter` para la siguiente página.", "title": "Nextcursor" }, "object": { "const": "list", "default": "list", "title": "Object", "type": "string" }, "previousCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Pásalo como `endingBefore` para la página anterior.", "title": "Previouscursor" }, "totalCount": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Total de coincidencias. Solo se calcula si pides `includeTotal=true` — es un `COUNT(*)` sobre el filtro entero y no se cobra a quien no lo necesita.", "title": "Totalcount" } }, "required": [ "data", "hasMore", "limit" ], "title": "ListEnvelope[PersonDocumentItem]", "type": "object" }, "ListEnvelope_PersonListItem_": { "properties": { "data": { "items": { "$ref": "#/components/schemas/PersonListItem" }, "title": "Data", "type": "array" }, "hasMore": { "description": "`true` si quedan resultados después de esta página.", "title": "Hasmore", "type": "boolean" }, "limit": { "description": "El límite realmente aplicado (puede ser menor al pedido).", "title": "Limit", "type": "integer" }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Pásalo como `startingAfter` para la siguiente página.", "title": "Nextcursor" }, "object": { "const": "list", "default": "list", "title": "Object", "type": "string" }, "previousCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Pásalo como `endingBefore` para la página anterior.", "title": "Previouscursor" }, "totalCount": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Total de coincidencias. Solo se calcula si pides `includeTotal=true` — es un `COUNT(*)` sobre el filtro entero y no se cobra a quien no lo necesita.", "title": "Totalcount" } }, "required": [ "data", "hasMore", "limit" ], "title": "ListEnvelope[PersonListItem]", "type": "object" }, "ListEnvelope_PersonVerificationSessionItem_": { "properties": { "data": { "items": { "$ref": "#/components/schemas/PersonVerificationSessionItem" }, "title": "Data", "type": "array" }, "hasMore": { "description": "`true` si quedan resultados después de esta página.", "title": "Hasmore", "type": "boolean" }, "limit": { "description": "El límite realmente aplicado (puede ser menor al pedido).", "title": "Limit", "type": "integer" }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Pásalo como `startingAfter` para la siguiente página.", "title": "Nextcursor" }, "object": { "const": "list", "default": "list", "title": "Object", "type": "string" }, "previousCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Pásalo como `endingBefore` para la página anterior.", "title": "Previouscursor" }, "totalCount": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Total de coincidencias. Solo se calcula si pides `includeTotal=true` — es un `COUNT(*)` sobre el filtro entero y no se cobra a quien no lo necesita.", "title": "Totalcount" } }, "required": [ "data", "hasMore", "limit" ], "title": "ListEnvelope[PersonVerificationSessionItem]", "type": "object" }, "ListEnvelope_ReviewQueueItem_": { "properties": { "data": { "items": { "$ref": "#/components/schemas/ReviewQueueItem" }, "title": "Data", "type": "array" }, "hasMore": { "description": "`true` si quedan resultados después de esta página.", "title": "Hasmore", "type": "boolean" }, "limit": { "description": "El límite realmente aplicado (puede ser menor al pedido).", "title": "Limit", "type": "integer" }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Pásalo como `startingAfter` para la siguiente página.", "title": "Nextcursor" }, "object": { "const": "list", "default": "list", "title": "Object", "type": "string" }, "previousCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Pásalo como `endingBefore` para la página anterior.", "title": "Previouscursor" }, "totalCount": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Total de coincidencias. Solo se calcula si pides `includeTotal=true` — es un `COUNT(*)` sobre el filtro entero y no se cobra a quien no lo necesita.", "title": "Totalcount" } }, "required": [ "data", "hasMore", "limit" ], "title": "ListEnvelope[ReviewQueueItem]", "type": "object" }, "ListEnvelope_ScreeningHitResponse_": { "properties": { "data": { "items": { "$ref": "#/components/schemas/ScreeningHitResponse" }, "title": "Data", "type": "array" }, "hasMore": { "description": "`true` si quedan resultados después de esta página.", "title": "Hasmore", "type": "boolean" }, "limit": { "description": "El límite realmente aplicado (puede ser menor al pedido).", "title": "Limit", "type": "integer" }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Pásalo como `startingAfter` para la siguiente página.", "title": "Nextcursor" }, "object": { "const": "list", "default": "list", "title": "Object", "type": "string" }, "previousCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Pásalo como `endingBefore` para la página anterior.", "title": "Previouscursor" }, "totalCount": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Total de coincidencias. Solo se calcula si pides `includeTotal=true` — es un `COUNT(*)` sobre el filtro entero y no se cobra a quien no lo necesita.", "title": "Totalcount" } }, "required": [ "data", "hasMore", "limit" ], "title": "ListEnvelope[ScreeningHitResponse]", "type": "object" }, "ListEnvelope_VerificationSessionResponse_": { "properties": { "data": { "items": { "$ref": "#/components/schemas/VerificationSessionResponse" }, "title": "Data", "type": "array" }, "hasMore": { "description": "`true` si quedan resultados después de esta página.", "title": "Hasmore", "type": "boolean" }, "limit": { "description": "El límite realmente aplicado (puede ser menor al pedido).", "title": "Limit", "type": "integer" }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Pásalo como `startingAfter` para la siguiente página.", "title": "Nextcursor" }, "object": { "const": "list", "default": "list", "title": "Object", "type": "string" }, "previousCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Pásalo como `endingBefore` para la página anterior.", "title": "Previouscursor" }, "totalCount": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Total de coincidencias. Solo se calcula si pides `includeTotal=true` — es un `COUNT(*)` sobre el filtro entero y no se cobra a quien no lo necesita.", "title": "Totalcount" } }, "required": [ "data", "hasMore", "limit" ], "title": "ListEnvelope[VerificationSessionResponse]", "type": "object" }, "ListEnvelope_WebhookDeliveryAttemptResponse_": { "properties": { "data": { "items": { "$ref": "#/components/schemas/WebhookDeliveryAttemptResponse" }, "title": "Data", "type": "array" }, "hasMore": { "description": "`true` si quedan resultados después de esta página.", "title": "Hasmore", "type": "boolean" }, "limit": { "description": "El límite realmente aplicado (puede ser menor al pedido).", "title": "Limit", "type": "integer" }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Pásalo como `startingAfter` para la siguiente página.", "title": "Nextcursor" }, "object": { "const": "list", "default": "list", "title": "Object", "type": "string" }, "previousCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Pásalo como `endingBefore` para la página anterior.", "title": "Previouscursor" }, "totalCount": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Total de coincidencias. Solo se calcula si pides `includeTotal=true` — es un `COUNT(*)` sobre el filtro entero y no se cobra a quien no lo necesita.", "title": "Totalcount" } }, "required": [ "data", "hasMore", "limit" ], "title": "ListEnvelope[WebhookDeliveryAttemptResponse]", "type": "object" }, "ListEnvelope_WebhookDeliveryResponse_": { "properties": { "data": { "items": { "$ref": "#/components/schemas/WebhookDeliveryResponse" }, "title": "Data", "type": "array" }, "hasMore": { "description": "`true` si quedan resultados después de esta página.", "title": "Hasmore", "type": "boolean" }, "limit": { "description": "El límite realmente aplicado (puede ser menor al pedido).", "title": "Limit", "type": "integer" }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Pásalo como `startingAfter` para la siguiente página.", "title": "Nextcursor" }, "object": { "const": "list", "default": "list", "title": "Object", "type": "string" }, "previousCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Pásalo como `endingBefore` para la página anterior.", "title": "Previouscursor" }, "totalCount": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Total de coincidencias. Solo se calcula si pides `includeTotal=true` — es un `COUNT(*)` sobre el filtro entero y no se cobra a quien no lo necesita.", "title": "Totalcount" } }, "required": [ "data", "hasMore", "limit" ], "title": "ListEnvelope[WebhookDeliveryResponse]", "type": "object" }, "ListEnvelope_WebhookEndpointResponse_": { "properties": { "data": { "items": { "$ref": "#/components/schemas/WebhookEndpointResponse" }, "title": "Data", "type": "array" }, "hasMore": { "description": "`true` si quedan resultados después de esta página.", "title": "Hasmore", "type": "boolean" }, "limit": { "description": "El límite realmente aplicado (puede ser menor al pedido).", "title": "Limit", "type": "integer" }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Pásalo como `startingAfter` para la siguiente página.", "title": "Nextcursor" }, "object": { "const": "list", "default": "list", "title": "Object", "type": "string" }, "previousCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Pásalo como `endingBefore` para la página anterior.", "title": "Previouscursor" }, "totalCount": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Total de coincidencias. Solo se calcula si pides `includeTotal=true` — es un `COUNT(*)` sobre el filtro entero y no se cobra a quien no lo necesita.", "title": "Totalcount" } }, "required": [ "data", "hasMore", "limit" ], "title": "ListEnvelope[WebhookEndpointResponse]", "type": "object" }, "MediaAssetLegalHoldItem": { "description": "Una fila de `idv.media_asset_legal_hold`. `action` distingue `set`/`release` -- el item\nMÁS RECIENTE (primero de `GET .../legal-holds`, orden desc por `createdAt`) indica el estado\nvigente: `action='set'` sin una fila `release` posterior => `MediaAsset.legal_hold=true`.", "properties": { "action": { "title": "Action", "type": "string" }, "assetId": { "title": "Assetid", "type": "string" }, "createdAt": { "format": "date-time", "title": "Createdat", "type": "string" }, "expiresAt": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Expiresat" }, "id": { "title": "Id", "type": "string" }, "legalBasis": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Legalbasis" }, "object": { "const": "media_asset.legal_hold", "default": "media_asset.legal_hold", "title": "Object", "type": "string" }, "personId": { "title": "Personid", "type": "string" }, "reason": { "title": "Reason", "type": "string" } }, "required": [ "id", "assetId", "personId", "action", "reason", "legalBasis", "expiresAt", "createdAt" ], "title": "MediaAssetLegalHoldItem", "type": "object" }, "MediaAssetLegalHoldReleaseRequest": { "description": "`POST /v1/persons/{id}/documents/{assetId}/legal-hold/release`. `reason` OBLIGATORIO (422\nsi falta o viene vacío) -- por qué se levanta el hold. `legalBasis` opcional.", "properties": { "legalBasis": { "anyOf": [ { "maxLength": 256, "type": "string" }, { "type": "null" } ], "title": "Legalbasis" }, "reason": { "maxLength": 2000, "minLength": 1, "title": "Reason", "type": "string" } }, "required": [ "reason" ], "title": "MediaAssetLegalHoldReleaseRequest", "type": "object" }, "MediaAssetLegalHoldSetRequest": { "description": "`POST /v1/persons/{id}/documents/{assetId}/legal-hold`. `reason`/`legalBasis`\nOBLIGATORIOS (422 si faltan o vienen vacíos) -- mismo criterio que `LegalHoldSetRequest` de\nPerson: un legal hold sin motivo ni base legal documentada no es defendible ante una\nauditoría/disputa. `expiresAt` opcional (hold indefinido, hasta un `release` explícito, si no\nviene).", "properties": { "expiresAt": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Expiresat" }, "legalBasis": { "maxLength": 256, "minLength": 1, "title": "Legalbasis", "type": "string" }, "reason": { "maxLength": 2000, "minLength": 1, "title": "Reason", "type": "string" } }, "required": [ "reason", "legalBasis" ], "title": "MediaAssetLegalHoldSetRequest", "type": "object" }, "MediaCaptureResult": { "description": "201 de `POST /v1/verification-sessions/{id}/media`. Superset de CaptureResponse (el shape\ndel canal applicant) + `analysis` cuando se pidió `?analyze=true` (BEL-384). `analysis=None`\nsi no se pidió análisis o el canal aún no lo soporta.", "properties": { "analysis": { "anyOf": [ { "$ref": "#/components/schemas/CaptureAnalysis" }, { "type": "null" } ] }, "kind": { "title": "Kind", "type": "string" }, "mediaId": { "description": "Opaque media asset id.", "pattern": "^med_[0-9a-f]{32}$", "title": "Mediaid", "type": "string" }, "mime": { "title": "Mime", "type": "string" }, "sha256": { "title": "Sha256", "type": "string" }, "sizeBytes": { "title": "Sizebytes", "type": "integer" }, "status": { "title": "Status", "type": "string" } }, "required": [ "mediaId", "kind", "sha256", "sizeBytes", "mime", "status" ], "title": "MediaCaptureResult", "type": "object" }, "MediaItem": { "properties": { "cameraForensicsReasons": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Cameraforensicsreasons" }, "cameraForensicsVerdict": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cameraforensicsverdict" }, "capturedAt": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Capturedat" }, "expiresAt": { "format": "date-time", "title": "Expiresat", "type": "string" }, "id": { "description": "Opaque media asset id.", "pattern": "^med_[0-9a-f]{32}$", "title": "Id", "type": "string" }, "kind": { "title": "Kind", "type": "string" }, "mime": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Mime" }, "signedUrl": { "title": "Signedurl", "type": "string" } }, "required": [ "id", "kind", "mime", "signedUrl", "expiresAt", "capturedAt" ], "title": "MediaItem", "type": "object" }, "MediaLinkRequest": { "properties": { "mediaAssetId": { "title": "Mediaassetid", "type": "string" }, "purpose": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Purpose" }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Reason" } }, "required": [ "mediaAssetId" ], "title": "MediaLinkRequest", "type": "object" }, "MediaLinkResponse": { "properties": { "assetId": { "title": "Assetid", "type": "string" }, "expiresAt": { "format": "date-time", "title": "Expiresat", "type": "string" }, "object": { "const": "media_link", "default": "media_link", "title": "Object", "type": "string" }, "url": { "title": "Url", "type": "string" } }, "required": [ "assetId", "url", "expiresAt" ], "title": "MediaLinkResponse", "type": "object" }, "MediaRef": { "description": "Referencia a un asset de media con URL FIRMADA (TTL ≥72h). El `url` apunta a\n`GET /v1/media/{id}?token=…`; AllSign lo baja y archiva en su S3. BEL-199.", "properties": { "expiresAt": { "format": "date-time", "title": "Expiresat", "type": "string" }, "kind": { "title": "Kind", "type": "string" }, "mediaId": { "description": "Opaque media asset id.", "pattern": "^med_[0-9a-f]{32}$", "title": "Mediaid", "type": "string" }, "mime": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Mime" }, "sha256": { "title": "Sha256", "type": "string" }, "sizeBytes": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Sizebytes" }, "url": { "title": "Url", "type": "string" } }, "required": [ "mediaId", "kind", "url", "mime", "sha256", "sizeBytes", "expiresAt" ], "title": "MediaRef", "type": "object" }, "MonitoringRunResponse": { "properties": { "completedAt": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Completedat" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error" }, "id": { "description": "Opaque monitoring run id.", "pattern": "^mrn_[0-9a-f]{32}$", "title": "Id", "type": "string" }, "newHits": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Newhits" }, "portfolioId": { "description": "Opaque monitoring portfolio id.", "pattern": "^pfo_[0-9a-f]{32}$", "title": "Portfolioid", "type": "string" }, "startedAt": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Startedat" }, "status": { "title": "Status", "type": "string" }, "subjectsScreened": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Subjectsscreened" } }, "required": [ "id", "portfolioId", "status", "subjectsScreened", "newHits", "startedAt", "completedAt", "error" ], "title": "MonitoringRunResponse", "type": "object" }, "NoteRequest": { "description": "BEL-509: nota standalone en la bitácora de un caso (no atada a una resolución).", "properties": { "note": { "title": "Note", "type": "string" } }, "required": [ "note" ], "title": "NoteRequest", "type": "object" }, "PersonDeletionCertificate": { "description": "`GET /v1/persons/{id}/deletion-certificate` -- certificado DETERMINÍSTICO (D4 LOCKED),\ngenerado on-the-fly, NUNCA almacenado. `contentHash`/`signature` se recomputan idénticos en\ncada llamada para la MISMA Person ya purgada (`deletion_certificate.build`).", "properties": { "contentHash": { "title": "Contenthash", "type": "string" }, "environment": { "title": "Environment", "type": "string" }, "object": { "const": "person.deletion_certificate", "default": "person.deletion_certificate", "title": "Object", "type": "string" }, "personId": { "title": "Personid", "type": "string" }, "purgedAt": { "format": "date-time", "title": "Purgedat", "type": "string" }, "signature": { "title": "Signature", "type": "string" }, "tenantId": { "description": "Opaque tenant id.", "pattern": "^ten_[0-9a-f]{32}$", "title": "Tenantid", "type": "string" } }, "required": [ "personId", "tenantId", "environment", "purgedAt", "contentHash", "signature" ], "title": "PersonDeletionCertificate", "type": "object" }, "PersonDetailMasked": { "description": "`GET /v1/persons/{id}` -- masked-by-default. `pii` trae SIEMPRE las 17 keys canónicas\n(camelCase, BEL-B1.1 sumó documentNumber/seccion/emision/vigencia/givenName/surname a las 11\nde BEL-418); el valor es `None` (campo ausente), enmascarado (default), o EN CLARO (solo los\ncampos pedidos por `expand=pii.` + scope + reason -- ver el router). NO expone\n`tenantId` (fuera del contrato público).", "properties": { "addressProvided": { "title": "Addressprovided", "type": "boolean" }, "birthDateProvided": { "title": "Birthdateprovided", "type": "boolean" }, "claveElectorProvided": { "title": "Claveelectorprovided", "type": "boolean" }, "createdAt": { "format": "date-time", "title": "Createdat", "type": "string" }, "curpProvided": { "title": "Curpprovided", "type": "boolean" }, "documentNumberProvided": { "title": "Documentnumberprovided", "type": "boolean" }, "emailProvided": { "title": "Emailprovided", "type": "boolean" }, "emisionProvided": { "title": "Emisionprovided", "type": "boolean" }, "environment": { "$ref": "#/components/schemas/ApiEnvironment" }, "externalRefs": { "items": { "$ref": "#/components/schemas/PersonExternalRefItem" }, "title": "Externalrefs", "type": "array" }, "forgetRequested": { "title": "Forgetrequested", "type": "boolean" }, "fullNameProvided": { "title": "Fullnameprovided", "type": "boolean" }, "givenNameProvided": { "title": "Givennameprovided", "type": "boolean" }, "id": { "title": "Id", "type": "string" }, "metadata": { "additionalProperties": true, "title": "Metadata", "type": "object" }, "nationalityProvided": { "title": "Nationalityprovided", "type": "boolean" }, "object": { "const": "person", "default": "person", "title": "Object", "type": "string" }, "phoneProvided": { "title": "Phoneprovided", "type": "boolean" }, "pii": { "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "title": "Pii", "type": "object" }, "piiProvenance": { "additionalProperties": { "$ref": "#/components/schemas/PersonFieldProvenanceItem" }, "title": "Piiprovenance", "type": "object" }, "piiVersion": { "title": "Piiversion", "type": "integer" }, "rfcProvided": { "title": "Rfcprovided", "type": "boolean" }, "seccionProvided": { "title": "Seccionprovided", "type": "boolean" }, "sexProvided": { "title": "Sexprovided", "type": "boolean" }, "stateProvided": { "title": "Stateprovided", "type": "boolean" }, "status": { "$ref": "#/components/schemas/PersonStatus" }, "surnameProvided": { "title": "Surnameprovided", "type": "boolean" }, "updatedAt": { "format": "date-time", "title": "Updatedat", "type": "string" }, "verificationSummary": { "$ref": "#/components/schemas/PersonVerificationSummary" }, "vigenciaProvided": { "title": "Vigenciaprovided", "type": "boolean" } }, "required": [ "id", "externalRefs", "fullNameProvided", "curpProvided", "rfcProvided", "claveElectorProvided", "emailProvided", "phoneProvided", "birthDateProvided", "sexProvided", "nationalityProvided", "stateProvided", "addressProvided", "documentNumberProvided", "seccionProvided", "emisionProvided", "vigenciaProvided", "givenNameProvided", "surnameProvided", "pii", "piiProvenance", "verificationSummary", "environment", "status", "piiVersion", "metadata", "forgetRequested", "createdAt", "updatedAt" ], "title": "PersonDetailMasked", "type": "object" }, "PersonDocumentItem": { "properties": { "assetId": { "title": "Assetid", "type": "string" }, "contentType": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Contenttype" }, "createdAt": { "format": "date-time", "title": "Createdat", "type": "string" }, "height": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Height" }, "kind": { "title": "Kind", "type": "string" }, "sizeBytes": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Sizebytes" }, "width": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Width" } }, "required": [ "assetId", "kind", "contentType", "createdAt", "sizeBytes", "width", "height" ], "title": "PersonDocumentItem", "type": "object" }, "PersonExportBulkJobEnvelope": { "description": "`POST /v1/persons/export-bulk` (202) / `GET /v1/persons/export-bulk/{jobId}`. SIN PII --\nsolo el estado agregado del batch + errores por Person. El dump en sí se pide aparte, vía\n`GET /v1/persons/export-bulk/{jobId}/download` (solo si `status` es terminal y\n`succeeded >= 1`).\n\n`expires_at` (adversarial review, blocker 2): TTL del dump -- `None` mientras el job no\nprodujo ninguno (en proceso, o cero Persons exportables) o tras vencer/purgarse (el barredor\nde mantenimiento lo pone en `NULL` junto con `dump_ciphertext`); poblado apenas el batch\ntermina con al menos una Person exportada. El caller puede usarlo para decidir CUÁNDO\ndescargar sin adivinar.", "properties": { "createdAt": { "format": "date-time", "title": "Createdat", "type": "string" }, "errors": { "items": { "$ref": "#/components/schemas/PersonExportBulkRowError" }, "title": "Errors", "type": "array" }, "expiresAt": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Expiresat" }, "failed": { "title": "Failed", "type": "integer" }, "id": { "title": "Id", "type": "string" }, "object": { "const": "person.export_job", "default": "person.export_job", "title": "Object", "type": "string" }, "status": { "title": "Status", "type": "string" }, "succeeded": { "title": "Succeeded", "type": "integer" }, "total": { "title": "Total", "type": "integer" } }, "required": [ "id", "status", "total", "succeeded", "failed", "errors", "createdAt" ], "title": "PersonExportBulkJobEnvelope", "type": "object" }, "PersonExportBulkRequest": { "description": "Cuerpo de `POST /v1/persons/export-bulk` (W9: `reason` se movió de la query al cuerpo,\nmismo motivo que en `PersonExportRequest` -- la URL completa de cada request con API key\nqueda en `developer.request_log.path`). Body ENTERO opcional: sin él, se audita sin `reason`\n(igual que antes de este cambio). `applicationId` se queda en la query: es un UUID, no texto\nlibre, y no viaja en el cuerpo por consistencia con el resto de filtros de este router.", "properties": { "reason": { "anyOf": [ { "maxLength": 2000, "type": "string" }, { "type": "null" } ], "title": "Reason" } }, "title": "PersonExportBulkRequest", "type": "object" }, "PersonExportBulkRowError": { "description": "Una Person del scope que NO se volcó (bloqueada/purgada -- `assert_person_processable`).\n`reason` es un mensaje humano (nunca el valor PII); `code` es el código de\n`BelfortApiError` que la excluyó (p.ej. `person_purged`/`person_forget_pending`).", "properties": { "code": { "title": "Code", "type": "string" }, "externalRefs": { "default": [], "items": { "$ref": "#/components/schemas/PersonExternalRefItem" }, "title": "Externalrefs", "type": "array" }, "personId": { "title": "Personid", "type": "string" }, "reason": { "title": "Reason", "type": "string" } }, "required": [ "personId", "code", "reason" ], "title": "PersonExportBulkRowError", "type": "object" }, "PersonExportBundle": { "description": "`pii`: 11 keys canónicas (mismas que `PersonDetailMasked.pii`) -- EN CLARO para los campos\nrevelados (clamped a `grant.allowed_fields` si el caller no es el tenant dueño, D1 LOCKED),\n`None` para el resto (ausente o no permitido -- ambos indistinguibles a propósito, anti-\nfingerprinting).", "properties": { "generatedAt": { "format": "date-time", "title": "Generatedat", "type": "string" }, "media": { "items": { "$ref": "#/components/schemas/ExportMediaItem" }, "title": "Media", "type": "array" }, "object": { "const": "person.export", "default": "person.export", "title": "Object", "type": "string" }, "personId": { "title": "Personid", "type": "string" }, "pii": { "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "title": "Pii", "type": "object" }, "piiProvenance": { "additionalProperties": { "$ref": "#/components/schemas/PersonFieldProvenanceItem" }, "title": "Piiprovenance", "type": "object" }, "verificationSessions": { "items": { "$ref": "#/components/schemas/ExportSessionItem" }, "title": "Verificationsessions", "type": "array" } }, "required": [ "personId", "pii", "piiProvenance", "verificationSessions", "media", "generatedAt" ], "title": "PersonExportBundle", "type": "object" }, "PersonExportRequest": { "description": "Cuerpo de `POST /v1/persons/{id}/export` (W9: `reason` se movió de la query al cuerpo --\n`developer.request_log.path` guarda la URL completa de cada request con API key, y un motivo\nde acceso ARCO es texto libre que esa tabla no debe acumular sin cifrar). Body ENTERO\nopcional: sin él, se audita sin `reason` (igual que antes de este cambio).", "properties": { "reason": { "anyOf": [ { "maxLength": 2000, "type": "string" }, { "type": "null" } ], "title": "Reason" } }, "title": "PersonExportRequest", "type": "object" }, "PersonExternalRefItem": { "description": "Una fila de `idv.person_external_identity` (BEL-417, F2): la Application que mapea a esta\nPerson y el `externalRef` que usa en ESA app/environment.", "properties": { "applicationId": { "description": "Opaque application id.", "pattern": "^app_[0-9a-f]{32}$", "title": "Applicationid", "type": "string" }, "externalRef": { "title": "Externalref", "type": "string" } }, "required": [ "applicationId", "externalRef" ], "title": "PersonExternalRefItem", "type": "object" }, "PersonFieldProvenanceItem": { "description": "Origen de un campo PII (`idv.person_field_provenance`, BEL-411): declarado vs verificado.\n\n`checksum_verified` (ALLSI-830, \"B-G6\"): certeza MATEMÁTICA vía checksums ICAO 9303 (FastMRZ)\nsobre un pasaporte con MRZ válido -- distinto de `verified` (contraste gubernamental). Nunca\nambos a la vez (mutuamente excluyentes, ver `PersonEnrichmentService._promote`).", "properties": { "checksumVerified": { "default": false, "title": "Checksumverified", "type": "boolean" }, "confidence": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Confidence" }, "session": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Session" }, "source": { "title": "Source", "type": "string" }, "verified": { "title": "Verified", "type": "boolean" } }, "required": [ "source", "verified", "confidence", "session" ], "title": "PersonFieldProvenanceItem", "type": "object" }, "PersonFieldsResponse": { "description": "`GET /v1/persons/{id}/fields` -- presencia SIN descifrar, sin auditoría (nunca toca PII).\n`fields` trae las mismas 17 keys canónicas (camelCase) que `pii` del detalle.", "properties": { "fields": { "additionalProperties": { "type": "boolean" }, "title": "Fields", "type": "object" }, "id": { "title": "Id", "type": "string" }, "object": { "const": "person.fields", "default": "person.fields", "title": "Object", "type": "string" } }, "required": [ "id", "fields" ], "title": "PersonFieldsResponse", "type": "object" }, "PersonForgetRequest": { "description": "`POST /v1/persons/{id}/forget` (W9: reemplaza el `DELETE` -- revocar/olvidar es una\ntransición, no un borrado de fila. Ver `tests/unit/contract/test_v1_transitions.py`).\n\n`reason` viaja en el CUERPO y no en la query: `developer.request_log.path` guarda la URL\ncompleta de cada request con API key, y un motivo de olvido es justo el tipo de texto libre\nque esa tabla no debe acumular sin cifrar.", "properties": { "mode": { "default": "block", "title": "Mode", "type": "string" }, "reason": { "anyOf": [ { "maxLength": 2000, "type": "string" }, { "type": "null" } ], "title": "Reason" } }, "title": "PersonForgetRequest", "type": "object" }, "PersonForgetResponse": { "description": "`POST /v1/persons/{id}/forget` -- respuesta del derecho de CANCELACIÓN/SUPRESIÓN (LFPDPPP\nart. 22 fr. III). `purgeDueAt` es cuándo se ejecutará la supresión REAL (ForgetWorkflow durable\no la red de seguridad periódica) -- este endpoint NUNCA purga síncrono.", "properties": { "mode": { "title": "Mode", "type": "string" }, "object": { "const": "person.forget", "default": "person.forget", "title": "Object", "type": "string" }, "personId": { "title": "Personid", "type": "string" }, "purgeDueAt": { "format": "date-time", "title": "Purgedueat", "type": "string" } }, "required": [ "personId", "mode", "purgeDueAt" ], "title": "PersonForgetResponse", "type": "object" }, "PersonImportJobEnvelope": { "description": "`POST /v1/persons/import` (202) / `GET /v1/persons/import/{jobId}`. SIN PII ni booleans\nde presencia -- solo el estado agregado del batch + errores por línea.", "properties": { "createdAt": { "format": "date-time", "title": "Createdat", "type": "string" }, "errors": { "items": { "$ref": "#/components/schemas/PersonImportRowError" }, "title": "Errors", "type": "array" }, "failed": { "title": "Failed", "type": "integer" }, "id": { "title": "Id", "type": "string" }, "object": { "const": "person.import_job", "default": "person.import_job", "title": "Object", "type": "string" }, "status": { "title": "Status", "type": "string" }, "succeeded": { "title": "Succeeded", "type": "integer" }, "total": { "title": "Total", "type": "integer" } }, "required": [ "id", "status", "total", "succeeded", "failed", "errors", "createdAt" ], "title": "PersonImportJobEnvelope", "type": "object" }, "PersonImportRowError": { "description": "Una fila del NDJSON que NO se pudo importar. `reason` es un mensaje humano (nunca el\nvalor PII que falló); `code` es un vocabulario NO necesariamente acotado a `KNOWN_CODES` de\n`app/api/conventions/errors.py` (estos códigos viven DENTRO de `job.errors`, un jsonb libre --\nno son el `{code, reason}` de un `BelfortApiError` HTTP).", "properties": { "code": { "title": "Code", "type": "string" }, "externalRef": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Externalref" }, "line": { "title": "Line", "type": "integer" }, "reason": { "title": "Reason", "type": "string" } }, "required": [ "line", "code", "reason" ], "title": "PersonImportRowError", "type": "object" }, "PersonListItem": { "description": "Item de `GET /v1/persons` (cursor). `fullName` SIEMPRE enmascarado (masked ≠ PII, no\naudita) -- ninguna PII en claro viaja en el listado, ni siquiera vía `expand` (no soportado\naquí; el detalle es la única superficie que revela claro).", "properties": { "createdAt": { "format": "date-time", "title": "Createdat", "type": "string" }, "environment": { "$ref": "#/components/schemas/ApiEnvironment" }, "externalRefs": { "items": { "$ref": "#/components/schemas/PersonExternalRefItem" }, "title": "Externalrefs", "type": "array" }, "forgetRequested": { "title": "Forgetrequested", "type": "boolean" }, "fullName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Fullname" }, "id": { "title": "Id", "type": "string" }, "object": { "const": "person", "default": "person", "title": "Object", "type": "string" }, "status": { "$ref": "#/components/schemas/PersonStatus" } }, "required": [ "id", "externalRefs", "fullName", "environment", "status", "forgetRequested", "createdAt" ], "title": "PersonListItem", "type": "object" }, "PersonPatchRequest": { "description": "`PATCH /v1/persons/{id}`: rectificación (ARCO-R). No cambia identidad/environment/app.", "properties": { "metadata": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Metadata" }, "pii": { "anyOf": [ { "$ref": "#/components/schemas/PiiInput" }, { "type": "null" } ] } }, "title": "PersonPatchRequest", "type": "object" }, "PersonSearchRequest": { "description": "`POST /v1/persons/search` (BEL-419) -- búsqueda ESTRUCTURADA (reemplaza el `q`\nadivinado-por-forma de BEL-348): el caller declara explícitamente `field` (nunca se infiere\ndel shape del valor). `value` va SIEMPRE por blind index/overlap (`app/services/\nperson_search.py::PersonSearch.search_page`), nunca por comparación en claro.\n`environment`: paridad JWT/dashboard con el resto del router -- IGNORADO en la vía API key\n(`resolve_environment` ancla el de la key, LOCKED #C). `cursor`: mismo cursor opaco que el\nresto del API (`encode_cursor`/`decode_cursor`), mapea a `after` internamente (LOCKED #B) --\nuno inválido es 400 `INVALID_CURSOR` (`decode_cursor`, fail-closed), nunca un 500.", "properties": { "cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cursor" }, "environment": { "anyOf": [ { "$ref": "#/components/schemas/ApiEnvironment" }, { "type": "null" } ] }, "field": { "enum": [ "curp", "rfc", "email", "phone", "name" ], "title": "Field", "type": "string" }, "limit": { "default": 20, "maximum": 100, "minimum": 1, "title": "Limit", "type": "integer" }, "value": { "minLength": 1, "title": "Value", "type": "string" } }, "required": [ "field", "value" ], "title": "PersonSearchRequest", "type": "object" }, "PersonSearchResults": { "description": "Respuesta de `POST /v1/persons/search`. A diferencia del resto del router (cursor puro,\nsin `total`), aquí SÍ hay `total` -- una búsqueda estructurada necesita saber \"cuántos\nmatchean\" para la UI del dashboard. `totalIsEstimate`: `False` para curp/rfc/email/phone\n(COUNT exacto sobre el mismo WHERE); `True` para `name` (COUNT de candidatos del overlap\nGIN, una posible sobre-estimación -- ver `PersonSearch.search_page`).", "properties": { "data": { "items": { "$ref": "#/components/schemas/PersonListItem" }, "title": "Data", "type": "array" }, "hasMore": { "title": "Hasmore", "type": "boolean" }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Nextcursor" }, "object": { "const": "list", "default": "list", "title": "Object", "type": "string" }, "totalCount": { "title": "Totalcount", "type": "integer" }, "totalIsEstimate": { "title": "Totalisestimate", "type": "boolean" } }, "required": [ "data", "totalCount", "totalIsEstimate", "hasMore" ], "title": "PersonSearchResults", "type": "object" }, "PersonStatus": { "description": "Estado del ciclo de vida de `idv.person` (Persons Vault F1, BEL-416).\n\n`ACTIVE` es el estado normal. `MERGED` marca una Person consolidada dentro de otra\n(`merged_into_person_id`, BEL-421) — deja de participar en los UNIQUE parciales por\n`(tenant_id, environment, curp_hash|external_ref)` para que la canónica pueda reclamarlos.\n`REDACTED` es reservado para un futuro camino de supresión que preserve la fila (a diferencia\nde `purged_at`, que hoy anonimiza in-place).", "enum": [ "active", "merged", "redacted" ], "title": "PersonStatus", "type": "string" }, "PersonVerificationSessionItem": { "description": "Sin PII -- sin cambios de forma respecto a BEL-348, solo el contenedor pasa a cursor.\n\n`id`/`public_id`: mismo `vrf_...` ya resuelto (familia ALMACENADA) -- ver el docstring de\n`ReviewQueueItem` en `app/schemas/review.py` para el porqué de preservar los dos campos.", "properties": { "applicationId": { "description": "Opaque application id.", "pattern": "^app_[0-9a-f]{32}$", "title": "Applicationid", "type": "string" }, "createdAt": { "format": "date-time", "title": "Createdat", "type": "string" }, "environment": { "$ref": "#/components/schemas/ApiEnvironment" }, "id": { "title": "Id", "type": "string" }, "publicId": { "title": "Publicid", "type": "string" }, "status": { "$ref": "#/components/schemas/VerificationStatus" }, "trustScore": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Trustscore" } }, "required": [ "id", "publicId", "status", "applicationId", "environment", "trustScore", "createdAt" ], "title": "PersonVerificationSessionItem", "type": "object" }, "PersonVerificationSummary": { "description": "Último resultado de verificación de la Person (proyección PII-free, mismo vocabulario que\n`verification_report.to_contract_status`/`normalize_trust_score`: `trustScore` 0-1,\n`status` ∈ {approved, declined, review, pending}). `None`/`null` si aún no tiene sesiones NI\nfue declarada `verified_import` (BEL-448).\n\n`source`/`verified_by_belfort`/`imported_at` (BEL-448, aditivos): distinguen una Person\nverificada POR Belfort (una `VerificationSession` real -- `source='belfort'`,\n`verifiedByBelfort=True`) de una declarada como verificada por el INTEGRADOR al importarla\nen bulk (`source='import'`, `verifiedByBelfort=False`, `status='imported'`, `trustScore=None`\n-- Belfort nunca calculó ese score). Una sesión real SIEMPRE gana sobre una declaración de\nimport si ambas existen (ver `app/api/v1/persons.py::_verification_summary`).\n\n`screening_status` (B-G2, aditivo): último screening AML de la Person, independiente de\n`trust_score`/`status` -- una Person puede estar `approved` por identidad Y tener un `hit` de\nAML pendiente de revisión; son señales ORTOGONALES, nunca se mezclan en un solo veredicto.", "properties": { "importedAt": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Importedat" }, "screeningStatus": { "anyOf": [ { "$ref": "#/components/schemas/ScreeningStatusItem" }, { "type": "null" } ] }, "source": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Source" }, "status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Status" }, "trustScore": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Trustscore" }, "verifiedByBelfort": { "default": false, "title": "Verifiedbybelfort", "type": "boolean" } }, "required": [ "trustScore", "status" ], "title": "PersonVerificationSummary", "type": "object" }, "PersonWriteRequest": { "description": "`POST /v1/persons`: crea, o hace upsert por `(application, externalRef)` (BEL-417) si\n`externalRef` viene.", "properties": { "applicationId": { "anyOf": [ { "description": "Opaque application id.", "pattern": "^app_[0-9a-f]{32}$", "type": "string" }, { "type": "null" } ], "title": "Applicationid" }, "environment": { "anyOf": [ { "$ref": "#/components/schemas/ApiEnvironment" }, { "type": "null" } ] }, "externalRef": { "anyOf": [ { "maxLength": 255, "minLength": 1, "type": "string" }, { "type": "null" } ], "description": "UID interno de tu sistema para este solicitante (p.ej. el id de tu tabla de usuarios). **No-PII por contrato**: nunca un email, teléfono, CURP ni nombre. A diferencia de los campos de `pii`, éste se almacena SIN cifrar y se indexa, así que NO recibe el tratamiento de vault (cifrado at-rest, auditoría de acceso, crypto-shred al vencer la retención). Es un namespace por Application: dos Applications del mismo tenant pueden usar el mismo valor y resuelven a Persons distintas.", "title": "Externalref" }, "metadata": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Metadata" }, "pii": { "anyOf": [ { "$ref": "#/components/schemas/PiiInput" }, { "type": "null" } ] } }, "title": "PersonWriteRequest", "type": "object" }, "PersonWriteResponse": { "description": "Respuesta de `POST`/`PATCH` -- NUNCA valores PII, solo presencia (Stripe `x_provided`).", "properties": { "addressProvided": { "title": "Addressprovided", "type": "boolean" }, "birthDateProvided": { "title": "Birthdateprovided", "type": "boolean" }, "claveElectorProvided": { "title": "Claveelectorprovided", "type": "boolean" }, "createdAt": { "format": "date-time", "title": "Createdat", "type": "string" }, "curpProvided": { "title": "Curpprovided", "type": "boolean" }, "documentNumberProvided": { "title": "Documentnumberprovided", "type": "boolean" }, "emailProvided": { "title": "Emailprovided", "type": "boolean" }, "emisionProvided": { "title": "Emisionprovided", "type": "boolean" }, "environment": { "$ref": "#/components/schemas/ApiEnvironment" }, "fullNameProvided": { "title": "Fullnameprovided", "type": "boolean" }, "givenNameProvided": { "title": "Givennameprovided", "type": "boolean" }, "id": { "title": "Id", "type": "string" }, "nationalityProvided": { "title": "Nationalityprovided", "type": "boolean" }, "object": { "const": "person", "default": "person", "title": "Object", "type": "string" }, "phoneProvided": { "title": "Phoneprovided", "type": "boolean" }, "piiVersion": { "title": "Piiversion", "type": "integer" }, "rfcProvided": { "title": "Rfcprovided", "type": "boolean" }, "seccionProvided": { "title": "Seccionprovided", "type": "boolean" }, "sexProvided": { "title": "Sexprovided", "type": "boolean" }, "stateProvided": { "title": "Stateprovided", "type": "boolean" }, "status": { "$ref": "#/components/schemas/PersonStatus" }, "surnameProvided": { "title": "Surnameprovided", "type": "boolean" }, "updatedAt": { "format": "date-time", "title": "Updatedat", "type": "string" }, "vigenciaProvided": { "title": "Vigenciaprovided", "type": "boolean" } }, "required": [ "id", "fullNameProvided", "curpProvided", "rfcProvided", "claveElectorProvided", "emailProvided", "phoneProvided", "birthDateProvided", "sexProvided", "nationalityProvided", "stateProvided", "addressProvided", "documentNumberProvided", "seccionProvided", "emisionProvided", "vigenciaProvided", "givenNameProvided", "surnameProvided", "piiVersion", "environment", "status", "createdAt", "updatedAt" ], "title": "PersonWriteResponse", "type": "object" }, "PiiInput": { "description": "PII en claro que el integrador manda UNA vez -- write-only, nunca se eco. Todos los\ncampos son opcionales/parciales: solo los provistos (`exclude_unset`) se aplican.", "properties": { "address": { "anyOf": [ { "additionalProperties": { "type": "string" }, "type": "object" }, { "type": "null" } ], "title": "Address" }, "birthDate": { "anyOf": [ { "format": "date", "type": "string" }, { "type": "null" } ], "title": "Birthdate" }, "claveElector": { "anyOf": [ { "maxLength": 32, "minLength": 1, "type": "string" }, { "type": "null" } ], "title": "Claveelector" }, "curp": { "anyOf": [ { "maxLength": 32, "minLength": 1, "type": "string" }, { "type": "null" } ], "title": "Curp" }, "documentNumber": { "anyOf": [ { "maxLength": 32, "minLength": 1, "type": "string" }, { "type": "null" } ], "title": "Documentnumber" }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Email" }, "emision": { "anyOf": [ { "maxLength": 16, "minLength": 1, "type": "string" }, { "type": "null" } ], "title": "Emision" }, "fullName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Fullname" }, "givenName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Givenname" }, "nationality": { "anyOf": [ { "maxLength": 8, "type": "string" }, { "type": "null" } ], "title": "Nationality" }, "phone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Phone" }, "rfc": { "anyOf": [ { "maxLength": 32, "minLength": 1, "type": "string" }, { "type": "null" } ], "title": "Rfc" }, "seccion": { "anyOf": [ { "maxLength": 32, "minLength": 1, "type": "string" }, { "type": "null" } ], "title": "Seccion" }, "sex": { "anyOf": [ { "maxLength": 8, "type": "string" }, { "type": "null" } ], "title": "Sex" }, "state": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "State" }, "surname": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Surname" }, "vigencia": { "anyOf": [ { "maxLength": 16, "minLength": 1, "type": "string" }, { "type": "null" } ], "title": "Vigencia" } }, "title": "PiiInput", "type": "object" }, "PolicyOverrideInput": { "description": "Override curado de la policy de revisión, por sesión (deep-merge sobre la base resuelta).", "properties": { "approveAbove": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Approveabove" }, "declineBelow": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Declinebelow" }, "enabled": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Enabled" }, "fourEyesRequired": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Foureyesrequired" }, "reviewRouting": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Reviewrouting" }, "triggers": { "anyOf": [ { "$ref": "#/components/schemas/PolicyTriggersInput" }, { "type": "null" } ] } }, "title": "PolicyOverrideInput", "type": "object" }, "PolicyTriggersInput": { "description": "Disparadores de fallback que el integrador puede sobrescribir (parcial).", "properties": { "govError": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Goverror" }, "govNoMatch": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Govnomatch" }, "govNotFound": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Govnotfound" }, "govTimeout": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Govtimeout" }, "lowConfidenceBelow": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Lowconfidencebelow" } }, "title": "PolicyTriggersInput", "type": "object" }, "Problem": { "description": "Error como documento de problema RFC 9457 (`application/problem+json`), PLANO — sin sobre anidado. Programa contra `code`, nunca contra `detail`.", "properties": { "code": { "description": "Código ESTABLE del catálogo. Append-only: un código publicado no se renombra ni se borra.", "enum": [ "ADMISSION_FULL", "ALLOWED_ORIGINS_REQUIRED", "API_KEY_INVALID", "API_KEY_NOT_FOUND", "APPLICATION_ARCHIVED", "APPLICATION_NAME_TAKEN", "APPLICATION_NOT_FOUND", "ARCO_INVALID_TRANSITION", "ARCO_REQUEST_NOT_FOUND", "ARCO_SUBJECT_REQUIRED", "AUTHENTICATION_REQUIRED", "BAD_REQUEST", "BATCH_TOO_LARGE", "BILLING_NOT_CONFIGURED", "CANNOT_ARCHIVE_DEFAULT", "CANNOT_MERGE_INTO_SELF", "CAPTURE_CREDENTIAL_INVALID", "CAPTURE_NOT_ALLOWED", "CASE_ALREADY_CLAIMED", "CASE_CLAIM_REQUIRED", "CASE_CLOSED", "CASE_HAS_NO_SESSION", "CASE_NOT_FOUND", "CHALLENGE_ID_REQUIRED", "CHECK_NOT_ENABLED_FOR_FLOW", "CLIENT_TOKEN_INVALID", "CLIENT_TOKEN_NOT_FOUND", "COMPANY_NOT_FOUND", "CONFLICT", "CONSENT_NOT_FOUND", "CONSENT_REQUIRED", "CONSOLIDATION_NOT_FOUND", "CURP_CONFLICT", "DEFAULT_FLOW_NOT_IN_ALLOWED", "DELETION_NOT_COMPLETE", "DISPUTE_NOT_FOUND", "EFIRMA_CERT_NOT_READY", "EFIRMA_CHALLENGE_ALREADY_USED", "EFIRMA_CHALLENGE_EXPIRED", "EFIRMA_CHALLENGE_NOT_FOUND", "ENVIRONMENT_MISMATCH", "EXPORT_DUMP_EXPIRED", "EXPORT_DUMP_NOT_READY", "EXPORT_JOB_NOT_FOUND", "FIELD_NOT_GRANTED", "FIELD_NOT_IN_TOKEN_SCOPE", "FLOW_KEY_TAKEN", "FLOW_NOT_ALLOWED_FOR_APPLICATION", "FLOW_NOT_ALLOWED_FOR_KEY", "FLOW_NOT_DELETABLE", "FLOW_NOT_FOUND", "FLOW_NOT_PUBLISHABLE", "FLOW_REQUIRED", "FLOW_VALIDATION_FAILED", "FORMAT_INVALID", "GONE", "GRANT_NOT_FOUND", "GRANT_PURPOSE_NOT_ALLOWED", "IDEMPOTENCY_KEY_INVALID", "IDEMPOTENCY_KEY_IN_PROGRESS", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "IMPORT_BATCH_TOO_LARGE", "IMPORT_BODY_INVALID", "IMPORT_JOB_NOT_FOUND", "INSUFFICIENT_CREDITS", "INSUFFICIENT_SCOPE", "INTEGRITY_FIELD_UNSUPPORTED", "INTEGRITY_NO_FIELDS", "INTEGRITY_SIGNING_KEY_INVALID", "INTERNAL_ERROR", "INVALID_CAPTURE_PLATFORM", "INVALID_CURSOR", "INVALID_ID", "INVALID_STATE_TRANSITION", "LIMIT_OUT_OF_RANGE", "MEDIA_CONTENT_INVALID", "MEDIA_LINK_INVALID", "MEDIA_NOT_FOUND", "METADATA_INVALID", "METHOD_NOT_ALLOWED", "MODE_INVALID", "NOTIFICATION_NOT_ACTIONABLE", "NOTIFICATION_NOT_FOUND", "NOT_ALLOWED_BY_APPLICATION", "NOT_A_REVIEWER", "NOT_IMPLEMENTED", "NO_ACTIVE_ORGANIZATION", "ORIGIN_CONFLICT", "ORIGIN_INVALID", "ORIGIN_NOT_ALLOWED", "PAYLOAD_TOO_LARGE", "PERMISSION_DENIED", "PERSON_ALREADY_MERGED", "PERSON_BLOCKED", "PERSON_FORGET_PENDING", "PERSON_LEGAL_HOLD", "PERSON_NOT_FOUND", "PERSON_PURGED", "PII_ACCESS_REASON_REQUIRED", "PII_DECRYPT_CAP_REACHED", "PII_IN_PLAINTEXT_FIELD", "PORTFOLIO_NOT_FOUND", "PUBLISHABLE_KEY_NOT_ALLOWED", "PUBLISHABLE_KEY_REQUIRED", "PURPOSE_UNKNOWN", "RATE_LIMITED", "REASON_REQUIRED", "REAUTH_ENGINE_UNAVAILABLE", "REAUTH_MEDIA_UNAVAILABLE", "REPORT_TYPE_INVALID", "RESERVATION_NOT_FOUND", "RESERVATION_NOT_PENDING", "RESOURCE_NOT_FOUND", "RFC_CONFLICT", "SCOPE_NOT_ALLOWED_FOR_KEY_TYPE", "SCREENING_NOT_FOUND", "SECOND_APPROVAL_REQUIRED", "SERVICE_KEY_REQUIRED", "SERVICE_UNAVAILABLE", "SESSION_ALREADY_USED", "SESSION_CANCELLED", "SESSION_COMPLETED", "SESSION_EXPIRED", "SESSION_INVALID", "SESSION_NOT_FOUND", "SESSION_NOT_SUBMITTABLE", "STRIPE_CUSTOMER_MISSING", "STRIPE_SIGNATURE_INVALID", "SURVIVOR_NOT_ACTIVE", "TENANT_NOT_FOUND", "TENANT_PROFILE_NOT_FOUND", "TEST_KEY_NOT_ALLOWED", "TEST_MODE_CONFLICTS_WITH_KEY_ENVIRONMENT", "TRIAL_LIMIT_REACHED", "UBO_NODE_NOT_FOUND", "UNKNOWN_EVENT_TYPE", "UNKNOWN_MEDIA_KIND", "UNKNOWN_NOTIFICATION_ACTION", "UNKNOWN_NOTIFICATION_CATEGORY", "UNKNOWN_PII_FIELD", "UNKNOWN_SCOPE", "UNSUPPORTED_API_VERSION", "UNSUPPORTED_MEDIA_TYPE", "URL_NOT_PUBLIC", "VALIDATION_ERROR", "VERIFIED_FIELD_CONFLICT", "WEBHOOK_DELIVERY_NOT_FOUND", "WEBHOOK_ENDPOINT_INACTIVE", "WEBHOOK_NOT_FOUND", "WEBHOOK_URL_INVALID" ], "type": "string" }, "detail": { "description": "Específico de ESTA ocurrencia. Legible, no parseable.", "type": "string" }, "errors": { "description": "Errores por campo de un 422 de validación.", "items": { "properties": { "field": { "description": "Ruta camelCase del campo.", "type": "string" }, "message": { "type": "string" }, "pointer": { "description": "JSON Pointer RFC 6901.", "type": "string" } }, "type": "object" }, "type": "array" }, "instance": { "description": "Path de la petición que falló.", "type": "string" }, "requestId": { "description": "El mismo valor del header `Belfort-Request-Id`. Es lo que se pide en un ticket de soporte.", "type": "string" }, "status": { "description": "El status HTTP de la respuesta.", "type": "integer" }, "title": { "description": "Frase estable por tipo de problema — la misma para todas las ocurrencias, apta para agrupar.", "type": "string" }, "type": { "description": "URI del tipo de problema: `https://belfort.ai/docs/errors#`.", "format": "uri", "type": "string" } }, "required": [ "type", "title", "status", "code" ], "type": "object" }, "RateLimitFamily": { "description": "Una familia de rate-limit (`default`/`reveal`/`batch`, BEL-452) -- `endpoints` es\nINFORMATIVO (documenta qué rutas caen en esta familia); el enforcement real vive en la\ndependencia `_rl_*` declarada en cada ruta (`app/api/rate_limit_deps.py`), no en esta lista.", "properties": { "description": { "title": "Description", "type": "string" }, "endpoints": { "items": { "type": "string" }, "title": "Endpoints", "type": "array" }, "name": { "title": "Name", "type": "string" }, "requestsPerMinute": { "title": "Requestsperminute", "type": "integer" } }, "required": [ "name", "endpoints", "requestsPerMinute", "description" ], "title": "RateLimitFamily", "type": "object" }, "RateLimitPolicy": { "description": "`GET /v1/compliance/limits` (BEL-452) -- fuente única `app/config/rate_limit_policy.py`.", "properties": { "decryptSlo": { "$ref": "#/components/schemas/DecryptSlo" }, "families": { "items": { "$ref": "#/components/schemas/RateLimitFamily" }, "title": "Families", "type": "array" }, "maskedDegradationPolicy": { "title": "Maskeddegradationpolicy", "type": "string" }, "object": { "const": "compliance.limits", "default": "compliance.limits", "title": "Object", "type": "string" }, "revealBudget": { "$ref": "#/components/schemas/RevealBudgetPolicy" } }, "required": [ "families", "revealBudget", "decryptSlo", "maskedDegradationPolicy" ], "title": "RateLimitPolicy", "type": "object" }, "ReassignRequest": { "description": "BEL-509: reasigna un caso a otro revisor del tenant (acción \"Reasignar\" del inbox).\n\nEl destino es SIEMPRE un revisor humano (`assigneeUserId`); no se reasigna a una API key\n(una key toma casos por su cuenta vía claim, no se le \"asignan\").", "properties": { "assigneeUserId": { "description": "Opaque user id.", "pattern": "^usr_[0-9a-f]{32}$", "title": "Assigneeuserid", "type": "string" } }, "required": [ "assigneeUserId" ], "title": "ReassignRequest", "type": "object" }, "ReauthFaceRequest": { "description": "Selfie fresca del firmante -- transporte JSON+base64 (mismo patrón que `MediaIngestJson`/\n`idv_client`, sin multipart: este endpoint es S2S, no un canal de captura del applicant).\nNUNCA se persiste: vive en memoria SOLO durante este request\n(`app/services/person_reauth_service.py`) -- no se crea un template facial nuevo ni una\ntabla de biometría.", "properties": { "mime": { "default": "image/jpeg", "title": "Mime", "type": "string" }, "selfieBase64": { "minLength": 1, "title": "Selfiebase64", "type": "string" } }, "required": [ "selfieBase64" ], "title": "ReauthFaceRequest", "type": "object" }, "ReauthFaceResult": { "description": "Resultado de re-autenticar al titular contra la selfie retenida MÁS RECIENTE de su Person.\n\nBEL-529: hasta ahora esto era SÓLO una comparación de caras, y por eso el reuso era la ruta\nmás débil del producto — la primera verificación exige documento + liveness + face match, y\nla segunda aceptaba un JPEG cualquiera: una foto impresa del titular la pasaba. Ahora corre\nel análisis biométrico completo (`/v1/extract/biometrics`): face match + prueba de vida +\nanti-deepfake sobre la selfie fresca, en una sola llamada.", "properties": { "decision": { "enum": [ "match", "inconclusive", "no_match" ], "title": "Decision", "type": "string" }, "deepfakeGenuineConfidence": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Deepfakegenuineconfidence" }, "livenessPassed": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Livenesspassed" }, "match": { "title": "Match", "type": "boolean" }, "object": { "const": "person.reauth_face", "default": "person.reauth_face", "title": "Object", "type": "string" }, "presentationAttack": { "default": false, "title": "Presentationattack", "type": "boolean" }, "reasonCodes": { "items": { "type": "string" }, "title": "Reasoncodes", "type": "array" }, "referenceCapturedAt": { "format": "date-time", "title": "Referencecapturedat", "type": "string" }, "score": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Score" }, "threshold": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Threshold" } }, "required": [ "match", "decision", "score", "threshold", "referenceCapturedAt" ], "title": "ReauthFaceResult", "type": "object" }, "ResolveRequest": { "properties": { "action": { "$ref": "#/components/schemas/ReviewActionType" }, "note": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Note" }, "reasonCodes": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Reasoncodes" } }, "required": [ "action" ], "title": "ResolveRequest", "type": "object" }, "ResolveResult": { "properties": { "awaitingSecondApproval": { "default": false, "title": "Awaitingsecondapproval", "type": "boolean" }, "caseId": { "title": "Caseid", "type": "string" }, "caseStatus": { "$ref": "#/components/schemas/CaseStatus" }, "outcome": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Outcome" }, "sessionStatus": { "title": "Sessionstatus", "type": "string" } }, "required": [ "caseId", "caseStatus", "sessionStatus" ], "title": "ResolveResult", "type": "object" }, "RetentionPolicyItem": { "properties": { "basis": { "title": "Basis", "type": "string" }, "description": { "title": "Description", "type": "string" }, "purpose": { "title": "Purpose", "type": "string" } }, "required": [ "purpose", "basis", "description" ], "title": "RetentionPolicyItem", "type": "object" }, "ReuseSummary": { "description": "Qué pasó con el reuso de identidad en esta verificación. CERO PII.\n\nLleva a propósito la RAZÓN además del booleano. Sin ella, un integrador que ve `applied:false`\nno puede distinguir \"este humano es nuevo\" de \"su verificación caducó\" de \"tu Application no\ntiene el reuso encendido\" — tres situaciones con tres acciones distintas, y ninguna deducible\ndel `false` a secas.\n\nLo que NO va aquí: el score del recheck facial y su umbral. Son evidencia forense y viven en el\n`EvidenceBundle` (el artefacto NOM-151), no en un contrato que el integrador lee en caliente.\nPublicar el score aquí invitaría a que alguien construyera su propia política sobre él, y la\npolítica es de Belfort.", "properties": { "applied": { "default": false, "title": "Applied", "type": "boolean" }, "basedOnAgeDays": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Basedonagedays" }, "basedOnSessionId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Basedonsessionid" }, "reason": { "title": "Reason", "type": "string" } }, "required": [ "reason" ], "title": "ReuseSummary", "type": "object" }, "RevealBudgetPolicy": { "description": "Presupuesto anti-exfil de VOLUMEN (distinto del RPM por familia -- ver\n`app/services/reveal_budget.py`).", "properties": { "description": { "title": "Description", "type": "string" }, "maxRevealsPerWindow": { "title": "Maxrevealsperwindow", "type": "integer" }, "windowSeconds": { "title": "Windowseconds", "type": "integer" } }, "required": [ "maxRevealsPerWindow", "windowSeconds", "description" ], "title": "RevealBudgetPolicy", "type": "object" }, "ReviewActionItem": { "properties": { "action": { "title": "Action", "type": "string" }, "createdAt": { "format": "date-time", "title": "Createdat", "type": "string" }, "note": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Note" }, "reviewerApiKeyId": { "anyOf": [ { "description": "Opaque API key id.", "pattern": "^key_[0-9a-f]{32}$", "type": "string" }, { "type": "null" } ], "title": "Reviewerapikeyid" }, "reviewerUserId": { "anyOf": [ { "description": "Opaque user id.", "pattern": "^usr_[0-9a-f]{32}$", "type": "string" }, { "type": "null" } ], "title": "Revieweruserid" } }, "required": [ "action", "note", "reviewerUserId", "createdAt" ], "title": "ReviewActionItem", "type": "object" }, "ReviewActionType": { "enum": [ "approve", "decline", "request_more_info", "escalate", "note", "assign" ], "title": "ReviewActionType", "type": "string" }, "ReviewCaseDetail": { "properties": { "actions": { "items": { "$ref": "#/components/schemas/ReviewActionItem" }, "title": "Actions", "type": "array" }, "applicant": { "anyOf": [ { "$ref": "#/components/schemas/ApplicantPII" }, { "type": "null" } ] }, "case": { "$ref": "#/components/schemas/CaseSummary" }, "decisions": { "items": { "$ref": "#/components/schemas/DecisionItem" }, "title": "Decisions", "type": "array" }, "events": { "items": { "$ref": "#/components/schemas/CaseEventItem" }, "title": "Events", "type": "array" }, "govLookups": { "items": { "$ref": "#/components/schemas/app__schemas__review__GovLookupItem" }, "title": "Govlookups", "type": "array" }, "media": { "items": { "$ref": "#/components/schemas/MediaItem" }, "title": "Media", "type": "array" }, "session": { "anyOf": [ { "$ref": "#/components/schemas/ReviewSessionSummary" }, { "type": "null" } ] } }, "required": [ "case", "session", "applicant", "media", "govLookups", "decisions", "actions", "events" ], "title": "ReviewCaseDetail", "type": "object" }, "ReviewQueueItem": { "description": "Fila de la cola: caso + resumen de su sesión. SIN PII en claro.\n\n`case_id`/`public_id` (ídem `session_id`/`session_public_id`): AMBOS son el mismo `case_...`/\n`vrf_...` ya resuelto (familia ALMACENADA, rule #5 -- el UUID interno de `CaseRecord`/\n`VerificationSession` nunca sale). Se preservan como dos campos por compat de forma con el\nresto del contrato ya publicado (`sessionPublicId`, etc.) en vez de colapsarlos.", "properties": { "assigneeApiKeyId": { "anyOf": [ { "description": "Opaque API key id.", "pattern": "^key_[0-9a-f]{32}$", "type": "string" }, { "type": "null" } ], "title": "Assigneeapikeyid" }, "assigneeUserId": { "anyOf": [ { "description": "Opaque user id.", "pattern": "^usr_[0-9a-f]{32}$", "type": "string" }, { "type": "null" } ], "title": "Assigneeuserid" }, "caseId": { "title": "Caseid", "type": "string" }, "caseNumber": { "title": "Casenumber", "type": "integer" }, "claimedAt": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Claimedat" }, "createdAt": { "format": "date-time", "title": "Createdat", "type": "string" }, "escalatedAt": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Escalatedat" }, "priority": { "$ref": "#/components/schemas/CasePriority" }, "publicId": { "title": "Publicid", "type": "string" }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Reason" }, "sessionId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Sessionid" }, "sessionPublicId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Sessionpublicid" }, "sessionStatus": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Sessionstatus" }, "slaDueAt": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Sladueat" }, "status": { "$ref": "#/components/schemas/CaseStatus" }, "tenantId": { "description": "Opaque tenant id.", "pattern": "^ten_[0-9a-f]{32}$", "title": "Tenantid", "type": "string" } }, "required": [ "caseId", "publicId", "caseNumber", "tenantId", "status", "priority", "reason", "assigneeUserId", "claimedAt", "slaDueAt", "escalatedAt", "createdAt", "sessionId", "sessionPublicId", "sessionStatus" ], "title": "ReviewQueueItem", "type": "object" }, "ReviewQueueSummary": { "description": "BEL-510: conteo de casos manuales por estado, tenant/app-scoped e INDEPENDIENTE del filtro\nde status/priority/paginación del toolbar — para KPIs correctos sin recalcular sobre la página\nvisible. `total` = suma de los estados.", "properties": { "closed": { "default": 0, "title": "Closed", "type": "integer" }, "escalated": { "default": 0, "title": "Escalated", "type": "integer" }, "inProgress": { "default": 0, "title": "Inprogress", "type": "integer" }, "open": { "default": 0, "title": "Open", "type": "integer" }, "resolved": { "default": 0, "title": "Resolved", "type": "integer" }, "total": { "default": 0, "title": "Total", "type": "integer" } }, "title": "ReviewQueueSummary", "type": "object" }, "ReviewSessionSummary": { "properties": { "channel": { "title": "Channel", "type": "string" }, "country": { "title": "Country", "type": "string" }, "createdAt": { "format": "date-time", "title": "Createdat", "type": "string" }, "publicId": { "title": "Publicid", "type": "string" }, "sessionId": { "title": "Sessionid", "type": "string" }, "status": { "title": "Status", "type": "string" }, "trustScore": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Trustscore" } }, "required": [ "sessionId", "publicId", "status", "channel", "trustScore", "country", "createdAt" ], "title": "ReviewSessionSummary", "type": "object" }, "RiskGradeSummary": { "description": "El grado de riesgo de la verificación (⑨, art. 95 Bis LGOAAC) — y de quién es la opinión.\n\n`basis` es el campo que impide vender un cumplimiento que no se tiene, con el MISMO mecanismo\nque `BiometricMatchSummary.matched_against`: un valor POSITIVO que nombra el referente, no un\nbooleano negativo. Un `false` se ignora al leer; `\"belfort_default_matrix\"` obliga a ver que el\ngrado sale de la matriz por defecto de BELFORT, no de la metodología del cliente.\n\nY eso importa jurídicamente: graduar el riesgo de sus clientes es obligación de la SOFOM, con SU\nmetodología, y es a ELLA a quien se la auditan. Esto es un insumo para esa metodología, nunca un\nsustituto. El día que un tenant pueda configurar su propia matriz, `basis` lo dirá — y hasta\nentonces dice la verdad de hoy.\n\n`grade` puede ser `None`, y NO significa \"bajo\": significa que no hubo con qué graduar.\nColapsarlo a `low` convertiría cada sesión sin evidencia en un cliente de bajo riesgo.", "properties": { "basis": { "title": "Basis", "type": "string" }, "grade": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Grade" }, "reasonCodes": { "items": { "type": "string" }, "title": "Reasoncodes", "type": "array" } }, "required": [ "grade", "basis", "reasonCodes" ], "title": "RiskGradeSummary", "type": "object" }, "ScreeningCreate": { "properties": { "companyId": { "description": "Opaque company id.", "pattern": "^com_[0-9a-f]{32}$", "title": "Companyid", "type": "string" } }, "required": [ "companyId" ], "title": "ScreeningCreate", "type": "object" }, "ScreeningHitResponse": { "properties": { "category": { "title": "Category", "type": "string" }, "companyId": { "anyOf": [ { "description": "Opaque company id.", "pattern": "^com_[0-9a-f]{32}$", "type": "string" }, { "type": "null" } ], "title": "Companyid" }, "createdAt": { "format": "date-time", "title": "Createdat", "type": "string" }, "id": { "description": "Opaque screening hit id.", "pattern": "^hit_[0-9a-f]{32}$", "title": "Id", "type": "string" }, "lists": { "anyOf": [ { "items": {}, "type": "array" }, { "type": "null" } ], "title": "Lists" }, "matchedName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Matchedname" }, "personId": { "anyOf": [ { "description": "Opaque person id.", "pattern": "^per_[0-9a-f]{32}$", "type": "string" }, { "type": "null" } ], "title": "Personid" }, "resolvedAt": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Resolvedat" }, "score": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Score" }, "screeningId": { "description": "Opaque screening id.", "pattern": "^scr_[0-9a-f]{32}$", "title": "Screeningid", "type": "string" }, "status": { "title": "Status", "type": "string" }, "tenantId": { "description": "Opaque tenant id.", "pattern": "^ten_[0-9a-f]{32}$", "title": "Tenantid", "type": "string" } }, "required": [ "id", "screeningId", "tenantId", "personId", "companyId", "category", "score", "matchedName", "lists", "status", "resolvedAt", "createdAt" ], "title": "ScreeningHitResponse", "type": "object" }, "ScreeningResponse": { "properties": { "companyScreeningId": { "description": "Opaque screening id.", "pattern": "^scr_[0-9a-f]{32}$", "title": "Companyscreeningid", "type": "string" }, "personScreeningIds": { "items": { "description": "Opaque screening id.", "pattern": "^scr_[0-9a-f]{32}$", "type": "string" }, "title": "Personscreeningids", "type": "array" }, "status": { "title": "Status", "type": "string" }, "totalHits": { "title": "Totalhits", "type": "integer" } }, "required": [ "companyScreeningId", "personScreeningIds", "status", "totalHits" ], "title": "ScreeningResponse", "type": "object" }, "ScreeningStatusItem": { "description": "Bloque NUEVO de `PersonVerificationSummary` (B-G2, ZERO_PII_BELFORT_MASTER_PLAN.md):\núltimo screening AML (OFAC/ONU/PEP, `idv.gov_lookup` con `GovProvider.AML_SCREENING`) de la\nPerson. Deliberadamente FUERA de `pii_provenance` (`PersonDetailMasked.pii_provenance`): NO\nes un campo PII verificado -- `pii_provenance` afirma \"este DATO PERSONAL del titular está\nconfirmado contra gobierno\" (p.ej. `clave_elector`); esto es una SEÑAL de cribado (\"¿esta\npersona aparece en listas de sanciones/PEP?\"), un vocabulario distinto que no encaja en el\ncontrato de un campo PII. `None`/`null` si la Person nunca tuvo un screening AML.\n\n`result`: `\"hit\"` (coincidencia en ≥1 lista), `\"no_hit\"`, o `\"error\"` (el proveedor falló --\nfail-closed, ver `app/services/aml_screening/provider.py`; `requiresReview=True` en ese\ncaso -- el error NUNCA se descarta silenciosamente, queda visible aquí para que un humano lo\nresuelva).", "properties": { "checkedAt": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Checkedat" }, "hits": { "items": { "type": "string" }, "title": "Hits", "type": "array" }, "listsChecked": { "items": { "type": "string" }, "title": "Listschecked", "type": "array" }, "provider": { "title": "Provider", "type": "string" }, "requiresReview": { "title": "Requiresreview", "type": "boolean" }, "result": { "title": "Result", "type": "string" } }, "required": [ "result", "listsChecked", "hits", "provider", "requiresReview", "checkedAt" ], "title": "ScreeningStatusItem", "type": "object" }, "SubprocessorItem": { "properties": { "dpaUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Dpaurl" }, "location": { "title": "Location", "type": "string" }, "name": { "title": "Name", "type": "string" }, "purpose": { "title": "Purpose", "type": "string" }, "role": { "title": "Role", "type": "string" } }, "required": [ "name", "role", "purpose", "location" ], "title": "SubprocessorItem", "type": "object" }, "SubprocessorList": { "properties": { "data": { "items": { "$ref": "#/components/schemas/SubprocessorItem" }, "title": "Data", "type": "array" }, "object": { "const": "list", "default": "list", "title": "Object", "type": "string" } }, "required": [ "data" ], "title": "SubprocessorList", "type": "object" }, "UboNodeCreate": { "properties": { "isControlPerson": { "default": false, "title": "Iscontrolperson", "type": "boolean" }, "name": { "maxLength": 500, "minLength": 1, "title": "Name", "type": "string" }, "nodeType": { "default": "person", "title": "Nodetype", "type": "string" }, "ownershipPct": { "anyOf": [ { "maximum": 100, "minimum": 0, "type": "number" }, { "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$", "type": "string" }, { "type": "null" } ], "title": "Ownershippct" }, "parentNodeId": { "anyOf": [ { "description": "Opaque UBO node id.", "pattern": "^ubo_[0-9a-f]{32}$", "type": "string" }, { "type": "null" } ], "title": "Parentnodeid" }, "personId": { "anyOf": [ { "description": "Opaque person id.", "pattern": "^per_[0-9a-f]{32}$", "type": "string" }, { "type": "null" } ], "title": "Personid" }, "role": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Role" } }, "required": [ "name" ], "title": "UboNodeCreate", "type": "object" }, "UboNodeResponse": { "properties": { "companyId": { "description": "Opaque company id.", "pattern": "^com_[0-9a-f]{32}$", "title": "Companyid", "type": "string" }, "createdAt": { "format": "date-time", "title": "Createdat", "type": "string" }, "effectivePct": { "anyOf": [ { "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$", "type": "string" }, { "type": "null" } ], "title": "Effectivepct" }, "id": { "description": "Opaque UBO node id.", "pattern": "^ubo_[0-9a-f]{32}$", "title": "Id", "type": "string" }, "isControlPerson": { "title": "Iscontrolperson", "type": "boolean" }, "name": { "title": "Name", "type": "string" }, "nodeType": { "title": "Nodetype", "type": "string" }, "ownershipPct": { "anyOf": [ { "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$", "type": "string" }, { "type": "null" } ], "title": "Ownershippct" }, "ownershipType": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Ownershiptype" }, "parentNodeId": { "anyOf": [ { "description": "Opaque UBO node id.", "pattern": "^ubo_[0-9a-f]{32}$", "type": "string" }, { "type": "null" } ], "title": "Parentnodeid" }, "personId": { "anyOf": [ { "description": "Opaque person id.", "pattern": "^per_[0-9a-f]{32}$", "type": "string" }, { "type": "null" } ], "title": "Personid" }, "relatedCompanyId": { "anyOf": [ { "description": "Opaque company id.", "pattern": "^com_[0-9a-f]{32}$", "type": "string" }, { "type": "null" } ], "title": "Relatedcompanyid" }, "role": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Role" }, "status": { "title": "Status", "type": "string" } }, "required": [ "id", "companyId", "parentNodeId", "nodeType", "personId", "relatedCompanyId", "name", "role", "ownershipPct", "effectivePct", "ownershipType", "isControlPerson", "status", "createdAt" ], "title": "UboNodeResponse", "type": "object" }, "VaultDecryptRequest": { "description": "`fields` omitido -> TODOS los `allowedFields` del token; provisto -> debe ser subconjunto\n(else 403 `field_not_in_token_scope`).", "properties": { "fields": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Fields" } }, "title": "VaultDecryptRequest", "type": "object" }, "VerificationCertificate": { "description": "⑩ La constancia SELLADA de una verificación: determinista y archivable.\n\nCÓMO SE VERIFICA, y por qué el orden de los campos importa. El `contentHash` es el sha256 —y la\n`signature` el HMAC-SHA256— sobre el JSON canónico de ESTE MISMO documento **sin sus dos campos\nde sello**, serializado con `sort_keys=True` y `separators=(\",\", \":\")`. Un integrador puede\nrecomputar el `contentHash` con lo que recibe; la `signature` sólo la puede recomputar quien\ntenga el secreto del servidor. El primero detecta una alteración accidental; la segunda, una\ndeliberada.\n\nEs un sello SIMÉTRICO verificable server-side, **no** una firma pública de terceros: no es\nNOM-151 ni pretende serlo.", "properties": { "biometric": { "items": { "$ref": "#/components/schemas/CertificateBiometric" }, "title": "Biometric", "type": "array" }, "contentHash": { "title": "Contenthash", "type": "string" }, "decidedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decidedat" }, "decidedBy": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decidedby" }, "environment": { "title": "Environment", "type": "string" }, "gov": { "items": { "$ref": "#/components/schemas/CertificateGov" }, "title": "Gov", "type": "array" }, "media": { "items": { "$ref": "#/components/schemas/CertificateMedia" }, "title": "Media", "type": "array" }, "outcome": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Outcome" }, "reasonCodes": { "items": { "type": "string" }, "title": "Reasoncodes", "type": "array" }, "riskBasis": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Riskbasis" }, "riskGrade": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Riskgrade" }, "sessionId": { "title": "Sessionid", "type": "string" }, "signature": { "title": "Signature", "type": "string" }, "tenantId": { "title": "Tenantid", "type": "string" }, "trustScore": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Trustscore" }, "verificationStatus": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Verificationstatus" } }, "required": [ "sessionId", "tenantId", "environment", "verificationStatus", "outcome", "decidedAt", "decidedBy", "trustScore", "reasonCodes", "riskGrade", "riskBasis", "biometric", "gov", "media", "contentHash", "signature" ], "title": "VerificationCertificate", "type": "object" }, "VerificationChannel": { "enum": [ "api", "sdk", "link", "embed" ], "title": "VerificationChannel", "type": "string" }, "VerificationReportDecision": { "description": "Bloque de decisión/estado, alineado al contrato saliente (helpers de verification_report).", "properties": { "decidedAt": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Decidedat" }, "decidedBy": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decidedby" }, "humanReviewAvailable": { "default": false, "title": "Humanreviewavailable", "type": "boolean" }, "outcome": { "anyOf": [ { "$ref": "#/components/schemas/DecisionOutcome" }, { "type": "null" } ] }, "reasonCodes": { "items": { "type": "string" }, "title": "Reasoncodes", "type": "array" }, "risk": { "anyOf": [ { "$ref": "#/components/schemas/RiskGradeSummary" }, { "type": "null" } ] }, "trustScore": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Trustscore" }, "verificationStatus": { "title": "Verificationstatus", "type": "string" } }, "required": [ "verificationStatus", "outcome", "reasonCodes", "trustScore", "decidedBy", "decidedAt" ], "title": "VerificationReportDecision", "type": "object" }, "VerificationReportDetail": { "description": "Detalle COMPLETO de una sesión para el dashboard del tenant.\n\n`id`/`public_id`: mismo `vrf_...` ya resuelto (familia ALMACENADA) -- ver el docstring de\n`ReviewQueueItem` (`app/schemas/review.py`) para el porqué de preservar los dos campos.", "properties": { "biometric": { "items": { "$ref": "#/components/schemas/BiometricCheckItem" }, "title": "Biometric", "type": "array" }, "channel": { "title": "Channel", "type": "string" }, "completedAt": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Completedat" }, "createdAt": { "format": "date-time", "title": "Createdat", "type": "string" }, "decidedAt": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Decidedat" }, "decision": { "anyOf": [ { "$ref": "#/components/schemas/VerificationReportDecision" }, { "type": "null" } ] }, "document": { "anyOf": [ { "$ref": "#/components/schemas/DocumentSummary" }, { "type": "null" } ] }, "gov": { "items": { "$ref": "#/components/schemas/app__schemas__verification__GovLookupItem" }, "title": "Gov", "type": "array" }, "id": { "title": "Id", "type": "string" }, "publicId": { "title": "Publicid", "type": "string" }, "status": { "title": "Status", "type": "string" }, "steps": { "items": { "$ref": "#/components/schemas/VerificationStepItem" }, "title": "Steps", "type": "array" }, "trustBreakdown": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Trustbreakdown" } }, "required": [ "id", "publicId", "status", "channel", "decision", "steps", "biometric", "gov", "trustBreakdown", "createdAt", "completedAt", "decidedAt" ], "title": "VerificationReportDetail", "type": "object" }, "VerificationSessionCreate": { "properties": { "applicationId": { "anyOf": [ { "description": "Opaque application id.", "pattern": "^app_[0-9a-f]{32}$", "type": "string" }, { "type": "null" } ], "title": "Applicationid" }, "callbackUrl": { "anyOf": [ { "format": "uri", "maxLength": 2083, "minLength": 1, "type": "string" }, { "type": "null" } ], "title": "Callbackurl" }, "channel": { "$ref": "#/components/schemas/VerificationChannel" }, "checks": { "anyOf": [ { "$ref": "#/components/schemas/CheckSelectionInput" }, { "type": "null" } ] }, "clientReference": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "title": "Clientreference" }, "country": { "default": "MX", "maxLength": 2, "minLength": 2, "title": "Country", "type": "string" }, "flow": { "anyOf": [ { "maxLength": 120, "minLength": 1, "type": "string" }, { "type": "null" } ], "title": "Flow" }, "flowId": { "anyOf": [ { "description": "Opaque flow id.", "pattern": "^flw_[0-9a-f]{32}$", "type": "string" }, { "type": "null" } ], "title": "Flowid" }, "locale": { "default": "es", "title": "Locale", "type": "string" }, "meta": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Meta" }, "notificationsMode": { "default": "belfort_managed", "enum": [ "belfort_managed", "integrator_managed" ], "title": "Notificationsmode", "type": "string" }, "personId": { "anyOf": [ { "description": "Opaque person id.", "pattern": "^per_[0-9a-f]{32}$", "type": "string" }, { "type": "null" } ], "title": "Personid" }, "policy": { "anyOf": [ { "$ref": "#/components/schemas/PolicyOverrideInput" }, { "type": "null" } ] }, "redirectUrl": { "anyOf": [ { "format": "uri", "maxLength": 2083, "minLength": 1, "type": "string" }, { "type": "null" } ], "title": "Redirecturl" } }, "required": [ "channel" ], "title": "VerificationSessionCreate", "type": "object" }, "VerificationSessionCreated": { "description": "Solo en el 201 de creación: el link_token se entrega UNA vez (estilo Stripe/Plaid).\n\n`hosted_url` (BEL-260) es la URL LISTA para entregar al usuario final (la página hospedada\nde verificación) — el integrador no arma nada; null en canales sin link (api/sdk).\n\n`callback_secret` (paridad Veriff) se entrega UNA sola vez, igual que `link_token`: es el\nsecreto HMAC que firma el webhook por-sesión (`callback_url`); null si la sesión no trajo\n`callback_url`. NUNCA vive en `VerificationSessionResponse` (GET/list).\n\n`requires_app` + `deep_link` (BEL-193): un flujo de nivel FUERTE (`requires_app=true`, un\ncheck SDK-only como anti-deepfake reforzado) exige la app nativa. `hosted_url` ES el\n`verification_url` del contrato (no se duplica). `deep_link` (`belfort://verify?token=…`)\nsolo se puebla en flujos fuertes con link_token; en canal api/sdk es null (el integrador\naporta la captura). `deep_link` embebe el link_token → credencial single-use, SOLO en el 201.", "properties": { "applicationId": { "description": "Opaque application id.", "pattern": "^app_[0-9a-f]{32}$", "title": "Applicationid", "type": "string" }, "callbackSecret": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Callbacksecret" }, "channel": { "$ref": "#/components/schemas/VerificationChannel" }, "clientReference": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Clientreference" }, "completedAt": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Completedat" }, "country": { "title": "Country", "type": "string" }, "createdAt": { "format": "date-time", "title": "Createdat", "type": "string" }, "currentStep": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Currentstep" }, "decidedAt": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Decidedat" }, "deepLink": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Deeplink" }, "expiresAt": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Expiresat" }, "flowId": { "anyOf": [ { "description": "Opaque flow id.", "pattern": "^flw_[0-9a-f]{32}$", "type": "string" }, { "type": "null" } ], "title": "Flowid" }, "hostedUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Hostedurl" }, "id": { "title": "Id", "type": "string" }, "linkToken": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Linktoken" }, "locale": { "title": "Locale", "type": "string" }, "personId": { "anyOf": [ { "description": "Opaque person id.", "pattern": "^per_[0-9a-f]{32}$", "type": "string" }, { "type": "null" } ], "title": "Personid" }, "publicId": { "title": "Publicid", "type": "string" }, "requiresApp": { "default": false, "title": "Requiresapp", "type": "boolean" }, "startedAt": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Startedat" }, "status": { "$ref": "#/components/schemas/VerificationStatus" }, "tenantId": { "description": "Opaque tenant id.", "pattern": "^ten_[0-9a-f]{32}$", "title": "Tenantid", "type": "string" }, "trustScore": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Trustscore" }, "updatedAt": { "format": "date-time", "title": "Updatedat", "type": "string" } }, "required": [ "id", "publicId", "tenantId", "applicationId", "personId", "flowId", "channel", "status", "trustScore", "country", "locale", "clientReference", "currentStep", "expiresAt", "startedAt", "completedAt", "decidedAt", "createdAt", "updatedAt", "linkToken" ], "title": "VerificationSessionCreated", "type": "object" }, "VerificationSessionResponse": { "description": "Respuesta estándar — NUNCA incluye link_token (credencial bearer del applicant).\n\n`id`/`public_id`: mismo `vrf_...` ya resuelto (familia ALMACENADA) -- ver el docstring de\n`ReviewQueueItem` (`app/schemas/review.py`) para el porqué de preservar los dos campos.\n`id` usa `stored_id_field()` (a diferencia de las construcciones explícitas del resto del\nrepo): este schema SÍ se llena vía `model_validate(session)` -- sin el alias, leería\n`session.id` (el UUID interno) en vez de `session.public_id`.", "properties": { "applicationId": { "description": "Opaque application id.", "pattern": "^app_[0-9a-f]{32}$", "title": "Applicationid", "type": "string" }, "channel": { "$ref": "#/components/schemas/VerificationChannel" }, "clientReference": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Clientreference" }, "completedAt": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Completedat" }, "country": { "title": "Country", "type": "string" }, "createdAt": { "format": "date-time", "title": "Createdat", "type": "string" }, "currentStep": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Currentstep" }, "decidedAt": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Decidedat" }, "expiresAt": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Expiresat" }, "flowId": { "anyOf": [ { "description": "Opaque flow id.", "pattern": "^flw_[0-9a-f]{32}$", "type": "string" }, { "type": "null" } ], "title": "Flowid" }, "id": { "title": "Id", "type": "string" }, "locale": { "title": "Locale", "type": "string" }, "personId": { "anyOf": [ { "description": "Opaque person id.", "pattern": "^per_[0-9a-f]{32}$", "type": "string" }, { "type": "null" } ], "title": "Personid" }, "publicId": { "title": "Publicid", "type": "string" }, "startedAt": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Startedat" }, "status": { "$ref": "#/components/schemas/VerificationStatus" }, "tenantId": { "description": "Opaque tenant id.", "pattern": "^ten_[0-9a-f]{32}$", "title": "Tenantid", "type": "string" }, "trustScore": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Trustscore" }, "updatedAt": { "format": "date-time", "title": "Updatedat", "type": "string" } }, "required": [ "id", "publicId", "tenantId", "applicationId", "personId", "flowId", "channel", "status", "trustScore", "country", "locale", "clientReference", "currentStep", "expiresAt", "startedAt", "completedAt", "decidedAt", "createdAt", "updatedAt" ], "title": "VerificationSessionResponse", "type": "object" }, "VerificationStatus": { "enum": [ "pending", "in_progress", "review", "awaiting_input", "approved", "declined", "expired", "abandoned" ], "title": "VerificationStatus", "type": "string" }, "VerificationStepItem": { "description": "Una etapa del pipeline (idv.verification_step).", "properties": { "completedAt": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Completedat" }, "errorCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Errorcode" }, "result": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Result" }, "sequence": { "title": "Sequence", "type": "integer" }, "startedAt": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Startedat" }, "status": { "title": "Status", "type": "string" }, "stepType": { "title": "Steptype", "type": "string" } }, "required": [ "stepType", "status", "sequence", "result", "errorCode", "startedAt", "completedAt" ], "title": "VerificationStepItem", "type": "object" }, "VerificationSubmitAccepted": { "description": "202 del submit en modo `durable` (BEL-70): el VerificationWorkflow corre async y el cliente\nsigue el progreso por el SSE existente. `tracking_id` = workflow id (verify-{id}). NO trae\ndecisión: el widget DEBE esperar la decisión real (SSE `pipeline_complete`) antes de emitir\n`belfort:complete` — si la trata como síncrona, manda `review` para el 100% (BEL-204).", "properties": { "kind": { "const": "pending", "default": "pending", "title": "Kind", "type": "string" }, "status": { "default": "in_progress", "title": "Status", "type": "string" }, "trackingId": { "title": "Trackingid", "type": "string" } }, "required": [ "trackingId" ], "title": "VerificationSubmitAccepted", "type": "object" }, "VerificationSubmitResult": { "description": "Resultado SÍNCRONO del submit (200): la decisión ya está. `kind` discrimina la unión\n`SubmitResult` para que el widget no confunda esto con el 202 async (BEL-204).", "properties": { "caseId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Caseid" }, "decision": { "$ref": "#/components/schemas/DecisionSummary" }, "kind": { "const": "decision", "default": "decision", "title": "Kind", "type": "string" }, "status": { "$ref": "#/components/schemas/VerificationStatus" } }, "required": [ "status", "decision" ], "title": "VerificationSubmitResult", "type": "object" }, "VerificationVolumeSummary": { "properties": { "approved": { "title": "Approved", "type": "integer" }, "declined": { "title": "Declined", "type": "integer" }, "review": { "title": "Review", "type": "integer" }, "total": { "title": "Total", "type": "integer" } }, "required": [ "total", "approved", "declined", "review" ], "title": "VerificationVolumeSummary", "type": "object" }, "VerifyPhase": { "description": "Fase del contrato de polling de /verify (BEL-209).\n\nDistingue procesando / revisión / completado / fallido para que el integrador (AllSign) sepa\ncuándo dejar de pollear. Solo `processing` es no-final; el approved/declined que sigue a un\n`review` llega por webhook, no por polling.", "enum": [ "processing", "review", "completed", "failed" ], "title": "VerifyPhase", "type": "string" }, "WebhookAttemptOutcome": { "description": "Resultado de UN intento de entrega (fila append-only en webhook_delivery_attempt).", "enum": [ "sent", "transient", "permanent" ], "title": "WebhookAttemptOutcome", "type": "string" }, "WebhookDeliveryAttemptResponse": { "description": "Un intento de entrega (estilo Stripe): el detalle completo de UN POST HTTP.", "properties": { "attemptNumber": { "title": "Attemptnumber", "type": "integer" }, "attemptedAt": { "format": "date-time", "title": "Attemptedat", "type": "string" }, "durationMs": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Durationms" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error" }, "id": { "description": "Opaque webhook delivery attempt id.", "pattern": "^wha_[0-9a-f]{32}$", "title": "Id", "type": "string" }, "outcome": { "$ref": "#/components/schemas/WebhookAttemptOutcome" }, "responseBody": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Responsebody" }, "statusCode": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Statuscode" } }, "required": [ "id", "attemptNumber", "outcome", "statusCode", "responseBody", "error", "durationMs", "attemptedAt" ], "title": "WebhookDeliveryAttemptResponse", "type": "object" }, "WebhookDeliveryPolicy": { "description": "Política de entrega ESTÁTICA (BEL-449), fuente única = las constantes de\n`app/services/webhook_service.py`. Documenta el contrato para que un integrador implemente\nsu receptor sin adivinar (timeouts, backoff, permanente-vs-transitorio, rate limit).", "properties": { "backoffBaseSeconds": { "title": "Backoffbaseseconds", "type": "integer" }, "httpTimeoutSeconds": { "title": "Httptimeoutseconds", "type": "integer" }, "maxBackoffSeconds": { "title": "Maxbackoffseconds", "type": "integer" }, "permanentVsTransientRule": { "title": "Permanentvstransientrule", "type": "string" }, "rateLimitDefaultRpm": { "title": "Ratelimitdefaultrpm", "type": "integer" }, "recommendedToleranceSeconds": { "title": "Recommendedtoleranceseconds", "type": "integer" }, "retryBudgetNote": { "title": "Retrybudgetnote", "type": "string" }, "signatureScheme": { "title": "Signaturescheme", "type": "string" } }, "required": [ "signatureScheme", "recommendedToleranceSeconds", "httpTimeoutSeconds", "backoffBaseSeconds", "maxBackoffSeconds", "retryBudgetNote", "permanentVsTransientRule", "rateLimitDefaultRpm" ], "title": "WebhookDeliveryPolicy", "type": "object" }, "WebhookDeliveryResponse": { "description": "Una fila del historial de entregas (observabilidad).", "properties": { "attempts": { "title": "Attempts", "type": "integer" }, "createdAt": { "format": "date-time", "title": "Createdat", "type": "string" }, "endpointId": { "anyOf": [ { "description": "Opaque webhook endpoint id.", "pattern": "^whe_[0-9a-f]{32}$", "type": "string" }, { "type": "null" } ], "title": "Endpointid" }, "eventId": { "anyOf": [ { "description": "Opaque event id.", "pattern": "^evt_[0-9a-f]{32}$", "type": "string" }, { "type": "null" } ], "title": "Eventid" }, "eventType": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Eventtype" }, "id": { "description": "Opaque webhook delivery id.", "pattern": "^whd_[0-9a-f]{32}$", "title": "Id", "type": "string" }, "lastError": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Lasterror" }, "lastStatusCode": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Laststatuscode" }, "nextRetryAt": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Nextretryat" }, "sentAt": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Sentat" }, "status": { "$ref": "#/components/schemas/DeliveryStatus" }, "targetUrl": { "title": "Targeturl", "type": "string" }, "updatedAt": { "format": "date-time", "title": "Updatedat", "type": "string" } }, "required": [ "id", "endpointId", "eventId", "eventType", "targetUrl", "status", "attempts", "lastStatusCode", "lastError", "nextRetryAt", "sentAt", "createdAt", "updatedAt" ], "title": "WebhookDeliveryResponse", "type": "object" }, "WebhookEndpointCreate": { "properties": { "applicationId": { "anyOf": [ { "description": "Opaque application id.", "pattern": "^app_[0-9a-f]{32}$", "type": "string" }, { "type": "null" } ], "title": "Applicationid" }, "description": { "anyOf": [ { "maxLength": 500, "type": "string" }, { "type": "null" } ], "title": "Description" }, "environment": { "$ref": "#/components/schemas/ApiEnvironment", "default": "live" }, "events": { "items": { "type": "string" }, "title": "Events", "type": "array" }, "url": { "format": "uri", "maxLength": 2083, "minLength": 1, "title": "Url", "type": "string" } }, "required": [ "url" ], "title": "WebhookEndpointCreate", "type": "object" }, "WebhookEndpointCreated": { "description": "Solo en el 201: el signing secret se entrega UNA vez (estilo Stripe whsec_).", "properties": { "applicationId": { "anyOf": [ { "description": "Opaque application id.", "pattern": "^app_[0-9a-f]{32}$", "type": "string" }, { "type": "null" } ], "title": "Applicationid" }, "createdAt": { "format": "date-time", "title": "Createdat", "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "environment": { "$ref": "#/components/schemas/ApiEnvironment" }, "events": { "anyOf": [ { "items": {}, "type": "array" }, { "type": "null" } ], "title": "Events" }, "id": { "description": "Opaque webhook endpoint id.", "pattern": "^whe_[0-9a-f]{32}$", "title": "Id", "type": "string" }, "isActive": { "title": "Isactive", "type": "boolean" }, "secret": { "title": "Secret", "type": "string" }, "updatedAt": { "format": "date-time", "title": "Updatedat", "type": "string" }, "url": { "title": "Url", "type": "string" } }, "required": [ "id", "url", "description", "events", "environment", "applicationId", "isActive", "createdAt", "updatedAt", "secret" ], "title": "WebhookEndpointCreated", "type": "object" }, "WebhookEndpointResponse": { "description": "Respuesta estándar — NUNCA incluye el signing secret.", "properties": { "applicationId": { "anyOf": [ { "description": "Opaque application id.", "pattern": "^app_[0-9a-f]{32}$", "type": "string" }, { "type": "null" } ], "title": "Applicationid" }, "createdAt": { "format": "date-time", "title": "Createdat", "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "environment": { "$ref": "#/components/schemas/ApiEnvironment" }, "events": { "anyOf": [ { "items": {}, "type": "array" }, { "type": "null" } ], "title": "Events" }, "id": { "description": "Opaque webhook endpoint id.", "pattern": "^whe_[0-9a-f]{32}$", "title": "Id", "type": "string" }, "isActive": { "title": "Isactive", "type": "boolean" }, "updatedAt": { "format": "date-time", "title": "Updatedat", "type": "string" }, "url": { "title": "Url", "type": "string" } }, "required": [ "id", "url", "description", "events", "environment", "applicationId", "isActive", "createdAt", "updatedAt" ], "title": "WebhookEndpointResponse", "type": "object" }, "WebhookEndpointUpdate": { "description": "PATCH parcial: solo los campos presentes se modifican. El entorno NO se edita\n(cambiarlo invalidaría el ruteo de outbox/delivery); para eso se crea otro endpoint.", "properties": { "applicationId": { "anyOf": [ { "description": "Opaque application id.", "pattern": "^app_[0-9a-f]{32}$", "type": "string" }, { "type": "null" } ], "title": "Applicationid" }, "description": { "anyOf": [ { "maxLength": 500, "type": "string" }, { "type": "null" } ], "title": "Description" }, "events": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Events" }, "isActive": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Isactive" }, "url": { "anyOf": [ { "format": "uri", "maxLength": 2083, "minLength": 1, "type": "string" }, { "type": "null" } ], "title": "Url" } }, "title": "WebhookEndpointUpdate", "type": "object" }, "WebhookEventTypeCatalog": { "description": "Respuesta de GET /developer/webhooks/event-types: keys exactas + patrones de\nsuscripción válidos para el campo `events` del registro de endpoints.", "properties": { "eventTypes": { "items": { "$ref": "#/components/schemas/WebhookEventTypeItem" }, "title": "Eventtypes", "type": "array" }, "patterns": { "items": { "type": "string" }, "title": "Patterns", "type": "array" } }, "required": [ "eventTypes", "patterns" ], "title": "WebhookEventTypeCatalog", "type": "object" }, "WebhookEventTypeItem": { "description": "Un event type del catálogo canónico (BEL-293).", "properties": { "description": { "title": "Description", "type": "string" }, "key": { "title": "Key", "type": "string" } }, "required": [ "key", "description" ], "title": "WebhookEventTypeItem", "type": "object" }, "WebhookSignatureVerifyRequest": { "description": "Body de `POST /{endpoint_id}/verify-signature` (BEL-449): un integrador que está\ndebuggeando su receptor manda EXACTAMENTE lo que recibió — el `payload` es el body RAW\nbyte-exacto (como string, NO re-serializado) y las tres cabeceras de Standard Webhooks.\n\nHabla el MISMO esquema que las entregas reales. Antes hablaba el legado (`Belfort-Signature`),\ny eso es peor que no tener la herramienta: el integrador verificaba con éxito contra un formato\nque ya nunca le llega, y se iba convencido de que su receptor estaba bien.\n\n`messageId` es obligatorio porque entra en el material firmado (`{id}.{ts}.{body}`): sin él no\nse puede recomputar nada.", "properties": { "messageId": { "title": "Messageid", "type": "string" }, "payload": { "title": "Payload", "type": "string" }, "signature": { "title": "Signature", "type": "string" }, "timestamp": { "title": "Timestamp", "type": "integer" } }, "required": [ "payload", "messageId", "timestamp", "signature" ], "title": "WebhookSignatureVerifyRequest", "type": "object" }, "WebhookSignatureVerifyResult": { "description": "Resultado de la verificación (BEL-449). `expected_signature` es SIEMPRE el formato de\nStandard Webhooks `v1,` recomputado con el secret del endpoint — NUNCA el secret\nmismo. Decía `t=,v1=`, que es el legado que la clase de arriba explica por qué se\nabandonó: describir aquí un formato que ya no se emite es la misma trampa, un escalón más\nabajo.", "properties": { "expectedSignature": { "title": "Expectedsignature", "type": "string" }, "valid": { "title": "Valid", "type": "boolean" } }, "required": [ "valid", "expectedSignature" ], "title": "WebhookSignatureVerifyResult", "type": "object" }, "WebhookTestRequest": { "description": "Body opcional de `POST /test` (BEL-449). Sin body (o `eventType=None`) preserva el ping\n`belfort.test` de siempre (retrocompat total). Si viene, DEBE ser una key del catálogo\ncanónico (`EVENT_TYPES`) — el router valida y rechaza 422 `webhook_test_event_unknown` si no\nlo es (ver `WebhookService.send_test`).", "properties": { "eventType": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Eventtype" } }, "title": "WebhookTestRequest", "type": "object" }, "WebhookTestResult": { "description": "Resultado de `POST /test`: ping firmado y síncrono al endpoint (no toca outbox/delivery).", "properties": { "delivered": { "title": "Delivered", "type": "boolean" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error" }, "sentPayload": { "additionalProperties": true, "title": "Sentpayload", "type": "object" }, "statusCode": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Statuscode" } }, "required": [ "delivered", "statusCode", "error", "sentPayload" ], "title": "WebhookTestResult", "type": "object" }, "app__schemas__review__GovLookupItem": { "properties": { "latencyMs": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Latencyms" }, "provider": { "title": "Provider", "type": "string" }, "queriedAt": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Queriedat" }, "response": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Response" }, "result": { "title": "Result", "type": "string" } }, "required": [ "provider", "result", "queriedAt", "latencyMs", "response" ], "title": "GovLookupItem", "type": "object" }, "app__schemas__verification__GovLookupItem": { "description": "Una consulta gubernamental (idv.gov_lookup). NUNCA expone la respuesta cruda completa (PII):\n`detail` es un subconjunto CURADO de estatus para Lista Nominal INE (BEL-383).", "properties": { "detail": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Detail" }, "latencyMs": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Latencyms" }, "provider": { "title": "Provider", "type": "string" }, "providerRequestId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Providerrequestid" }, "queriedAt": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Queriedat" }, "result": { "title": "Result", "type": "string" } }, "required": [ "provider", "result", "queriedAt", "latencyMs", "providerRequestId" ], "title": "GovLookupItem", "type": "object" } }, "securitySchemes": { "clientToken": { "bearerFormat": "ctok_...", "description": "Token efímero emitido por `POST /v1/persons/{id}/client-token` -- browser-safe, SIN secreto de API key. Redimido en `POST /v1/vault/decrypt`.\n\n**REUSABLE hasta su TTL (<=15 min), NO de un solo uso.** Cada redención audita su propia fila de `pii_access_event` e incrementa `redeemed_count`, pero no consume ni invalida el token: sigue descifrando hasta que expira. Trátalo como una credencial viva durante toda su ventana -- si se filtra, revócalo con `POST /v1/persons/{id}/client-token/{ctkId}/revoke`; no basta con que ya se haya usado. Emítelo con el TTL más corto que te sirva y los `allowedFields` mínimos (quedan FIJOS al emitir; la redención solo puede pedir un subconjunto).", "scheme": "bearer", "type": "http" }, "publishableKey": { "bearerFormat": "belfort_{env}_pk_...", "description": "Key publicable del tenant. Viaja al NAVEGADOR, así que no concede nada por sí sola: solo abre una sesión embebida contra los `allowedOrigins` configurados. Nunca la uses para leer datos -- para eso está `secretKey`, que jamás debe salir de tu backend.", "scheme": "bearer", "type": "http" }, "secretKey": { "bearerFormat": "belfort_{env}_sk_...", "description": "API key secreta del tenant. `belfort_test_sk_...` opera en sandbox (test_mode determinista, sin créditos); `belfort_live_sk_...` opera en LIVE. El scope concedido a la key debe cubrir el `x-required-scope` de cada operación.", "scheme": "bearer", "type": "http" } } }, "info": { "description": "API pública de Belfort: verificación de identidad y vault de PII.\n\nCubre el flujo de verificación (canal API-direct y canal embebido en el navegador), el vault de\npersonas con revelado auditado de PII, KYB de empresas, screening AML, la cola de revisión manual,\nwebhooks y la superficie de cumplimiento (`audit-logs`, `compliance`) — todo detrás de una API key\n`sk_` con scopes granulares.\n\nEmpieza por la guía de inicio rápido en https://belfort.ai/docs/quickstart, un sandbox reproducible\ncon una API key de prueba y un CURP mágico.\n\nTodo error es un documento de problema RFC 9457 (`application/problem+json`) plano: programa contra\n`code` (top-level, vocabulario append-only), nunca contra `detail`. El catálogo completo, con el\nsignificado de cada código, está en https://belfort.ai/docs/errors.\n\nCualquier generador OpenAPI 3.1 (openapi-generator, Speakeasy, Stainless) produce un cliente usable\ndirecto desde este documento.\n", "title": "Belfort API", "version": "2026-07-30" }, "openapi": "3.1.0", "paths": { "/v1/audit-logs": { "get": { "description": "Los accesos a datos personales, por cursor. Quién, cuándo, a qué persona, con qué finalidad y si vio el dato en claro o enmascarado.", "operationId": "listAuditLogs", "parameters": [ { "in": "query", "name": "actorId", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Actorid" } }, { "in": "query", "name": "actorType", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Actortype" } }, { "in": "query", "name": "channel", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Channel" } }, { "in": "query", "name": "createdGte", "required": false, "schema": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Createdgte" } }, { "in": "query", "name": "createdLte", "required": false, "schema": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Createdlte" } }, { "in": "query", "name": "format", "required": false, "schema": { "default": "json", "title": "Format", "type": "string" } }, { "description": "Tamaño de página (1–100).", "in": "query", "name": "limit", "required": false, "schema": { "default": 20, "description": "Tamaño de página (1–100).", "title": "Limit", "type": "integer" } }, { "description": "`nextCursor` de la página anterior. Excluyente con `endingBefore`.", "in": "query", "name": "startingAfter", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "`nextCursor` de la página anterior. Excluyente con `endingBefore`.", "title": "Startingafter" } }, { "description": "`previousCursor` de la página actual. Excluyente con `startingAfter`.", "in": "query", "name": "endingBefore", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "`previousCursor` de la página actual. Excluyente con `startingAfter`.", "title": "Endingbefore" } }, { "description": "Calcula `totalCount`. Cuesta un `COUNT(*)` sobre el filtro entero, así que está apagado por defecto: pídelo solo cuando vayas a enseñar el total.", "in": "query", "name": "includeTotal", "required": false, "schema": { "default": false, "description": "Calcula `totalCount`. Cuesta un `COUNT(*)` sobre el filtro entero, así que está apagado por defecto: pídelo solo cuando vayas a enseñar el total.", "title": "Includetotal", "type": "boolean" } }, { "in": "query", "name": "personId", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Personid" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListEnvelope_AuditLogEntry_" } } }, "description": "Successful Response" }, "400": { "content": { "application/problem+json": { "examples": { "UNSUPPORTED_API_VERSION": { "summary": "UNSUPPORTED_API_VERSION", "value": { "code": "UNSUPPORTED_API_VERSION", "detail": "Unsupported API version", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 400, "title": "Unsupported API version", "type": "https://belfort.ai/docs/errors#UNSUPPORTED_API_VERSION" } } } } }, "description": "UNSUPPORTED_API_VERSION" }, "405": { "content": { "application/problem+json": { "examples": { "METHOD_NOT_ALLOWED": { "summary": "METHOD_NOT_ALLOWED", "value": { "code": "METHOD_NOT_ALLOWED", "detail": "Method not allowed", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 405, "title": "Method not allowed", "type": "https://belfort.ai/docs/errors#METHOD_NOT_ALLOWED" } } } } }, "description": "METHOD_NOT_ALLOWED" }, "422": { "content": { "application/problem+json": { "examples": { "VALIDATION_ERROR": { "summary": "VALIDATION_ERROR", "value": { "code": "VALIDATION_ERROR", "detail": "Validation error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 422, "title": "Validation error", "type": "https://belfort.ai/docs/errors#VALIDATION_ERROR" } } } } }, "description": "VALIDATION_ERROR" }, "500": { "content": { "application/problem+json": { "examples": { "INTERNAL_ERROR": { "summary": "INTERNAL_ERROR", "value": { "code": "INTERNAL_ERROR", "detail": "Internal server error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 500, "title": "Internal server error", "type": "https://belfort.ai/docs/errors#INTERNAL_ERROR" } } } } }, "description": "INTERNAL_ERROR" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Error — documento de problema RFC 9457 (`application/problem+json`)." } }, "security": [ { "secretKey": [] } ], "summary": "Consultar la bitácora", "tags": [ "compliance" ], "x-required-scope": "compliance:read" } }, "/v1/audit-logs/verify": { "get": { "description": "La bitácora está encadenada por hash. Esto comprueba que nadie borró ni alteró una entrada — incluidos nosotros.", "operationId": "verifyAuditLogChain", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuditChainVerification" } } }, "description": "Successful Response" }, "400": { "content": { "application/problem+json": { "examples": { "UNSUPPORTED_API_VERSION": { "summary": "UNSUPPORTED_API_VERSION", "value": { "code": "UNSUPPORTED_API_VERSION", "detail": "Unsupported API version", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 400, "title": "Unsupported API version", "type": "https://belfort.ai/docs/errors#UNSUPPORTED_API_VERSION" } } } } }, "description": "UNSUPPORTED_API_VERSION" }, "405": { "content": { "application/problem+json": { "examples": { "METHOD_NOT_ALLOWED": { "summary": "METHOD_NOT_ALLOWED", "value": { "code": "METHOD_NOT_ALLOWED", "detail": "Method not allowed", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 405, "title": "Method not allowed", "type": "https://belfort.ai/docs/errors#METHOD_NOT_ALLOWED" } } } } }, "description": "METHOD_NOT_ALLOWED" }, "422": { "content": { "application/problem+json": { "examples": { "VALIDATION_ERROR": { "summary": "VALIDATION_ERROR", "value": { "code": "VALIDATION_ERROR", "detail": "Validation error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 422, "title": "Validation error", "type": "https://belfort.ai/docs/errors#VALIDATION_ERROR" } } } } }, "description": "VALIDATION_ERROR" }, "500": { "content": { "application/problem+json": { "examples": { "INTERNAL_ERROR": { "summary": "INTERNAL_ERROR", "value": { "code": "INTERNAL_ERROR", "detail": "Internal server error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 500, "title": "Internal server error", "type": "https://belfort.ai/docs/errors#INTERNAL_ERROR" } } } } }, "description": "INTERNAL_ERROR" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Error — documento de problema RFC 9457 (`application/problem+json`)." } }, "security": [ { "secretKey": [] } ], "summary": "Verificar la cadena de la bitácora", "tags": [ "compliance" ], "x-required-scope": "compliance:read" } }, "/v1/companies": { "get": { "description": "Página por cursor de las empresas bajo verificación KYB.", "operationId": "listCompanies", "parameters": [ { "in": "query", "name": "claimStatus", "required": false, "schema": { "anyOf": [ { "$ref": "#/components/schemas/CompanyClaimStatus" }, { "type": "null" } ], "title": "Claimstatus" } }, { "description": "Tamaño de página (1–100).", "in": "query", "name": "limit", "required": false, "schema": { "default": 20, "description": "Tamaño de página (1–100).", "title": "Limit", "type": "integer" } }, { "description": "`nextCursor` de la página anterior. Excluyente con `endingBefore`.", "in": "query", "name": "startingAfter", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "`nextCursor` de la página anterior. Excluyente con `endingBefore`.", "title": "Startingafter" } }, { "description": "`previousCursor` de la página actual. Excluyente con `startingAfter`.", "in": "query", "name": "endingBefore", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "`previousCursor` de la página actual. Excluyente con `startingAfter`.", "title": "Endingbefore" } }, { "description": "Calcula `totalCount`. Cuesta un `COUNT(*)` sobre el filtro entero, así que está apagado por defecto: pídelo solo cuando vayas a enseñar el total.", "in": "query", "name": "includeTotal", "required": false, "schema": { "default": false, "description": "Calcula `totalCount`. Cuesta un `COUNT(*)` sobre el filtro entero, así que está apagado por defecto: pídelo solo cuando vayas a enseñar el total.", "title": "Includetotal", "type": "boolean" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListEnvelope_CompanyResponse_" } } }, "description": "Successful Response" }, "400": { "content": { "application/problem+json": { "examples": { "UNSUPPORTED_API_VERSION": { "summary": "UNSUPPORTED_API_VERSION", "value": { "code": "UNSUPPORTED_API_VERSION", "detail": "Unsupported API version", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 400, "title": "Unsupported API version", "type": "https://belfort.ai/docs/errors#UNSUPPORTED_API_VERSION" } } } } }, "description": "UNSUPPORTED_API_VERSION" }, "405": { "content": { "application/problem+json": { "examples": { "METHOD_NOT_ALLOWED": { "summary": "METHOD_NOT_ALLOWED", "value": { "code": "METHOD_NOT_ALLOWED", "detail": "Method not allowed", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 405, "title": "Method not allowed", "type": "https://belfort.ai/docs/errors#METHOD_NOT_ALLOWED" } } } } }, "description": "METHOD_NOT_ALLOWED" }, "422": { "content": { "application/problem+json": { "examples": { "VALIDATION_ERROR": { "summary": "VALIDATION_ERROR", "value": { "code": "VALIDATION_ERROR", "detail": "Validation error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 422, "title": "Validation error", "type": "https://belfort.ai/docs/errors#VALIDATION_ERROR" } } } } }, "description": "VALIDATION_ERROR" }, "500": { "content": { "application/problem+json": { "examples": { "INTERNAL_ERROR": { "summary": "INTERNAL_ERROR", "value": { "code": "INTERNAL_ERROR", "detail": "Internal server error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 500, "title": "Internal server error", "type": "https://belfort.ai/docs/errors#INTERNAL_ERROR" } } } } }, "description": "INTERNAL_ERROR" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Error — documento de problema RFC 9457 (`application/problem+json`)." } }, "security": [ { "secretKey": [] } ], "summary": "Listar empresas", "tags": [ "kyb" ], "x-required-scope": "kyb:read" }, "post": { "description": "Crea el expediente. Todavía no verifica nada: primero cargas miembros y documentos, después disparas el pipeline. `Idempotency-Key` obligatoria.", "operationId": "createCompany", "parameters": [ { "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Idempotency-Key" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyCreate" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyResponse" } } }, "description": "Successful Response" }, "400": { "content": { "application/problem+json": { "examples": { "UNSUPPORTED_API_VERSION": { "summary": "UNSUPPORTED_API_VERSION", "value": { "code": "UNSUPPORTED_API_VERSION", "detail": "Unsupported API version", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 400, "title": "Unsupported API version", "type": "https://belfort.ai/docs/errors#UNSUPPORTED_API_VERSION" } } } } }, "description": "UNSUPPORTED_API_VERSION" }, "405": { "content": { "application/problem+json": { "examples": { "METHOD_NOT_ALLOWED": { "summary": "METHOD_NOT_ALLOWED", "value": { "code": "METHOD_NOT_ALLOWED", "detail": "Method not allowed", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 405, "title": "Method not allowed", "type": "https://belfort.ai/docs/errors#METHOD_NOT_ALLOWED" } } } } }, "description": "METHOD_NOT_ALLOWED" }, "422": { "content": { "application/problem+json": { "examples": { "VALIDATION_ERROR": { "summary": "VALIDATION_ERROR", "value": { "code": "VALIDATION_ERROR", "detail": "Validation error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 422, "title": "Validation error", "type": "https://belfort.ai/docs/errors#VALIDATION_ERROR" } } } } }, "description": "VALIDATION_ERROR" }, "500": { "content": { "application/problem+json": { "examples": { "INTERNAL_ERROR": { "summary": "INTERNAL_ERROR", "value": { "code": "INTERNAL_ERROR", "detail": "Internal server error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 500, "title": "Internal server error", "type": "https://belfort.ai/docs/errors#INTERNAL_ERROR" } } } } }, "description": "INTERNAL_ERROR" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Error — documento de problema RFC 9457 (`application/problem+json`)." } }, "security": [ { "secretKey": [] } ], "summary": "Dar de alta una empresa", "tags": [ "kyb" ], "x-required-scope": "kyb:write" } }, "/v1/companies/{company_id}": { "get": { "description": "El expediente completo: grafo de propiedad, miembros, comprobaciones, documentos y coincidencias AML.", "operationId": "getCompanyDetail", "parameters": [ { "in": "path", "name": "company_id", "required": true, "schema": { "title": "Company Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyDetail" } } }, "description": "Successful Response" }, "400": { "content": { "application/problem+json": { "examples": { "UNSUPPORTED_API_VERSION": { "summary": "UNSUPPORTED_API_VERSION", "value": { "code": "UNSUPPORTED_API_VERSION", "detail": "Unsupported API version", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 400, "title": "Unsupported API version", "type": "https://belfort.ai/docs/errors#UNSUPPORTED_API_VERSION" } } } } }, "description": "UNSUPPORTED_API_VERSION" }, "405": { "content": { "application/problem+json": { "examples": { "METHOD_NOT_ALLOWED": { "summary": "METHOD_NOT_ALLOWED", "value": { "code": "METHOD_NOT_ALLOWED", "detail": "Method not allowed", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 405, "title": "Method not allowed", "type": "https://belfort.ai/docs/errors#METHOD_NOT_ALLOWED" } } } } }, "description": "METHOD_NOT_ALLOWED" }, "422": { "content": { "application/problem+json": { "examples": { "VALIDATION_ERROR": { "summary": "VALIDATION_ERROR", "value": { "code": "VALIDATION_ERROR", "detail": "Validation error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 422, "title": "Validation error", "type": "https://belfort.ai/docs/errors#VALIDATION_ERROR" } } } } }, "description": "VALIDATION_ERROR" }, "500": { "content": { "application/problem+json": { "examples": { "INTERNAL_ERROR": { "summary": "INTERNAL_ERROR", "value": { "code": "INTERNAL_ERROR", "detail": "Internal server error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 500, "title": "Internal server error", "type": "https://belfort.ai/docs/errors#INTERNAL_ERROR" } } } } }, "description": "INTERNAL_ERROR" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Error — documento de problema RFC 9457 (`application/problem+json`)." } }, "security": [ { "secretKey": [] } ], "summary": "Consultar una empresa", "tags": [ "kyb" ], "x-required-scope": "kyb:read" } }, "/v1/companies/{company_id}/documents": { "post": { "description": "Acta constitutiva, poderes, comprobante de domicilio. Se registra la referencia al archivo y sus metadatos.", "operationId": "addCompanyDocument", "parameters": [ { "in": "path", "name": "company_id", "required": true, "schema": { "title": "Company Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyDocumentCreate" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyDocumentResponse" } } }, "description": "Successful Response" }, "400": { "content": { "application/problem+json": { "examples": { "UNSUPPORTED_API_VERSION": { "summary": "UNSUPPORTED_API_VERSION", "value": { "code": "UNSUPPORTED_API_VERSION", "detail": "Unsupported API version", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 400, "title": "Unsupported API version", "type": "https://belfort.ai/docs/errors#UNSUPPORTED_API_VERSION" } } } } }, "description": "UNSUPPORTED_API_VERSION" }, "405": { "content": { "application/problem+json": { "examples": { "METHOD_NOT_ALLOWED": { "summary": "METHOD_NOT_ALLOWED", "value": { "code": "METHOD_NOT_ALLOWED", "detail": "Method not allowed", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 405, "title": "Method not allowed", "type": "https://belfort.ai/docs/errors#METHOD_NOT_ALLOWED" } } } } }, "description": "METHOD_NOT_ALLOWED" }, "422": { "content": { "application/problem+json": { "examples": { "VALIDATION_ERROR": { "summary": "VALIDATION_ERROR", "value": { "code": "VALIDATION_ERROR", "detail": "Validation error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 422, "title": "Validation error", "type": "https://belfort.ai/docs/errors#VALIDATION_ERROR" } } } } }, "description": "VALIDATION_ERROR" }, "500": { "content": { "application/problem+json": { "examples": { "INTERNAL_ERROR": { "summary": "INTERNAL_ERROR", "value": { "code": "INTERNAL_ERROR", "detail": "Internal server error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 500, "title": "Internal server error", "type": "https://belfort.ai/docs/errors#INTERNAL_ERROR" } } } } }, "description": "INTERNAL_ERROR" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Error — documento de problema RFC 9457 (`application/problem+json`)." } }, "security": [ { "secretKey": [] } ], "summary": "Añadir un documento corporativo", "tags": [ "kyb" ], "x-required-scope": "kyb:write" } }, "/v1/companies/{company_id}/members": { "post": { "description": "Representante legal, administrador o cualquier persona física ligada a la empresa.", "operationId": "addCompanyMember", "parameters": [ { "in": "path", "name": "company_id", "required": true, "schema": { "title": "Company Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyMemberCreate" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyMemberResponse" } } }, "description": "Successful Response" }, "400": { "content": { "application/problem+json": { "examples": { "UNSUPPORTED_API_VERSION": { "summary": "UNSUPPORTED_API_VERSION", "value": { "code": "UNSUPPORTED_API_VERSION", "detail": "Unsupported API version", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 400, "title": "Unsupported API version", "type": "https://belfort.ai/docs/errors#UNSUPPORTED_API_VERSION" } } } } }, "description": "UNSUPPORTED_API_VERSION" }, "405": { "content": { "application/problem+json": { "examples": { "METHOD_NOT_ALLOWED": { "summary": "METHOD_NOT_ALLOWED", "value": { "code": "METHOD_NOT_ALLOWED", "detail": "Method not allowed", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 405, "title": "Method not allowed", "type": "https://belfort.ai/docs/errors#METHOD_NOT_ALLOWED" } } } } }, "description": "METHOD_NOT_ALLOWED" }, "422": { "content": { "application/problem+json": { "examples": { "VALIDATION_ERROR": { "summary": "VALIDATION_ERROR", "value": { "code": "VALIDATION_ERROR", "detail": "Validation error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 422, "title": "Validation error", "type": "https://belfort.ai/docs/errors#VALIDATION_ERROR" } } } } }, "description": "VALIDATION_ERROR" }, "500": { "content": { "application/problem+json": { "examples": { "INTERNAL_ERROR": { "summary": "INTERNAL_ERROR", "value": { "code": "INTERNAL_ERROR", "detail": "Internal server error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 500, "title": "Internal server error", "type": "https://belfort.ai/docs/errors#INTERNAL_ERROR" } } } } }, "description": "INTERNAL_ERROR" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Error — documento de problema RFC 9457 (`application/problem+json`)." } }, "security": [ { "secretKey": [] } ], "summary": "Añadir un miembro", "tags": [ "kyb" ], "x-required-scope": "kyb:write" } }, "/v1/companies/{company_id}/status": { "get": { "description": "La versión ligera del detalle: en qué punto está y con qué nivel de riesgo. Para pintar un semáforo sin traerte el expediente entero.", "operationId": "getCompanyStatus", "parameters": [ { "in": "path", "name": "company_id", "required": true, "schema": { "title": "Company Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyStatusResponse" } } }, "description": "Successful Response" }, "400": { "content": { "application/problem+json": { "examples": { "UNSUPPORTED_API_VERSION": { "summary": "UNSUPPORTED_API_VERSION", "value": { "code": "UNSUPPORTED_API_VERSION", "detail": "Unsupported API version", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 400, "title": "Unsupported API version", "type": "https://belfort.ai/docs/errors#UNSUPPORTED_API_VERSION" } } } } }, "description": "UNSUPPORTED_API_VERSION" }, "405": { "content": { "application/problem+json": { "examples": { "METHOD_NOT_ALLOWED": { "summary": "METHOD_NOT_ALLOWED", "value": { "code": "METHOD_NOT_ALLOWED", "detail": "Method not allowed", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 405, "title": "Method not allowed", "type": "https://belfort.ai/docs/errors#METHOD_NOT_ALLOWED" } } } } }, "description": "METHOD_NOT_ALLOWED" }, "422": { "content": { "application/problem+json": { "examples": { "VALIDATION_ERROR": { "summary": "VALIDATION_ERROR", "value": { "code": "VALIDATION_ERROR", "detail": "Validation error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 422, "title": "Validation error", "type": "https://belfort.ai/docs/errors#VALIDATION_ERROR" } } } } }, "description": "VALIDATION_ERROR" }, "500": { "content": { "application/problem+json": { "examples": { "INTERNAL_ERROR": { "summary": "INTERNAL_ERROR", "value": { "code": "INTERNAL_ERROR", "detail": "Internal server error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 500, "title": "Internal server error", "type": "https://belfort.ai/docs/errors#INTERNAL_ERROR" } } } } }, "description": "INTERNAL_ERROR" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Error — documento de problema RFC 9457 (`application/problem+json`)." } }, "security": [ { "secretKey": [] } ], "summary": "Estado de una empresa", "tags": [ "kyb" ], "x-required-scope": "kyb:read" } }, "/v1/companies/{company_id}/ubo": { "post": { "description": "Un nodo del grafo de beneficiarios finales. Se llama una vez por nodo; el grafo se arma con las llamadas sucesivas.", "operationId": "addUboNode", "parameters": [ { "in": "path", "name": "company_id", "required": true, "schema": { "title": "Company Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UboNodeCreate" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UboNodeResponse" } } }, "description": "Successful Response" }, "400": { "content": { "application/problem+json": { "examples": { "UNSUPPORTED_API_VERSION": { "summary": "UNSUPPORTED_API_VERSION", "value": { "code": "UNSUPPORTED_API_VERSION", "detail": "Unsupported API version", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 400, "title": "Unsupported API version", "type": "https://belfort.ai/docs/errors#UNSUPPORTED_API_VERSION" } } } } }, "description": "UNSUPPORTED_API_VERSION" }, "405": { "content": { "application/problem+json": { "examples": { "METHOD_NOT_ALLOWED": { "summary": "METHOD_NOT_ALLOWED", "value": { "code": "METHOD_NOT_ALLOWED", "detail": "Method not allowed", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 405, "title": "Method not allowed", "type": "https://belfort.ai/docs/errors#METHOD_NOT_ALLOWED" } } } } }, "description": "METHOD_NOT_ALLOWED" }, "422": { "content": { "application/problem+json": { "examples": { "VALIDATION_ERROR": { "summary": "VALIDATION_ERROR", "value": { "code": "VALIDATION_ERROR", "detail": "Validation error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 422, "title": "Validation error", "type": "https://belfort.ai/docs/errors#VALIDATION_ERROR" } } } } }, "description": "VALIDATION_ERROR" }, "500": { "content": { "application/problem+json": { "examples": { "INTERNAL_ERROR": { "summary": "INTERNAL_ERROR", "value": { "code": "INTERNAL_ERROR", "detail": "Internal server error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 500, "title": "Internal server error", "type": "https://belfort.ai/docs/errors#INTERNAL_ERROR" } } } } }, "description": "INTERNAL_ERROR" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Error — documento de problema RFC 9457 (`application/problem+json`)." } }, "security": [ { "secretKey": [] } ], "summary": "Añadir un nodo de propiedad", "tags": [ "kyb" ], "x-required-scope": "kyb:write" } }, "/v1/companies/{company_id}/verify": { "post": { "description": "Dispara el pipeline completo: registro público, cadena de propiedad, screening AML y cálculo de riesgo.", "operationId": "verifyCompany", "parameters": [ { "in": "path", "name": "company_id", "required": true, "schema": { "title": "Company Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyVerifyResponse" } } }, "description": "Successful Response" }, "400": { "content": { "application/problem+json": { "examples": { "UNSUPPORTED_API_VERSION": { "summary": "UNSUPPORTED_API_VERSION", "value": { "code": "UNSUPPORTED_API_VERSION", "detail": "Unsupported API version", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 400, "title": "Unsupported API version", "type": "https://belfort.ai/docs/errors#UNSUPPORTED_API_VERSION" } } } } }, "description": "UNSUPPORTED_API_VERSION" }, "405": { "content": { "application/problem+json": { "examples": { "METHOD_NOT_ALLOWED": { "summary": "METHOD_NOT_ALLOWED", "value": { "code": "METHOD_NOT_ALLOWED", "detail": "Method not allowed", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 405, "title": "Method not allowed", "type": "https://belfort.ai/docs/errors#METHOD_NOT_ALLOWED" } } } } }, "description": "METHOD_NOT_ALLOWED" }, "422": { "content": { "application/problem+json": { "examples": { "VALIDATION_ERROR": { "summary": "VALIDATION_ERROR", "value": { "code": "VALIDATION_ERROR", "detail": "Validation error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 422, "title": "Validation error", "type": "https://belfort.ai/docs/errors#VALIDATION_ERROR" } } } } }, "description": "VALIDATION_ERROR" }, "500": { "content": { "application/problem+json": { "examples": { "INTERNAL_ERROR": { "summary": "INTERNAL_ERROR", "value": { "code": "INTERNAL_ERROR", "detail": "Internal server error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 500, "title": "Internal server error", "type": "https://belfort.ai/docs/errors#INTERNAL_ERROR" } } } } }, "description": "INTERNAL_ERROR" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Error — documento de problema RFC 9457 (`application/problem+json`)." } }, "security": [ { "secretKey": [] } ], "summary": "Verificar la empresa", "tags": [ "kyb" ], "x-required-scope": "kyb:write" } }, "/v1/compliance/breach-notifications": { "post": { "description": "Registra y dispara la notificación de una vulneración de seguridad. `Idempotency-Key` obligatoria: un reintento no puede duplicar un aviso que tiene consecuencias regulatorias.", "operationId": "triggerBreachNotification", "parameters": [ { "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Idempotency-Key" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BreachNotificationRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BreachNotificationResponse" } } }, "description": "Successful Response" }, "400": { "content": { "application/problem+json": { "examples": { "UNSUPPORTED_API_VERSION": { "summary": "UNSUPPORTED_API_VERSION", "value": { "code": "UNSUPPORTED_API_VERSION", "detail": "Unsupported API version", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 400, "title": "Unsupported API version", "type": "https://belfort.ai/docs/errors#UNSUPPORTED_API_VERSION" } } } } }, "description": "UNSUPPORTED_API_VERSION" }, "405": { "content": { "application/problem+json": { "examples": { "METHOD_NOT_ALLOWED": { "summary": "METHOD_NOT_ALLOWED", "value": { "code": "METHOD_NOT_ALLOWED", "detail": "Method not allowed", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 405, "title": "Method not allowed", "type": "https://belfort.ai/docs/errors#METHOD_NOT_ALLOWED" } } } } }, "description": "METHOD_NOT_ALLOWED" }, "422": { "content": { "application/problem+json": { "examples": { "VALIDATION_ERROR": { "summary": "VALIDATION_ERROR", "value": { "code": "VALIDATION_ERROR", "detail": "Validation error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 422, "title": "Validation error", "type": "https://belfort.ai/docs/errors#VALIDATION_ERROR" } } } } }, "description": "VALIDATION_ERROR" }, "500": { "content": { "application/problem+json": { "examples": { "INTERNAL_ERROR": { "summary": "INTERNAL_ERROR", "value": { "code": "INTERNAL_ERROR", "detail": "Internal server error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 500, "title": "Internal server error", "type": "https://belfort.ai/docs/errors#INTERNAL_ERROR" } } } } }, "description": "INTERNAL_ERROR" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Error — documento de problema RFC 9457 (`application/problem+json`)." } }, "security": [ { "secretKey": [] } ], "summary": "Notificar una vulneración", "tags": [ "compliance" ], "x-required-scope": "compliance:write" } }, "/v1/compliance/datacenters": { "get": { "description": "Dónde se procesan y se guardan los datos. Es la respuesta a la pregunta de localización que aparece en toda due diligence.", "operationId": "listDatacenters", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DatacenterList" } } }, "description": "Successful Response" }, "400": { "content": { "application/problem+json": { "examples": { "UNSUPPORTED_API_VERSION": { "summary": "UNSUPPORTED_API_VERSION", "value": { "code": "UNSUPPORTED_API_VERSION", "detail": "Unsupported API version", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 400, "title": "Unsupported API version", "type": "https://belfort.ai/docs/errors#UNSUPPORTED_API_VERSION" } } } } }, "description": "UNSUPPORTED_API_VERSION" }, "405": { "content": { "application/problem+json": { "examples": { "METHOD_NOT_ALLOWED": { "summary": "METHOD_NOT_ALLOWED", "value": { "code": "METHOD_NOT_ALLOWED", "detail": "Method not allowed", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 405, "title": "Method not allowed", "type": "https://belfort.ai/docs/errors#METHOD_NOT_ALLOWED" } } } } }, "description": "METHOD_NOT_ALLOWED" }, "422": { "content": { "application/problem+json": { "examples": { "VALIDATION_ERROR": { "summary": "VALIDATION_ERROR", "value": { "code": "VALIDATION_ERROR", "detail": "Validation error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 422, "title": "Validation error", "type": "https://belfort.ai/docs/errors#VALIDATION_ERROR" } } } } }, "description": "VALIDATION_ERROR" }, "500": { "content": { "application/problem+json": { "examples": { "INTERNAL_ERROR": { "summary": "INTERNAL_ERROR", "value": { "code": "INTERNAL_ERROR", "detail": "Internal server error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 500, "title": "Internal server error", "type": "https://belfort.ai/docs/errors#INTERNAL_ERROR" } } } } }, "description": "INTERNAL_ERROR" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Error — documento de problema RFC 9457 (`application/problem+json`)." } }, "security": [ { "secretKey": [] } ], "summary": "Listar centros de datos", "tags": [ "compliance" ], "x-required-scope": "compliance:read" } }, "/v1/compliance/limits": { "get": { "description": "Los topes y objetivos de servicio vigentes para tu cuenta. Es la fuente única: léelos en vez de transcribirlos, porque cambian sin que cambie tu código.", "operationId": "getLimits", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitPolicy" } } }, "description": "Successful Response" }, "400": { "content": { "application/problem+json": { "examples": { "UNSUPPORTED_API_VERSION": { "summary": "UNSUPPORTED_API_VERSION", "value": { "code": "UNSUPPORTED_API_VERSION", "detail": "Unsupported API version", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 400, "title": "Unsupported API version", "type": "https://belfort.ai/docs/errors#UNSUPPORTED_API_VERSION" } } } } }, "description": "UNSUPPORTED_API_VERSION" }, "405": { "content": { "application/problem+json": { "examples": { "METHOD_NOT_ALLOWED": { "summary": "METHOD_NOT_ALLOWED", "value": { "code": "METHOD_NOT_ALLOWED", "detail": "Method not allowed", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 405, "title": "Method not allowed", "type": "https://belfort.ai/docs/errors#METHOD_NOT_ALLOWED" } } } } }, "description": "METHOD_NOT_ALLOWED" }, "422": { "content": { "application/problem+json": { "examples": { "VALIDATION_ERROR": { "summary": "VALIDATION_ERROR", "value": { "code": "VALIDATION_ERROR", "detail": "Validation error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 422, "title": "Validation error", "type": "https://belfort.ai/docs/errors#VALIDATION_ERROR" } } } } }, "description": "VALIDATION_ERROR" }, "500": { "content": { "application/problem+json": { "examples": { "INTERNAL_ERROR": { "summary": "INTERNAL_ERROR", "value": { "code": "INTERNAL_ERROR", "detail": "Internal server error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 500, "title": "Internal server error", "type": "https://belfort.ai/docs/errors#INTERNAL_ERROR" } } } } }, "description": "INTERNAL_ERROR" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Error — documento de problema RFC 9457 (`application/problem+json`)." } }, "security": [ { "secretKey": [] } ], "summary": "Consultar tus límites", "tags": [ "compliance" ], "x-required-scope": "compliance:read" } }, "/v1/compliance/reports": { "get": { "description": "El informe que tu equipo legal puede archivar, generado a partir de la bitácora real.", "operationId": "getComplianceReport", "parameters": [ { "in": "query", "name": "type", "required": true, "schema": { "title": "Type", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ComplianceReport" } } }, "description": "Successful Response" }, "400": { "content": { "application/problem+json": { "examples": { "UNSUPPORTED_API_VERSION": { "summary": "UNSUPPORTED_API_VERSION", "value": { "code": "UNSUPPORTED_API_VERSION", "detail": "Unsupported API version", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 400, "title": "Unsupported API version", "type": "https://belfort.ai/docs/errors#UNSUPPORTED_API_VERSION" } } } } }, "description": "UNSUPPORTED_API_VERSION" }, "405": { "content": { "application/problem+json": { "examples": { "METHOD_NOT_ALLOWED": { "summary": "METHOD_NOT_ALLOWED", "value": { "code": "METHOD_NOT_ALLOWED", "detail": "Method not allowed", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 405, "title": "Method not allowed", "type": "https://belfort.ai/docs/errors#METHOD_NOT_ALLOWED" } } } } }, "description": "METHOD_NOT_ALLOWED" }, "422": { "content": { "application/problem+json": { "examples": { "VALIDATION_ERROR": { "summary": "VALIDATION_ERROR", "value": { "code": "VALIDATION_ERROR", "detail": "Validation error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 422, "title": "Validation error", "type": "https://belfort.ai/docs/errors#VALIDATION_ERROR" } } } } }, "description": "VALIDATION_ERROR" }, "500": { "content": { "application/problem+json": { "examples": { "INTERNAL_ERROR": { "summary": "INTERNAL_ERROR", "value": { "code": "INTERNAL_ERROR", "detail": "Internal server error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 500, "title": "Internal server error", "type": "https://belfort.ai/docs/errors#INTERNAL_ERROR" } } } } }, "description": "INTERNAL_ERROR" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Error — documento de problema RFC 9457 (`application/problem+json`)." } }, "security": [ { "secretKey": [] } ], "summary": "Obtener un informe de cumplimiento", "tags": [ "compliance" ], "x-required-scope": "compliance:read" } }, "/v1/compliance/subprocessors": { "get": { "description": "Los terceros que intervienen en el tratamiento, con su función. Lo exige el contrato de encargo.", "operationId": "listSubprocessors", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubprocessorList" } } }, "description": "Successful Response" }, "400": { "content": { "application/problem+json": { "examples": { "UNSUPPORTED_API_VERSION": { "summary": "UNSUPPORTED_API_VERSION", "value": { "code": "UNSUPPORTED_API_VERSION", "detail": "Unsupported API version", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 400, "title": "Unsupported API version", "type": "https://belfort.ai/docs/errors#UNSUPPORTED_API_VERSION" } } } } }, "description": "UNSUPPORTED_API_VERSION" }, "405": { "content": { "application/problem+json": { "examples": { "METHOD_NOT_ALLOWED": { "summary": "METHOD_NOT_ALLOWED", "value": { "code": "METHOD_NOT_ALLOWED", "detail": "Method not allowed", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 405, "title": "Method not allowed", "type": "https://belfort.ai/docs/errors#METHOD_NOT_ALLOWED" } } } } }, "description": "METHOD_NOT_ALLOWED" }, "422": { "content": { "application/problem+json": { "examples": { "VALIDATION_ERROR": { "summary": "VALIDATION_ERROR", "value": { "code": "VALIDATION_ERROR", "detail": "Validation error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 422, "title": "Validation error", "type": "https://belfort.ai/docs/errors#VALIDATION_ERROR" } } } } }, "description": "VALIDATION_ERROR" }, "500": { "content": { "application/problem+json": { "examples": { "INTERNAL_ERROR": { "summary": "INTERNAL_ERROR", "value": { "code": "INTERNAL_ERROR", "detail": "Internal server error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 500, "title": "Internal server error", "type": "https://belfort.ai/docs/errors#INTERNAL_ERROR" } } } } }, "description": "INTERNAL_ERROR" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Error — documento de problema RFC 9457 (`application/problem+json`)." } }, "security": [ { "secretKey": [] } ], "summary": "Listar subprocesadores", "tags": [ "compliance" ], "x-required-scope": "compliance:read" } }, "/v1/developer/webhooks": { "get": { "description": "Tus endpoints de webhook registrados.", "operationId": "listWebhooks", "parameters": [ { "description": "Tamaño de página (1–100).", "in": "query", "name": "limit", "required": false, "schema": { "default": 20, "description": "Tamaño de página (1–100).", "title": "Limit", "type": "integer" } }, { "description": "`nextCursor` de la página anterior. Excluyente con `endingBefore`.", "in": "query", "name": "startingAfter", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "`nextCursor` de la página anterior. Excluyente con `endingBefore`.", "title": "Startingafter" } }, { "description": "`previousCursor` de la página actual. Excluyente con `startingAfter`.", "in": "query", "name": "endingBefore", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "`previousCursor` de la página actual. Excluyente con `startingAfter`.", "title": "Endingbefore" } }, { "description": "Calcula `totalCount`. Cuesta un `COUNT(*)` sobre el filtro entero, así que está apagado por defecto: pídelo solo cuando vayas a enseñar el total.", "in": "query", "name": "includeTotal", "required": false, "schema": { "default": false, "description": "Calcula `totalCount`. Cuesta un `COUNT(*)` sobre el filtro entero, así que está apagado por defecto: pídelo solo cuando vayas a enseñar el total.", "title": "Includetotal", "type": "boolean" } }, { "in": "query", "name": "applicationId", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Applicationid" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListEnvelope_WebhookEndpointResponse_" } } }, "description": "Successful Response" }, "400": { "content": { "application/problem+json": { "examples": { "UNSUPPORTED_API_VERSION": { "summary": "UNSUPPORTED_API_VERSION", "value": { "code": "UNSUPPORTED_API_VERSION", "detail": "Unsupported API version", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 400, "title": "Unsupported API version", "type": "https://belfort.ai/docs/errors#UNSUPPORTED_API_VERSION" } } } } }, "description": "UNSUPPORTED_API_VERSION" }, "405": { "content": { "application/problem+json": { "examples": { "METHOD_NOT_ALLOWED": { "summary": "METHOD_NOT_ALLOWED", "value": { "code": "METHOD_NOT_ALLOWED", "detail": "Method not allowed", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 405, "title": "Method not allowed", "type": "https://belfort.ai/docs/errors#METHOD_NOT_ALLOWED" } } } } }, "description": "METHOD_NOT_ALLOWED" }, "422": { "content": { "application/problem+json": { "examples": { "VALIDATION_ERROR": { "summary": "VALIDATION_ERROR", "value": { "code": "VALIDATION_ERROR", "detail": "Validation error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 422, "title": "Validation error", "type": "https://belfort.ai/docs/errors#VALIDATION_ERROR" } } } } }, "description": "VALIDATION_ERROR" }, "500": { "content": { "application/problem+json": { "examples": { "INTERNAL_ERROR": { "summary": "INTERNAL_ERROR", "value": { "code": "INTERNAL_ERROR", "detail": "Internal server error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 500, "title": "Internal server error", "type": "https://belfort.ai/docs/errors#INTERNAL_ERROR" } } } } }, "description": "INTERNAL_ERROR" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Error — documento de problema RFC 9457 (`application/problem+json`)." } }, "security": [ { "secretKey": [] } ], "summary": "Listar endpoints", "tags": [ "developers" ], "x-required-scope": "webhook:read" }, "post": { "description": "Da de alta una URL y los eventos a los que se suscribe. La respuesta trae el signing secret **en claro, una sola vez**: guárdalo ahora, no se puede volver a consultar.", "operationId": "registerWebhook", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpointCreate" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpointCreated" } } }, "description": "Successful Response" }, "400": { "content": { "application/problem+json": { "examples": { "UNSUPPORTED_API_VERSION": { "summary": "UNSUPPORTED_API_VERSION", "value": { "code": "UNSUPPORTED_API_VERSION", "detail": "Unsupported API version", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 400, "title": "Unsupported API version", "type": "https://belfort.ai/docs/errors#UNSUPPORTED_API_VERSION" } } } } }, "description": "UNSUPPORTED_API_VERSION" }, "405": { "content": { "application/problem+json": { "examples": { "METHOD_NOT_ALLOWED": { "summary": "METHOD_NOT_ALLOWED", "value": { "code": "METHOD_NOT_ALLOWED", "detail": "Method not allowed", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 405, "title": "Method not allowed", "type": "https://belfort.ai/docs/errors#METHOD_NOT_ALLOWED" } } } } }, "description": "METHOD_NOT_ALLOWED" }, "422": { "content": { "application/problem+json": { "examples": { "VALIDATION_ERROR": { "summary": "VALIDATION_ERROR", "value": { "code": "VALIDATION_ERROR", "detail": "Validation error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 422, "title": "Validation error", "type": "https://belfort.ai/docs/errors#VALIDATION_ERROR" } } } } }, "description": "VALIDATION_ERROR" }, "500": { "content": { "application/problem+json": { "examples": { "INTERNAL_ERROR": { "summary": "INTERNAL_ERROR", "value": { "code": "INTERNAL_ERROR", "detail": "Internal server error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 500, "title": "Internal server error", "type": "https://belfort.ai/docs/errors#INTERNAL_ERROR" } } } } }, "description": "INTERNAL_ERROR" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Error — documento de problema RFC 9457 (`application/problem+json`)." } }, "security": [ { "secretKey": [] } ], "summary": "Registrar un endpoint", "tags": [ "developers" ], "x-required-scope": "webhook:write" } }, "/v1/developer/webhooks/deliveries": { "get": { "description": "Todas las entregas de todos tus endpoints.", "operationId": "listAllDeliveries", "parameters": [ { "description": "Tamaño de página (1–100).", "in": "query", "name": "limit", "required": false, "schema": { "default": 20, "description": "Tamaño de página (1–100).", "title": "Limit", "type": "integer" } }, { "description": "`nextCursor` de la página anterior. Excluyente con `endingBefore`.", "in": "query", "name": "startingAfter", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "`nextCursor` de la página anterior. Excluyente con `endingBefore`.", "title": "Startingafter" } }, { "description": "`previousCursor` de la página actual. Excluyente con `startingAfter`.", "in": "query", "name": "endingBefore", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "`previousCursor` de la página actual. Excluyente con `startingAfter`.", "title": "Endingbefore" } }, { "description": "Calcula `totalCount`. Cuesta un `COUNT(*)` sobre el filtro entero, así que está apagado por defecto: pídelo solo cuando vayas a enseñar el total.", "in": "query", "name": "includeTotal", "required": false, "schema": { "default": false, "description": "Calcula `totalCount`. Cuesta un `COUNT(*)` sobre el filtro entero, así que está apagado por defecto: pídelo solo cuando vayas a enseñar el total.", "title": "Includetotal", "type": "boolean" } }, { "in": "query", "name": "applicationId", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Applicationid" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListEnvelope_WebhookDeliveryResponse_" } } }, "description": "Successful Response" }, "400": { "content": { "application/problem+json": { "examples": { "UNSUPPORTED_API_VERSION": { "summary": "UNSUPPORTED_API_VERSION", "value": { "code": "UNSUPPORTED_API_VERSION", "detail": "Unsupported API version", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 400, "title": "Unsupported API version", "type": "https://belfort.ai/docs/errors#UNSUPPORTED_API_VERSION" } } } } }, "description": "UNSUPPORTED_API_VERSION" }, "405": { "content": { "application/problem+json": { "examples": { "METHOD_NOT_ALLOWED": { "summary": "METHOD_NOT_ALLOWED", "value": { "code": "METHOD_NOT_ALLOWED", "detail": "Method not allowed", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 405, "title": "Method not allowed", "type": "https://belfort.ai/docs/errors#METHOD_NOT_ALLOWED" } } } } }, "description": "METHOD_NOT_ALLOWED" }, "422": { "content": { "application/problem+json": { "examples": { "VALIDATION_ERROR": { "summary": "VALIDATION_ERROR", "value": { "code": "VALIDATION_ERROR", "detail": "Validation error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 422, "title": "Validation error", "type": "https://belfort.ai/docs/errors#VALIDATION_ERROR" } } } } }, "description": "VALIDATION_ERROR" }, "500": { "content": { "application/problem+json": { "examples": { "INTERNAL_ERROR": { "summary": "INTERNAL_ERROR", "value": { "code": "INTERNAL_ERROR", "detail": "Internal server error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 500, "title": "Internal server error", "type": "https://belfort.ai/docs/errors#INTERNAL_ERROR" } } } } }, "description": "INTERNAL_ERROR" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Error — documento de problema RFC 9457 (`application/problem+json`)." } }, "security": [ { "secretKey": [] } ], "summary": "Listar entregas", "tags": [ "developers" ], "x-required-scope": "webhook:read" } }, "/v1/developer/webhooks/deliveries/{delivery_id}/attempts": { "get": { "description": "Cada intento con su código de respuesta y su latencia. Es por donde se diagnostica un endpoint que falla de forma intermitente.", "operationId": "listDeliveryAttempts", "parameters": [ { "in": "path", "name": "delivery_id", "required": true, "schema": { "title": "Delivery Id", "type": "string" } }, { "description": "Tamaño de página (1–100).", "in": "query", "name": "limit", "required": false, "schema": { "default": 20, "description": "Tamaño de página (1–100).", "title": "Limit", "type": "integer" } }, { "description": "`nextCursor` de la página anterior. Excluyente con `endingBefore`.", "in": "query", "name": "startingAfter", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "`nextCursor` de la página anterior. Excluyente con `endingBefore`.", "title": "Startingafter" } }, { "description": "`previousCursor` de la página actual. Excluyente con `startingAfter`.", "in": "query", "name": "endingBefore", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "`previousCursor` de la página actual. Excluyente con `startingAfter`.", "title": "Endingbefore" } }, { "description": "Calcula `totalCount`. Cuesta un `COUNT(*)` sobre el filtro entero, así que está apagado por defecto: pídelo solo cuando vayas a enseñar el total.", "in": "query", "name": "includeTotal", "required": false, "schema": { "default": false, "description": "Calcula `totalCount`. Cuesta un `COUNT(*)` sobre el filtro entero, así que está apagado por defecto: pídelo solo cuando vayas a enseñar el total.", "title": "Includetotal", "type": "boolean" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListEnvelope_WebhookDeliveryAttemptResponse_" } } }, "description": "Successful Response" }, "400": { "content": { "application/problem+json": { "examples": { "UNSUPPORTED_API_VERSION": { "summary": "UNSUPPORTED_API_VERSION", "value": { "code": "UNSUPPORTED_API_VERSION", "detail": "Unsupported API version", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 400, "title": "Unsupported API version", "type": "https://belfort.ai/docs/errors#UNSUPPORTED_API_VERSION" } } } } }, "description": "UNSUPPORTED_API_VERSION" }, "405": { "content": { "application/problem+json": { "examples": { "METHOD_NOT_ALLOWED": { "summary": "METHOD_NOT_ALLOWED", "value": { "code": "METHOD_NOT_ALLOWED", "detail": "Method not allowed", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 405, "title": "Method not allowed", "type": "https://belfort.ai/docs/errors#METHOD_NOT_ALLOWED" } } } } }, "description": "METHOD_NOT_ALLOWED" }, "422": { "content": { "application/problem+json": { "examples": { "VALIDATION_ERROR": { "summary": "VALIDATION_ERROR", "value": { "code": "VALIDATION_ERROR", "detail": "Validation error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 422, "title": "Validation error", "type": "https://belfort.ai/docs/errors#VALIDATION_ERROR" } } } } }, "description": "VALIDATION_ERROR" }, "500": { "content": { "application/problem+json": { "examples": { "INTERNAL_ERROR": { "summary": "INTERNAL_ERROR", "value": { "code": "INTERNAL_ERROR", "detail": "Internal server error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 500, "title": "Internal server error", "type": "https://belfort.ai/docs/errors#INTERNAL_ERROR" } } } } }, "description": "INTERNAL_ERROR" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Error — documento de problema RFC 9457 (`application/problem+json`)." } }, "security": [ { "secretKey": [] } ], "summary": "Intentos de una entrega", "tags": [ "developers" ], "x-required-scope": "webhook:read" } }, "/v1/developer/webhooks/deliveries/{delivery_id}/retry": { "post": { "description": "Crea una entrega NUEVA del mismo evento, con la URL y el secreto actuales. El intento original se conserva en el historial.", "operationId": "retryDelivery", "parameters": [ { "in": "path", "name": "delivery_id", "required": true, "schema": { "title": "Delivery Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookDeliveryResponse" } } }, "description": "Successful Response" }, "400": { "content": { "application/problem+json": { "examples": { "UNSUPPORTED_API_VERSION": { "summary": "UNSUPPORTED_API_VERSION", "value": { "code": "UNSUPPORTED_API_VERSION", "detail": "Unsupported API version", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 400, "title": "Unsupported API version", "type": "https://belfort.ai/docs/errors#UNSUPPORTED_API_VERSION" } } } } }, "description": "UNSUPPORTED_API_VERSION" }, "405": { "content": { "application/problem+json": { "examples": { "METHOD_NOT_ALLOWED": { "summary": "METHOD_NOT_ALLOWED", "value": { "code": "METHOD_NOT_ALLOWED", "detail": "Method not allowed", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 405, "title": "Method not allowed", "type": "https://belfort.ai/docs/errors#METHOD_NOT_ALLOWED" } } } } }, "description": "METHOD_NOT_ALLOWED" }, "422": { "content": { "application/problem+json": { "examples": { "VALIDATION_ERROR": { "summary": "VALIDATION_ERROR", "value": { "code": "VALIDATION_ERROR", "detail": "Validation error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 422, "title": "Validation error", "type": "https://belfort.ai/docs/errors#VALIDATION_ERROR" } } } } }, "description": "VALIDATION_ERROR" }, "500": { "content": { "application/problem+json": { "examples": { "INTERNAL_ERROR": { "summary": "INTERNAL_ERROR", "value": { "code": "INTERNAL_ERROR", "detail": "Internal server error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 500, "title": "Internal server error", "type": "https://belfort.ai/docs/errors#INTERNAL_ERROR" } } } } }, "description": "INTERNAL_ERROR" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Error — documento de problema RFC 9457 (`application/problem+json`)." } }, "security": [ { "secretKey": [] } ], "summary": "Reintentar una entrega", "tags": [ "developers" ], "x-required-scope": "webhook:write" } }, "/v1/developer/webhooks/delivery-policy": { "get": { "description": "Cuántas veces se reintenta, con qué espera, qué se considera fallo permanente y qué tiempo máximo de respuesta se espera de ti.", "operationId": "getDeliveryPolicy", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookDeliveryPolicy" } } }, "description": "Successful Response" }, "400": { "content": { "application/problem+json": { "examples": { "UNSUPPORTED_API_VERSION": { "summary": "UNSUPPORTED_API_VERSION", "value": { "code": "UNSUPPORTED_API_VERSION", "detail": "Unsupported API version", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 400, "title": "Unsupported API version", "type": "https://belfort.ai/docs/errors#UNSUPPORTED_API_VERSION" } } } } }, "description": "UNSUPPORTED_API_VERSION" }, "405": { "content": { "application/problem+json": { "examples": { "METHOD_NOT_ALLOWED": { "summary": "METHOD_NOT_ALLOWED", "value": { "code": "METHOD_NOT_ALLOWED", "detail": "Method not allowed", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 405, "title": "Method not allowed", "type": "https://belfort.ai/docs/errors#METHOD_NOT_ALLOWED" } } } } }, "description": "METHOD_NOT_ALLOWED" }, "422": { "content": { "application/problem+json": { "examples": { "VALIDATION_ERROR": { "summary": "VALIDATION_ERROR", "value": { "code": "VALIDATION_ERROR", "detail": "Validation error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 422, "title": "Validation error", "type": "https://belfort.ai/docs/errors#VALIDATION_ERROR" } } } } }, "description": "VALIDATION_ERROR" }, "500": { "content": { "application/problem+json": { "examples": { "INTERNAL_ERROR": { "summary": "INTERNAL_ERROR", "value": { "code": "INTERNAL_ERROR", "detail": "Internal server error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 500, "title": "Internal server error", "type": "https://belfort.ai/docs/errors#INTERNAL_ERROR" } } } } }, "description": "INTERNAL_ERROR" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Error — documento de problema RFC 9457 (`application/problem+json`)." } }, "security": [ { "secretKey": [] } ], "summary": "Política de entrega", "tags": [ "developers" ], "x-required-scope": "webhook:read" } }, "/v1/developer/webhooks/event-types": { "get": { "description": "Los tipos de evento que Belfort emite y los patrones válidos para suscribirse.", "operationId": "listEventTypes", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEventTypeCatalog" } } }, "description": "Successful Response" }, "400": { "content": { "application/problem+json": { "examples": { "UNSUPPORTED_API_VERSION": { "summary": "UNSUPPORTED_API_VERSION", "value": { "code": "UNSUPPORTED_API_VERSION", "detail": "Unsupported API version", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 400, "title": "Unsupported API version", "type": "https://belfort.ai/docs/errors#UNSUPPORTED_API_VERSION" } } } } }, "description": "UNSUPPORTED_API_VERSION" }, "405": { "content": { "application/problem+json": { "examples": { "METHOD_NOT_ALLOWED": { "summary": "METHOD_NOT_ALLOWED", "value": { "code": "METHOD_NOT_ALLOWED", "detail": "Method not allowed", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 405, "title": "Method not allowed", "type": "https://belfort.ai/docs/errors#METHOD_NOT_ALLOWED" } } } } }, "description": "METHOD_NOT_ALLOWED" }, "422": { "content": { "application/problem+json": { "examples": { "VALIDATION_ERROR": { "summary": "VALIDATION_ERROR", "value": { "code": "VALIDATION_ERROR", "detail": "Validation error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 422, "title": "Validation error", "type": "https://belfort.ai/docs/errors#VALIDATION_ERROR" } } } } }, "description": "VALIDATION_ERROR" }, "500": { "content": { "application/problem+json": { "examples": { "INTERNAL_ERROR": { "summary": "INTERNAL_ERROR", "value": { "code": "INTERNAL_ERROR", "detail": "Internal server error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 500, "title": "Internal server error", "type": "https://belfort.ai/docs/errors#INTERNAL_ERROR" } } } } }, "description": "INTERNAL_ERROR" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Error — documento de problema RFC 9457 (`application/problem+json`)." } }, "security": [ { "secretKey": [] } ], "summary": "Catálogo de eventos", "tags": [ "developers" ], "x-required-scope": "webhook:read" } }, "/v1/developer/webhooks/{endpoint_id}": { "get": { "description": "Configuración del endpoint. Nunca incluye el secreto.", "operationId": "getWebhook", "parameters": [ { "in": "path", "name": "endpoint_id", "required": true, "schema": { "title": "Endpoint Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpointResponse" } } }, "description": "Successful Response" }, "400": { "content": { "application/problem+json": { "examples": { "UNSUPPORTED_API_VERSION": { "summary": "UNSUPPORTED_API_VERSION", "value": { "code": "UNSUPPORTED_API_VERSION", "detail": "Unsupported API version", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 400, "title": "Unsupported API version", "type": "https://belfort.ai/docs/errors#UNSUPPORTED_API_VERSION" } } } } }, "description": "UNSUPPORTED_API_VERSION" }, "405": { "content": { "application/problem+json": { "examples": { "METHOD_NOT_ALLOWED": { "summary": "METHOD_NOT_ALLOWED", "value": { "code": "METHOD_NOT_ALLOWED", "detail": "Method not allowed", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 405, "title": "Method not allowed", "type": "https://belfort.ai/docs/errors#METHOD_NOT_ALLOWED" } } } } }, "description": "METHOD_NOT_ALLOWED" }, "422": { "content": { "application/problem+json": { "examples": { "VALIDATION_ERROR": { "summary": "VALIDATION_ERROR", "value": { "code": "VALIDATION_ERROR", "detail": "Validation error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 422, "title": "Validation error", "type": "https://belfort.ai/docs/errors#VALIDATION_ERROR" } } } } }, "description": "VALIDATION_ERROR" }, "500": { "content": { "application/problem+json": { "examples": { "INTERNAL_ERROR": { "summary": "INTERNAL_ERROR", "value": { "code": "INTERNAL_ERROR", "detail": "Internal server error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 500, "title": "Internal server error", "type": "https://belfort.ai/docs/errors#INTERNAL_ERROR" } } } } }, "description": "INTERNAL_ERROR" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Error — documento de problema RFC 9457 (`application/problem+json`)." } }, "security": [ { "secretKey": [] } ], "summary": "Consultar un endpoint", "tags": [ "developers" ], "x-required-scope": "webhook:read" }, "patch": { "description": "Cambia URL, eventos, descripción o si está activo. Desactivarlo es la forma de dejar de recibir sin perder el historial: por eso no hay borrado.", "operationId": "updateWebhook", "parameters": [ { "in": "path", "name": "endpoint_id", "required": true, "schema": { "title": "Endpoint Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpointUpdate" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpointResponse" } } }, "description": "Successful Response" }, "400": { "content": { "application/problem+json": { "examples": { "UNSUPPORTED_API_VERSION": { "summary": "UNSUPPORTED_API_VERSION", "value": { "code": "UNSUPPORTED_API_VERSION", "detail": "Unsupported API version", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 400, "title": "Unsupported API version", "type": "https://belfort.ai/docs/errors#UNSUPPORTED_API_VERSION" } } } } }, "description": "UNSUPPORTED_API_VERSION" }, "405": { "content": { "application/problem+json": { "examples": { "METHOD_NOT_ALLOWED": { "summary": "METHOD_NOT_ALLOWED", "value": { "code": "METHOD_NOT_ALLOWED", "detail": "Method not allowed", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 405, "title": "Method not allowed", "type": "https://belfort.ai/docs/errors#METHOD_NOT_ALLOWED" } } } } }, "description": "METHOD_NOT_ALLOWED" }, "422": { "content": { "application/problem+json": { "examples": { "VALIDATION_ERROR": { "summary": "VALIDATION_ERROR", "value": { "code": "VALIDATION_ERROR", "detail": "Validation error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 422, "title": "Validation error", "type": "https://belfort.ai/docs/errors#VALIDATION_ERROR" } } } } }, "description": "VALIDATION_ERROR" }, "500": { "content": { "application/problem+json": { "examples": { "INTERNAL_ERROR": { "summary": "INTERNAL_ERROR", "value": { "code": "INTERNAL_ERROR", "detail": "Internal server error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 500, "title": "Internal server error", "type": "https://belfort.ai/docs/errors#INTERNAL_ERROR" } } } } }, "description": "INTERNAL_ERROR" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Error — documento de problema RFC 9457 (`application/problem+json`)." } }, "security": [ { "secretKey": [] } ], "summary": "Editar un endpoint", "tags": [ "developers" ], "x-required-scope": "webhook:write" } }, "/v1/developer/webhooks/{endpoint_id}/deliveries": { "get": { "description": "Lo mismo, acotado a un endpoint.", "operationId": "listEndpointDeliveries", "parameters": [ { "in": "path", "name": "endpoint_id", "required": true, "schema": { "title": "Endpoint Id", "type": "string" } }, { "description": "Tamaño de página (1–100).", "in": "query", "name": "limit", "required": false, "schema": { "default": 20, "description": "Tamaño de página (1–100).", "title": "Limit", "type": "integer" } }, { "description": "`nextCursor` de la página anterior. Excluyente con `endingBefore`.", "in": "query", "name": "startingAfter", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "`nextCursor` de la página anterior. Excluyente con `endingBefore`.", "title": "Startingafter" } }, { "description": "`previousCursor` de la página actual. Excluyente con `startingAfter`.", "in": "query", "name": "endingBefore", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "`previousCursor` de la página actual. Excluyente con `startingAfter`.", "title": "Endingbefore" } }, { "description": "Calcula `totalCount`. Cuesta un `COUNT(*)` sobre el filtro entero, así que está apagado por defecto: pídelo solo cuando vayas a enseñar el total.", "in": "query", "name": "includeTotal", "required": false, "schema": { "default": false, "description": "Calcula `totalCount`. Cuesta un `COUNT(*)` sobre el filtro entero, así que está apagado por defecto: pídelo solo cuando vayas a enseñar el total.", "title": "Includetotal", "type": "boolean" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListEnvelope_WebhookDeliveryResponse_" } } }, "description": "Successful Response" }, "400": { "content": { "application/problem+json": { "examples": { "UNSUPPORTED_API_VERSION": { "summary": "UNSUPPORTED_API_VERSION", "value": { "code": "UNSUPPORTED_API_VERSION", "detail": "Unsupported API version", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 400, "title": "Unsupported API version", "type": "https://belfort.ai/docs/errors#UNSUPPORTED_API_VERSION" } } } } }, "description": "UNSUPPORTED_API_VERSION" }, "405": { "content": { "application/problem+json": { "examples": { "METHOD_NOT_ALLOWED": { "summary": "METHOD_NOT_ALLOWED", "value": { "code": "METHOD_NOT_ALLOWED", "detail": "Method not allowed", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 405, "title": "Method not allowed", "type": "https://belfort.ai/docs/errors#METHOD_NOT_ALLOWED" } } } } }, "description": "METHOD_NOT_ALLOWED" }, "422": { "content": { "application/problem+json": { "examples": { "VALIDATION_ERROR": { "summary": "VALIDATION_ERROR", "value": { "code": "VALIDATION_ERROR", "detail": "Validation error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 422, "title": "Validation error", "type": "https://belfort.ai/docs/errors#VALIDATION_ERROR" } } } } }, "description": "VALIDATION_ERROR" }, "500": { "content": { "application/problem+json": { "examples": { "INTERNAL_ERROR": { "summary": "INTERNAL_ERROR", "value": { "code": "INTERNAL_ERROR", "detail": "Internal server error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 500, "title": "Internal server error", "type": "https://belfort.ai/docs/errors#INTERNAL_ERROR" } } } } }, "description": "INTERNAL_ERROR" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Error — documento de problema RFC 9457 (`application/problem+json`)." } }, "security": [ { "secretKey": [] } ], "summary": "Entregas de un endpoint", "tags": [ "developers" ], "x-required-scope": "webhook:read" } }, "/v1/developer/webhooks/{endpoint_id}/rotate-secret": { "post": { "description": "Genera un secreto nuevo, que se muestra una sola vez. Durante 24 horas cada entrega va firmada con el nuevo **y** con el anterior, así que puedes desplegar tu cambio sin perder eventos.", "operationId": "rotateWebhookSecret", "parameters": [ { "in": "path", "name": "endpoint_id", "required": true, "schema": { "title": "Endpoint Id", "type": "string" } }, { "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Idempotency-Key" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpointCreated" } } }, "description": "Successful Response" }, "400": { "content": { "application/problem+json": { "examples": { "UNSUPPORTED_API_VERSION": { "summary": "UNSUPPORTED_API_VERSION", "value": { "code": "UNSUPPORTED_API_VERSION", "detail": "Unsupported API version", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 400, "title": "Unsupported API version", "type": "https://belfort.ai/docs/errors#UNSUPPORTED_API_VERSION" } } } } }, "description": "UNSUPPORTED_API_VERSION" }, "405": { "content": { "application/problem+json": { "examples": { "METHOD_NOT_ALLOWED": { "summary": "METHOD_NOT_ALLOWED", "value": { "code": "METHOD_NOT_ALLOWED", "detail": "Method not allowed", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 405, "title": "Method not allowed", "type": "https://belfort.ai/docs/errors#METHOD_NOT_ALLOWED" } } } } }, "description": "METHOD_NOT_ALLOWED" }, "422": { "content": { "application/problem+json": { "examples": { "VALIDATION_ERROR": { "summary": "VALIDATION_ERROR", "value": { "code": "VALIDATION_ERROR", "detail": "Validation error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 422, "title": "Validation error", "type": "https://belfort.ai/docs/errors#VALIDATION_ERROR" } } } } }, "description": "VALIDATION_ERROR" }, "500": { "content": { "application/problem+json": { "examples": { "INTERNAL_ERROR": { "summary": "INTERNAL_ERROR", "value": { "code": "INTERNAL_ERROR", "detail": "Internal server error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 500, "title": "Internal server error", "type": "https://belfort.ai/docs/errors#INTERNAL_ERROR" } } } } }, "description": "INTERNAL_ERROR" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Error — documento de problema RFC 9457 (`application/problem+json`)." } }, "security": [ { "secretKey": [] } ], "summary": "Rotar el signing secret", "tags": [ "developers" ], "x-required-scope": "webhook:write" } }, "/v1/developer/webhooks/{endpoint_id}/test": { "post": { "description": "Manda un evento firmado a tu endpoint y te dice qué respondió. Síncrono y fuera de la cola: sirve para comprobar tu verificador en el momento.", "operationId": "testWebhook", "parameters": [ { "in": "path", "name": "endpoint_id", "required": true, "schema": { "title": "Endpoint Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/WebhookTestRequest" }, { "type": "null" } ], "title": "Data" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookTestResult" } } }, "description": "Successful Response" }, "400": { "content": { "application/problem+json": { "examples": { "UNSUPPORTED_API_VERSION": { "summary": "UNSUPPORTED_API_VERSION", "value": { "code": "UNSUPPORTED_API_VERSION", "detail": "Unsupported API version", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 400, "title": "Unsupported API version", "type": "https://belfort.ai/docs/errors#UNSUPPORTED_API_VERSION" } } } } }, "description": "UNSUPPORTED_API_VERSION" }, "405": { "content": { "application/problem+json": { "examples": { "METHOD_NOT_ALLOWED": { "summary": "METHOD_NOT_ALLOWED", "value": { "code": "METHOD_NOT_ALLOWED", "detail": "Method not allowed", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 405, "title": "Method not allowed", "type": "https://belfort.ai/docs/errors#METHOD_NOT_ALLOWED" } } } } }, "description": "METHOD_NOT_ALLOWED" }, "422": { "content": { "application/problem+json": { "examples": { "VALIDATION_ERROR": { "summary": "VALIDATION_ERROR", "value": { "code": "VALIDATION_ERROR", "detail": "Validation error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 422, "title": "Validation error", "type": "https://belfort.ai/docs/errors#VALIDATION_ERROR" } } } } }, "description": "VALIDATION_ERROR" }, "500": { "content": { "application/problem+json": { "examples": { "INTERNAL_ERROR": { "summary": "INTERNAL_ERROR", "value": { "code": "INTERNAL_ERROR", "detail": "Internal server error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 500, "title": "Internal server error", "type": "https://belfort.ai/docs/errors#INTERNAL_ERROR" } } } } }, "description": "INTERNAL_ERROR" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Error — documento de problema RFC 9457 (`application/problem+json`)." } }, "security": [ { "secretKey": [] } ], "summary": "Enviar un evento de prueba", "tags": [ "developers" ], "x-required-scope": "webhook:write" } }, "/v1/developer/webhooks/{endpoint_id}/verify-signature": { "post": { "description": "Le pasas un cuerpo tal cual lo recibiste y recomputa la firma esperada. Es la herramienta para depurar un verificador que rechaza entregas legítimas, normalmente porque algo en tu servidor reescribió el cuerpo antes de que lo vieras.", "operationId": "verifyWebhookSignature", "parameters": [ { "in": "path", "name": "endpoint_id", "required": true, "schema": { "title": "Endpoint Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookSignatureVerifyRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookSignatureVerifyResult" } } }, "description": "Successful Response" }, "400": { "content": { "application/problem+json": { "examples": { "UNSUPPORTED_API_VERSION": { "summary": "UNSUPPORTED_API_VERSION", "value": { "code": "UNSUPPORTED_API_VERSION", "detail": "Unsupported API version", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 400, "title": "Unsupported API version", "type": "https://belfort.ai/docs/errors#UNSUPPORTED_API_VERSION" } } } } }, "description": "UNSUPPORTED_API_VERSION" }, "405": { "content": { "application/problem+json": { "examples": { "METHOD_NOT_ALLOWED": { "summary": "METHOD_NOT_ALLOWED", "value": { "code": "METHOD_NOT_ALLOWED", "detail": "Method not allowed", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 405, "title": "Method not allowed", "type": "https://belfort.ai/docs/errors#METHOD_NOT_ALLOWED" } } } } }, "description": "METHOD_NOT_ALLOWED" }, "422": { "content": { "application/problem+json": { "examples": { "VALIDATION_ERROR": { "summary": "VALIDATION_ERROR", "value": { "code": "VALIDATION_ERROR", "detail": "Validation error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 422, "title": "Validation error", "type": "https://belfort.ai/docs/errors#VALIDATION_ERROR" } } } } }, "description": "VALIDATION_ERROR" }, "500": { "content": { "application/problem+json": { "examples": { "INTERNAL_ERROR": { "summary": "INTERNAL_ERROR", "value": { "code": "INTERNAL_ERROR", "detail": "Internal server error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 500, "title": "Internal server error", "type": "https://belfort.ai/docs/errors#INTERNAL_ERROR" } } } } }, "description": "INTERNAL_ERROR" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Error — documento de problema RFC 9457 (`application/problem+json`)." } }, "security": [ { "secretKey": [] } ], "summary": "Comprobar una firma", "tags": [ "developers" ], "x-required-scope": "webhook:read" } }, "/v1/embedded/sessions": { "post": { "description": "Desde tu backend, con tu clave secreta. Devuelve el `clientSecret` con el que montas el widget en el navegador de la persona.", "operationId": "createEmbeddedSession", "parameters": [ { "in": "header", "name": "x-service-key", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Service-Key" } }, { "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Idempotency-Key" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmbeddedSessionCreateV2" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmbeddedSessionCreateResponse" } } }, "description": "Successful Response" }, "400": { "content": { "application/problem+json": { "examples": { "UNSUPPORTED_API_VERSION": { "summary": "UNSUPPORTED_API_VERSION", "value": { "code": "UNSUPPORTED_API_VERSION", "detail": "Unsupported API version", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 400, "title": "Unsupported API version", "type": "https://belfort.ai/docs/errors#UNSUPPORTED_API_VERSION" } } } } }, "description": "UNSUPPORTED_API_VERSION" }, "405": { "content": { "application/problem+json": { "examples": { "METHOD_NOT_ALLOWED": { "summary": "METHOD_NOT_ALLOWED", "value": { "code": "METHOD_NOT_ALLOWED", "detail": "Method not allowed", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 405, "title": "Method not allowed", "type": "https://belfort.ai/docs/errors#METHOD_NOT_ALLOWED" } } } } }, "description": "METHOD_NOT_ALLOWED" }, "422": { "content": { "application/problem+json": { "examples": { "VALIDATION_ERROR": { "summary": "VALIDATION_ERROR", "value": { "code": "VALIDATION_ERROR", "detail": "Validation error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 422, "title": "Validation error", "type": "https://belfort.ai/docs/errors#VALIDATION_ERROR" } } } } }, "description": "VALIDATION_ERROR" }, "500": { "content": { "application/problem+json": { "examples": { "INTERNAL_ERROR": { "summary": "INTERNAL_ERROR", "value": { "code": "INTERNAL_ERROR", "detail": "Internal server error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 500, "title": "Internal server error", "type": "https://belfort.ai/docs/errors#INTERNAL_ERROR" } } } } }, "description": "INTERNAL_ERROR" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Error — documento de problema RFC 9457 (`application/problem+json`)." } }, "security": [ { "secretKey": [] } ], "summary": "Crear una sesión embebida", "tags": [ "embedded" ], "x-required-scope": "verification:write" } }, "/v1/embedded/sessions/browser": { "post": { "description": "La variante client-side, para cuando no quieres un salto por tu backend. Usa la publishable key y solo acepta un flujo ya publicado, contra los orígenes que autorizaste.", "operationId": "createBrowserEmbeddedSession", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmbeddedBrowserSessionCreate" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmbeddedSessionCreateResponse" } } }, "description": "Successful Response" }, "400": { "content": { "application/problem+json": { "examples": { "UNSUPPORTED_API_VERSION": { "summary": "UNSUPPORTED_API_VERSION", "value": { "code": "UNSUPPORTED_API_VERSION", "detail": "Unsupported API version", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 400, "title": "Unsupported API version", "type": "https://belfort.ai/docs/errors#UNSUPPORTED_API_VERSION" } } } } }, "description": "UNSUPPORTED_API_VERSION" }, "405": { "content": { "application/problem+json": { "examples": { "METHOD_NOT_ALLOWED": { "summary": "METHOD_NOT_ALLOWED", "value": { "code": "METHOD_NOT_ALLOWED", "detail": "Method not allowed", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 405, "title": "Method not allowed", "type": "https://belfort.ai/docs/errors#METHOD_NOT_ALLOWED" } } } } }, "description": "METHOD_NOT_ALLOWED" }, "422": { "content": { "application/problem+json": { "examples": { "VALIDATION_ERROR": { "summary": "VALIDATION_ERROR", "value": { "code": "VALIDATION_ERROR", "detail": "Validation error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 422, "title": "Validation error", "type": "https://belfort.ai/docs/errors#VALIDATION_ERROR" } } } } }, "description": "VALIDATION_ERROR" }, "500": { "content": { "application/problem+json": { "examples": { "INTERNAL_ERROR": { "summary": "INTERNAL_ERROR", "value": { "code": "INTERNAL_ERROR", "detail": "Internal server error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 500, "title": "Internal server error", "type": "https://belfort.ai/docs/errors#INTERNAL_ERROR" } } } } }, "description": "INTERNAL_ERROR" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Error — documento de problema RFC 9457 (`application/problem+json`)." } }, "security": [ { "publishableKey": [] } ], "summary": "Crear una sesión embebida desde el navegador", "tags": [ "embedded" ], "x-required-scope": "embedded:create_session" } }, "/v1/embedded/sessions/init": { "post": { "description": "Lo llama el propio widget para canjear el `clientSecret` por su token de trabajo. No lo llamas tú.", "operationId": "initEmbeddedSession", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmbeddedInitRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmbeddedInitResponse" } } }, "description": "Successful Response" }, "400": { "content": { "application/problem+json": { "examples": { "UNSUPPORTED_API_VERSION": { "summary": "UNSUPPORTED_API_VERSION", "value": { "code": "UNSUPPORTED_API_VERSION", "detail": "Unsupported API version", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 400, "title": "Unsupported API version", "type": "https://belfort.ai/docs/errors#UNSUPPORTED_API_VERSION" } } } } }, "description": "UNSUPPORTED_API_VERSION" }, "405": { "content": { "application/problem+json": { "examples": { "METHOD_NOT_ALLOWED": { "summary": "METHOD_NOT_ALLOWED", "value": { "code": "METHOD_NOT_ALLOWED", "detail": "Method not allowed", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 405, "title": "Method not allowed", "type": "https://belfort.ai/docs/errors#METHOD_NOT_ALLOWED" } } } } }, "description": "METHOD_NOT_ALLOWED" }, "422": { "content": { "application/problem+json": { "examples": { "VALIDATION_ERROR": { "summary": "VALIDATION_ERROR", "value": { "code": "VALIDATION_ERROR", "detail": "Validation error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 422, "title": "Validation error", "type": "https://belfort.ai/docs/errors#VALIDATION_ERROR" } } } } }, "description": "VALIDATION_ERROR" }, "500": { "content": { "application/problem+json": { "examples": { "INTERNAL_ERROR": { "summary": "INTERNAL_ERROR", "value": { "code": "INTERNAL_ERROR", "detail": "Internal server error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 500, "title": "Internal server error", "type": "https://belfort.ai/docs/errors#INTERNAL_ERROR" } } } } }, "description": "INTERNAL_ERROR" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Error — documento de problema RFC 9457 (`application/problem+json`)." } }, "security": [ { "secretKey": [] } ], "summary": "Inicializar el widget", "tags": [ "embedded" ] } }, "/v1/embedded/sessions/{session_id}/policy": { "get": { "description": "Devuelve las cabeceras de seguridad que el iframe debe respetar en esa sesión. Público a propósito: el navegador lo consulta antes de tener credencial alguna.", "operationId": "getSessionPolicy", "parameters": [ { "in": "path", "name": "session_id", "required": true, "schema": { "title": "Session Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmbeddedPolicyResponse" } } }, "description": "Successful Response" }, "400": { "content": { "application/problem+json": { "examples": { "UNSUPPORTED_API_VERSION": { "summary": "UNSUPPORTED_API_VERSION", "value": { "code": "UNSUPPORTED_API_VERSION", "detail": "Unsupported API version", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 400, "title": "Unsupported API version", "type": "https://belfort.ai/docs/errors#UNSUPPORTED_API_VERSION" } } } } }, "description": "UNSUPPORTED_API_VERSION" }, "405": { "content": { "application/problem+json": { "examples": { "METHOD_NOT_ALLOWED": { "summary": "METHOD_NOT_ALLOWED", "value": { "code": "METHOD_NOT_ALLOWED", "detail": "Method not allowed", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 405, "title": "Method not allowed", "type": "https://belfort.ai/docs/errors#METHOD_NOT_ALLOWED" } } } } }, "description": "METHOD_NOT_ALLOWED" }, "422": { "content": { "application/problem+json": { "examples": { "VALIDATION_ERROR": { "summary": "VALIDATION_ERROR", "value": { "code": "VALIDATION_ERROR", "detail": "Validation error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 422, "title": "Validation error", "type": "https://belfort.ai/docs/errors#VALIDATION_ERROR" } } } } }, "description": "VALIDATION_ERROR" }, "500": { "content": { "application/problem+json": { "examples": { "INTERNAL_ERROR": { "summary": "INTERNAL_ERROR", "value": { "code": "INTERNAL_ERROR", "detail": "Internal server error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 500, "title": "Internal server error", "type": "https://belfort.ai/docs/errors#INTERNAL_ERROR" } } } } }, "description": "INTERNAL_ERROR" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Error — documento de problema RFC 9457 (`application/problem+json`)." } }, "security": [ { "secretKey": [] } ], "summary": "Consultar la política del iframe", "tags": [ "embedded" ] } }, "/v1/embedded/sessions/{session_id}/verify": { "post": { "description": "Comprueba, desde tu backend, el estado final de una sesión embebida. Existe para que no tengas que confiar en lo que te diga el navegador.", "operationId": "verifyEmbeddedSession", "parameters": [ { "in": "path", "name": "session_id", "required": true, "schema": { "title": "Session Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmbeddedVerifyResponse" } } }, "description": "Successful Response" }, "400": { "content": { "application/problem+json": { "examples": { "UNSUPPORTED_API_VERSION": { "summary": "UNSUPPORTED_API_VERSION", "value": { "code": "UNSUPPORTED_API_VERSION", "detail": "Unsupported API version", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 400, "title": "Unsupported API version", "type": "https://belfort.ai/docs/errors#UNSUPPORTED_API_VERSION" } } } } }, "description": "UNSUPPORTED_API_VERSION" }, "405": { "content": { "application/problem+json": { "examples": { "METHOD_NOT_ALLOWED": { "summary": "METHOD_NOT_ALLOWED", "value": { "code": "METHOD_NOT_ALLOWED", "detail": "Method not allowed", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 405, "title": "Method not allowed", "type": "https://belfort.ai/docs/errors#METHOD_NOT_ALLOWED" } } } } }, "description": "METHOD_NOT_ALLOWED" }, "422": { "content": { "application/problem+json": { "examples": { "VALIDATION_ERROR": { "summary": "VALIDATION_ERROR", "value": { "code": "VALIDATION_ERROR", "detail": "Validation error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 422, "title": "Validation error", "type": "https://belfort.ai/docs/errors#VALIDATION_ERROR" } } } } }, "description": "VALIDATION_ERROR" }, "500": { "content": { "application/problem+json": { "examples": { "INTERNAL_ERROR": { "summary": "INTERNAL_ERROR", "value": { "code": "INTERNAL_ERROR", "detail": "Internal server error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 500, "title": "Internal server error", "type": "https://belfort.ai/docs/errors#INTERNAL_ERROR" } } } } }, "description": "INTERNAL_ERROR" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Error — documento de problema RFC 9457 (`application/problem+json`)." } }, "security": [ { "secretKey": [] } ], "summary": "Confirmar el resultado desde tu servidor", "tags": [ "embedded" ], "x-required-scope": "verification:write" } }, "/v1/media-links": { "post": { "description": "Genera una URL de vida corta para un archivo de evidencia. Queda auditado: emitir el enlace es, a efectos de bitácora, acceder al archivo.", "operationId": "createMediaLink", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MediaLinkRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MediaLinkResponse" } } }, "description": "Successful Response" }, "400": { "content": { "application/problem+json": { "examples": { "UNSUPPORTED_API_VERSION": { "summary": "UNSUPPORTED_API_VERSION", "value": { "code": "UNSUPPORTED_API_VERSION", "detail": "Unsupported API version", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 400, "title": "Unsupported API version", "type": "https://belfort.ai/docs/errors#UNSUPPORTED_API_VERSION" } } } } }, "description": "UNSUPPORTED_API_VERSION" }, "405": { "content": { "application/problem+json": { "examples": { "METHOD_NOT_ALLOWED": { "summary": "METHOD_NOT_ALLOWED", "value": { "code": "METHOD_NOT_ALLOWED", "detail": "Method not allowed", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 405, "title": "Method not allowed", "type": "https://belfort.ai/docs/errors#METHOD_NOT_ALLOWED" } } } } }, "description": "METHOD_NOT_ALLOWED" }, "422": { "content": { "application/problem+json": { "examples": { "VALIDATION_ERROR": { "summary": "VALIDATION_ERROR", "value": { "code": "VALIDATION_ERROR", "detail": "Validation error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 422, "title": "Validation error", "type": "https://belfort.ai/docs/errors#VALIDATION_ERROR" } } } } }, "description": "VALIDATION_ERROR" }, "500": { "content": { "application/problem+json": { "examples": { "INTERNAL_ERROR": { "summary": "INTERNAL_ERROR", "value": { "code": "INTERNAL_ERROR", "detail": "Internal server error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 500, "title": "Internal server error", "type": "https://belfort.ai/docs/errors#INTERNAL_ERROR" } } } } }, "description": "INTERNAL_ERROR" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Error — documento de problema RFC 9457 (`application/problem+json`)." } }, "security": [ { "secretKey": [] } ], "summary": "Emitir un enlace firmado", "tags": [ "media-links" ], "x-required-scope": "persons:read_pii" } }, "/v1/media/{asset_id}": { "get": { "description": "Sirve los bytes de un archivo de evidencia. La credencial es la firma que viaja en la URL, no tu API key: si la firma no valida o el enlace caducó, responde 403.", "operationId": "getMedia", "parameters": [ { "in": "path", "name": "asset_id", "required": true, "schema": { "title": "Asset Id", "type": "string" } }, { "in": "query", "name": "token", "required": true, "schema": { "minLength": 1, "title": "Token", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response" }, "400": { "content": { "application/problem+json": { "examples": { "UNSUPPORTED_API_VERSION": { "summary": "UNSUPPORTED_API_VERSION", "value": { "code": "UNSUPPORTED_API_VERSION", "detail": "Unsupported API version", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 400, "title": "Unsupported API version", "type": "https://belfort.ai/docs/errors#UNSUPPORTED_API_VERSION" } } } } }, "description": "UNSUPPORTED_API_VERSION" }, "403": { "description": "Token inválido o expirado" }, "404": { "description": "No existe" }, "405": { "content": { "application/problem+json": { "examples": { "METHOD_NOT_ALLOWED": { "summary": "METHOD_NOT_ALLOWED", "value": { "code": "METHOD_NOT_ALLOWED", "detail": "Method not allowed", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 405, "title": "Method not allowed", "type": "https://belfort.ai/docs/errors#METHOD_NOT_ALLOWED" } } } } }, "description": "METHOD_NOT_ALLOWED" }, "422": { "content": { "application/problem+json": { "examples": { "VALIDATION_ERROR": { "summary": "VALIDATION_ERROR", "value": { "code": "VALIDATION_ERROR", "detail": "Validation error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 422, "title": "Validation error", "type": "https://belfort.ai/docs/errors#VALIDATION_ERROR" } } } } }, "description": "VALIDATION_ERROR" }, "500": { "content": { "application/problem+json": { "examples": { "INTERNAL_ERROR": { "summary": "INTERNAL_ERROR", "value": { "code": "INTERNAL_ERROR", "detail": "Internal server error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 500, "title": "Internal server error", "type": "https://belfort.ai/docs/errors#INTERNAL_ERROR" } } } } }, "description": "INTERNAL_ERROR" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Error — documento de problema RFC 9457 (`application/problem+json`)." } }, "security": [ { "secretKey": [] } ], "summary": "Descargar un archivo firmado", "tags": [ "media" ] } }, "/v1/monitoring/portfolios/{portfolio_id}/run": { "post": { "description": "Vuelve a cotejar todo un portafolio contra las listas actualizadas. Es el mecanismo de monitoreo continuo.", "operationId": "triggerPortfolioRun", "parameters": [ { "in": "path", "name": "portfolio_id", "required": true, "schema": { "title": "Portfolio Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MonitoringRunResponse" } } }, "description": "Successful Response" }, "400": { "content": { "application/problem+json": { "examples": { "UNSUPPORTED_API_VERSION": { "summary": "UNSUPPORTED_API_VERSION", "value": { "code": "UNSUPPORTED_API_VERSION", "detail": "Unsupported API version", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 400, "title": "Unsupported API version", "type": "https://belfort.ai/docs/errors#UNSUPPORTED_API_VERSION" } } } } }, "description": "UNSUPPORTED_API_VERSION" }, "405": { "content": { "application/problem+json": { "examples": { "METHOD_NOT_ALLOWED": { "summary": "METHOD_NOT_ALLOWED", "value": { "code": "METHOD_NOT_ALLOWED", "detail": "Method not allowed", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 405, "title": "Method not allowed", "type": "https://belfort.ai/docs/errors#METHOD_NOT_ALLOWED" } } } } }, "description": "METHOD_NOT_ALLOWED" }, "422": { "content": { "application/problem+json": { "examples": { "VALIDATION_ERROR": { "summary": "VALIDATION_ERROR", "value": { "code": "VALIDATION_ERROR", "detail": "Validation error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 422, "title": "Validation error", "type": "https://belfort.ai/docs/errors#VALIDATION_ERROR" } } } } }, "description": "VALIDATION_ERROR" }, "500": { "content": { "application/problem+json": { "examples": { "INTERNAL_ERROR": { "summary": "INTERNAL_ERROR", "value": { "code": "INTERNAL_ERROR", "detail": "Internal server error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 500, "title": "Internal server error", "type": "https://belfort.ai/docs/errors#INTERNAL_ERROR" } } } } }, "description": "INTERNAL_ERROR" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Error — documento de problema RFC 9457 (`application/problem+json`)." } }, "security": [ { "secretKey": [] } ], "summary": "Re-escanear un portafolio", "tags": [ "aml" ], "x-required-scope": "aml:write" } }, "/v1/persons": { "get": { "description": "Página por cursor. Para buscar por atributos, usa la búsqueda estructurada en vez de filtrar en tu lado.", "operationId": "listPersons", "parameters": [ { "in": "query", "name": "environment", "required": false, "schema": { "anyOf": [ { "$ref": "#/components/schemas/ApiEnvironment" }, { "type": "null" } ], "title": "Environment" } }, { "in": "query", "name": "created[gte]", "required": false, "schema": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Created[Gte]" } }, { "in": "query", "name": "created[lte]", "required": false, "schema": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Created[Lte]" } }, { "in": "query", "name": "forgetRequested", "required": false, "schema": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Forgetrequested" } }, { "description": "Tamaño de página (1–100).", "in": "query", "name": "limit", "required": false, "schema": { "default": 20, "description": "Tamaño de página (1–100).", "title": "Limit", "type": "integer" } }, { "description": "`nextCursor` de la página anterior. Excluyente con `endingBefore`.", "in": "query", "name": "startingAfter", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "`nextCursor` de la página anterior. Excluyente con `endingBefore`.", "title": "Startingafter" } }, { "description": "`previousCursor` de la página actual. Excluyente con `startingAfter`.", "in": "query", "name": "endingBefore", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "`previousCursor` de la página actual. Excluyente con `startingAfter`.", "title": "Endingbefore" } }, { "description": "Calcula `totalCount`. Cuesta un `COUNT(*)` sobre el filtro entero, así que está apagado por defecto: pídelo solo cuando vayas a enseñar el total.", "in": "query", "name": "includeTotal", "required": false, "schema": { "default": false, "description": "Calcula `totalCount`. Cuesta un `COUNT(*)` sobre el filtro entero, así que está apagado por defecto: pídelo solo cuando vayas a enseñar el total.", "title": "Includetotal", "type": "boolean" } }, { "in": "query", "name": "application", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Application" } }, { "in": "header", "name": "Belfort-Version", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Belfort-Version" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListEnvelope_PersonListItem_" } } }, "description": "Successful Response" }, "400": { "content": { "application/problem+json": { "examples": { "UNSUPPORTED_API_VERSION": { "summary": "UNSUPPORTED_API_VERSION", "value": { "code": "UNSUPPORTED_API_VERSION", "detail": "Unsupported API version", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 400, "title": "Unsupported API version", "type": "https://belfort.ai/docs/errors#UNSUPPORTED_API_VERSION" } } } } }, "description": "UNSUPPORTED_API_VERSION" }, "405": { "content": { "application/problem+json": { "examples": { "METHOD_NOT_ALLOWED": { "summary": "METHOD_NOT_ALLOWED", "value": { "code": "METHOD_NOT_ALLOWED", "detail": "Method not allowed", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 405, "title": "Method not allowed", "type": "https://belfort.ai/docs/errors#METHOD_NOT_ALLOWED" } } } } }, "description": "METHOD_NOT_ALLOWED" }, "422": { "content": { "application/problem+json": { "examples": { "VALIDATION_ERROR": { "summary": "VALIDATION_ERROR", "value": { "code": "VALIDATION_ERROR", "detail": "Validation error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 422, "title": "Validation error", "type": "https://belfort.ai/docs/errors#VALIDATION_ERROR" } } } } }, "description": "VALIDATION_ERROR" }, "500": { "content": { "application/problem+json": { "examples": { "INTERNAL_ERROR": { "summary": "INTERNAL_ERROR", "value": { "code": "INTERNAL_ERROR", "detail": "Internal server error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 500, "title": "Internal server error", "type": "https://belfort.ai/docs/errors#INTERNAL_ERROR" } } } } }, "description": "INTERNAL_ERROR" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Error — documento de problema RFC 9457 (`application/problem+json`)." } }, "security": [ { "secretKey": [] } ], "summary": "Listar personas", "tags": [ "persons" ], "x-required-scope": "persons:read" }, "post": { "description": "Da de alta una identidad en el vault. Si mandas `externalRef`, la operación es un upsert por `(aplicación, externalRef)`: llamarla dos veces con el mismo identificador de tu sistema actualiza, no duplica. La PII se escribe cifrada y no vuelve en la respuesta.", "operationId": "createPerson", "parameters": [ { "in": "header", "name": "Belfort-Version", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Belfort-Version" } }, { "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Idempotency-Key" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonWriteRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonWriteResponse" } } }, "description": "Successful Response" }, "400": { "content": { "application/problem+json": { "examples": { "UNSUPPORTED_API_VERSION": { "summary": "UNSUPPORTED_API_VERSION", "value": { "code": "UNSUPPORTED_API_VERSION", "detail": "Unsupported API version", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 400, "title": "Unsupported API version", "type": "https://belfort.ai/docs/errors#UNSUPPORTED_API_VERSION" } } } } }, "description": "UNSUPPORTED_API_VERSION" }, "405": { "content": { "application/problem+json": { "examples": { "METHOD_NOT_ALLOWED": { "summary": "METHOD_NOT_ALLOWED", "value": { "code": "METHOD_NOT_ALLOWED", "detail": "Method not allowed", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 405, "title": "Method not allowed", "type": "https://belfort.ai/docs/errors#METHOD_NOT_ALLOWED" } } } } }, "description": "METHOD_NOT_ALLOWED" }, "422": { "content": { "application/problem+json": { "examples": { "VALIDATION_ERROR": { "summary": "VALIDATION_ERROR", "value": { "code": "VALIDATION_ERROR", "detail": "Validation error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 422, "title": "Validation error", "type": "https://belfort.ai/docs/errors#VALIDATION_ERROR" } } } } }, "description": "VALIDATION_ERROR" }, "500": { "content": { "application/problem+json": { "examples": { "INTERNAL_ERROR": { "summary": "INTERNAL_ERROR", "value": { "code": "INTERNAL_ERROR", "detail": "Internal server error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 500, "title": "Internal server error", "type": "https://belfort.ai/docs/errors#INTERNAL_ERROR" } } } } }, "description": "INTERNAL_ERROR" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Error — documento de problema RFC 9457 (`application/problem+json`)." } }, "security": [ { "secretKey": [] } ], "summary": "Crear una persona", "tags": [ "persons" ], "x-required-scope": "persons:write" } }, "/v1/persons/batch-decrypt": { "post": { "description": "El mismo revelado para hasta 100 personas de una vez. Audita una entrada por persona, igual que si las hubieras pedido una a una.", "operationId": "batchDecryptPersons", "parameters": [ { "in": "header", "name": "Belfort-Version", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Belfort-Version" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchDecryptRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchDecryptResponse" } } }, "description": "Successful Response" }, "400": { "content": { "application/problem+json": { "examples": { "UNSUPPORTED_API_VERSION": { "summary": "UNSUPPORTED_API_VERSION", "value": { "code": "UNSUPPORTED_API_VERSION", "detail": "Unsupported API version", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 400, "title": "Unsupported API version", "type": "https://belfort.ai/docs/errors#UNSUPPORTED_API_VERSION" } } } } }, "description": "UNSUPPORTED_API_VERSION" }, "405": { "content": { "application/problem+json": { "examples": { "METHOD_NOT_ALLOWED": { "summary": "METHOD_NOT_ALLOWED", "value": { "code": "METHOD_NOT_ALLOWED", "detail": "Method not allowed", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 405, "title": "Method not allowed", "type": "https://belfort.ai/docs/errors#METHOD_NOT_ALLOWED" } } } } }, "description": "METHOD_NOT_ALLOWED" }, "422": { "content": { "application/problem+json": { "examples": { "VALIDATION_ERROR": { "summary": "VALIDATION_ERROR", "value": { "code": "VALIDATION_ERROR", "detail": "Validation error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 422, "title": "Validation error", "type": "https://belfort.ai/docs/errors#VALIDATION_ERROR" } } } } }, "description": "VALIDATION_ERROR" }, "500": { "content": { "application/problem+json": { "examples": { "INTERNAL_ERROR": { "summary": "INTERNAL_ERROR", "value": { "code": "INTERNAL_ERROR", "detail": "Internal server error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 500, "title": "Internal server error", "type": "https://belfort.ai/docs/errors#INTERNAL_ERROR" } } } } }, "description": "INTERNAL_ERROR" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Error — documento de problema RFC 9457 (`application/problem+json`)." } }, "security": [ { "secretKey": [] } ], "summary": "Revelar PII en lote", "tags": [ "persons" ], "x-required-scope": "persons:read_pii" } }, "/v1/persons/export-bulk": { "post": { "description": "Encola la exportación y responde de inmediato. Genera un archivo cifrado que se descarga aparte.", "operationId": "exportPersonsBulk", "parameters": [ { "in": "query", "name": "applicationId", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Applicationid" } }, { "in": "header", "name": "Belfort-Version", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Belfort-Version" } }, { "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Idempotency-Key" } } ], "requestBody": { "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/PersonExportBulkRequest" }, { "type": "null" } ], "title": "Body" } } } }, "responses": { "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonExportBulkJobEnvelope" } } }, "description": "Successful Response" }, "400": { "content": { "application/problem+json": { "examples": { "UNSUPPORTED_API_VERSION": { "summary": "UNSUPPORTED_API_VERSION", "value": { "code": "UNSUPPORTED_API_VERSION", "detail": "Unsupported API version", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 400, "title": "Unsupported API version", "type": "https://belfort.ai/docs/errors#UNSUPPORTED_API_VERSION" } } } } }, "description": "UNSUPPORTED_API_VERSION" }, "405": { "content": { "application/problem+json": { "examples": { "METHOD_NOT_ALLOWED": { "summary": "METHOD_NOT_ALLOWED", "value": { "code": "METHOD_NOT_ALLOWED", "detail": "Method not allowed", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 405, "title": "Method not allowed", "type": "https://belfort.ai/docs/errors#METHOD_NOT_ALLOWED" } } } } }, "description": "METHOD_NOT_ALLOWED" }, "422": { "content": { "application/problem+json": { "examples": { "VALIDATION_ERROR": { "summary": "VALIDATION_ERROR", "value": { "code": "VALIDATION_ERROR", "detail": "Validation error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 422, "title": "Validation error", "type": "https://belfort.ai/docs/errors#VALIDATION_ERROR" } } } } }, "description": "VALIDATION_ERROR" }, "500": { "content": { "application/problem+json": { "examples": { "INTERNAL_ERROR": { "summary": "INTERNAL_ERROR", "value": { "code": "INTERNAL_ERROR", "detail": "Internal server error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 500, "title": "Internal server error", "type": "https://belfort.ai/docs/errors#INTERNAL_ERROR" } } } } }, "description": "INTERNAL_ERROR" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Error — documento de problema RFC 9457 (`application/problem+json`)." } }, "security": [ { "secretKey": [] } ], "summary": "Exportar personas en lote", "tags": [ "persons" ], "x-required-scope": "persons:read_pii" } }, "/v1/persons/export-bulk/{job_id}": { "get": { "description": "Estado del trabajo de exportación.", "operationId": "getExportBulkJob", "parameters": [ { "in": "path", "name": "job_id", "required": true, "schema": { "title": "Job Id", "type": "string" } }, { "in": "header", "name": "Belfort-Version", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Belfort-Version" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonExportBulkJobEnvelope" } } }, "description": "Successful Response" }, "400": { "content": { "application/problem+json": { "examples": { "UNSUPPORTED_API_VERSION": { "summary": "UNSUPPORTED_API_VERSION", "value": { "code": "UNSUPPORTED_API_VERSION", "detail": "Unsupported API version", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 400, "title": "Unsupported API version", "type": "https://belfort.ai/docs/errors#UNSUPPORTED_API_VERSION" } } } } }, "description": "UNSUPPORTED_API_VERSION" }, "405": { "content": { "application/problem+json": { "examples": { "METHOD_NOT_ALLOWED": { "summary": "METHOD_NOT_ALLOWED", "value": { "code": "METHOD_NOT_ALLOWED", "detail": "Method not allowed", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 405, "title": "Method not allowed", "type": "https://belfort.ai/docs/errors#METHOD_NOT_ALLOWED" } } } } }, "description": "METHOD_NOT_ALLOWED" }, "422": { "content": { "application/problem+json": { "examples": { "VALIDATION_ERROR": { "summary": "VALIDATION_ERROR", "value": { "code": "VALIDATION_ERROR", "detail": "Validation error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 422, "title": "Validation error", "type": "https://belfort.ai/docs/errors#VALIDATION_ERROR" } } } } }, "description": "VALIDATION_ERROR" }, "500": { "content": { "application/problem+json": { "examples": { "INTERNAL_ERROR": { "summary": "INTERNAL_ERROR", "value": { "code": "INTERNAL_ERROR", "detail": "Internal server error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 500, "title": "Internal server error", "type": "https://belfort.ai/docs/errors#INTERNAL_ERROR" } } } } }, "description": "INTERNAL_ERROR" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Error — documento de problema RFC 9457 (`application/problem+json`)." } }, "security": [ { "secretKey": [] } ], "summary": "Consultar una exportación", "tags": [ "persons" ], "x-required-scope": "persons:read" } }, "/v1/persons/export-bulk/{job_id}/download": { "get": { "description": "Descifra y sirve el archivo completo. Exige el mismo permiso que crearlo: descargar es revelar, y se audita igual.", "operationId": "downloadExportBulkJob", "parameters": [ { "in": "path", "name": "job_id", "required": true, "schema": { "title": "Job Id", "type": "string" } }, { "in": "header", "name": "Belfort-Version", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Belfort-Version" } } ], "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response" }, "400": { "content": { "application/problem+json": { "examples": { "UNSUPPORTED_API_VERSION": { "summary": "UNSUPPORTED_API_VERSION", "value": { "code": "UNSUPPORTED_API_VERSION", "detail": "Unsupported API version", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 400, "title": "Unsupported API version", "type": "https://belfort.ai/docs/errors#UNSUPPORTED_API_VERSION" } } } } }, "description": "UNSUPPORTED_API_VERSION" }, "405": { "content": { "application/problem+json": { "examples": { "METHOD_NOT_ALLOWED": { "summary": "METHOD_NOT_ALLOWED", "value": { "code": "METHOD_NOT_ALLOWED", "detail": "Method not allowed", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 405, "title": "Method not allowed", "type": "https://belfort.ai/docs/errors#METHOD_NOT_ALLOWED" } } } } }, "description": "METHOD_NOT_ALLOWED" }, "422": { "content": { "application/problem+json": { "examples": { "VALIDATION_ERROR": { "summary": "VALIDATION_ERROR", "value": { "code": "VALIDATION_ERROR", "detail": "Validation error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 422, "title": "Validation error", "type": "https://belfort.ai/docs/errors#VALIDATION_ERROR" } } } } }, "description": "VALIDATION_ERROR" }, "500": { "content": { "application/problem+json": { "examples": { "INTERNAL_ERROR": { "summary": "INTERNAL_ERROR", "value": { "code": "INTERNAL_ERROR", "detail": "Internal server error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 500, "title": "Internal server error", "type": "https://belfort.ai/docs/errors#INTERNAL_ERROR" } } } } }, "description": "INTERNAL_ERROR" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Error — documento de problema RFC 9457 (`application/problem+json`)." } }, "security": [ { "secretKey": [] } ], "summary": "Descargar una exportación", "tags": [ "persons" ], "x-required-scope": "persons:read_pii" } }, "/v1/persons/import": { "post": { "description": "Recibe NDJSON —una persona por línea— y responde con un trabajo que puedes consultar. El entorno lo fija la key: una clave de prueba no puede escribir en producción.", "operationId": "importPersons", "parameters": [ { "in": "query", "name": "applicationId", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Applicationid" } }, { "in": "header", "name": "Belfort-Version", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Belfort-Version" } }, { "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Idempotency-Key" } } ], "responses": { "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonImportJobEnvelope" } } }, "description": "Successful Response" }, "400": { "content": { "application/problem+json": { "examples": { "UNSUPPORTED_API_VERSION": { "summary": "UNSUPPORTED_API_VERSION", "value": { "code": "UNSUPPORTED_API_VERSION", "detail": "Unsupported API version", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 400, "title": "Unsupported API version", "type": "https://belfort.ai/docs/errors#UNSUPPORTED_API_VERSION" } } } } }, "description": "UNSUPPORTED_API_VERSION" }, "405": { "content": { "application/problem+json": { "examples": { "METHOD_NOT_ALLOWED": { "summary": "METHOD_NOT_ALLOWED", "value": { "code": "METHOD_NOT_ALLOWED", "detail": "Method not allowed", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 405, "title": "Method not allowed", "type": "https://belfort.ai/docs/errors#METHOD_NOT_ALLOWED" } } } } }, "description": "METHOD_NOT_ALLOWED" }, "422": { "content": { "application/problem+json": { "examples": { "VALIDATION_ERROR": { "summary": "VALIDATION_ERROR", "value": { "code": "VALIDATION_ERROR", "detail": "Validation error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 422, "title": "Validation error", "type": "https://belfort.ai/docs/errors#VALIDATION_ERROR" } } } } }, "description": "VALIDATION_ERROR" }, "500": { "content": { "application/problem+json": { "examples": { "INTERNAL_ERROR": { "summary": "INTERNAL_ERROR", "value": { "code": "INTERNAL_ERROR", "detail": "Internal server error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 500, "title": "Internal server error", "type": "https://belfort.ai/docs/errors#INTERNAL_ERROR" } } } } }, "description": "INTERNAL_ERROR" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Error — documento de problema RFC 9457 (`application/problem+json`)." } }, "security": [ { "secretKey": [] } ], "summary": "Importar personas en lote", "tags": [ "persons" ], "x-required-scope": "persons:write" } }, "/v1/persons/import/{job_id}": { "get": { "description": "Progreso y errores por fila del trabajo de importación.", "operationId": "getImportJob", "parameters": [ { "in": "path", "name": "job_id", "required": true, "schema": { "title": "Job Id", "type": "string" } }, { "in": "header", "name": "Belfort-Version", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Belfort-Version" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonImportJobEnvelope" } } }, "description": "Successful Response" }, "400": { "content": { "application/problem+json": { "examples": { "UNSUPPORTED_API_VERSION": { "summary": "UNSUPPORTED_API_VERSION", "value": { "code": "UNSUPPORTED_API_VERSION", "detail": "Unsupported API version", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 400, "title": "Unsupported API version", "type": "https://belfort.ai/docs/errors#UNSUPPORTED_API_VERSION" } } } } }, "description": "UNSUPPORTED_API_VERSION" }, "405": { "content": { "application/problem+json": { "examples": { "METHOD_NOT_ALLOWED": { "summary": "METHOD_NOT_ALLOWED", "value": { "code": "METHOD_NOT_ALLOWED", "detail": "Method not allowed", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 405, "title": "Method not allowed", "type": "https://belfort.ai/docs/errors#METHOD_NOT_ALLOWED" } } } } }, "description": "METHOD_NOT_ALLOWED" }, "422": { "content": { "application/problem+json": { "examples": { "VALIDATION_ERROR": { "summary": "VALIDATION_ERROR", "value": { "code": "VALIDATION_ERROR", "detail": "Validation error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 422, "title": "Validation error", "type": "https://belfort.ai/docs/errors#VALIDATION_ERROR" } } } } }, "description": "VALIDATION_ERROR" }, "500": { "content": { "application/problem+json": { "examples": { "INTERNAL_ERROR": { "summary": "INTERNAL_ERROR", "value": { "code": "INTERNAL_ERROR", "detail": "Internal server error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 500, "title": "Internal server error", "type": "https://belfort.ai/docs/errors#INTERNAL_ERROR" } } } } }, "description": "INTERNAL_ERROR" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Error — documento de problema RFC 9457 (`application/problem+json`)." } }, "security": [ { "secretKey": [] } ], "summary": "Consultar una importación", "tags": [ "persons" ], "x-required-scope": "persons:read" } }, "/v1/persons/search": { "post": { "description": "Búsqueda estructurada: declaras contra qué campo buscas en vez de mandar un texto libre y esperar que el servidor adivine. Va por POST porque los criterios pueden contener datos personales, y una query string acaba en los registros de todos los intermediarios.", "operationId": "searchPersons", "parameters": [ { "in": "header", "name": "Belfort-Version", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Belfort-Version" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonSearchRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonSearchResults" } } }, "description": "Successful Response" }, "400": { "content": { "application/problem+json": { "examples": { "UNSUPPORTED_API_VERSION": { "summary": "UNSUPPORTED_API_VERSION", "value": { "code": "UNSUPPORTED_API_VERSION", "detail": "Unsupported API version", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 400, "title": "Unsupported API version", "type": "https://belfort.ai/docs/errors#UNSUPPORTED_API_VERSION" } } } } }, "description": "UNSUPPORTED_API_VERSION" }, "405": { "content": { "application/problem+json": { "examples": { "METHOD_NOT_ALLOWED": { "summary": "METHOD_NOT_ALLOWED", "value": { "code": "METHOD_NOT_ALLOWED", "detail": "Method not allowed", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 405, "title": "Method not allowed", "type": "https://belfort.ai/docs/errors#METHOD_NOT_ALLOWED" } } } } }, "description": "METHOD_NOT_ALLOWED" }, "422": { "content": { "application/problem+json": { "examples": { "VALIDATION_ERROR": { "summary": "VALIDATION_ERROR", "value": { "code": "VALIDATION_ERROR", "detail": "Validation error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 422, "title": "Validation error", "type": "https://belfort.ai/docs/errors#VALIDATION_ERROR" } } } } }, "description": "VALIDATION_ERROR" }, "500": { "content": { "application/problem+json": { "examples": { "INTERNAL_ERROR": { "summary": "INTERNAL_ERROR", "value": { "code": "INTERNAL_ERROR", "detail": "Internal server error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 500, "title": "Internal server error", "type": "https://belfort.ai/docs/errors#INTERNAL_ERROR" } } } } }, "description": "INTERNAL_ERROR" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Error — documento de problema RFC 9457 (`application/problem+json`)." } }, "security": [ { "secretKey": [] } ], "summary": "Buscar personas", "tags": [ "persons" ], "x-required-scope": "persons:read" } }, "/v1/persons/{person_id}": { "get": { "description": "Enmascarada por defecto: no descifra nada, no audita y no consume presupuesto de revelado. Para ver un campo en claro tienes que pedirlo explícitamente.", "operationId": "getPersonDetail", "parameters": [ { "in": "path", "name": "person_id", "required": true, "schema": { "title": "Person Id", "type": "string" } }, { "in": "query", "name": "expand", "required": false, "schema": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Expand" } }, { "in": "header", "name": "Belfort-Reason", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Belfort-Reason" } }, { "in": "header", "name": "Belfort-Version", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Belfort-Version" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonDetailMasked" } } }, "description": "Successful Response" }, "400": { "content": { "application/problem+json": { "examples": { "UNSUPPORTED_API_VERSION": { "summary": "UNSUPPORTED_API_VERSION", "value": { "code": "UNSUPPORTED_API_VERSION", "detail": "Unsupported API version", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 400, "title": "Unsupported API version", "type": "https://belfort.ai/docs/errors#UNSUPPORTED_API_VERSION" } } } } }, "description": "UNSUPPORTED_API_VERSION" }, "405": { "content": { "application/problem+json": { "examples": { "METHOD_NOT_ALLOWED": { "summary": "METHOD_NOT_ALLOWED", "value": { "code": "METHOD_NOT_ALLOWED", "detail": "Method not allowed", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 405, "title": "Method not allowed", "type": "https://belfort.ai/docs/errors#METHOD_NOT_ALLOWED" } } } } }, "description": "METHOD_NOT_ALLOWED" }, "422": { "content": { "application/problem+json": { "examples": { "VALIDATION_ERROR": { "summary": "VALIDATION_ERROR", "value": { "code": "VALIDATION_ERROR", "detail": "Validation error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 422, "title": "Validation error", "type": "https://belfort.ai/docs/errors#VALIDATION_ERROR" } } } } }, "description": "VALIDATION_ERROR" }, "500": { "content": { "application/problem+json": { "examples": { "INTERNAL_ERROR": { "summary": "INTERNAL_ERROR", "value": { "code": "INTERNAL_ERROR", "detail": "Internal server error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 500, "title": "Internal server error", "type": "https://belfort.ai/docs/errors#INTERNAL_ERROR" } } } } }, "description": "INTERNAL_ERROR" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Error — documento de problema RFC 9457 (`application/problem+json`)." } }, "security": [ { "secretKey": [] } ], "summary": "Consultar una persona", "tags": [ "persons" ], "x-required-scope": "persons:read" }, "patch": { "description": "El derecho de rectificación de ARCO. La PII sigue siendo de solo escritura, y cualquier cambio sobre ella queda registrado como una revisión.", "operationId": "patchPerson", "parameters": [ { "in": "path", "name": "person_id", "required": true, "schema": { "title": "Person Id", "type": "string" } }, { "in": "header", "name": "Belfort-Version", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Belfort-Version" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonPatchRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonWriteResponse" } } }, "description": "Successful Response" }, "400": { "content": { "application/problem+json": { "examples": { "UNSUPPORTED_API_VERSION": { "summary": "UNSUPPORTED_API_VERSION", "value": { "code": "UNSUPPORTED_API_VERSION", "detail": "Unsupported API version", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 400, "title": "Unsupported API version", "type": "https://belfort.ai/docs/errors#UNSUPPORTED_API_VERSION" } } } } }, "description": "UNSUPPORTED_API_VERSION" }, "405": { "content": { "application/problem+json": { "examples": { "METHOD_NOT_ALLOWED": { "summary": "METHOD_NOT_ALLOWED", "value": { "code": "METHOD_NOT_ALLOWED", "detail": "Method not allowed", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 405, "title": "Method not allowed", "type": "https://belfort.ai/docs/errors#METHOD_NOT_ALLOWED" } } } } }, "description": "METHOD_NOT_ALLOWED" }, "422": { "content": { "application/problem+json": { "examples": { "VALIDATION_ERROR": { "summary": "VALIDATION_ERROR", "value": { "code": "VALIDATION_ERROR", "detail": "Validation error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 422, "title": "Validation error", "type": "https://belfort.ai/docs/errors#VALIDATION_ERROR" } } } } }, "description": "VALIDATION_ERROR" }, "500": { "content": { "application/problem+json": { "examples": { "INTERNAL_ERROR": { "summary": "INTERNAL_ERROR", "value": { "code": "INTERNAL_ERROR", "detail": "Internal server error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 500, "title": "Internal server error", "type": "https://belfort.ai/docs/errors#INTERNAL_ERROR" } } } } }, "description": "INTERNAL_ERROR" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Error — documento de problema RFC 9457 (`application/problem+json`)." } }, "security": [ { "secretKey": [] } ], "summary": "Rectificar una persona", "tags": [ "persons" ], "x-required-scope": "persons:write" } }, "/v1/persons/{person_id}/client-token": { "post": { "description": "Crea una credencial efímera para que un navegador revele campos concretos, sin que tu clave secreta salga de tu servidor. Declaras qué campos autoriza; el token no puede pedir más.", "operationId": "issuePersonClientToken", "parameters": [ { "in": "path", "name": "person_id", "required": true, "schema": { "title": "Person Id", "type": "string" } }, { "in": "header", "name": "Belfort-Version", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Belfort-Version" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientTokenCreateRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientTokenIssueResponse" } } }, "description": "Successful Response" }, "400": { "content": { "application/problem+json": { "examples": { "UNSUPPORTED_API_VERSION": { "summary": "UNSUPPORTED_API_VERSION", "value": { "code": "UNSUPPORTED_API_VERSION", "detail": "Unsupported API version", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 400, "title": "Unsupported API version", "type": "https://belfort.ai/docs/errors#UNSUPPORTED_API_VERSION" } } } } }, "description": "UNSUPPORTED_API_VERSION" }, "405": { "content": { "application/problem+json": { "examples": { "METHOD_NOT_ALLOWED": { "summary": "METHOD_NOT_ALLOWED", "value": { "code": "METHOD_NOT_ALLOWED", "detail": "Method not allowed", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 405, "title": "Method not allowed", "type": "https://belfort.ai/docs/errors#METHOD_NOT_ALLOWED" } } } } }, "description": "METHOD_NOT_ALLOWED" }, "422": { "content": { "application/problem+json": { "examples": { "VALIDATION_ERROR": { "summary": "VALIDATION_ERROR", "value": { "code": "VALIDATION_ERROR", "detail": "Validation error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 422, "title": "Validation error", "type": "https://belfort.ai/docs/errors#VALIDATION_ERROR" } } } } }, "description": "VALIDATION_ERROR" }, "500": { "content": { "application/problem+json": { "examples": { "INTERNAL_ERROR": { "summary": "INTERNAL_ERROR", "value": { "code": "INTERNAL_ERROR", "detail": "Internal server error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 500, "title": "Internal server error", "type": "https://belfort.ai/docs/errors#INTERNAL_ERROR" } } } } }, "description": "INTERNAL_ERROR" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Error — documento de problema RFC 9457 (`application/problem+json`)." } }, "security": [ { "secretKey": [] } ], "summary": "Emitir un client-token", "tags": [ "persons" ], "x-required-scope": "persons:read_pii" } }, "/v1/persons/{person_id}/client-token/{token_id}/revoke": { "post": { "description": "Invalida el token antes de que expire. Idempotente: revocar dos veces devuelve el mismo momento de revocación, no un error.", "operationId": "revokePersonClientToken", "parameters": [ { "in": "path", "name": "person_id", "required": true, "schema": { "title": "Person Id", "type": "string" } }, { "in": "path", "name": "token_id", "required": true, "schema": { "title": "Token Id", "type": "string" } }, { "in": "header", "name": "Belfort-Version", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Belfort-Version" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientTokenRevokeResponse" } } }, "description": "Successful Response" }, "400": { "content": { "application/problem+json": { "examples": { "UNSUPPORTED_API_VERSION": { "summary": "UNSUPPORTED_API_VERSION", "value": { "code": "UNSUPPORTED_API_VERSION", "detail": "Unsupported API version", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 400, "title": "Unsupported API version", "type": "https://belfort.ai/docs/errors#UNSUPPORTED_API_VERSION" } } } } }, "description": "UNSUPPORTED_API_VERSION" }, "405": { "content": { "application/problem+json": { "examples": { "METHOD_NOT_ALLOWED": { "summary": "METHOD_NOT_ALLOWED", "value": { "code": "METHOD_NOT_ALLOWED", "detail": "Method not allowed", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 405, "title": "Method not allowed", "type": "https://belfort.ai/docs/errors#METHOD_NOT_ALLOWED" } } } } }, "description": "METHOD_NOT_ALLOWED" }, "422": { "content": { "application/problem+json": { "examples": { "VALIDATION_ERROR": { "summary": "VALIDATION_ERROR", "value": { "code": "VALIDATION_ERROR", "detail": "Validation error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 422, "title": "Validation error", "type": "https://belfort.ai/docs/errors#VALIDATION_ERROR" } } } } }, "description": "VALIDATION_ERROR" }, "500": { "content": { "application/problem+json": { "examples": { "INTERNAL_ERROR": { "summary": "INTERNAL_ERROR", "value": { "code": "INTERNAL_ERROR", "detail": "Internal server error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 500, "title": "Internal server error", "type": "https://belfort.ai/docs/errors#INTERNAL_ERROR" } } } } }, "description": "INTERNAL_ERROR" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Error — documento de problema RFC 9457 (`application/problem+json`)." } }, "security": [ { "secretKey": [] } ], "summary": "Revocar un client-token", "tags": [ "persons" ], "x-required-scope": "persons:write" } }, "/v1/persons/{person_id}/consents": { "get": { "description": "Los consentimientos vigentes y revocados de la persona. La evidencia del consentimiento nunca viaja en esta lista: es de solo escritura.", "operationId": "listPersonConsents", "parameters": [ { "in": "path", "name": "person_id", "required": true, "schema": { "title": "Person Id", "type": "string" } }, { "description": "Tamaño de página (1–100).", "in": "query", "name": "limit", "required": false, "schema": { "default": 20, "description": "Tamaño de página (1–100).", "title": "Limit", "type": "integer" } }, { "description": "`nextCursor` de la página anterior. Excluyente con `endingBefore`.", "in": "query", "name": "startingAfter", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "`nextCursor` de la página anterior. Excluyente con `endingBefore`.", "title": "Startingafter" } }, { "description": "`previousCursor` de la página actual. Excluyente con `startingAfter`.", "in": "query", "name": "endingBefore", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "`previousCursor` de la página actual. Excluyente con `startingAfter`.", "title": "Endingbefore" } }, { "description": "Calcula `totalCount`. Cuesta un `COUNT(*)` sobre el filtro entero, así que está apagado por defecto: pídelo solo cuando vayas a enseñar el total.", "in": "query", "name": "includeTotal", "required": false, "schema": { "default": false, "description": "Calcula `totalCount`. Cuesta un `COUNT(*)` sobre el filtro entero, así que está apagado por defecto: pídelo solo cuando vayas a enseñar el total.", "title": "Includetotal", "type": "boolean" } }, { "in": "header", "name": "Belfort-Version", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Belfort-Version" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListEnvelope_ConsentItem_" } } }, "description": "Successful Response" }, "400": { "content": { "application/problem+json": { "examples": { "UNSUPPORTED_API_VERSION": { "summary": "UNSUPPORTED_API_VERSION", "value": { "code": "UNSUPPORTED_API_VERSION", "detail": "Unsupported API version", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 400, "title": "Unsupported API version", "type": "https://belfort.ai/docs/errors#UNSUPPORTED_API_VERSION" } } } } }, "description": "UNSUPPORTED_API_VERSION" }, "405": { "content": { "application/problem+json": { "examples": { "METHOD_NOT_ALLOWED": { "summary": "METHOD_NOT_ALLOWED", "value": { "code": "METHOD_NOT_ALLOWED", "detail": "Method not allowed", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 405, "title": "Method not allowed", "type": "https://belfort.ai/docs/errors#METHOD_NOT_ALLOWED" } } } } }, "description": "METHOD_NOT_ALLOWED" }, "422": { "content": { "application/problem+json": { "examples": { "VALIDATION_ERROR": { "summary": "VALIDATION_ERROR", "value": { "code": "VALIDATION_ERROR", "detail": "Validation error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 422, "title": "Validation error", "type": "https://belfort.ai/docs/errors#VALIDATION_ERROR" } } } } }, "description": "VALIDATION_ERROR" }, "500": { "content": { "application/problem+json": { "examples": { "INTERNAL_ERROR": { "summary": "INTERNAL_ERROR", "value": { "code": "INTERNAL_ERROR", "detail": "Internal server error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 500, "title": "Internal server error", "type": "https://belfort.ai/docs/errors#INTERNAL_ERROR" } } } } }, "description": "INTERNAL_ERROR" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Error — documento de problema RFC 9457 (`application/problem+json`)." } }, "security": [ { "secretKey": [] } ], "summary": "Listar consentimientos", "tags": [ "persons" ], "x-required-scope": "persons:read" }, "post": { "description": "Asocia un consentimiento a una finalidad concreta. La finalidad tiene que existir en el catálogo: aceptar una inventada sería registrar un consentimiento que no significa nada.", "operationId": "grantPersonConsent", "parameters": [ { "in": "path", "name": "person_id", "required": true, "schema": { "title": "Person Id", "type": "string" } }, { "in": "header", "name": "Belfort-Version", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Belfort-Version" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConsentGrantRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConsentItem" } } }, "description": "Successful Response" }, "400": { "content": { "application/problem+json": { "examples": { "UNSUPPORTED_API_VERSION": { "summary": "UNSUPPORTED_API_VERSION", "value": { "code": "UNSUPPORTED_API_VERSION", "detail": "Unsupported API version", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 400, "title": "Unsupported API version", "type": "https://belfort.ai/docs/errors#UNSUPPORTED_API_VERSION" } } } } }, "description": "UNSUPPORTED_API_VERSION" }, "405": { "content": { "application/problem+json": { "examples": { "METHOD_NOT_ALLOWED": { "summary": "METHOD_NOT_ALLOWED", "value": { "code": "METHOD_NOT_ALLOWED", "detail": "Method not allowed", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 405, "title": "Method not allowed", "type": "https://belfort.ai/docs/errors#METHOD_NOT_ALLOWED" } } } } }, "description": "METHOD_NOT_ALLOWED" }, "422": { "content": { "application/problem+json": { "examples": { "VALIDATION_ERROR": { "summary": "VALIDATION_ERROR", "value": { "code": "VALIDATION_ERROR", "detail": "Validation error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 422, "title": "Validation error", "type": "https://belfort.ai/docs/errors#VALIDATION_ERROR" } } } } }, "description": "VALIDATION_ERROR" }, "500": { "content": { "application/problem+json": { "examples": { "INTERNAL_ERROR": { "summary": "INTERNAL_ERROR", "value": { "code": "INTERNAL_ERROR", "detail": "Internal server error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 500, "title": "Internal server error", "type": "https://belfort.ai/docs/errors#INTERNAL_ERROR" } } } } }, "description": "INTERNAL_ERROR" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Error — documento de problema RFC 9457 (`application/problem+json`)." } }, "security": [ { "secretKey": [] } ], "summary": "Registrar un consentimiento", "tags": [ "persons" ], "x-required-scope": "persons:write" } }, "/v1/persons/{person_id}/consents/{consent_id}/revoke": { "post": { "description": "Idempotente: la fecha de revocación es la de la primera vez, no la de la última llamada.", "operationId": "revokePersonConsent", "parameters": [ { "in": "path", "name": "person_id", "required": true, "schema": { "title": "Person Id", "type": "string" } }, { "in": "path", "name": "consent_id", "required": true, "schema": { "title": "Consent Id", "type": "string" } }, { "in": "header", "name": "Belfort-Version", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Belfort-Version" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConsentItem" } } }, "description": "Successful Response" }, "400": { "content": { "application/problem+json": { "examples": { "UNSUPPORTED_API_VERSION": { "summary": "UNSUPPORTED_API_VERSION", "value": { "code": "UNSUPPORTED_API_VERSION", "detail": "Unsupported API version", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 400, "title": "Unsupported API version", "type": "https://belfort.ai/docs/errors#UNSUPPORTED_API_VERSION" } } } } }, "description": "UNSUPPORTED_API_VERSION" }, "405": { "content": { "application/problem+json": { "examples": { "METHOD_NOT_ALLOWED": { "summary": "METHOD_NOT_ALLOWED", "value": { "code": "METHOD_NOT_ALLOWED", "detail": "Method not allowed", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 405, "title": "Method not allowed", "type": "https://belfort.ai/docs/errors#METHOD_NOT_ALLOWED" } } } } }, "description": "METHOD_NOT_ALLOWED" }, "422": { "content": { "application/problem+json": { "examples": { "VALIDATION_ERROR": { "summary": "VALIDATION_ERROR", "value": { "code": "VALIDATION_ERROR", "detail": "Validation error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 422, "title": "Validation error", "type": "https://belfort.ai/docs/errors#VALIDATION_ERROR" } } } } }, "description": "VALIDATION_ERROR" }, "500": { "content": { "application/problem+json": { "examples": { "INTERNAL_ERROR": { "summary": "INTERNAL_ERROR", "value": { "code": "INTERNAL_ERROR", "detail": "Internal server error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 500, "title": "Internal server error", "type": "https://belfort.ai/docs/errors#INTERNAL_ERROR" } } } } }, "description": "INTERNAL_ERROR" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Error — documento de problema RFC 9457 (`application/problem+json`)." } }, "security": [ { "secretKey": [] } ], "summary": "Revocar un consentimiento", "tags": [ "persons" ], "x-required-scope": "persons:write" } }, "/v1/persons/{person_id}/consolidate": { "post": { "description": "Fusiona una o varias personas dentro de esta, que es la que sobrevive. Es asíncrono: responde de inmediato con un identificador que puedes consultar.", "operationId": "consolidatePerson", "parameters": [ { "in": "path", "name": "person_id", "required": true, "schema": { "title": "Person Id", "type": "string" } }, { "in": "header", "name": "Belfort-Version", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Belfort-Version" } }, { "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Idempotency-Key" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConsolidateRequest" } } }, "required": true }, "responses": { "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConsolidationEnvelope" } } }, "description": "Successful Response" }, "400": { "content": { "application/problem+json": { "examples": { "UNSUPPORTED_API_VERSION": { "summary": "UNSUPPORTED_API_VERSION", "value": { "code": "UNSUPPORTED_API_VERSION", "detail": "Unsupported API version", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 400, "title": "Unsupported API version", "type": "https://belfort.ai/docs/errors#UNSUPPORTED_API_VERSION" } } } } }, "description": "UNSUPPORTED_API_VERSION" }, "405": { "content": { "application/problem+json": { "examples": { "METHOD_NOT_ALLOWED": { "summary": "METHOD_NOT_ALLOWED", "value": { "code": "METHOD_NOT_ALLOWED", "detail": "Method not allowed", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 405, "title": "Method not allowed", "type": "https://belfort.ai/docs/errors#METHOD_NOT_ALLOWED" } } } } }, "description": "METHOD_NOT_ALLOWED" }, "422": { "content": { "application/problem+json": { "examples": { "VALIDATION_ERROR": { "summary": "VALIDATION_ERROR", "value": { "code": "VALIDATION_ERROR", "detail": "Validation error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 422, "title": "Validation error", "type": "https://belfort.ai/docs/errors#VALIDATION_ERROR" } } } } }, "description": "VALIDATION_ERROR" }, "500": { "content": { "application/problem+json": { "examples": { "INTERNAL_ERROR": { "summary": "INTERNAL_ERROR", "value": { "code": "INTERNAL_ERROR", "detail": "Internal server error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 500, "title": "Internal server error", "type": "https://belfort.ai/docs/errors#INTERNAL_ERROR" } } } } }, "description": "INTERNAL_ERROR" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Error — documento de problema RFC 9457 (`application/problem+json`)." } }, "security": [ { "secretKey": [] } ], "summary": "Consolidar duplicados", "tags": [ "persons" ], "x-required-scope": "persons:write" } }, "/v1/persons/{person_id}/consolidations/{consolidation_id}": { "get": { "description": "Solo aparece como terminada cuando TODAS las fuentes se fusionaron. Una consolidación a medias no se reporta como hecha.", "operationId": "getConsolidationStatus", "parameters": [ { "in": "path", "name": "person_id", "required": true, "schema": { "title": "Person Id", "type": "string" } }, { "in": "path", "name": "consolidation_id", "required": true, "schema": { "title": "Consolidation Id", "type": "string" } }, { "in": "header", "name": "Belfort-Version", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Belfort-Version" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConsolidationStatusResponse" } } }, "description": "Successful Response" }, "400": { "content": { "application/problem+json": { "examples": { "UNSUPPORTED_API_VERSION": { "summary": "UNSUPPORTED_API_VERSION", "value": { "code": "UNSUPPORTED_API_VERSION", "detail": "Unsupported API version", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 400, "title": "Unsupported API version", "type": "https://belfort.ai/docs/errors#UNSUPPORTED_API_VERSION" } } } } }, "description": "UNSUPPORTED_API_VERSION" }, "405": { "content": { "application/problem+json": { "examples": { "METHOD_NOT_ALLOWED": { "summary": "METHOD_NOT_ALLOWED", "value": { "code": "METHOD_NOT_ALLOWED", "detail": "Method not allowed", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 405, "title": "Method not allowed", "type": "https://belfort.ai/docs/errors#METHOD_NOT_ALLOWED" } } } } }, "description": "METHOD_NOT_ALLOWED" }, "422": { "content": { "application/problem+json": { "examples": { "VALIDATION_ERROR": { "summary": "VALIDATION_ERROR", "value": { "code": "VALIDATION_ERROR", "detail": "Validation error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 422, "title": "Validation error", "type": "https://belfort.ai/docs/errors#VALIDATION_ERROR" } } } } }, "description": "VALIDATION_ERROR" }, "500": { "content": { "application/problem+json": { "examples": { "INTERNAL_ERROR": { "summary": "INTERNAL_ERROR", "value": { "code": "INTERNAL_ERROR", "detail": "Internal server error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 500, "title": "Internal server error", "type": "https://belfort.ai/docs/errors#INTERNAL_ERROR" } } } } }, "description": "INTERNAL_ERROR" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Error — documento de problema RFC 9457 (`application/problem+json`)." } }, "security": [ { "secretKey": [] } ], "summary": "Consultar una consolidación", "tags": [ "persons" ], "x-required-scope": "persons:read" } }, "/v1/persons/{person_id}/decrypt": { "post": { "description": "El revelado canónico servidor a servidor. Exige declarar la finalidad, escribe una entrada en la bitácora de accesos y consume presupuesto diario. **No es idempotente a propósito**: reintentar tiene que dejar su propia huella, porque la ley pide constancia de cada acceso, no de cada intención.", "operationId": "decryptPerson", "parameters": [ { "in": "path", "name": "person_id", "required": true, "schema": { "title": "Person Id", "type": "string" } }, { "in": "header", "name": "Belfort-Version", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Belfort-Version" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DecryptRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DecryptResponse" } } }, "description": "Successful Response" }, "400": { "content": { "application/problem+json": { "examples": { "UNSUPPORTED_API_VERSION": { "summary": "UNSUPPORTED_API_VERSION", "value": { "code": "UNSUPPORTED_API_VERSION", "detail": "Unsupported API version", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 400, "title": "Unsupported API version", "type": "https://belfort.ai/docs/errors#UNSUPPORTED_API_VERSION" } } } } }, "description": "UNSUPPORTED_API_VERSION" }, "405": { "content": { "application/problem+json": { "examples": { "METHOD_NOT_ALLOWED": { "summary": "METHOD_NOT_ALLOWED", "value": { "code": "METHOD_NOT_ALLOWED", "detail": "Method not allowed", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 405, "title": "Method not allowed", "type": "https://belfort.ai/docs/errors#METHOD_NOT_ALLOWED" } } } } }, "description": "METHOD_NOT_ALLOWED" }, "422": { "content": { "application/problem+json": { "examples": { "VALIDATION_ERROR": { "summary": "VALIDATION_ERROR", "value": { "code": "VALIDATION_ERROR", "detail": "Validation error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 422, "title": "Validation error", "type": "https://belfort.ai/docs/errors#VALIDATION_ERROR" } } } } }, "description": "VALIDATION_ERROR" }, "500": { "content": { "application/problem+json": { "examples": { "INTERNAL_ERROR": { "summary": "INTERNAL_ERROR", "value": { "code": "INTERNAL_ERROR", "detail": "Internal server error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 500, "title": "Internal server error", "type": "https://belfort.ai/docs/errors#INTERNAL_ERROR" } } } } }, "description": "INTERNAL_ERROR" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Error — documento de problema RFC 9457 (`application/problem+json`)." } }, "security": [ { "secretKey": [] } ], "summary": "Revelar PII en claro", "tags": [ "persons" ], "x-required-scope": "persons:read_pii" } }, "/v1/persons/{person_id}/deletion-certificate": { "get": { "description": "La constancia de que una persona fue purgada de verdad. Determinista: la misma supresión produce siempre el mismo certificado, así que sirve como prueba.", "operationId": "getDeletionCertificate", "parameters": [ { "in": "path", "name": "person_id", "required": true, "schema": { "title": "Person Id", "type": "string" } }, { "in": "header", "name": "Belfort-Version", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Belfort-Version" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonDeletionCertificate" } } }, "description": "Successful Response" }, "400": { "content": { "application/problem+json": { "examples": { "UNSUPPORTED_API_VERSION": { "summary": "UNSUPPORTED_API_VERSION", "value": { "code": "UNSUPPORTED_API_VERSION", "detail": "Unsupported API version", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 400, "title": "Unsupported API version", "type": "https://belfort.ai/docs/errors#UNSUPPORTED_API_VERSION" } } } } }, "description": "UNSUPPORTED_API_VERSION" }, "405": { "content": { "application/problem+json": { "examples": { "METHOD_NOT_ALLOWED": { "summary": "METHOD_NOT_ALLOWED", "value": { "code": "METHOD_NOT_ALLOWED", "detail": "Method not allowed", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 405, "title": "Method not allowed", "type": "https://belfort.ai/docs/errors#METHOD_NOT_ALLOWED" } } } } }, "description": "METHOD_NOT_ALLOWED" }, "422": { "content": { "application/problem+json": { "examples": { "VALIDATION_ERROR": { "summary": "VALIDATION_ERROR", "value": { "code": "VALIDATION_ERROR", "detail": "Validation error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 422, "title": "Validation error", "type": "https://belfort.ai/docs/errors#VALIDATION_ERROR" } } } } }, "description": "VALIDATION_ERROR" }, "500": { "content": { "application/problem+json": { "examples": { "INTERNAL_ERROR": { "summary": "INTERNAL_ERROR", "value": { "code": "INTERNAL_ERROR", "detail": "Internal server error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 500, "title": "Internal server error", "type": "https://belfort.ai/docs/errors#INTERNAL_ERROR" } } } } }, "description": "INTERNAL_ERROR" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Error — documento de problema RFC 9457 (`application/problem+json`)." } }, "security": [ { "secretKey": [] } ], "summary": "Obtener el certificado de supresión", "tags": [ "persons" ], "x-required-scope": "persons:read" } }, "/v1/persons/{person_id}/documents": { "get": { "description": "Solo metadatos: qué archivos existen, de qué tipo y de cuándo. Para verlos hay que emitir un enlace firmado, que es una operación distinta y auditada.", "operationId": "listPersonDocuments", "parameters": [ { "in": "path", "name": "person_id", "required": true, "schema": { "title": "Person Id", "type": "string" } }, { "description": "Tamaño de página (1–100).", "in": "query", "name": "limit", "required": false, "schema": { "default": 20, "description": "Tamaño de página (1–100).", "title": "Limit", "type": "integer" } }, { "description": "`nextCursor` de la página anterior. Excluyente con `endingBefore`.", "in": "query", "name": "startingAfter", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "`nextCursor` de la página anterior. Excluyente con `endingBefore`.", "title": "Startingafter" } }, { "description": "`previousCursor` de la página actual. Excluyente con `startingAfter`.", "in": "query", "name": "endingBefore", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "`previousCursor` de la página actual. Excluyente con `startingAfter`.", "title": "Endingbefore" } }, { "description": "Calcula `totalCount`. Cuesta un `COUNT(*)` sobre el filtro entero, así que está apagado por defecto: pídelo solo cuando vayas a enseñar el total.", "in": "query", "name": "includeTotal", "required": false, "schema": { "default": false, "description": "Calcula `totalCount`. Cuesta un `COUNT(*)` sobre el filtro entero, así que está apagado por defecto: pídelo solo cuando vayas a enseñar el total.", "title": "Includetotal", "type": "boolean" } }, { "in": "header", "name": "Belfort-Version", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Belfort-Version" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListEnvelope_PersonDocumentItem_" } } }, "description": "Successful Response" }, "400": { "content": { "application/problem+json": { "examples": { "UNSUPPORTED_API_VERSION": { "summary": "UNSUPPORTED_API_VERSION", "value": { "code": "UNSUPPORTED_API_VERSION", "detail": "Unsupported API version", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 400, "title": "Unsupported API version", "type": "https://belfort.ai/docs/errors#UNSUPPORTED_API_VERSION" } } } } }, "description": "UNSUPPORTED_API_VERSION" }, "405": { "content": { "application/problem+json": { "examples": { "METHOD_NOT_ALLOWED": { "summary": "METHOD_NOT_ALLOWED", "value": { "code": "METHOD_NOT_ALLOWED", "detail": "Method not allowed", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 405, "title": "Method not allowed", "type": "https://belfort.ai/docs/errors#METHOD_NOT_ALLOWED" } } } } }, "description": "METHOD_NOT_ALLOWED" }, "422": { "content": { "application/problem+json": { "examples": { "VALIDATION_ERROR": { "summary": "VALIDATION_ERROR", "value": { "code": "VALIDATION_ERROR", "detail": "Validation error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 422, "title": "Validation error", "type": "https://belfort.ai/docs/errors#VALIDATION_ERROR" } } } } }, "description": "VALIDATION_ERROR" }, "500": { "content": { "application/problem+json": { "examples": { "INTERNAL_ERROR": { "summary": "INTERNAL_ERROR", "value": { "code": "INTERNAL_ERROR", "detail": "Internal server error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 500, "title": "Internal server error", "type": "https://belfort.ai/docs/errors#INTERNAL_ERROR" } } } } }, "description": "INTERNAL_ERROR" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Error — documento de problema RFC 9457 (`application/problem+json`)." } }, "security": [ { "secretKey": [] } ], "summary": "Listar documentos de la persona", "tags": [ "persons" ], "x-required-scope": "persons:read" } }, "/v1/persons/{person_id}/documents/{asset_id}/legal-hold": { "post": { "description": "Bloquea un asset de media concreto: mientras el hold esté vigente, ni el barrido de retención ni el derecho al olvido lo eliminan, aunque su fecha de retención ya haya vencido. `reason` y `legalBasis` son obligatorios. Cada llamada agrega una fila nueva al historial append-only, aunque el hold ya estuviera puesto. Requiere scope `persons:write`.", "operationId": "setDocumentLegalHold", "parameters": [ { "in": "path", "name": "person_id", "required": true, "schema": { "title": "Person Id", "type": "string" } }, { "in": "path", "name": "asset_id", "required": true, "schema": { "title": "Asset Id", "type": "string" } }, { "in": "header", "name": "Belfort-Version", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Belfort-Version" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MediaAssetLegalHoldSetRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MediaAssetLegalHoldItem" } } }, "description": "Successful Response" }, "400": { "content": { "application/problem+json": { "examples": { "UNSUPPORTED_API_VERSION": { "summary": "UNSUPPORTED_API_VERSION", "value": { "code": "UNSUPPORTED_API_VERSION", "detail": "Unsupported API version", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 400, "title": "Unsupported API version", "type": "https://belfort.ai/docs/errors#UNSUPPORTED_API_VERSION" } } } } }, "description": "UNSUPPORTED_API_VERSION" }, "405": { "content": { "application/problem+json": { "examples": { "METHOD_NOT_ALLOWED": { "summary": "METHOD_NOT_ALLOWED", "value": { "code": "METHOD_NOT_ALLOWED", "detail": "Method not allowed", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 405, "title": "Method not allowed", "type": "https://belfort.ai/docs/errors#METHOD_NOT_ALLOWED" } } } } }, "description": "METHOD_NOT_ALLOWED" }, "422": { "content": { "application/problem+json": { "examples": { "VALIDATION_ERROR": { "summary": "VALIDATION_ERROR", "value": { "code": "VALIDATION_ERROR", "detail": "Validation error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 422, "title": "Validation error", "type": "https://belfort.ai/docs/errors#VALIDATION_ERROR" } } } } }, "description": "VALIDATION_ERROR" }, "500": { "content": { "application/problem+json": { "examples": { "INTERNAL_ERROR": { "summary": "INTERNAL_ERROR", "value": { "code": "INTERNAL_ERROR", "detail": "Internal server error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 500, "title": "Internal server error", "type": "https://belfort.ai/docs/errors#INTERNAL_ERROR" } } } } }, "description": "INTERNAL_ERROR" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Error — documento de problema RFC 9457 (`application/problem+json`)." } }, "security": [ { "secretKey": [] } ], "summary": "Imponer un legal hold sobre un documento", "tags": [ "persons" ], "x-required-scope": "persons:write" } }, "/v1/persons/{person_id}/documents/{asset_id}/legal-hold/release": { "post": { "description": "Libera un asset de media: vuelve a quedar sujeto al TTL normal de retención, así que si su `retentionUntil` ya venció lo elimina el siguiente barrido. `reason` es obligatorio; `legalBasis`, opcional. Siempre inserta una fila `release` nueva en el historial append-only. Requiere scope `persons:write`.", "operationId": "releaseDocumentLegalHold", "parameters": [ { "in": "path", "name": "person_id", "required": true, "schema": { "title": "Person Id", "type": "string" } }, { "in": "path", "name": "asset_id", "required": true, "schema": { "title": "Asset Id", "type": "string" } }, { "in": "header", "name": "Belfort-Version", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Belfort-Version" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MediaAssetLegalHoldReleaseRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MediaAssetLegalHoldItem" } } }, "description": "Successful Response" }, "400": { "content": { "application/problem+json": { "examples": { "UNSUPPORTED_API_VERSION": { "summary": "UNSUPPORTED_API_VERSION", "value": { "code": "UNSUPPORTED_API_VERSION", "detail": "Unsupported API version", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 400, "title": "Unsupported API version", "type": "https://belfort.ai/docs/errors#UNSUPPORTED_API_VERSION" } } } } }, "description": "UNSUPPORTED_API_VERSION" }, "405": { "content": { "application/problem+json": { "examples": { "METHOD_NOT_ALLOWED": { "summary": "METHOD_NOT_ALLOWED", "value": { "code": "METHOD_NOT_ALLOWED", "detail": "Method not allowed", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 405, "title": "Method not allowed", "type": "https://belfort.ai/docs/errors#METHOD_NOT_ALLOWED" } } } } }, "description": "METHOD_NOT_ALLOWED" }, "422": { "content": { "application/problem+json": { "examples": { "VALIDATION_ERROR": { "summary": "VALIDATION_ERROR", "value": { "code": "VALIDATION_ERROR", "detail": "Validation error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 422, "title": "Validation error", "type": "https://belfort.ai/docs/errors#VALIDATION_ERROR" } } } } }, "description": "VALIDATION_ERROR" }, "500": { "content": { "application/problem+json": { "examples": { "INTERNAL_ERROR": { "summary": "INTERNAL_ERROR", "value": { "code": "INTERNAL_ERROR", "detail": "Internal server error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 500, "title": "Internal server error", "type": "https://belfort.ai/docs/errors#INTERNAL_ERROR" } } } } }, "description": "INTERNAL_ERROR" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Error — documento de problema RFC 9457 (`application/problem+json`)." } }, "security": [ { "secretKey": [] } ], "summary": "Levantar el legal hold de un documento", "tags": [ "persons" ], "x-required-scope": "persons:write" } }, "/v1/persons/{person_id}/documents/{asset_id}/legal-holds": { "get": { "description": "Cursor list del historial append-only de un asset, en orden descendente por `createdAt`. El estado vigente lo dice `data[0]`: un `action='set'` sin un `release` posterior más reciente significa que el documento sigue bloqueado. Requiere scope `persons:read`.", "operationId": "listDocumentLegalHolds", "parameters": [ { "in": "path", "name": "person_id", "required": true, "schema": { "title": "Person Id", "type": "string" } }, { "in": "path", "name": "asset_id", "required": true, "schema": { "title": "Asset Id", "type": "string" } }, { "description": "Tamaño de página (1–100).", "in": "query", "name": "limit", "required": false, "schema": { "default": 20, "description": "Tamaño de página (1–100).", "title": "Limit", "type": "integer" } }, { "description": "`nextCursor` de la página anterior. Excluyente con `endingBefore`.", "in": "query", "name": "startingAfter", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "`nextCursor` de la página anterior. Excluyente con `endingBefore`.", "title": "Startingafter" } }, { "description": "`previousCursor` de la página actual. Excluyente con `startingAfter`.", "in": "query", "name": "endingBefore", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "`previousCursor` de la página actual. Excluyente con `startingAfter`.", "title": "Endingbefore" } }, { "description": "Calcula `totalCount`. Cuesta un `COUNT(*)` sobre el filtro entero, así que está apagado por defecto: pídelo solo cuando vayas a enseñar el total.", "in": "query", "name": "includeTotal", "required": false, "schema": { "default": false, "description": "Calcula `totalCount`. Cuesta un `COUNT(*)` sobre el filtro entero, así que está apagado por defecto: pídelo solo cuando vayas a enseñar el total.", "title": "Includetotal", "type": "boolean" } }, { "in": "header", "name": "Belfort-Version", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Belfort-Version" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListEnvelope_MediaAssetLegalHoldItem_" } } }, "description": "Successful Response" }, "400": { "content": { "application/problem+json": { "examples": { "UNSUPPORTED_API_VERSION": { "summary": "UNSUPPORTED_API_VERSION", "value": { "code": "UNSUPPORTED_API_VERSION", "detail": "Unsupported API version", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 400, "title": "Unsupported API version", "type": "https://belfort.ai/docs/errors#UNSUPPORTED_API_VERSION" } } } } }, "description": "UNSUPPORTED_API_VERSION" }, "405": { "content": { "application/problem+json": { "examples": { "METHOD_NOT_ALLOWED": { "summary": "METHOD_NOT_ALLOWED", "value": { "code": "METHOD_NOT_ALLOWED", "detail": "Method not allowed", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 405, "title": "Method not allowed", "type": "https://belfort.ai/docs/errors#METHOD_NOT_ALLOWED" } } } } }, "description": "METHOD_NOT_ALLOWED" }, "422": { "content": { "application/problem+json": { "examples": { "VALIDATION_ERROR": { "summary": "VALIDATION_ERROR", "value": { "code": "VALIDATION_ERROR", "detail": "Validation error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 422, "title": "Validation error", "type": "https://belfort.ai/docs/errors#VALIDATION_ERROR" } } } } }, "description": "VALIDATION_ERROR" }, "500": { "content": { "application/problem+json": { "examples": { "INTERNAL_ERROR": { "summary": "INTERNAL_ERROR", "value": { "code": "INTERNAL_ERROR", "detail": "Internal server error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 500, "title": "Internal server error", "type": "https://belfort.ai/docs/errors#INTERNAL_ERROR" } } } } }, "description": "INTERNAL_ERROR" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Error — documento de problema RFC 9457 (`application/problem+json`)." } }, "security": [ { "secretKey": [] } ], "summary": "Listar el historial de legal hold de un documento", "tags": [ "persons" ], "x-required-scope": "persons:read" } }, "/v1/persons/{person_id}/duplicates": { "get": { "description": "Candidatos a ser la misma persona, por coincidencia de CURP o correo. Sugiere; no fusiona nada.", "operationId": "listPersonDuplicates", "parameters": [ { "in": "path", "name": "person_id", "required": true, "schema": { "title": "Person Id", "type": "string" } }, { "in": "header", "name": "Belfort-Version", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Belfort-Version" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DuplicatesResponse" } } }, "description": "Successful Response" }, "400": { "content": { "application/problem+json": { "examples": { "UNSUPPORTED_API_VERSION": { "summary": "UNSUPPORTED_API_VERSION", "value": { "code": "UNSUPPORTED_API_VERSION", "detail": "Unsupported API version", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 400, "title": "Unsupported API version", "type": "https://belfort.ai/docs/errors#UNSUPPORTED_API_VERSION" } } } } }, "description": "UNSUPPORTED_API_VERSION" }, "405": { "content": { "application/problem+json": { "examples": { "METHOD_NOT_ALLOWED": { "summary": "METHOD_NOT_ALLOWED", "value": { "code": "METHOD_NOT_ALLOWED", "detail": "Method not allowed", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 405, "title": "Method not allowed", "type": "https://belfort.ai/docs/errors#METHOD_NOT_ALLOWED" } } } } }, "description": "METHOD_NOT_ALLOWED" }, "422": { "content": { "application/problem+json": { "examples": { "VALIDATION_ERROR": { "summary": "VALIDATION_ERROR", "value": { "code": "VALIDATION_ERROR", "detail": "Validation error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 422, "title": "Validation error", "type": "https://belfort.ai/docs/errors#VALIDATION_ERROR" } } } } }, "description": "VALIDATION_ERROR" }, "500": { "content": { "application/problem+json": { "examples": { "INTERNAL_ERROR": { "summary": "INTERNAL_ERROR", "value": { "code": "INTERNAL_ERROR", "detail": "Internal server error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 500, "title": "Internal server error", "type": "https://belfort.ai/docs/errors#INTERNAL_ERROR" } } } } }, "description": "INTERNAL_ERROR" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Error — documento de problema RFC 9457 (`application/problem+json`)." } }, "security": [ { "secretKey": [] } ], "summary": "Buscar duplicados", "tags": [ "persons" ], "x-required-scope": "persons:read" } }, "/v1/persons/{person_id}/export": { "post": { "description": "El derecho de acceso de ARCO: todo lo que Belfort guarda sobre esa persona, en un formato que puedes entregarle. Cuenta como revelado y queda auditado.", "operationId": "exportPerson", "parameters": [ { "in": "path", "name": "person_id", "required": true, "schema": { "title": "Person Id", "type": "string" } }, { "in": "header", "name": "Belfort-Version", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Belfort-Version" } } ], "requestBody": { "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/PersonExportRequest" }, { "type": "null" } ], "title": "Body" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonExportBundle" } } }, "description": "Successful Response" }, "400": { "content": { "application/problem+json": { "examples": { "UNSUPPORTED_API_VERSION": { "summary": "UNSUPPORTED_API_VERSION", "value": { "code": "UNSUPPORTED_API_VERSION", "detail": "Unsupported API version", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 400, "title": "Unsupported API version", "type": "https://belfort.ai/docs/errors#UNSUPPORTED_API_VERSION" } } } } }, "description": "UNSUPPORTED_API_VERSION" }, "405": { "content": { "application/problem+json": { "examples": { "METHOD_NOT_ALLOWED": { "summary": "METHOD_NOT_ALLOWED", "value": { "code": "METHOD_NOT_ALLOWED", "detail": "Method not allowed", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 405, "title": "Method not allowed", "type": "https://belfort.ai/docs/errors#METHOD_NOT_ALLOWED" } } } } }, "description": "METHOD_NOT_ALLOWED" }, "422": { "content": { "application/problem+json": { "examples": { "VALIDATION_ERROR": { "summary": "VALIDATION_ERROR", "value": { "code": "VALIDATION_ERROR", "detail": "Validation error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 422, "title": "Validation error", "type": "https://belfort.ai/docs/errors#VALIDATION_ERROR" } } } } }, "description": "VALIDATION_ERROR" }, "500": { "content": { "application/problem+json": { "examples": { "INTERNAL_ERROR": { "summary": "INTERNAL_ERROR", "value": { "code": "INTERNAL_ERROR", "detail": "Internal server error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 500, "title": "Internal server error", "type": "https://belfort.ai/docs/errors#INTERNAL_ERROR" } } } } }, "description": "INTERNAL_ERROR" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Error — documento de problema RFC 9457 (`application/problem+json`)." } }, "security": [ { "secretKey": [] } ], "summary": "Exportar los datos de una persona", "tags": [ "persons" ], "x-required-scope": "persons:read_pii" } }, "/v1/persons/{person_id}/fields": { "get": { "description": "Responde \"¿ya tengo la CURP de esta persona?\" sin descifrar nada. Es la forma correcta de decidir si hace falta pedir un dato más: preguntar por presencia no es acceder a PII.", "operationId": "getPersonFields", "parameters": [ { "in": "path", "name": "person_id", "required": true, "schema": { "title": "Person Id", "type": "string" } }, { "in": "header", "name": "Belfort-Version", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Belfort-Version" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonFieldsResponse" } } }, "description": "Successful Response" }, "400": { "content": { "application/problem+json": { "examples": { "UNSUPPORTED_API_VERSION": { "summary": "UNSUPPORTED_API_VERSION", "value": { "code": "UNSUPPORTED_API_VERSION", "detail": "Unsupported API version", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 400, "title": "Unsupported API version", "type": "https://belfort.ai/docs/errors#UNSUPPORTED_API_VERSION" } } } } }, "description": "UNSUPPORTED_API_VERSION" }, "405": { "content": { "application/problem+json": { "examples": { "METHOD_NOT_ALLOWED": { "summary": "METHOD_NOT_ALLOWED", "value": { "code": "METHOD_NOT_ALLOWED", "detail": "Method not allowed", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 405, "title": "Method not allowed", "type": "https://belfort.ai/docs/errors#METHOD_NOT_ALLOWED" } } } } }, "description": "METHOD_NOT_ALLOWED" }, "422": { "content": { "application/problem+json": { "examples": { "VALIDATION_ERROR": { "summary": "VALIDATION_ERROR", "value": { "code": "VALIDATION_ERROR", "detail": "Validation error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 422, "title": "Validation error", "type": "https://belfort.ai/docs/errors#VALIDATION_ERROR" } } } } }, "description": "VALIDATION_ERROR" }, "500": { "content": { "application/problem+json": { "examples": { "INTERNAL_ERROR": { "summary": "INTERNAL_ERROR", "value": { "code": "INTERNAL_ERROR", "detail": "Internal server error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 500, "title": "Internal server error", "type": "https://belfort.ai/docs/errors#INTERNAL_ERROR" } } } } }, "description": "INTERNAL_ERROR" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Error — documento de problema RFC 9457 (`application/problem+json`)." } }, "security": [ { "secretKey": [] } ], "summary": "Ver qué campos existen", "tags": [ "persons" ], "x-required-scope": "persons:read" } }, "/v1/persons/{person_id}/forget": { "post": { "description": "El derecho de cancelación. `block` deja los datos inaccesibles pero conservados —que es lo que exige el periodo de bloqueo previo a la supresión— y `purge` los destruye. Va por POST y con el motivo en el cuerpo: el motivo es un dato personal y no puede acabar en la URL de todos los registros por los que pasa la petición.", "operationId": "forgetPerson", "parameters": [ { "in": "path", "name": "person_id", "required": true, "schema": { "title": "Person Id", "type": "string" } }, { "in": "header", "name": "Belfort-Version", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Belfort-Version" } } ], "requestBody": { "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/PersonForgetRequest" }, { "type": "null" } ], "title": "Body" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonForgetResponse" } } }, "description": "Successful Response" }, "400": { "content": { "application/problem+json": { "examples": { "UNSUPPORTED_API_VERSION": { "summary": "UNSUPPORTED_API_VERSION", "value": { "code": "UNSUPPORTED_API_VERSION", "detail": "Unsupported API version", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 400, "title": "Unsupported API version", "type": "https://belfort.ai/docs/errors#UNSUPPORTED_API_VERSION" } } } } }, "description": "UNSUPPORTED_API_VERSION" }, "405": { "content": { "application/problem+json": { "examples": { "METHOD_NOT_ALLOWED": { "summary": "METHOD_NOT_ALLOWED", "value": { "code": "METHOD_NOT_ALLOWED", "detail": "Method not allowed", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 405, "title": "Method not allowed", "type": "https://belfort.ai/docs/errors#METHOD_NOT_ALLOWED" } } } } }, "description": "METHOD_NOT_ALLOWED" }, "422": { "content": { "application/problem+json": { "examples": { "VALIDATION_ERROR": { "summary": "VALIDATION_ERROR", "value": { "code": "VALIDATION_ERROR", "detail": "Validation error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 422, "title": "Validation error", "type": "https://belfort.ai/docs/errors#VALIDATION_ERROR" } } } } }, "description": "VALIDATION_ERROR" }, "500": { "content": { "application/problem+json": { "examples": { "INTERNAL_ERROR": { "summary": "INTERNAL_ERROR", "value": { "code": "INTERNAL_ERROR", "detail": "Internal server error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 500, "title": "Internal server error", "type": "https://belfort.ai/docs/errors#INTERNAL_ERROR" } } } } }, "description": "INTERNAL_ERROR" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Error — documento de problema RFC 9457 (`application/problem+json`)." } }, "security": [ { "secretKey": [] } ], "summary": "Bloquear o suprimir una persona", "tags": [ "persons" ], "x-required-scope": "persons:redact" } }, "/v1/persons/{person_id}/grants": { "get": { "description": "Qué aplicaciones tuyas pueden ver a esta persona. Es el control de acceso entre tus propios productos.", "operationId": "listPersonGrants", "parameters": [ { "in": "path", "name": "person_id", "required": true, "schema": { "title": "Person Id", "type": "string" } }, { "description": "Tamaño de página (1–100).", "in": "query", "name": "limit", "required": false, "schema": { "default": 20, "description": "Tamaño de página (1–100).", "title": "Limit", "type": "integer" } }, { "description": "`nextCursor` de la página anterior. Excluyente con `endingBefore`.", "in": "query", "name": "startingAfter", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "`nextCursor` de la página anterior. Excluyente con `endingBefore`.", "title": "Startingafter" } }, { "description": "`previousCursor` de la página actual. Excluyente con `startingAfter`.", "in": "query", "name": "endingBefore", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "`previousCursor` de la página actual. Excluyente con `startingAfter`.", "title": "Endingbefore" } }, { "description": "Calcula `totalCount`. Cuesta un `COUNT(*)` sobre el filtro entero, así que está apagado por defecto: pídelo solo cuando vayas a enseñar el total.", "in": "query", "name": "includeTotal", "required": false, "schema": { "default": false, "description": "Calcula `totalCount`. Cuesta un `COUNT(*)` sobre el filtro entero, así que está apagado por defecto: pídelo solo cuando vayas a enseñar el total.", "title": "Includetotal", "type": "boolean" } }, { "in": "header", "name": "Belfort-Version", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Belfort-Version" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListEnvelope_GrantItem_" } } }, "description": "Successful Response" }, "400": { "content": { "application/problem+json": { "examples": { "UNSUPPORTED_API_VERSION": { "summary": "UNSUPPORTED_API_VERSION", "value": { "code": "UNSUPPORTED_API_VERSION", "detail": "Unsupported API version", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 400, "title": "Unsupported API version", "type": "https://belfort.ai/docs/errors#UNSUPPORTED_API_VERSION" } } } } }, "description": "UNSUPPORTED_API_VERSION" }, "405": { "content": { "application/problem+json": { "examples": { "METHOD_NOT_ALLOWED": { "summary": "METHOD_NOT_ALLOWED", "value": { "code": "METHOD_NOT_ALLOWED", "detail": "Method not allowed", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 405, "title": "Method not allowed", "type": "https://belfort.ai/docs/errors#METHOD_NOT_ALLOWED" } } } } }, "description": "METHOD_NOT_ALLOWED" }, "422": { "content": { "application/problem+json": { "examples": { "VALIDATION_ERROR": { "summary": "VALIDATION_ERROR", "value": { "code": "VALIDATION_ERROR", "detail": "Validation error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 422, "title": "Validation error", "type": "https://belfort.ai/docs/errors#VALIDATION_ERROR" } } } } }, "description": "VALIDATION_ERROR" }, "500": { "content": { "application/problem+json": { "examples": { "INTERNAL_ERROR": { "summary": "INTERNAL_ERROR", "value": { "code": "INTERNAL_ERROR", "detail": "Internal server error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 500, "title": "Internal server error", "type": "https://belfort.ai/docs/errors#INTERNAL_ERROR" } } } } }, "description": "INTERNAL_ERROR" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Error — documento de problema RFC 9457 (`application/problem+json`)." } }, "security": [ { "secretKey": [] } ], "summary": "Listar cesiones", "tags": [ "persons" ], "x-required-scope": "persons:read" }, "post": { "description": "Crea o reemplaza la cesión para una aplicación. Repetirla no acumula cesiones: sustituye la anterior.", "operationId": "createPersonGrant", "parameters": [ { "in": "path", "name": "person_id", "required": true, "schema": { "title": "Person Id", "type": "string" } }, { "in": "header", "name": "Belfort-Version", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Belfort-Version" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GrantCreateRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GrantItem" } } }, "description": "Successful Response" }, "400": { "content": { "application/problem+json": { "examples": { "UNSUPPORTED_API_VERSION": { "summary": "UNSUPPORTED_API_VERSION", "value": { "code": "UNSUPPORTED_API_VERSION", "detail": "Unsupported API version", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 400, "title": "Unsupported API version", "type": "https://belfort.ai/docs/errors#UNSUPPORTED_API_VERSION" } } } } }, "description": "UNSUPPORTED_API_VERSION" }, "405": { "content": { "application/problem+json": { "examples": { "METHOD_NOT_ALLOWED": { "summary": "METHOD_NOT_ALLOWED", "value": { "code": "METHOD_NOT_ALLOWED", "detail": "Method not allowed", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 405, "title": "Method not allowed", "type": "https://belfort.ai/docs/errors#METHOD_NOT_ALLOWED" } } } } }, "description": "METHOD_NOT_ALLOWED" }, "422": { "content": { "application/problem+json": { "examples": { "VALIDATION_ERROR": { "summary": "VALIDATION_ERROR", "value": { "code": "VALIDATION_ERROR", "detail": "Validation error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 422, "title": "Validation error", "type": "https://belfort.ai/docs/errors#VALIDATION_ERROR" } } } } }, "description": "VALIDATION_ERROR" }, "500": { "content": { "application/problem+json": { "examples": { "INTERNAL_ERROR": { "summary": "INTERNAL_ERROR", "value": { "code": "INTERNAL_ERROR", "detail": "Internal server error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 500, "title": "Internal server error", "type": "https://belfort.ai/docs/errors#INTERNAL_ERROR" } } } } }, "description": "INTERNAL_ERROR" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Error — documento de problema RFC 9457 (`application/problem+json`)." } }, "security": [ { "secretKey": [] } ], "summary": "Conceder acceso a una aplicación", "tags": [ "persons" ], "x-required-scope": "persons:write" } }, "/v1/persons/{person_id}/grants/{grant_id}/revoke": { "post": { "description": "Idempotente, como el resto de revocaciones del vault.", "operationId": "revokePersonGrant", "parameters": [ { "in": "path", "name": "person_id", "required": true, "schema": { "title": "Person Id", "type": "string" } }, { "in": "path", "name": "grant_id", "required": true, "schema": { "title": "Grant Id", "type": "string" } }, { "in": "header", "name": "Belfort-Version", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Belfort-Version" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GrantItem" } } }, "description": "Successful Response" }, "400": { "content": { "application/problem+json": { "examples": { "UNSUPPORTED_API_VERSION": { "summary": "UNSUPPORTED_API_VERSION", "value": { "code": "UNSUPPORTED_API_VERSION", "detail": "Unsupported API version", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 400, "title": "Unsupported API version", "type": "https://belfort.ai/docs/errors#UNSUPPORTED_API_VERSION" } } } } }, "description": "UNSUPPORTED_API_VERSION" }, "405": { "content": { "application/problem+json": { "examples": { "METHOD_NOT_ALLOWED": { "summary": "METHOD_NOT_ALLOWED", "value": { "code": "METHOD_NOT_ALLOWED", "detail": "Method not allowed", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 405, "title": "Method not allowed", "type": "https://belfort.ai/docs/errors#METHOD_NOT_ALLOWED" } } } } }, "description": "METHOD_NOT_ALLOWED" }, "422": { "content": { "application/problem+json": { "examples": { "VALIDATION_ERROR": { "summary": "VALIDATION_ERROR", "value": { "code": "VALIDATION_ERROR", "detail": "Validation error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 422, "title": "Validation error", "type": "https://belfort.ai/docs/errors#VALIDATION_ERROR" } } } } }, "description": "VALIDATION_ERROR" }, "500": { "content": { "application/problem+json": { "examples": { "INTERNAL_ERROR": { "summary": "INTERNAL_ERROR", "value": { "code": "INTERNAL_ERROR", "detail": "Internal server error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 500, "title": "Internal server error", "type": "https://belfort.ai/docs/errors#INTERNAL_ERROR" } } } } }, "description": "INTERNAL_ERROR" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Error — documento de problema RFC 9457 (`application/problem+json`)." } }, "security": [ { "secretKey": [] } ], "summary": "Revocar una cesión", "tags": [ "persons" ], "x-required-scope": "persons:write" } }, "/v1/persons/{person_id}/integrity": { "post": { "description": "Le mandas el hash que tú calculaste de un dato y te dice si coincide con el que hay guardado, sin descifrar nada ni revelarte el valor. Sirve para confirmar que tu copia y la nuestra siguen siendo la misma.", "operationId": "checkPersonIntegrity", "parameters": [ { "in": "path", "name": "person_id", "required": true, "schema": { "title": "Person Id", "type": "string" } }, { "in": "header", "name": "Belfort-Version", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Belfort-Version" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrityRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrityResponse" } } }, "description": "Successful Response" }, "400": { "content": { "application/problem+json": { "examples": { "UNSUPPORTED_API_VERSION": { "summary": "UNSUPPORTED_API_VERSION", "value": { "code": "UNSUPPORTED_API_VERSION", "detail": "Unsupported API version", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 400, "title": "Unsupported API version", "type": "https://belfort.ai/docs/errors#UNSUPPORTED_API_VERSION" } } } } }, "description": "UNSUPPORTED_API_VERSION" }, "405": { "content": { "application/problem+json": { "examples": { "METHOD_NOT_ALLOWED": { "summary": "METHOD_NOT_ALLOWED", "value": { "code": "METHOD_NOT_ALLOWED", "detail": "Method not allowed", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 405, "title": "Method not allowed", "type": "https://belfort.ai/docs/errors#METHOD_NOT_ALLOWED" } } } } }, "description": "METHOD_NOT_ALLOWED" }, "422": { "content": { "application/problem+json": { "examples": { "VALIDATION_ERROR": { "summary": "VALIDATION_ERROR", "value": { "code": "VALIDATION_ERROR", "detail": "Validation error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 422, "title": "Validation error", "type": "https://belfort.ai/docs/errors#VALIDATION_ERROR" } } } } }, "description": "VALIDATION_ERROR" }, "500": { "content": { "application/problem+json": { "examples": { "INTERNAL_ERROR": { "summary": "INTERNAL_ERROR", "value": { "code": "INTERNAL_ERROR", "detail": "Internal server error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 500, "title": "Internal server error", "type": "https://belfort.ai/docs/errors#INTERNAL_ERROR" } } } } }, "description": "INTERNAL_ERROR" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Error — documento de problema RFC 9457 (`application/problem+json`)." } }, "security": [ { "secretKey": [] } ], "summary": "Comprobar la integridad de un campo", "tags": [ "persons" ], "x-required-scope": "persons:read_pii" } }, "/v1/persons/{person_id}/legal-hold": { "post": { "description": "Congela a la persona frente a cualquier supresión, incluida una solicitud ARCO, mientras dure un requerimiento de autoridad. Renueva si ya había una vigente.", "operationId": "setPersonLegalHold", "parameters": [ { "in": "path", "name": "person_id", "required": true, "schema": { "title": "Person Id", "type": "string" } }, { "in": "header", "name": "Belfort-Version", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Belfort-Version" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegalHoldSetRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegalHoldItem" } } }, "description": "Successful Response" }, "400": { "content": { "application/problem+json": { "examples": { "UNSUPPORTED_API_VERSION": { "summary": "UNSUPPORTED_API_VERSION", "value": { "code": "UNSUPPORTED_API_VERSION", "detail": "Unsupported API version", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 400, "title": "Unsupported API version", "type": "https://belfort.ai/docs/errors#UNSUPPORTED_API_VERSION" } } } } }, "description": "UNSUPPORTED_API_VERSION" }, "405": { "content": { "application/problem+json": { "examples": { "METHOD_NOT_ALLOWED": { "summary": "METHOD_NOT_ALLOWED", "value": { "code": "METHOD_NOT_ALLOWED", "detail": "Method not allowed", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 405, "title": "Method not allowed", "type": "https://belfort.ai/docs/errors#METHOD_NOT_ALLOWED" } } } } }, "description": "METHOD_NOT_ALLOWED" }, "422": { "content": { "application/problem+json": { "examples": { "VALIDATION_ERROR": { "summary": "VALIDATION_ERROR", "value": { "code": "VALIDATION_ERROR", "detail": "Validation error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 422, "title": "Validation error", "type": "https://belfort.ai/docs/errors#VALIDATION_ERROR" } } } } }, "description": "VALIDATION_ERROR" }, "500": { "content": { "application/problem+json": { "examples": { "INTERNAL_ERROR": { "summary": "INTERNAL_ERROR", "value": { "code": "INTERNAL_ERROR", "detail": "Internal server error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 500, "title": "Internal server error", "type": "https://belfort.ai/docs/errors#INTERNAL_ERROR" } } } } }, "description": "INTERNAL_ERROR" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Error — documento de problema RFC 9457 (`application/problem+json`)." } }, "security": [ { "secretKey": [] } ], "summary": "Imponer retención legal", "tags": [ "persons" ], "x-required-scope": "persons:write" } }, "/v1/persons/{person_id}/legal-hold/release": { "post": { "description": "Devuelve a la persona al régimen normal de conservación.", "operationId": "releasePersonLegalHold", "parameters": [ { "in": "path", "name": "person_id", "required": true, "schema": { "title": "Person Id", "type": "string" } }, { "in": "header", "name": "Belfort-Version", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Belfort-Version" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegalHoldReleaseRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegalHoldItem" } } }, "description": "Successful Response" }, "400": { "content": { "application/problem+json": { "examples": { "UNSUPPORTED_API_VERSION": { "summary": "UNSUPPORTED_API_VERSION", "value": { "code": "UNSUPPORTED_API_VERSION", "detail": "Unsupported API version", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 400, "title": "Unsupported API version", "type": "https://belfort.ai/docs/errors#UNSUPPORTED_API_VERSION" } } } } }, "description": "UNSUPPORTED_API_VERSION" }, "405": { "content": { "application/problem+json": { "examples": { "METHOD_NOT_ALLOWED": { "summary": "METHOD_NOT_ALLOWED", "value": { "code": "METHOD_NOT_ALLOWED", "detail": "Method not allowed", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 405, "title": "Method not allowed", "type": "https://belfort.ai/docs/errors#METHOD_NOT_ALLOWED" } } } } }, "description": "METHOD_NOT_ALLOWED" }, "422": { "content": { "application/problem+json": { "examples": { "VALIDATION_ERROR": { "summary": "VALIDATION_ERROR", "value": { "code": "VALIDATION_ERROR", "detail": "Validation error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 422, "title": "Validation error", "type": "https://belfort.ai/docs/errors#VALIDATION_ERROR" } } } } }, "description": "VALIDATION_ERROR" }, "500": { "content": { "application/problem+json": { "examples": { "INTERNAL_ERROR": { "summary": "INTERNAL_ERROR", "value": { "code": "INTERNAL_ERROR", "detail": "Internal server error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 500, "title": "Internal server error", "type": "https://belfort.ai/docs/errors#INTERNAL_ERROR" } } } } }, "description": "INTERNAL_ERROR" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Error — documento de problema RFC 9457 (`application/problem+json`)." } }, "security": [ { "secretKey": [] } ], "summary": "Levantar la retención legal", "tags": [ "persons" ], "x-required-scope": "persons:write" } }, "/v1/persons/{person_id}/legal-holds": { "get": { "description": "Append-only y en orden descendente: una retención levantada no se borra del historial, porque el historial es justo lo que se exhibe ante la autoridad.", "operationId": "listPersonLegalHolds", "parameters": [ { "in": "path", "name": "person_id", "required": true, "schema": { "title": "Person Id", "type": "string" } }, { "description": "Tamaño de página (1–100).", "in": "query", "name": "limit", "required": false, "schema": { "default": 20, "description": "Tamaño de página (1–100).", "title": "Limit", "type": "integer" } }, { "description": "`nextCursor` de la página anterior. Excluyente con `endingBefore`.", "in": "query", "name": "startingAfter", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "`nextCursor` de la página anterior. Excluyente con `endingBefore`.", "title": "Startingafter" } }, { "description": "`previousCursor` de la página actual. Excluyente con `startingAfter`.", "in": "query", "name": "endingBefore", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "`previousCursor` de la página actual. Excluyente con `startingAfter`.", "title": "Endingbefore" } }, { "description": "Calcula `totalCount`. Cuesta un `COUNT(*)` sobre el filtro entero, así que está apagado por defecto: pídelo solo cuando vayas a enseñar el total.", "in": "query", "name": "includeTotal", "required": false, "schema": { "default": false, "description": "Calcula `totalCount`. Cuesta un `COUNT(*)` sobre el filtro entero, así que está apagado por defecto: pídelo solo cuando vayas a enseñar el total.", "title": "Includetotal", "type": "boolean" } }, { "in": "header", "name": "Belfort-Version", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Belfort-Version" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListEnvelope_LegalHoldItem_" } } }, "description": "Successful Response" }, "400": { "content": { "application/problem+json": { "examples": { "UNSUPPORTED_API_VERSION": { "summary": "UNSUPPORTED_API_VERSION", "value": { "code": "UNSUPPORTED_API_VERSION", "detail": "Unsupported API version", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 400, "title": "Unsupported API version", "type": "https://belfort.ai/docs/errors#UNSUPPORTED_API_VERSION" } } } } }, "description": "UNSUPPORTED_API_VERSION" }, "405": { "content": { "application/problem+json": { "examples": { "METHOD_NOT_ALLOWED": { "summary": "METHOD_NOT_ALLOWED", "value": { "code": "METHOD_NOT_ALLOWED", "detail": "Method not allowed", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 405, "title": "Method not allowed", "type": "https://belfort.ai/docs/errors#METHOD_NOT_ALLOWED" } } } } }, "description": "METHOD_NOT_ALLOWED" }, "422": { "content": { "application/problem+json": { "examples": { "VALIDATION_ERROR": { "summary": "VALIDATION_ERROR", "value": { "code": "VALIDATION_ERROR", "detail": "Validation error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 422, "title": "Validation error", "type": "https://belfort.ai/docs/errors#VALIDATION_ERROR" } } } } }, "description": "VALIDATION_ERROR" }, "500": { "content": { "application/problem+json": { "examples": { "INTERNAL_ERROR": { "summary": "INTERNAL_ERROR", "value": { "code": "INTERNAL_ERROR", "detail": "Internal server error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 500, "title": "Internal server error", "type": "https://belfort.ai/docs/errors#INTERNAL_ERROR" } } } } }, "description": "INTERNAL_ERROR" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Error — documento de problema RFC 9457 (`application/problem+json`)." } }, "security": [ { "secretKey": [] } ], "summary": "Historial de retenciones legales", "tags": [ "persons" ], "x-required-scope": "persons:read" } }, "/v1/persons/{person_id}/reauth-face": { "post": { "description": "Cotejo uno a uno contra el rostro ya verificado de la persona. Sirve para confirmar que quien vuelve es la misma persona, sin repetir la verificación documental completa.", "operationId": "reauthPersonFace", "parameters": [ { "in": "path", "name": "person_id", "required": true, "schema": { "title": "Person Id", "type": "string" } }, { "in": "header", "name": "Belfort-Version", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Belfort-Version" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReauthFaceRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReauthFaceResult" } } }, "description": "Successful Response" }, "400": { "content": { "application/problem+json": { "examples": { "UNSUPPORTED_API_VERSION": { "summary": "UNSUPPORTED_API_VERSION", "value": { "code": "UNSUPPORTED_API_VERSION", "detail": "Unsupported API version", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 400, "title": "Unsupported API version", "type": "https://belfort.ai/docs/errors#UNSUPPORTED_API_VERSION" } } } } }, "description": "UNSUPPORTED_API_VERSION" }, "405": { "content": { "application/problem+json": { "examples": { "METHOD_NOT_ALLOWED": { "summary": "METHOD_NOT_ALLOWED", "value": { "code": "METHOD_NOT_ALLOWED", "detail": "Method not allowed", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 405, "title": "Method not allowed", "type": "https://belfort.ai/docs/errors#METHOD_NOT_ALLOWED" } } } } }, "description": "METHOD_NOT_ALLOWED" }, "422": { "content": { "application/problem+json": { "examples": { "VALIDATION_ERROR": { "summary": "VALIDATION_ERROR", "value": { "code": "VALIDATION_ERROR", "detail": "Validation error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 422, "title": "Validation error", "type": "https://belfort.ai/docs/errors#VALIDATION_ERROR" } } } } }, "description": "VALIDATION_ERROR" }, "500": { "content": { "application/problem+json": { "examples": { "INTERNAL_ERROR": { "summary": "INTERNAL_ERROR", "value": { "code": "INTERNAL_ERROR", "detail": "Internal server error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 500, "title": "Internal server error", "type": "https://belfort.ai/docs/errors#INTERNAL_ERROR" } } } } }, "description": "INTERNAL_ERROR" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Error — documento de problema RFC 9457 (`application/problem+json`)." } }, "security": [ { "secretKey": [] } ], "summary": "Re-autenticar por rostro", "tags": [ "persons" ], "x-required-scope": "persons:read_pii" } }, "/v1/persons/{person_id}/verification-sessions": { "get": { "description": "Todas las veces que esta persona ha pasado por el motor de identidad, de la más reciente a la más antigua.", "operationId": "listPersonSessions", "parameters": [ { "in": "path", "name": "person_id", "required": true, "schema": { "title": "Person Id", "type": "string" } }, { "description": "Tamaño de página (1–100).", "in": "query", "name": "limit", "required": false, "schema": { "default": 20, "description": "Tamaño de página (1–100).", "title": "Limit", "type": "integer" } }, { "description": "`nextCursor` de la página anterior. Excluyente con `endingBefore`.", "in": "query", "name": "startingAfter", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "`nextCursor` de la página anterior. Excluyente con `endingBefore`.", "title": "Startingafter" } }, { "description": "`previousCursor` de la página actual. Excluyente con `startingAfter`.", "in": "query", "name": "endingBefore", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "`previousCursor` de la página actual. Excluyente con `startingAfter`.", "title": "Endingbefore" } }, { "description": "Calcula `totalCount`. Cuesta un `COUNT(*)` sobre el filtro entero, así que está apagado por defecto: pídelo solo cuando vayas a enseñar el total.", "in": "query", "name": "includeTotal", "required": false, "schema": { "default": false, "description": "Calcula `totalCount`. Cuesta un `COUNT(*)` sobre el filtro entero, así que está apagado por defecto: pídelo solo cuando vayas a enseñar el total.", "title": "Includetotal", "type": "boolean" } }, { "in": "header", "name": "Belfort-Version", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Belfort-Version" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListEnvelope_PersonVerificationSessionItem_" } } }, "description": "Successful Response" }, "400": { "content": { "application/problem+json": { "examples": { "UNSUPPORTED_API_VERSION": { "summary": "UNSUPPORTED_API_VERSION", "value": { "code": "UNSUPPORTED_API_VERSION", "detail": "Unsupported API version", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 400, "title": "Unsupported API version", "type": "https://belfort.ai/docs/errors#UNSUPPORTED_API_VERSION" } } } } }, "description": "UNSUPPORTED_API_VERSION" }, "405": { "content": { "application/problem+json": { "examples": { "METHOD_NOT_ALLOWED": { "summary": "METHOD_NOT_ALLOWED", "value": { "code": "METHOD_NOT_ALLOWED", "detail": "Method not allowed", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 405, "title": "Method not allowed", "type": "https://belfort.ai/docs/errors#METHOD_NOT_ALLOWED" } } } } }, "description": "METHOD_NOT_ALLOWED" }, "422": { "content": { "application/problem+json": { "examples": { "VALIDATION_ERROR": { "summary": "VALIDATION_ERROR", "value": { "code": "VALIDATION_ERROR", "detail": "Validation error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 422, "title": "Validation error", "type": "https://belfort.ai/docs/errors#VALIDATION_ERROR" } } } } }, "description": "VALIDATION_ERROR" }, "500": { "content": { "application/problem+json": { "examples": { "INTERNAL_ERROR": { "summary": "INTERNAL_ERROR", "value": { "code": "INTERNAL_ERROR", "detail": "Internal server error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 500, "title": "Internal server error", "type": "https://belfort.ai/docs/errors#INTERNAL_ERROR" } } } } }, "description": "INTERNAL_ERROR" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Error — documento de problema RFC 9457 (`application/problem+json`)." } }, "security": [ { "secretKey": [] } ], "summary": "Listar verificaciones de la persona", "tags": [ "persons" ], "x-required-scope": "persons:read" } }, "/v1/review/cases/{case_id}": { "get": { "description": "Todo lo que el revisor necesita: PII descifrada, media accesible y la cronología. **Cada consulta descifra y se audita** — no lo uses para listar.", "operationId": "reviewCaseDetail", "parameters": [ { "in": "path", "name": "case_id", "required": true, "schema": { "title": "Case Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReviewCaseDetail" } } }, "description": "Successful Response" }, "400": { "content": { "application/problem+json": { "examples": { "UNSUPPORTED_API_VERSION": { "summary": "UNSUPPORTED_API_VERSION", "value": { "code": "UNSUPPORTED_API_VERSION", "detail": "Unsupported API version", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 400, "title": "Unsupported API version", "type": "https://belfort.ai/docs/errors#UNSUPPORTED_API_VERSION" } } } } }, "description": "UNSUPPORTED_API_VERSION" }, "405": { "content": { "application/problem+json": { "examples": { "METHOD_NOT_ALLOWED": { "summary": "METHOD_NOT_ALLOWED", "value": { "code": "METHOD_NOT_ALLOWED", "detail": "Method not allowed", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 405, "title": "Method not allowed", "type": "https://belfort.ai/docs/errors#METHOD_NOT_ALLOWED" } } } } }, "description": "METHOD_NOT_ALLOWED" }, "422": { "content": { "application/problem+json": { "examples": { "VALIDATION_ERROR": { "summary": "VALIDATION_ERROR", "value": { "code": "VALIDATION_ERROR", "detail": "Validation error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 422, "title": "Validation error", "type": "https://belfort.ai/docs/errors#VALIDATION_ERROR" } } } } }, "description": "VALIDATION_ERROR" }, "500": { "content": { "application/problem+json": { "examples": { "INTERNAL_ERROR": { "summary": "INTERNAL_ERROR", "value": { "code": "INTERNAL_ERROR", "detail": "Internal server error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 500, "title": "Internal server error", "type": "https://belfort.ai/docs/errors#INTERNAL_ERROR" } } } } }, "description": "INTERNAL_ERROR" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Error — documento de problema RFC 9457 (`application/problem+json`)." } }, "security": [ { "secretKey": [] } ], "summary": "Consultar un caso", "tags": [ "review" ], "x-required-scope": "review:read" } }, "/v1/review/cases/{case_id}/claim": { "post": { "description": "Te asigna el caso para que dos revisores no trabajen el mismo a la vez.", "operationId": "claimCase", "parameters": [ { "in": "path", "name": "case_id", "required": true, "schema": { "title": "Case Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClaimResult" } } }, "description": "Successful Response" }, "400": { "content": { "application/problem+json": { "examples": { "UNSUPPORTED_API_VERSION": { "summary": "UNSUPPORTED_API_VERSION", "value": { "code": "UNSUPPORTED_API_VERSION", "detail": "Unsupported API version", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 400, "title": "Unsupported API version", "type": "https://belfort.ai/docs/errors#UNSUPPORTED_API_VERSION" } } } } }, "description": "UNSUPPORTED_API_VERSION" }, "405": { "content": { "application/problem+json": { "examples": { "METHOD_NOT_ALLOWED": { "summary": "METHOD_NOT_ALLOWED", "value": { "code": "METHOD_NOT_ALLOWED", "detail": "Method not allowed", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 405, "title": "Method not allowed", "type": "https://belfort.ai/docs/errors#METHOD_NOT_ALLOWED" } } } } }, "description": "METHOD_NOT_ALLOWED" }, "422": { "content": { "application/problem+json": { "examples": { "VALIDATION_ERROR": { "summary": "VALIDATION_ERROR", "value": { "code": "VALIDATION_ERROR", "detail": "Validation error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 422, "title": "Validation error", "type": "https://belfort.ai/docs/errors#VALIDATION_ERROR" } } } } }, "description": "VALIDATION_ERROR" }, "500": { "content": { "application/problem+json": { "examples": { "INTERNAL_ERROR": { "summary": "INTERNAL_ERROR", "value": { "code": "INTERNAL_ERROR", "detail": "Internal server error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 500, "title": "Internal server error", "type": "https://belfort.ai/docs/errors#INTERNAL_ERROR" } } } } }, "description": "INTERNAL_ERROR" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Error — documento de problema RFC 9457 (`application/problem+json`)." } }, "security": [ { "secretKey": [] } ], "summary": "Reclamar un caso", "tags": [ "review" ], "x-required-scope": "review:write" } }, "/v1/review/cases/{case_id}/notes": { "post": { "description": "Nota a la bitácora del caso. No exige tenerlo reclamado: comentar es colaborativo, decidir no.", "operationId": "addCaseNote", "parameters": [ { "in": "path", "name": "case_id", "required": true, "schema": { "title": "Case Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NoteRequest" } } }, "required": true }, "responses": { "204": { "description": "Successful Response" }, "400": { "content": { "application/problem+json": { "examples": { "UNSUPPORTED_API_VERSION": { "summary": "UNSUPPORTED_API_VERSION", "value": { "code": "UNSUPPORTED_API_VERSION", "detail": "Unsupported API version", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 400, "title": "Unsupported API version", "type": "https://belfort.ai/docs/errors#UNSUPPORTED_API_VERSION" } } } } }, "description": "UNSUPPORTED_API_VERSION" }, "405": { "content": { "application/problem+json": { "examples": { "METHOD_NOT_ALLOWED": { "summary": "METHOD_NOT_ALLOWED", "value": { "code": "METHOD_NOT_ALLOWED", "detail": "Method not allowed", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 405, "title": "Method not allowed", "type": "https://belfort.ai/docs/errors#METHOD_NOT_ALLOWED" } } } } }, "description": "METHOD_NOT_ALLOWED" }, "422": { "content": { "application/problem+json": { "examples": { "VALIDATION_ERROR": { "summary": "VALIDATION_ERROR", "value": { "code": "VALIDATION_ERROR", "detail": "Validation error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 422, "title": "Validation error", "type": "https://belfort.ai/docs/errors#VALIDATION_ERROR" } } } } }, "description": "VALIDATION_ERROR" }, "500": { "content": { "application/problem+json": { "examples": { "INTERNAL_ERROR": { "summary": "INTERNAL_ERROR", "value": { "code": "INTERNAL_ERROR", "detail": "Internal server error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 500, "title": "Internal server error", "type": "https://belfort.ai/docs/errors#INTERNAL_ERROR" } } } } }, "description": "INTERNAL_ERROR" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Error — documento de problema RFC 9457 (`application/problem+json`)." } }, "security": [ { "secretKey": [] } ], "summary": "Añadir una nota", "tags": [ "review" ], "x-required-scope": "review:write" } }, "/v1/review/cases/{case_id}/reassign": { "post": { "description": "Pasa el caso a otro revisor de tu organización.", "operationId": "reassignCase", "parameters": [ { "in": "path", "name": "case_id", "required": true, "schema": { "title": "Case Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReassignRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClaimResult" } } }, "description": "Successful Response" }, "400": { "content": { "application/problem+json": { "examples": { "UNSUPPORTED_API_VERSION": { "summary": "UNSUPPORTED_API_VERSION", "value": { "code": "UNSUPPORTED_API_VERSION", "detail": "Unsupported API version", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 400, "title": "Unsupported API version", "type": "https://belfort.ai/docs/errors#UNSUPPORTED_API_VERSION" } } } } }, "description": "UNSUPPORTED_API_VERSION" }, "405": { "content": { "application/problem+json": { "examples": { "METHOD_NOT_ALLOWED": { "summary": "METHOD_NOT_ALLOWED", "value": { "code": "METHOD_NOT_ALLOWED", "detail": "Method not allowed", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 405, "title": "Method not allowed", "type": "https://belfort.ai/docs/errors#METHOD_NOT_ALLOWED" } } } } }, "description": "METHOD_NOT_ALLOWED" }, "422": { "content": { "application/problem+json": { "examples": { "VALIDATION_ERROR": { "summary": "VALIDATION_ERROR", "value": { "code": "VALIDATION_ERROR", "detail": "Validation error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 422, "title": "Validation error", "type": "https://belfort.ai/docs/errors#VALIDATION_ERROR" } } } } }, "description": "VALIDATION_ERROR" }, "500": { "content": { "application/problem+json": { "examples": { "INTERNAL_ERROR": { "summary": "INTERNAL_ERROR", "value": { "code": "INTERNAL_ERROR", "detail": "Internal server error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 500, "title": "Internal server error", "type": "https://belfort.ai/docs/errors#INTERNAL_ERROR" } } } } }, "description": "INTERNAL_ERROR" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Error — documento de problema RFC 9457 (`application/problem+json`)." } }, "security": [ { "secretKey": [] } ], "summary": "Reasignar un caso", "tags": [ "review" ], "x-required-scope": "review:write" } }, "/v1/review/cases/{case_id}/release": { "post": { "description": "Devuelve el caso a la cola sin resolverlo.", "operationId": "releaseCase", "parameters": [ { "in": "path", "name": "case_id", "required": true, "schema": { "title": "Case Id", "type": "string" } } ], "responses": { "204": { "description": "Successful Response" }, "400": { "content": { "application/problem+json": { "examples": { "UNSUPPORTED_API_VERSION": { "summary": "UNSUPPORTED_API_VERSION", "value": { "code": "UNSUPPORTED_API_VERSION", "detail": "Unsupported API version", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 400, "title": "Unsupported API version", "type": "https://belfort.ai/docs/errors#UNSUPPORTED_API_VERSION" } } } } }, "description": "UNSUPPORTED_API_VERSION" }, "405": { "content": { "application/problem+json": { "examples": { "METHOD_NOT_ALLOWED": { "summary": "METHOD_NOT_ALLOWED", "value": { "code": "METHOD_NOT_ALLOWED", "detail": "Method not allowed", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 405, "title": "Method not allowed", "type": "https://belfort.ai/docs/errors#METHOD_NOT_ALLOWED" } } } } }, "description": "METHOD_NOT_ALLOWED" }, "422": { "content": { "application/problem+json": { "examples": { "VALIDATION_ERROR": { "summary": "VALIDATION_ERROR", "value": { "code": "VALIDATION_ERROR", "detail": "Validation error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 422, "title": "Validation error", "type": "https://belfort.ai/docs/errors#VALIDATION_ERROR" } } } } }, "description": "VALIDATION_ERROR" }, "500": { "content": { "application/problem+json": { "examples": { "INTERNAL_ERROR": { "summary": "INTERNAL_ERROR", "value": { "code": "INTERNAL_ERROR", "detail": "Internal server error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 500, "title": "Internal server error", "type": "https://belfort.ai/docs/errors#INTERNAL_ERROR" } } } } }, "description": "INTERNAL_ERROR" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Error — documento de problema RFC 9457 (`application/problem+json`)." } }, "security": [ { "secretKey": [] } ], "summary": "Liberar un caso", "tags": [ "review" ], "x-required-scope": "review:write" } }, "/v1/review/cases/{case_id}/resolve": { "post": { "description": "Aprobar, rechazar, pedir más información o escalar. Si tu política exige doble aprobación, la primera resolución deja el caso a la espera del segundo par de ojos en vez de cerrarlo.", "operationId": "resolveCase", "parameters": [ { "in": "path", "name": "case_id", "required": true, "schema": { "title": "Case Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResolveRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResolveResult" } } }, "description": "Successful Response" }, "400": { "content": { "application/problem+json": { "examples": { "UNSUPPORTED_API_VERSION": { "summary": "UNSUPPORTED_API_VERSION", "value": { "code": "UNSUPPORTED_API_VERSION", "detail": "Unsupported API version", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 400, "title": "Unsupported API version", "type": "https://belfort.ai/docs/errors#UNSUPPORTED_API_VERSION" } } } } }, "description": "UNSUPPORTED_API_VERSION" }, "405": { "content": { "application/problem+json": { "examples": { "METHOD_NOT_ALLOWED": { "summary": "METHOD_NOT_ALLOWED", "value": { "code": "METHOD_NOT_ALLOWED", "detail": "Method not allowed", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 405, "title": "Method not allowed", "type": "https://belfort.ai/docs/errors#METHOD_NOT_ALLOWED" } } } } }, "description": "METHOD_NOT_ALLOWED" }, "422": { "content": { "application/problem+json": { "examples": { "VALIDATION_ERROR": { "summary": "VALIDATION_ERROR", "value": { "code": "VALIDATION_ERROR", "detail": "Validation error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 422, "title": "Validation error", "type": "https://belfort.ai/docs/errors#VALIDATION_ERROR" } } } } }, "description": "VALIDATION_ERROR" }, "500": { "content": { "application/problem+json": { "examples": { "INTERNAL_ERROR": { "summary": "INTERNAL_ERROR", "value": { "code": "INTERNAL_ERROR", "detail": "Internal server error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 500, "title": "Internal server error", "type": "https://belfort.ai/docs/errors#INTERNAL_ERROR" } } } } }, "description": "INTERNAL_ERROR" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Error — documento de problema RFC 9457 (`application/problem+json`)." } }, "security": [ { "secretKey": [] } ], "summary": "Resolver un caso", "tags": [ "review" ], "x-required-scope": "review:write" } }, "/v1/review/media/{media_id}": { "get": { "description": "Sirve el archivo al revisor autorizado, descifrándolo al vuelo.", "operationId": "getReviewMedia", "parameters": [ { "in": "path", "name": "media_id", "required": true, "schema": { "title": "Media Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response" }, "400": { "content": { "application/problem+json": { "examples": { "UNSUPPORTED_API_VERSION": { "summary": "UNSUPPORTED_API_VERSION", "value": { "code": "UNSUPPORTED_API_VERSION", "detail": "Unsupported API version", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 400, "title": "Unsupported API version", "type": "https://belfort.ai/docs/errors#UNSUPPORTED_API_VERSION" } } } } }, "description": "UNSUPPORTED_API_VERSION" }, "405": { "content": { "application/problem+json": { "examples": { "METHOD_NOT_ALLOWED": { "summary": "METHOD_NOT_ALLOWED", "value": { "code": "METHOD_NOT_ALLOWED", "detail": "Method not allowed", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 405, "title": "Method not allowed", "type": "https://belfort.ai/docs/errors#METHOD_NOT_ALLOWED" } } } } }, "description": "METHOD_NOT_ALLOWED" }, "422": { "content": { "application/problem+json": { "examples": { "VALIDATION_ERROR": { "summary": "VALIDATION_ERROR", "value": { "code": "VALIDATION_ERROR", "detail": "Validation error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 422, "title": "Validation error", "type": "https://belfort.ai/docs/errors#VALIDATION_ERROR" } } } } }, "description": "VALIDATION_ERROR" }, "500": { "content": { "application/problem+json": { "examples": { "INTERNAL_ERROR": { "summary": "INTERNAL_ERROR", "value": { "code": "INTERNAL_ERROR", "detail": "Internal server error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 500, "title": "Internal server error", "type": "https://belfort.ai/docs/errors#INTERNAL_ERROR" } } } } }, "description": "INTERNAL_ERROR" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Error — documento de problema RFC 9457 (`application/problem+json`)." } }, "security": [ { "secretKey": [] } ], "summary": "Ver la media de un caso", "tags": [ "review" ], "x-required-scope": "review:read" } }, "/v1/review/queue": { "get": { "description": "Los casos que esperan decisión humana, por cursor.", "operationId": "reviewQueue", "parameters": [ { "in": "query", "name": "scope", "required": false, "schema": { "default": "tenant", "pattern": "^(tenant|platform)$", "title": "Scope", "type": "string" } }, { "in": "query", "name": "status", "required": false, "schema": { "anyOf": [ { "$ref": "#/components/schemas/CaseStatus" }, { "type": "null" } ], "title": "Status" } }, { "in": "query", "name": "priority", "required": false, "schema": { "anyOf": [ { "$ref": "#/components/schemas/CasePriority" }, { "type": "null" } ], "title": "Priority" } }, { "in": "query", "name": "mine", "required": false, "schema": { "default": false, "title": "Mine", "type": "boolean" } }, { "description": "Tamaño de página (1–100).", "in": "query", "name": "limit", "required": false, "schema": { "default": 20, "description": "Tamaño de página (1–100).", "title": "Limit", "type": "integer" } }, { "description": "`nextCursor` de la página anterior. Excluyente con `endingBefore`.", "in": "query", "name": "startingAfter", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "`nextCursor` de la página anterior. Excluyente con `endingBefore`.", "title": "Startingafter" } }, { "description": "`previousCursor` de la página actual. Excluyente con `startingAfter`.", "in": "query", "name": "endingBefore", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "`previousCursor` de la página actual. Excluyente con `startingAfter`.", "title": "Endingbefore" } }, { "description": "Calcula `totalCount`. Cuesta un `COUNT(*)` sobre el filtro entero, así que está apagado por defecto: pídelo solo cuando vayas a enseñar el total.", "in": "query", "name": "includeTotal", "required": false, "schema": { "default": false, "description": "Calcula `totalCount`. Cuesta un `COUNT(*)` sobre el filtro entero, así que está apagado por defecto: pídelo solo cuando vayas a enseñar el total.", "title": "Includetotal", "type": "boolean" } }, { "in": "query", "name": "tenantId", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Tenantid" } }, { "in": "query", "name": "applicationId", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Applicationid" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListEnvelope_ReviewQueueItem_" } } }, "description": "Successful Response" }, "400": { "content": { "application/problem+json": { "examples": { "UNSUPPORTED_API_VERSION": { "summary": "UNSUPPORTED_API_VERSION", "value": { "code": "UNSUPPORTED_API_VERSION", "detail": "Unsupported API version", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 400, "title": "Unsupported API version", "type": "https://belfort.ai/docs/errors#UNSUPPORTED_API_VERSION" } } } } }, "description": "UNSUPPORTED_API_VERSION" }, "405": { "content": { "application/problem+json": { "examples": { "METHOD_NOT_ALLOWED": { "summary": "METHOD_NOT_ALLOWED", "value": { "code": "METHOD_NOT_ALLOWED", "detail": "Method not allowed", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 405, "title": "Method not allowed", "type": "https://belfort.ai/docs/errors#METHOD_NOT_ALLOWED" } } } } }, "description": "METHOD_NOT_ALLOWED" }, "422": { "content": { "application/problem+json": { "examples": { "VALIDATION_ERROR": { "summary": "VALIDATION_ERROR", "value": { "code": "VALIDATION_ERROR", "detail": "Validation error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 422, "title": "Validation error", "type": "https://belfort.ai/docs/errors#VALIDATION_ERROR" } } } } }, "description": "VALIDATION_ERROR" }, "500": { "content": { "application/problem+json": { "examples": { "INTERNAL_ERROR": { "summary": "INTERNAL_ERROR", "value": { "code": "INTERNAL_ERROR", "detail": "Internal server error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 500, "title": "Internal server error", "type": "https://belfort.ai/docs/errors#INTERNAL_ERROR" } } } } }, "description": "INTERNAL_ERROR" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Error — documento de problema RFC 9457 (`application/problem+json`)." } }, "security": [ { "secretKey": [] } ], "summary": "Consultar la cola de revisión", "tags": [ "review" ], "x-required-scope": "review:read" } }, "/v1/review/queue/summary": { "get": { "description": "Conteo por estado. Es lo que quieres para un panel: no te trae los casos.", "operationId": "reviewQueueSummary", "parameters": [ { "in": "query", "name": "scope", "required": false, "schema": { "default": "tenant", "pattern": "^(tenant|platform)$", "title": "Scope", "type": "string" } }, { "in": "query", "name": "tenantId", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Tenantid" } }, { "in": "query", "name": "applicationId", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Applicationid" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReviewQueueSummary" } } }, "description": "Successful Response" }, "400": { "content": { "application/problem+json": { "examples": { "UNSUPPORTED_API_VERSION": { "summary": "UNSUPPORTED_API_VERSION", "value": { "code": "UNSUPPORTED_API_VERSION", "detail": "Unsupported API version", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 400, "title": "Unsupported API version", "type": "https://belfort.ai/docs/errors#UNSUPPORTED_API_VERSION" } } } } }, "description": "UNSUPPORTED_API_VERSION" }, "405": { "content": { "application/problem+json": { "examples": { "METHOD_NOT_ALLOWED": { "summary": "METHOD_NOT_ALLOWED", "value": { "code": "METHOD_NOT_ALLOWED", "detail": "Method not allowed", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 405, "title": "Method not allowed", "type": "https://belfort.ai/docs/errors#METHOD_NOT_ALLOWED" } } } } }, "description": "METHOD_NOT_ALLOWED" }, "422": { "content": { "application/problem+json": { "examples": { "VALIDATION_ERROR": { "summary": "VALIDATION_ERROR", "value": { "code": "VALIDATION_ERROR", "detail": "Validation error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 422, "title": "Validation error", "type": "https://belfort.ai/docs/errors#VALIDATION_ERROR" } } } } }, "description": "VALIDATION_ERROR" }, "500": { "content": { "application/problem+json": { "examples": { "INTERNAL_ERROR": { "summary": "INTERNAL_ERROR", "value": { "code": "INTERNAL_ERROR", "detail": "Internal server error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 500, "title": "Internal server error", "type": "https://belfort.ai/docs/errors#INTERNAL_ERROR" } } } } }, "description": "INTERNAL_ERROR" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Error — documento de problema RFC 9457 (`application/problem+json`)." } }, "security": [ { "secretKey": [] } ], "summary": "Resumen de la cola", "tags": [ "review" ], "x-required-scope": "review:read" } }, "/v1/screening-hits": { "get": { "description": "Las coincidencias encontradas, filtrables por estado. Una coincidencia es material para decidir, no una decisión.", "operationId": "listScreeningHits", "parameters": [ { "in": "query", "name": "status", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Status" } }, { "description": "Tamaño de página (1–100).", "in": "query", "name": "limit", "required": false, "schema": { "default": 20, "description": "Tamaño de página (1–100).", "title": "Limit", "type": "integer" } }, { "description": "`nextCursor` de la página anterior. Excluyente con `endingBefore`.", "in": "query", "name": "startingAfter", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "`nextCursor` de la página anterior. Excluyente con `endingBefore`.", "title": "Startingafter" } }, { "description": "`previousCursor` de la página actual. Excluyente con `startingAfter`.", "in": "query", "name": "endingBefore", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "`previousCursor` de la página actual. Excluyente con `startingAfter`.", "title": "Endingbefore" } }, { "description": "Calcula `totalCount`. Cuesta un `COUNT(*)` sobre el filtro entero, así que está apagado por defecto: pídelo solo cuando vayas a enseñar el total.", "in": "query", "name": "includeTotal", "required": false, "schema": { "default": false, "description": "Calcula `totalCount`. Cuesta un `COUNT(*)` sobre el filtro entero, así que está apagado por defecto: pídelo solo cuando vayas a enseñar el total.", "title": "Includetotal", "type": "boolean" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListEnvelope_ScreeningHitResponse_" } } }, "description": "Successful Response" }, "400": { "content": { "application/problem+json": { "examples": { "UNSUPPORTED_API_VERSION": { "summary": "UNSUPPORTED_API_VERSION", "value": { "code": "UNSUPPORTED_API_VERSION", "detail": "Unsupported API version", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 400, "title": "Unsupported API version", "type": "https://belfort.ai/docs/errors#UNSUPPORTED_API_VERSION" } } } } }, "description": "UNSUPPORTED_API_VERSION" }, "405": { "content": { "application/problem+json": { "examples": { "METHOD_NOT_ALLOWED": { "summary": "METHOD_NOT_ALLOWED", "value": { "code": "METHOD_NOT_ALLOWED", "detail": "Method not allowed", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 405, "title": "Method not allowed", "type": "https://belfort.ai/docs/errors#METHOD_NOT_ALLOWED" } } } } }, "description": "METHOD_NOT_ALLOWED" }, "422": { "content": { "application/problem+json": { "examples": { "VALIDATION_ERROR": { "summary": "VALIDATION_ERROR", "value": { "code": "VALIDATION_ERROR", "detail": "Validation error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 422, "title": "Validation error", "type": "https://belfort.ai/docs/errors#VALIDATION_ERROR" } } } } }, "description": "VALIDATION_ERROR" }, "500": { "content": { "application/problem+json": { "examples": { "INTERNAL_ERROR": { "summary": "INTERNAL_ERROR", "value": { "code": "INTERNAL_ERROR", "detail": "Internal server error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 500, "title": "Internal server error", "type": "https://belfort.ai/docs/errors#INTERNAL_ERROR" } } } } }, "description": "INTERNAL_ERROR" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Error — documento de problema RFC 9457 (`application/problem+json`)." } }, "security": [ { "secretKey": [] } ], "summary": "Listar coincidencias", "tags": [ "aml" ], "x-required-scope": "aml:read" } }, "/v1/screenings": { "post": { "description": "Coteja una empresa y sus personas asociadas contra listas de sanciones, PEP y medios adversos. `Idempotency-Key` obligatoria.", "operationId": "runScreening", "parameters": [ { "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Idempotency-Key" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScreeningCreate" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScreeningResponse" } } }, "description": "Successful Response" }, "400": { "content": { "application/problem+json": { "examples": { "UNSUPPORTED_API_VERSION": { "summary": "UNSUPPORTED_API_VERSION", "value": { "code": "UNSUPPORTED_API_VERSION", "detail": "Unsupported API version", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 400, "title": "Unsupported API version", "type": "https://belfort.ai/docs/errors#UNSUPPORTED_API_VERSION" } } } } }, "description": "UNSUPPORTED_API_VERSION" }, "405": { "content": { "application/problem+json": { "examples": { "METHOD_NOT_ALLOWED": { "summary": "METHOD_NOT_ALLOWED", "value": { "code": "METHOD_NOT_ALLOWED", "detail": "Method not allowed", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 405, "title": "Method not allowed", "type": "https://belfort.ai/docs/errors#METHOD_NOT_ALLOWED" } } } } }, "description": "METHOD_NOT_ALLOWED" }, "422": { "content": { "application/problem+json": { "examples": { "VALIDATION_ERROR": { "summary": "VALIDATION_ERROR", "value": { "code": "VALIDATION_ERROR", "detail": "Validation error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 422, "title": "Validation error", "type": "https://belfort.ai/docs/errors#VALIDATION_ERROR" } } } } }, "description": "VALIDATION_ERROR" }, "500": { "content": { "application/problem+json": { "examples": { "INTERNAL_ERROR": { "summary": "INTERNAL_ERROR", "value": { "code": "INTERNAL_ERROR", "detail": "Internal server error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 500, "title": "Internal server error", "type": "https://belfort.ai/docs/errors#INTERNAL_ERROR" } } } } }, "description": "INTERNAL_ERROR" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Error — documento de problema RFC 9457 (`application/problem+json`)." } }, "security": [ { "secretKey": [] } ], "summary": "Lanzar un screening", "tags": [ "aml" ], "x-required-scope": "aml:write" } }, "/v1/vault/decrypt": { "post": { "description": "Canjea un `ctok_` por los campos en claro que ese token autoriza. Un solo uso. Si omites `fields`, devuelve todos los que el token permite; si los pides, tienen que ser un subconjunto.", "operationId": "redeemClientToken", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VaultDecryptRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DecryptResponse" } } }, "description": "Successful Response" }, "400": { "content": { "application/problem+json": { "examples": { "UNSUPPORTED_API_VERSION": { "summary": "UNSUPPORTED_API_VERSION", "value": { "code": "UNSUPPORTED_API_VERSION", "detail": "Unsupported API version", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 400, "title": "Unsupported API version", "type": "https://belfort.ai/docs/errors#UNSUPPORTED_API_VERSION" } } } } }, "description": "UNSUPPORTED_API_VERSION" }, "405": { "content": { "application/problem+json": { "examples": { "METHOD_NOT_ALLOWED": { "summary": "METHOD_NOT_ALLOWED", "value": { "code": "METHOD_NOT_ALLOWED", "detail": "Method not allowed", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 405, "title": "Method not allowed", "type": "https://belfort.ai/docs/errors#METHOD_NOT_ALLOWED" } } } } }, "description": "METHOD_NOT_ALLOWED" }, "422": { "content": { "application/problem+json": { "examples": { "VALIDATION_ERROR": { "summary": "VALIDATION_ERROR", "value": { "code": "VALIDATION_ERROR", "detail": "Validation error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 422, "title": "Validation error", "type": "https://belfort.ai/docs/errors#VALIDATION_ERROR" } } } } }, "description": "VALIDATION_ERROR" }, "500": { "content": { "application/problem+json": { "examples": { "INTERNAL_ERROR": { "summary": "INTERNAL_ERROR", "value": { "code": "INTERNAL_ERROR", "detail": "Internal server error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 500, "title": "Internal server error", "type": "https://belfort.ai/docs/errors#INTERNAL_ERROR" } } } } }, "description": "INTERNAL_ERROR" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Error — documento de problema RFC 9457 (`application/problem+json`)." } }, "security": [ { "clientToken": [] } ], "summary": "Redimir un client-token", "tags": [ "vault" ] } }, "/v1/verification-sessions": { "get": { "description": "Cursor list de las sesiones del tenant, filtrable por `status` y `applicationId`. Devuelve el registro de cada sesión (estado, tiempos, `trustScore`), no su expediente: para el detalle con pasos del pipeline y biometría pide `/report`. Requiere scope `verification:read`.", "operationId": "listSessions", "parameters": [ { "in": "query", "name": "status", "required": false, "schema": { "anyOf": [ { "$ref": "#/components/schemas/VerificationStatus" }, { "type": "null" } ], "title": "Status" } }, { "description": "Tamaño de página (1–100).", "in": "query", "name": "limit", "required": false, "schema": { "default": 20, "description": "Tamaño de página (1–100).", "title": "Limit", "type": "integer" } }, { "description": "`nextCursor` de la página anterior. Excluyente con `endingBefore`.", "in": "query", "name": "startingAfter", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "`nextCursor` de la página anterior. Excluyente con `endingBefore`.", "title": "Startingafter" } }, { "description": "`previousCursor` de la página actual. Excluyente con `startingAfter`.", "in": "query", "name": "endingBefore", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "`previousCursor` de la página actual. Excluyente con `startingAfter`.", "title": "Endingbefore" } }, { "description": "Calcula `totalCount`. Cuesta un `COUNT(*)` sobre el filtro entero, así que está apagado por defecto: pídelo solo cuando vayas a enseñar el total.", "in": "query", "name": "includeTotal", "required": false, "schema": { "default": false, "description": "Calcula `totalCount`. Cuesta un `COUNT(*)` sobre el filtro entero, así que está apagado por defecto: pídelo solo cuando vayas a enseñar el total.", "title": "Includetotal", "type": "boolean" } }, { "in": "query", "name": "applicationId", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Applicationid" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListEnvelope_VerificationSessionResponse_" } } }, "description": "Successful Response" }, "400": { "content": { "application/problem+json": { "examples": { "UNSUPPORTED_API_VERSION": { "summary": "UNSUPPORTED_API_VERSION", "value": { "code": "UNSUPPORTED_API_VERSION", "detail": "Unsupported API version", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 400, "title": "Unsupported API version", "type": "https://belfort.ai/docs/errors#UNSUPPORTED_API_VERSION" } } } } }, "description": "UNSUPPORTED_API_VERSION" }, "405": { "content": { "application/problem+json": { "examples": { "METHOD_NOT_ALLOWED": { "summary": "METHOD_NOT_ALLOWED", "value": { "code": "METHOD_NOT_ALLOWED", "detail": "Method not allowed", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 405, "title": "Method not allowed", "type": "https://belfort.ai/docs/errors#METHOD_NOT_ALLOWED" } } } } }, "description": "METHOD_NOT_ALLOWED" }, "422": { "content": { "application/problem+json": { "examples": { "VALIDATION_ERROR": { "summary": "VALIDATION_ERROR", "value": { "code": "VALIDATION_ERROR", "detail": "Validation error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 422, "title": "Validation error", "type": "https://belfort.ai/docs/errors#VALIDATION_ERROR" } } } } }, "description": "VALIDATION_ERROR" }, "500": { "content": { "application/problem+json": { "examples": { "INTERNAL_ERROR": { "summary": "INTERNAL_ERROR", "value": { "code": "INTERNAL_ERROR", "detail": "Internal server error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 500, "title": "Internal server error", "type": "https://belfort.ai/docs/errors#INTERNAL_ERROR" } } } } }, "description": "INTERNAL_ERROR" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Error — documento de problema RFC 9457 (`application/problem+json`)." } }, "security": [ { "secretKey": [] } ], "summary": "Listar sesiones de verificación", "tags": [ "verifications" ], "x-required-scope": "verification:read" }, "post": { "description": "Abre una sesión y devuelve su `id` (`vrf_…`). A partir de aquí subes la media y la envías a evaluar. Lleva `Idempotency-Key` obligatoria: un reintento por timeout devuelve la MISMA sesión, no una segunda.", "operationId": "createSession", "parameters": [ { "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Idempotency-Key" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerificationSessionCreate" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerificationSessionCreated" } } }, "description": "Successful Response" }, "400": { "content": { "application/problem+json": { "examples": { "UNSUPPORTED_API_VERSION": { "summary": "UNSUPPORTED_API_VERSION", "value": { "code": "UNSUPPORTED_API_VERSION", "detail": "Unsupported API version", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 400, "title": "Unsupported API version", "type": "https://belfort.ai/docs/errors#UNSUPPORTED_API_VERSION" } } } } }, "description": "UNSUPPORTED_API_VERSION" }, "405": { "content": { "application/problem+json": { "examples": { "METHOD_NOT_ALLOWED": { "summary": "METHOD_NOT_ALLOWED", "value": { "code": "METHOD_NOT_ALLOWED", "detail": "Method not allowed", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 405, "title": "Method not allowed", "type": "https://belfort.ai/docs/errors#METHOD_NOT_ALLOWED" } } } } }, "description": "METHOD_NOT_ALLOWED" }, "422": { "content": { "application/problem+json": { "examples": { "VALIDATION_ERROR": { "summary": "VALIDATION_ERROR", "value": { "code": "VALIDATION_ERROR", "detail": "Validation error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 422, "title": "Validation error", "type": "https://belfort.ai/docs/errors#VALIDATION_ERROR" } } } } }, "description": "VALIDATION_ERROR" }, "500": { "content": { "application/problem+json": { "examples": { "INTERNAL_ERROR": { "summary": "INTERNAL_ERROR", "value": { "code": "INTERNAL_ERROR", "detail": "Internal server error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 500, "title": "Internal server error", "type": "https://belfort.ai/docs/errors#INTERNAL_ERROR" } } } } }, "description": "INTERNAL_ERROR" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Error — documento de problema RFC 9457 (`application/problem+json`)." } }, "security": [ { "secretKey": [] } ], "summary": "Crear una sesión de verificación", "tags": [ "verifications" ], "x-required-scope": "verification:write" } }, "/v1/verification-sessions/{session_id}": { "get": { "description": "El registro de la sesión: estado actual, paso en curso, tiempos, `trustScore` y las referencias a flow, application y person. Es el **estado**, no la evidencia — el expediente completo (pasos, biometría, consultas de gobierno) vive en `/report`, y su copia sellada y archivable en `/certificate`. Requiere scope `verification:read`.", "operationId": "getSession", "parameters": [ { "in": "path", "name": "session_id", "required": true, "schema": { "title": "Session Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerificationSessionResponse" } } }, "description": "Successful Response" }, "400": { "content": { "application/problem+json": { "examples": { "UNSUPPORTED_API_VERSION": { "summary": "UNSUPPORTED_API_VERSION", "value": { "code": "UNSUPPORTED_API_VERSION", "detail": "Unsupported API version", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 400, "title": "Unsupported API version", "type": "https://belfort.ai/docs/errors#UNSUPPORTED_API_VERSION" } } } } }, "description": "UNSUPPORTED_API_VERSION" }, "405": { "content": { "application/problem+json": { "examples": { "METHOD_NOT_ALLOWED": { "summary": "METHOD_NOT_ALLOWED", "value": { "code": "METHOD_NOT_ALLOWED", "detail": "Method not allowed", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 405, "title": "Method not allowed", "type": "https://belfort.ai/docs/errors#METHOD_NOT_ALLOWED" } } } } }, "description": "METHOD_NOT_ALLOWED" }, "422": { "content": { "application/problem+json": { "examples": { "VALIDATION_ERROR": { "summary": "VALIDATION_ERROR", "value": { "code": "VALIDATION_ERROR", "detail": "Validation error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 422, "title": "Validation error", "type": "https://belfort.ai/docs/errors#VALIDATION_ERROR" } } } } }, "description": "VALIDATION_ERROR" }, "500": { "content": { "application/problem+json": { "examples": { "INTERNAL_ERROR": { "summary": "INTERNAL_ERROR", "value": { "code": "INTERNAL_ERROR", "detail": "Internal server error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 500, "title": "Internal server error", "type": "https://belfort.ai/docs/errors#INTERNAL_ERROR" } } } } }, "description": "INTERNAL_ERROR" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Error — documento de problema RFC 9457 (`application/problem+json`)." } }, "security": [ { "secretKey": [] } ], "summary": "Obtener una sesión de verificación", "tags": [ "verifications" ], "x-required-scope": "verification:read" } }, "/v1/verification-sessions/{session_id}/certificate": { "get": { "description": "La constancia determinista y archivable de la verificación: el mismo expediente de `/report` pero sin nada que dependa del instante en que se pide, más `contentHash` (sha256 del canónico) y `signature` (HMAC-SHA256). Pedirla dos veces devuelve EXACTAMENTE el mismo documento, byte a byte — sin esa garantía el sello no significaría nada. Requiere scope `verification:read`.", "operationId": "getSessionCertificate", "parameters": [ { "in": "path", "name": "session_id", "required": true, "schema": { "title": "Session Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerificationCertificate" } } }, "description": "Successful Response" }, "400": { "content": { "application/problem+json": { "examples": { "UNSUPPORTED_API_VERSION": { "summary": "UNSUPPORTED_API_VERSION", "value": { "code": "UNSUPPORTED_API_VERSION", "detail": "Unsupported API version", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 400, "title": "Unsupported API version", "type": "https://belfort.ai/docs/errors#UNSUPPORTED_API_VERSION" } } } } }, "description": "UNSUPPORTED_API_VERSION" }, "405": { "content": { "application/problem+json": { "examples": { "METHOD_NOT_ALLOWED": { "summary": "METHOD_NOT_ALLOWED", "value": { "code": "METHOD_NOT_ALLOWED", "detail": "Method not allowed", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 405, "title": "Method not allowed", "type": "https://belfort.ai/docs/errors#METHOD_NOT_ALLOWED" } } } } }, "description": "METHOD_NOT_ALLOWED" }, "422": { "content": { "application/problem+json": { "examples": { "VALIDATION_ERROR": { "summary": "VALIDATION_ERROR", "value": { "code": "VALIDATION_ERROR", "detail": "Validation error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 422, "title": "Validation error", "type": "https://belfort.ai/docs/errors#VALIDATION_ERROR" } } } } }, "description": "VALIDATION_ERROR" }, "500": { "content": { "application/problem+json": { "examples": { "INTERNAL_ERROR": { "summary": "INTERNAL_ERROR", "value": { "code": "INTERNAL_ERROR", "detail": "Internal server error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 500, "title": "Internal server error", "type": "https://belfort.ai/docs/errors#INTERNAL_ERROR" } } } } }, "description": "INTERNAL_ERROR" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Error — documento de problema RFC 9457 (`application/problem+json`)." } }, "security": [ { "secretKey": [] } ], "summary": "Obtener la constancia sellada", "tags": [ "verifications" ], "x-required-scope": "verification:read" } }, "/v1/verification-sessions/{session_id}/consent": { "post": { "description": "Deja constancia del consentimiento informado de la persona titular, con su evidencia. Es un requisito de la LFPDPPP y una precondición para evaluar: sin él, `submit` rechaza.", "operationId": "recordSessionConsent", "parameters": [ { "in": "path", "name": "session_id", "required": true, "schema": { "title": "Session Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConsentRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConsentResponse" } } }, "description": "Successful Response" }, "400": { "content": { "application/problem+json": { "examples": { "UNSUPPORTED_API_VERSION": { "summary": "UNSUPPORTED_API_VERSION", "value": { "code": "UNSUPPORTED_API_VERSION", "detail": "Unsupported API version", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 400, "title": "Unsupported API version", "type": "https://belfort.ai/docs/errors#UNSUPPORTED_API_VERSION" } } } } }, "description": "UNSUPPORTED_API_VERSION" }, "405": { "content": { "application/problem+json": { "examples": { "METHOD_NOT_ALLOWED": { "summary": "METHOD_NOT_ALLOWED", "value": { "code": "METHOD_NOT_ALLOWED", "detail": "Method not allowed", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 405, "title": "Method not allowed", "type": "https://belfort.ai/docs/errors#METHOD_NOT_ALLOWED" } } } } }, "description": "METHOD_NOT_ALLOWED" }, "422": { "content": { "application/problem+json": { "examples": { "VALIDATION_ERROR": { "summary": "VALIDATION_ERROR", "value": { "code": "VALIDATION_ERROR", "detail": "Validation error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 422, "title": "Validation error", "type": "https://belfort.ai/docs/errors#VALIDATION_ERROR" } } } } }, "description": "VALIDATION_ERROR" }, "500": { "content": { "application/problem+json": { "examples": { "INTERNAL_ERROR": { "summary": "INTERNAL_ERROR", "value": { "code": "INTERNAL_ERROR", "detail": "Internal server error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 500, "title": "Internal server error", "type": "https://belfort.ai/docs/errors#INTERNAL_ERROR" } } } } }, "description": "INTERNAL_ERROR" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Error — documento de problema RFC 9457 (`application/problem+json`)." } }, "security": [ { "secretKey": [] } ], "summary": "Registrar el consentimiento", "tags": [ "verifications" ], "x-required-scope": "verification:write" } }, "/v1/verification-sessions/{session_id}/events": { "get": { "description": "Stream Server-Sent Events del avance de los agentes de verificación, para pintar el progreso en vivo. Es el canal del revisor/tenant: se autentica por JWT y valida la pertenencia al tenant. Requiere scope `verification:read`.", "operationId": "sessionEvents", "parameters": [ { "in": "path", "name": "session_id", "required": true, "schema": { "title": "Session Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response" }, "400": { "content": { "application/problem+json": { "examples": { "UNSUPPORTED_API_VERSION": { "summary": "UNSUPPORTED_API_VERSION", "value": { "code": "UNSUPPORTED_API_VERSION", "detail": "Unsupported API version", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 400, "title": "Unsupported API version", "type": "https://belfort.ai/docs/errors#UNSUPPORTED_API_VERSION" } } } } }, "description": "UNSUPPORTED_API_VERSION" }, "405": { "content": { "application/problem+json": { "examples": { "METHOD_NOT_ALLOWED": { "summary": "METHOD_NOT_ALLOWED", "value": { "code": "METHOD_NOT_ALLOWED", "detail": "Method not allowed", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 405, "title": "Method not allowed", "type": "https://belfort.ai/docs/errors#METHOD_NOT_ALLOWED" } } } } }, "description": "METHOD_NOT_ALLOWED" }, "422": { "content": { "application/problem+json": { "examples": { "VALIDATION_ERROR": { "summary": "VALIDATION_ERROR", "value": { "code": "VALIDATION_ERROR", "detail": "Validation error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 422, "title": "Validation error", "type": "https://belfort.ai/docs/errors#VALIDATION_ERROR" } } } } }, "description": "VALIDATION_ERROR" }, "500": { "content": { "application/problem+json": { "examples": { "INTERNAL_ERROR": { "summary": "INTERNAL_ERROR", "value": { "code": "INTERNAL_ERROR", "detail": "Internal server error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 500, "title": "Internal server error", "type": "https://belfort.ai/docs/errors#INTERNAL_ERROR" } } } } }, "description": "INTERNAL_ERROR" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Error — documento de problema RFC 9457 (`application/problem+json`)." } }, "security": [ { "secretKey": [] } ], "summary": "Seguir el progreso de la sesión (SSE)", "tags": [ "verifications" ], "x-required-scope": "verification:read" } }, "/v1/verification-sessions/{session_id}/evidence": { "get": { "description": "El paquete de evidencia de la verificación: veredicto, puntuaciones biométricas y referencias a la media, en la forma que exige una constancia NOM-151. Es el canal de lectura por API key — el detalle completo de la sesión vive en el dashboard.", "operationId": "getSessionEvidence", "parameters": [ { "in": "path", "name": "session_id", "required": true, "schema": { "title": "Session Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EvidenceBundle" } } }, "description": "Successful Response" }, "400": { "content": { "application/problem+json": { "examples": { "UNSUPPORTED_API_VERSION": { "summary": "UNSUPPORTED_API_VERSION", "value": { "code": "UNSUPPORTED_API_VERSION", "detail": "Unsupported API version", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 400, "title": "Unsupported API version", "type": "https://belfort.ai/docs/errors#UNSUPPORTED_API_VERSION" } } } } }, "description": "UNSUPPORTED_API_VERSION" }, "405": { "content": { "application/problem+json": { "examples": { "METHOD_NOT_ALLOWED": { "summary": "METHOD_NOT_ALLOWED", "value": { "code": "METHOD_NOT_ALLOWED", "detail": "Method not allowed", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 405, "title": "Method not allowed", "type": "https://belfort.ai/docs/errors#METHOD_NOT_ALLOWED" } } } } }, "description": "METHOD_NOT_ALLOWED" }, "422": { "content": { "application/problem+json": { "examples": { "VALIDATION_ERROR": { "summary": "VALIDATION_ERROR", "value": { "code": "VALIDATION_ERROR", "detail": "Validation error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 422, "title": "Validation error", "type": "https://belfort.ai/docs/errors#VALIDATION_ERROR" } } } } }, "description": "VALIDATION_ERROR" }, "500": { "content": { "application/problem+json": { "examples": { "INTERNAL_ERROR": { "summary": "INTERNAL_ERROR", "value": { "code": "INTERNAL_ERROR", "detail": "Internal server error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 500, "title": "Internal server error", "type": "https://belfort.ai/docs/errors#INTERNAL_ERROR" } } } } }, "description": "INTERNAL_ERROR" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Error — documento de problema RFC 9457 (`application/problem+json`)." } }, "security": [ { "secretKey": [] } ], "summary": "Obtener la evidencia de la sesión", "tags": [ "verifications" ], "x-required-scope": "verification:read" } }, "/v1/verification-sessions/{session_id}/media": { "post": { "description": "Envía una captura —anverso o reverso del documento, o el video de prueba de vida— a la sesión abierta. Se llama una vez por pieza.", "operationId": "ingestSessionMedia", "parameters": [ { "in": "path", "name": "session_id", "required": true, "schema": { "title": "Session Id", "type": "string" } }, { "in": "query", "name": "analyze", "required": false, "schema": { "default": false, "title": "Analyze", "type": "boolean" } } ], "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MediaCaptureResult" } } }, "description": "Successful Response" }, "400": { "content": { "application/problem+json": { "examples": { "UNSUPPORTED_API_VERSION": { "summary": "UNSUPPORTED_API_VERSION", "value": { "code": "UNSUPPORTED_API_VERSION", "detail": "Unsupported API version", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 400, "title": "Unsupported API version", "type": "https://belfort.ai/docs/errors#UNSUPPORTED_API_VERSION" } } } } }, "description": "UNSUPPORTED_API_VERSION" }, "405": { "content": { "application/problem+json": { "examples": { "METHOD_NOT_ALLOWED": { "summary": "METHOD_NOT_ALLOWED", "value": { "code": "METHOD_NOT_ALLOWED", "detail": "Method not allowed", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 405, "title": "Method not allowed", "type": "https://belfort.ai/docs/errors#METHOD_NOT_ALLOWED" } } } } }, "description": "METHOD_NOT_ALLOWED" }, "422": { "content": { "application/problem+json": { "examples": { "VALIDATION_ERROR": { "summary": "VALIDATION_ERROR", "value": { "code": "VALIDATION_ERROR", "detail": "Validation error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 422, "title": "Validation error", "type": "https://belfort.ai/docs/errors#VALIDATION_ERROR" } } } } }, "description": "VALIDATION_ERROR" }, "500": { "content": { "application/problem+json": { "examples": { "INTERNAL_ERROR": { "summary": "INTERNAL_ERROR", "value": { "code": "INTERNAL_ERROR", "detail": "Internal server error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 500, "title": "Internal server error", "type": "https://belfort.ai/docs/errors#INTERNAL_ERROR" } } } } }, "description": "INTERNAL_ERROR" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Error — documento de problema RFC 9457 (`application/problem+json`)." } }, "security": [ { "secretKey": [] } ], "summary": "Subir media a la sesión", "tags": [ "verifications" ], "x-required-scope": "verification:write" } }, "/v1/verification-sessions/{session_id}/report": { "get": { "description": "Detalle completo de la verificación: decisión, pasos del pipeline, biometría, documento y consultas de gobierno, con el desglose del `trustScore`. No expone PII cruda. Es la lectura viva del expediente; si necesitas una copia determinista y sellable, pide `/certificate`. Requiere scope `verification:read`.", "operationId": "getSessionReport", "parameters": [ { "in": "path", "name": "session_id", "required": true, "schema": { "title": "Session Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerificationReportDetail" } } }, "description": "Successful Response" }, "400": { "content": { "application/problem+json": { "examples": { "UNSUPPORTED_API_VERSION": { "summary": "UNSUPPORTED_API_VERSION", "value": { "code": "UNSUPPORTED_API_VERSION", "detail": "Unsupported API version", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 400, "title": "Unsupported API version", "type": "https://belfort.ai/docs/errors#UNSUPPORTED_API_VERSION" } } } } }, "description": "UNSUPPORTED_API_VERSION" }, "405": { "content": { "application/problem+json": { "examples": { "METHOD_NOT_ALLOWED": { "summary": "METHOD_NOT_ALLOWED", "value": { "code": "METHOD_NOT_ALLOWED", "detail": "Method not allowed", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 405, "title": "Method not allowed", "type": "https://belfort.ai/docs/errors#METHOD_NOT_ALLOWED" } } } } }, "description": "METHOD_NOT_ALLOWED" }, "422": { "content": { "application/problem+json": { "examples": { "VALIDATION_ERROR": { "summary": "VALIDATION_ERROR", "value": { "code": "VALIDATION_ERROR", "detail": "Validation error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 422, "title": "Validation error", "type": "https://belfort.ai/docs/errors#VALIDATION_ERROR" } } } } }, "description": "VALIDATION_ERROR" }, "500": { "content": { "application/problem+json": { "examples": { "INTERNAL_ERROR": { "summary": "INTERNAL_ERROR", "value": { "code": "INTERNAL_ERROR", "detail": "Internal server error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 500, "title": "Internal server error", "type": "https://belfort.ai/docs/errors#INTERNAL_ERROR" } } } } }, "description": "INTERNAL_ERROR" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Error — documento de problema RFC 9457 (`application/problem+json`)." } }, "security": [ { "secretKey": [] } ], "summary": "Obtener el expediente de la sesión", "tags": [ "verifications" ], "x-required-scope": "verification:read" } }, "/v1/verification-sessions/{session_id}/submit": { "post": { "description": "Cierra la captura y dispara el pipeline: consulta a la fuente gubernamental, cotejo biométrico y política de decisión. La respuesta te dice si quedó aprobada, rechazada o en revisión manual; el veredicto definitivo también llega por webhook.", "operationId": "submitSession", "parameters": [ { "in": "path", "name": "session_id", "required": true, "schema": { "title": "Session Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "discriminator": { "mapping": { "decision": "#/components/schemas/VerificationSubmitResult", "pending": "#/components/schemas/VerificationSubmitAccepted" }, "propertyName": "kind" }, "oneOf": [ { "$ref": "#/components/schemas/VerificationSubmitResult" }, { "$ref": "#/components/schemas/VerificationSubmitAccepted" } ], "title": "Response Submitsession" } } }, "description": "Successful Response" }, "400": { "content": { "application/problem+json": { "examples": { "UNSUPPORTED_API_VERSION": { "summary": "UNSUPPORTED_API_VERSION", "value": { "code": "UNSUPPORTED_API_VERSION", "detail": "Unsupported API version", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 400, "title": "Unsupported API version", "type": "https://belfort.ai/docs/errors#UNSUPPORTED_API_VERSION" } } } } }, "description": "UNSUPPORTED_API_VERSION" }, "405": { "content": { "application/problem+json": { "examples": { "METHOD_NOT_ALLOWED": { "summary": "METHOD_NOT_ALLOWED", "value": { "code": "METHOD_NOT_ALLOWED", "detail": "Method not allowed", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 405, "title": "Method not allowed", "type": "https://belfort.ai/docs/errors#METHOD_NOT_ALLOWED" } } } } }, "description": "METHOD_NOT_ALLOWED" }, "422": { "content": { "application/problem+json": { "examples": { "VALIDATION_ERROR": { "summary": "VALIDATION_ERROR", "value": { "code": "VALIDATION_ERROR", "detail": "Validation error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 422, "title": "Validation error", "type": "https://belfort.ai/docs/errors#VALIDATION_ERROR" } } } } }, "description": "VALIDATION_ERROR" }, "500": { "content": { "application/problem+json": { "examples": { "INTERNAL_ERROR": { "summary": "INTERNAL_ERROR", "value": { "code": "INTERNAL_ERROR", "detail": "Internal server error", "requestId": "9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "status": 500, "title": "Internal server error", "type": "https://belfort.ai/docs/errors#INTERNAL_ERROR" } } } } }, "description": "INTERNAL_ERROR" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Error — documento de problema RFC 9457 (`application/problem+json`)." } }, "security": [ { "secretKey": [] } ], "summary": "Enviar la sesión a evaluar", "tags": [ "verifications" ], "x-required-scope": "verification:write" } } }, "servers": [ { "description": "Producción", "url": "https://api.belfort.ai" }, { "description": "Sandbox de pruebas", "url": "https://api.dev.belfort.ai" } ], "x-domainIntros": { "verifications": { "title": "Verificaciones", "lead": "Una verificación es una persona pasando por el motor de identidad: documento oficial, prueba de vida y cotejo biométrico. Este es el **canal API-direct**, el que usas cuando tu backend controla la captura. Si prefieres que Belfort ponga la interfaz, usa el [canal embebido](/endpoints/embedded).", "notes": [ "El flujo son cinco llamadas en orden: crear la sesión, registrar el consentimiento, subir la media, enviarla a evaluar y recoger la evidencia.", "El veredicto llega por [webhook](/webhooks). `GET .../evidence` existe para reconciliar, no para hacer polling agresivo.", "Los ids de sesión son opacos y con prefijo (`vrf_…`). Nunca envíes un UUID crudo: la API lo rechaza con `400 INVALID_ID`." ] }, "embedded": { "title": "Canal embebido", "lead": "Belfort pone la interfaz de captura dentro de un iframe en tu producto. Tú creas la sesión desde tu backend, montas el widget con el `clientSecret` y recibes el veredicto por webhook — sin tocar biometría ni almacenar una sola imagen.", "notes": [ "Hay dos formas de crear la sesión: desde tu **backend** con una `sk_`, o desde el **navegador** con una publishable `pk_` cuando el flujo ya está fijado.", "La `pk_` viaja al navegador, así que no concede nada por sí sola: solo abre sesiones contra los `allowedOrigins` que configuraste.", "`init` y `policy` no llevan credencial de integrador: los llama el propio widget con el token de la sesión." ] }, "persons": { "title": "Personas", "lead": "El vault guarda identidades **ya verificadas** y su PII cifrada. La escritura es directa; la lectura en claro nunca lo es: cada revelado deja una entrada en la bitácora, consume presupuesto y exige el scope `persons:read_pii`.", "notes": [ "La PII es **write-only** en las respuestas normales. Para verla en claro se pasa por `decrypt`, que audita; `fields` te dice qué campos existen sin descifrar ninguno.", "Los derechos ARCO están cubiertos por API: acceso (`export`), rectificación (`PATCH`) y cancelación (`forget`).", "`createPerson` hace upsert por `(application, externalRef)`: reintentar con el mismo `externalRef` no crea un duplicado." ] }, "vault": { "title": "Vault", "lead": "Un client-token (`ctok_`) es una credencial efímera y de un solo uso que puedes mandar al navegador para revelar campos concretos de una persona, sin que tu clave secreta salga de tu servidor.", "notes": [ "Lo emites con `POST /v1/persons/{id}/client-token` y lo rediges aquí. Caduca en 15 minutos o al primer uso, lo que ocurra antes.", "Solo puede revelar los campos que declaraste al emitirlo. Pedir uno fuera de esa lista es un error, no una revelación parcial." ] }, "companies": { "title": "Empresas (KYB)", "lead": "Verificación de personas morales: registro público, estructura de propiedad (UBO), miembros y screening AML, en un solo pipeline. El resultado es un expediente con nivel de riesgo, no un sí/no.", "notes": [ "El alta y el disparo del pipeline están separados a propósito: puedes cargar documentos y miembros antes de verificar.", "El grafo UBO se construye con `POST .../ubo`, un nodo por llamada." ] }, "screening": { "title": "Screening AML", "lead": "Cotejo contra listas de sanciones, personas políticamente expuestas y medios adversos, con re-screening periódico por portafolio.", "notes": [ "Un screening devuelve *hits*, no veredictos: la decisión de negocio sigue siendo tuya.", "El monitoreo continuo se dispara por portafolio, no por persona." ] }, "review": { "title": "Revisión manual", "lead": "Cuando el motor no decide solo, el caso cae en una cola para revisión humana. Estos endpoints existen para que puedas operar esa cola desde tu propio sistema en vez de desde el dashboard de Belfort.", "notes": [ "Abrir el detalle de un caso **descifra PII y audita el acceso**. No lo uses para listar.", "El flujo normal es reclamar el caso, resolverlo y —si tu política lo exige— pasar por un segundo par de ojos." ] }, "webhooks-api": { "title": "Webhooks (API)", "lead": "Gestión de tus endpoints de webhook: alta, rotación de secreto, catálogo de eventos y la bitácora de entregas con reintentos. Cómo verificar la firma está explicado en la [guía de webhooks](/webhooks).", "notes": [ "El signing secret se muestra **una sola vez**, al crear el endpoint y al rotarlo.", "Rotar no es una interrupción: durante 24 horas cada entrega va firmada con el secreto nuevo **y** con el anterior.", "`verify-signature` recomputa la firma de un cuerpo que le pases. Es la forma de depurar tu verificador sin esperar a un evento real." ] }, "compliance": { "title": "Cumplimiento", "lead": "La superficie que tu equipo legal necesita sin pedirte nada a ti: bitácora de accesos encadenada y verificable, informes, subprocesadores, centros de datos y los límites vigentes de tu cuenta.", "notes": [ "La bitácora es append-only y encadenada por hash: `verify` comprueba que nadie la alteró.", "`limits` es la fuente única de los topes que te aplican. No los transcribas: léelos." ] }, "media": { "title": "Media", "lead": "Los archivos de una verificación no se sirven con tu API key. Se pide un enlace firmado, de vida corta, y ese enlace es el que puedes pasar a un navegador o guardar en un expediente.", "notes": [ "La credencial del archivo es la firma de la URL, no la key: quien tenga el enlace ve el archivo hasta que caduque.", "Emitir el enlace exige `persons:read_pii` y queda auditado." ] } }, "x-prose-covered": [ "addCaseNote", "addCompanyDocument", "addCompanyMember", "addUboNode", "batchDecryptPersons", "checkPersonIntegrity", "claimCase", "consolidatePerson", "createBrowserEmbeddedSession", "createCompany", "createEmbeddedSession", "createMediaLink", "createPerson", "createPersonGrant", "createSession", "decryptPerson", "downloadExportBulkJob", "exportPerson", "exportPersonsBulk", "forgetPerson", "getCompanyDetail", "getCompanyStatus", "getComplianceReport", "getConsolidationStatus", "getDeletionCertificate", "getDeliveryPolicy", "getExportBulkJob", "getImportJob", "getLimits", "getMedia", "getPersonDetail", "getPersonFields", "getReviewMedia", "getSession", "getSessionCertificate", "getSessionEvidence", "getSessionPolicy", "getSessionReport", "getWebhook", "grantPersonConsent", "importPersons", "ingestSessionMedia", "initEmbeddedSession", "issuePersonClientToken", "listAllDeliveries", "listAuditLogs", "listCompanies", "listDatacenters", "listDeliveryAttempts", "listDocumentLegalHolds", "listEndpointDeliveries", "listEventTypes", "listPersonConsents", "listPersonDocuments", "listPersonDuplicates", "listPersonGrants", "listPersonLegalHolds", "listPersonSessions", "listPersons", "listScreeningHits", "listSessions", "listSubprocessors", "listWebhooks", "patchPerson", "reassignCase", "reauthPersonFace", "recordSessionConsent", "redeemClientToken", "registerWebhook", "releaseCase", "releaseDocumentLegalHold", "releasePersonLegalHold", "resolveCase", "retryDelivery", "reviewCaseDetail", "reviewQueue", "reviewQueueSummary", "revokePersonClientToken", "revokePersonConsent", "revokePersonGrant", "rotateWebhookSecret", "runScreening", "searchPersons", "sessionEvents", "setDocumentLegalHold", "setPersonLegalHold", "submitSession", "testWebhook", "triggerBreachNotification", "triggerPortfolioRun", "updateWebhook", "verifyAuditLogChain", "verifyCompany", "verifyEmbeddedSession", "verifyWebhookSignature" ] }