{"openapi":"3.1.0","info":{"title":"CIVITAS BETGOV API","version":"1.0.0","description":"API de governança e proteção para operadores de apostas regulamentadas. Ambiente demonstrativo — integrações governamentais não configuradas. Respostas não contêm dados pessoais: o titular é identificado por subject_token pseudonimizado por operador.","contact":{"name":"MOBIURB Tecnologia"}},"servers":[{"url":"/","description":"Servidor atual (sandbox: chaves bgv_test_; produção: bgv_live_)"}],"security":[{"bearerAuth":[]}],"tags":[{"name":"Identidade"},{"name":"Elegibilidade"},{"name":"Limites"},{"name":"Eventos"},{"name":"Autoexclusão"},{"name":"Decisões"},{"name":"Integrações"}],"paths":{"/v1/identity/verify":{"post":{"tags":["Identidade"],"summary":"Verificar identidade e obter subject_token","operationId":"verifyIdentity","description":"Verifica o CPF contra a base BETGOV (demonstrativa). Provedor oficial de identidade: NÃO CONFIGURADO. O CPF não é persistido em claro.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["cpf"],"properties":{"cpf":{"type":"string","example":"999.000.001-00"},"birth_date":{"type":"string","format":"date","example":"1990-05-10"}}}}}},"responses":{"200":{"description":"Resultado da verificação","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IdentityResult"}}}},"400":{"description":"Entrada inválida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Chave ausente, inválida, revogada ou expirada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Recurso inexistente para este operador","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflito de idempotência","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit excedido (ver Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/eligibility/check":{"post":{"tags":["Elegibilidade"],"summary":"Solicitar decisão de elegibilidade","operationId":"checkEligibility","description":"Executa o pipeline IDENTIDADE → ELEGIBILIDADE → LIMITES → MOTOR DE REGRAS → RISCO/COMPLIANCE → DECISÃO. Idempotente via cabeçalho Idempotency-Key.","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":100}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["subject_token"],"properties":{"subject_token":{"type":"string"},"action":{"type":"string","enum":["ELIGIBILITY","ACCOUNT_OPENING","DEPOSIT","SESSION_START"]},"amount_cents":{"type":"integer","minimum":0}}}}}},"responses":{"200":{"description":"Replay idempotente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Decision"}}}},"201":{"description":"Decisão emitida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Decision"}}}},"400":{"description":"Entrada inválida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Chave ausente, inválida, revogada ou expirada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Recurso inexistente para este operador","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflito de idempotência","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit excedido (ver Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/limits/check":{"post":{"tags":["Limites"],"summary":"Verificar limites prudenciais (sem consumo)","operationId":"checkLimits","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["subject_token"],"properties":{"subject_token":{"type":"string"},"action":{"type":"string","example":"DEPOSIT"},"amount_cents":{"type":"integer"}}}}}},"responses":{"200":{"description":"Situação dos limites","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["WITHIN_LIMITS","LIMIT_REACHED"]},"reason_code":{"type":"string"},"scope":{"type":"string"},"limits":{"type":"array","items":{"type":"object"}}}}}}},"400":{"description":"Entrada inválida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Chave ausente, inválida, revogada ou expirada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Recurso inexistente para este operador","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflito de idempotência","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit excedido (ver Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/events":{"post":{"tags":["Eventos"],"summary":"Registrar evento no ledger imutável","operationId":"recordEvent","description":"Registro append-only com hash encadeado. Idempotency-Key obrigatória; mesma chave com payload diferente retorna 409. Depósitos são rejeitados (status REJECTED) quando há autoexclusão, pausa ou limite atingido.","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["subject_token","event_type"],"properties":{"subject_token":{"type":"string"},"event_type":{"type":"string","enum":["DEPOSIT","WITHDRAWAL","NET_LOSS","SESSION_TIME","ACCOUNT_OPENED","ACCOUNT_CLOSED"]},"amount_cents":{"type":"integer"},"duration_minutes":{"type":"integer"},"decision_id":{"type":"string","format":"uuid"},"occurred_at":{"type":"string","format":"date-time"}}}}}},"responses":{"200":{"description":"Replay idempotente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EventReceipt"}}}},"201":{"description":"Evento registrado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EventReceipt"}}}},"400":{"description":"Entrada inválida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Chave ausente, inválida, revogada ou expirada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Recurso inexistente para este operador","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflito de idempotência","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit excedido (ver Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/self-exclusion/check":{"post":{"tags":["Autoexclusão"],"summary":"Consultar autoexclusão/pausa ativa","operationId":"checkSelfExclusion","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["subject_token"],"properties":{"subject_token":{"type":"string"}}}}}},"responses":{"200":{"description":"Situação","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["NONE","PAUSED","SELF_EXCLUDED"]},"reason_code":{"type":"string"},"active_until":{"type":["string","null"]},"source":{"type":"string"},"external_registry":{"type":"string"}}}}}},"400":{"description":"Entrada inválida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Chave ausente, inválida, revogada ou expirada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Recurso inexistente para este operador","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflito de idempotência","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit excedido (ver Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/decisions/{id}":{"get":{"tags":["Decisões"],"summary":"Consultar decisão emitida","operationId":"getDecision","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Decisão","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Decision"}}}},"400":{"description":"Entrada inválida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Chave ausente, inválida, revogada ou expirada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Recurso inexistente para este operador","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflito de idempotência","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit excedido (ver Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/integrations/status":{"get":{"tags":["Integrações"],"summary":"Status honesto das integrações","operationId":"integrationsStatus","responses":{"200":{"description":"Lista de integrações","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Entrada inválida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Chave ausente, inválida, revogada ou expirada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Recurso inexistente para este operador","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflito de idempotência","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit excedido (ver Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Chave de API do operador (bgv_test_… ou bgv_live_…)."}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"correlation_id":{"type":"string"}}}}},"Decision":{"type":"object","required":["decision_id","status","reason_code","expires_at"],"properties":{"decision_id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["AUTHORIZED","RESTRICTED","BLOCKED","REVIEW"]},"reason_code":{"type":"string","example":"OK"},"reason_codes":{"type":"array","items":{"type":"string"}},"expires_at":{"type":"string","format":"date-time"},"issued_at":{"type":"string","format":"date-time"},"rule_set_hash":{"type":"string"},"mechanism":{"type":"string","enum":["RULE_BASED"]},"environment":{"type":"string"},"simulation":{"type":"boolean"},"idempotent_replay":{"type":"boolean"},"correlation_id":{"type":"string"}}},"IdentityResult":{"type":"object","properties":{"verification_id":{"type":"string"},"status":{"type":"string","enum":["VERIFIED","NOT_FOUND","MISMATCH","INVALID_INPUT"]},"subject_token":{"type":["string","null"]},"assurance_level":{"type":"string"},"method":{"type":"string"},"official_provider":{"type":"object"},"notice":{"type":"string"}}},"EventReceipt":{"type":"object","properties":{"event_id":{"type":"string"},"sequence":{"type":"integer"},"status":{"type":"string","enum":["ACCEPTED","REJECTED"]},"reason_code":{"type":"string"},"hash":{"type":"string"},"prev_hash":{"type":"string"},"idempotent_replay":{"type":"boolean"}}}}}}