naftiko: 1.0.0-alpha2
info:
  label: Telefónica Fraud Prevention
  description: Fraud prevention capability combining Telefónica's Number Verification, SIM Swap, KYC Match, and Location Verification
    APIs into a unified workflow. Enables financial services, e-commerce, and insurance companies to verify user identity,
    detect account takeover attempts, and validate location claims using Telefónica's carrier network data without compromising
    privacy.
  tags:
  - Telefónica
  - Fraud Prevention
  - Authentication
  - Identity Verification
  - KYC
  - Financial Services
  - CAMARA
  - Open Gateway
  created: '2026-05-03'
  modified: '2026-05-06'
binds:
- namespace: env
  keys:
    TELEFONICA_ACCESS_TOKEN: TELEFONICA_ACCESS_TOKEN
capability:
  consumes:
  - type: http
    namespace: telefonica-number-verification
    baseUri: https://opengateway.telefonica.com/v1
    description: Telefónica Number Verification API via Open Gateway.
    authentication:
      type: bearer
      token: '{{TELEFONICA_ACCESS_TOKEN}}'
    resources:
    - name: number-verification
      path: /number-verification
      description: Mobile number verification endpoints.
      operations:
      - name: verify-phone-number
        method: POST
        description: Verify that the device is connected via the specified phone number.
        body:
          type: json
          data:
            phoneNumber: '{{tools.phoneNumber}}'
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: get-phone-number
        method: POST
        description: Get the phone number associated with the device connection.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
  - type: http
    namespace: telefonica-sim-swap
    baseUri: https://opengateway.telefonica.com/v1
    description: Telefónica SIM Swap API via Open Gateway.
    authentication:
      type: bearer
      token: '{{TELEFONICA_ACCESS_TOKEN}}'
    resources:
    - name: sim-swap
      path: /sim-swap
      description: SIM swap detection endpoints.
      operations:
      - name: check-sim-swap
        method: POST
        description: Check whether a recent SIM swap occurred on a phone number.
        body:
          type: json
          data:
            phoneNumber: '{{tools.phoneNumber}}'
            maxAge: '{{tools.maxAge}}'
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: get-sim-swap-date
        method: POST
        description: Get the date of the most recent SIM swap.
        body:
          type: json
          data:
            phoneNumber: '{{tools.phoneNumber}}'
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
  - type: http
    namespace: telefonica-kyc
    baseUri: https://opengateway.telefonica.com/v1
    description: Telefónica KYC Match API via Open Gateway.
    authentication:
      type: bearer
      token: '{{TELEFONICA_ACCESS_TOKEN}}'
    resources:
    - name: kyc-match
      path: /kyc-match
      description: Know Your Customer identity matching endpoint.
      operations:
      - name: match-kyc
        method: POST
        description: Validate identity data against carrier records.
        body:
          type: json
          data:
            phoneNumber: '{{tools.phoneNumber}}'
            givenName: '{{tools.givenName}}'
            familyName: '{{tools.familyName}}'
            birthdate: '{{tools.birthdate}}'
            email: '{{tools.email}}'
            address: '{{tools.address}}'
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
  - type: http
    namespace: telefonica-location
    baseUri: https://opengateway.telefonica.com/v1
    description: Telefónica Location Verification API via Open Gateway.
    authentication:
      type: bearer
      token: '{{TELEFONICA_ACCESS_TOKEN}}'
    resources:
    - name: location-verification
      path: /location-verification
      description: Device location verification endpoint.
      operations:
      - name: verify-device-location
        method: POST
        description: Verify whether a device is within a specified geographic area.
        body:
          type: json
          data:
            device: '{{tools.device}}'
            area: '{{tools.area}}'
            maxAge: '{{tools.maxAge}}'
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
  exposes:
  - type: rest
    port: 8080
    namespace: telefonica-fraud-api
    description: Unified REST API for Telefónica fraud prevention workflows.
    resources:
    - path: /v1/verification/phone-number
      name: phone-number-verification
      description: Phone number verification using carrier data.
      operations:
      - method: POST
        name: verify-phone-number
        description: Verify a phone number matches the device's SIM connection.
        call: telefonica-number-verification.verify-phone-number
        with:
          phoneNumber: rest.phoneNumber
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/verification/sim-swap
      name: sim-swap-check
      description: SIM swap fraud detection.
      operations:
      - method: POST
        name: check-sim-swap
        description: Check for recent SIM swap on a phone number.
        call: telefonica-sim-swap.check-sim-swap
        with:
          phoneNumber: rest.phoneNumber
          maxAge: rest.maxAge
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/verification/kyc
      name: kyc-match
      description: KYC identity data matching.
      operations:
      - method: POST
        name: match-kyc
        description: Validate identity data against carrier records.
        call: telefonica-kyc.match-kyc
        with:
          phoneNumber: rest.phoneNumber
          givenName: rest.givenName
          familyName: rest.familyName
          birthdate: rest.birthdate
          email: rest.email
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/verification/location
      name: location-verification
      description: Device location verification.
      operations:
      - method: POST
        name: verify-location
        description: Verify device is within a geographic area.
        call: telefonica-location.verify-device-location
        with:
          device: rest.device
          area: rest.area
        outputParameters:
        - type: object
          mapping: $.
  - type: mcp
    port: 9090
    namespace: telefonica-fraud-mcp
    transport: http
    description: MCP server for AI-assisted Telefónica fraud prevention workflows.
    tools:
    - name: verify-phone-number
      description: Verify that a user's phone number matches their device's SIM card connection using Telefónica carrier data.
      hints:
        readOnly: true
      call: telefonica-number-verification.verify-phone-number
      with:
        phoneNumber: tools.phoneNumber
      outputParameters:
      - type: object
        mapping: $.
    - name: get-device-phone-number
      description: Get the phone number associated with the user's current device connection (for passwordless login).
      hints:
        readOnly: true
      call: telefonica-number-verification.get-phone-number
      outputParameters:
      - type: object
        mapping: $.
    - name: check-sim-swap
      description: Check if a SIM swap fraud attempt occurred recently on a phone number.
      hints:
        readOnly: true
      call: telefonica-sim-swap.check-sim-swap
      with:
        phoneNumber: tools.phoneNumber
        maxAge: tools.maxAge
      outputParameters:
      - type: object
        mapping: $.
    - name: get-sim-swap-date
      description: Get the date of the most recent SIM swap for detailed fraud investigation.
      hints:
        readOnly: true
      call: telefonica-sim-swap.get-sim-swap-date
      with:
        phoneNumber: tools.phoneNumber
      outputParameters:
      - type: object
        mapping: $.
    - name: match-kyc-identity
      description: Validate user identity data (name, birthdate, address, email) against Telefónica carrier records for KYC
        compliance.
      hints:
        readOnly: true
      call: telefonica-kyc.match-kyc
      with:
        phoneNumber: tools.phoneNumber
        givenName: tools.givenName
        familyName: tools.familyName
        birthdate: tools.birthdate
        email: tools.email
        address: tools.address
      outputParameters:
      - type: object
        mapping: $.
    - name: verify-device-location
      description: Verify that a user's device is present within a specified geographic area using network data.
      hints:
        readOnly: true
      call: telefonica-location.verify-device-location
      with:
        device: tools.device
        area: tools.area
        maxAge: tools.maxAge
      outputParameters:
      - type: object
        mapping: $.