OpenMercantil Spanish Company Intelligence

naftiko: 1.0.0-alpha2
info:
  label: OpenMercantil Spanish Company Intelligence
  description: Unified capability for searching Spanish companies and persons, retrieving registry reports, navigating BORME timelines, accessing CNAE sectors, and pulling integrated public-data signals (sanctions, grants, contracts, CNMV, embargoes, trust score) from OpenMercantil's public API. No API key required; rate-limited per IP.
  tags:
    - Company Data
    - Business Registry
    - BORME
    - Spain
    - Open Data
    - Public Records
  created: '2026-05-16'
  modified: '2026-05-16'
binds:
  - namespace: env
    keys: {}
capability:
  consumes:
    - type: http
      namespace: openmercantil
      baseUri: https://openmercantil.es
      description: OpenMercantil public REST API
      authentication:
        type: none
      resources:
        - name: search
          path: /api/v1/search
          description: Company and person search
          operations:
            - name: search-companies
              method: GET
              description: Search Spanish companies by name, alias or CIF
              inputParameters:
                - name: q
                  in: query
                  type: string
                  required: true
                  description: Search query (minimum 2 characters)
                - name: limit
                  in: query
                  type: integer
                  required: false
                  description: Max results (1-100, default 20)
                - name: offset
                  in: query
                  type: integer
                  required: false
                  description: Pagination offset
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: $.
        - name: company
          path: /api/v1/company/{slug}
          description: Company report
          operations:
            - name: get-company
              method: GET
              description: Return the OpenMercantil report for a company slug
              inputParameters:
                - name: slug
                  in: path
                  type: string
                  required: true
                  description: Company slug
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: $.
        - name: company-events
          path: /api/v1/company/{slug}/events
          description: Company BORME event timeline
          operations:
            - name: get-company-events
              method: GET
              description: Return paginated BORME events for a company
              inputParameters:
                - name: slug
                  in: path
                  type: string
                  required: true
                - name: year
                  in: query
                  type: integer
                  required: false
                - name: page
                  in: query
                  type: integer
                  required: false
                - name: page_size
                  in: query
                  type: integer
                  required: false
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: $.
        - name: company-officers
          path: /api/v1/company/{slug}/officers
          description: Company officers (administrators, apoderados)
          operations:
            - name: get-company-officers
              method: GET
              description: List officers for a company
              inputParameters:
                - name: slug
                  in: path
                  type: string
                  required: true
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: $.
        - name: company-export
          path: /api/v1/company/{slug}/export
          description: Export a company report
          operations:
            - name: export-company
              method: GET
              description: Export a company report in JSON or CSV
              inputParameters:
                - name: slug
                  in: path
                  type: string
                  required: true
                - name: format
                  in: query
                  type: string
                  required: false
                  description: json or csv (default json)
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: $.
        - name: company-score
          path: /api/v1/company/{slug}/score
          description: Composite company score
          operations:
            - name: get-company-score
              method: GET
              description: Return the OpenMercantil score for a company
              inputParameters:
                - name: slug
                  in: path
                  type: string
                  required: true
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: $.
        - name: company-trust-score
          path: /api/v1/company/{slug}/trust-score
          description: Cross-source trust score
          operations:
            - name: get-company-trust-score
              method: GET
              description: Return the v1.4 trust score for a company
              inputParameters:
                - name: slug
                  in: path
                  type: string
                  required: true
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: $.
        - name: company-network
          path: /api/v1/company/{slug}/network
          description: Company relationship graph
          operations:
            - name: get-company-network
              method: GET
              description: Return the officer/shareholder relationship graph
              inputParameters:
                - name: slug
                  in: path
                  type: string
                  required: true
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: $.
        - name: company-sanctions
          path: /api/v1/company/{slug}/sanctions
          description: Sanctions hits
          operations:
            - name: get-company-sanctions
              method: GET
              description: Return sanctions hits for a company
              inputParameters:
                - name: slug
                  in: path
                  type: string
                  required: true
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: $.
        - name: company-grants
          path: /api/v1/company/{slug}/grants
          description: Public grants (BDNS)
          operations:
            - name: get-company-grants
              method: GET
              description: Return BDNS grants for a company
              inputParameters:
                - name: slug
                  in: path
                  type: string
                  required: true
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: $.
        - name: company-geocode
          path: /api/v1/company/{slug}/geocode
          description: Geocode a company address
          operations:
            - name: geocode-company
              method: GET
              description: Resolve a company's registered address to coordinates
              inputParameters:
                - name: slug
                  in: path
                  type: string
                  required: true
                - name: force
                  in: query
                  type: integer
                  required: false
                  description: Set 1 to bypass cache
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: $.
        - name: person
          path: /api/v1/person/{slug}
          description: Person report
          operations:
            - name: get-person
              method: GET
              description: Return the report for a person slug
              inputParameters:
                - name: slug
                  in: path
                  type: string
                  required: true
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: $.
        - name: person-search
          path: /api/v1/person/search
          description: Person search
          operations:
            - name: search-persons
              method: GET
              description: Search persons by name
              inputParameters:
                - name: q
                  in: query
                  type: string
                  required: true
                - name: limit
                  in: query
                  type: integer
                  required: false
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: $.
        - name: daily
          path: /api/v1/daily/{date}
          description: Daily BORME summary
          operations:
            - name: get-daily-summary
              method: GET
              description: Return the BORME summary for a given date
              inputParameters:
                - name: date
                  in: path
                  type: string
                  required: true
                  description: ISO 8601 date
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: $.
        - name: sources-status
          path: /api/v1/sources/status
          description: External sources freshness
          operations:
            - name: get-sources-status
              method: GET
              description: Return last-ingested timestamps and status for each integrated source
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: $.
        - name: health
          path: /api/v1/health
          description: Service health
          operations:
            - name: get-health
              method: GET
              description: Return service status and dataset counters
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: $.
  exposes:
    - type: rest
      port: 8080
      namespace: openmercantil-api
      description: Unified REST API for Spanish company intelligence
      resources:
        - path: /v1/search
          name: search
          description: Company and person search
          operations:
            - method: GET
              name: search-companies
              description: Search Spanish companies
              call: openmercantil.search-companies
              outputParameters:
                - type: object
                  mapping: $.
        - path: /v1/companies/{slug}
          name: company
          description: Company report
          operations:
            - method: GET
              name: get-company
              description: Get a company report
              call: openmercantil.get-company
              outputParameters:
                - type: object
                  mapping: $.
        - path: /v1/companies/{slug}/events
          name: company-events
          description: Company event timeline
          operations:
            - method: GET
              name: get-company-events
              description: Get paginated BORME events for a company
              call: openmercantil.get-company-events
              outputParameters:
                - type: object
                  mapping: $.
        - path: /v1/companies/{slug}/officers
          name: company-officers
          description: Company officers
          operations:
            - method: GET
              name: get-company-officers
              description: List company officers
              call: openmercantil.get-company-officers
              outputParameters:
                - type: object
                  mapping: $.
        - path: /v1/companies/{slug}/trust-score
          name: company-trust-score
          description: Trust score
          operations:
            - method: GET
              name: get-company-trust-score
              description: Get the OpenMercantil trust score
              call: openmercantil.get-company-trust-score
              outputParameters:
                - type: object
                  mapping: $.
        - path: /v1/sources/status
          name: sources-status
          description: Source freshness
          operations:
            - method: GET
              name: get-sources-status
              description: Get freshness across integrated sources
              call: openmercantil.get-sources-status
              outputParameters:
                - type: object
                  mapping: $.
        - path: /v1/health
          name: health
          description: Health check
          operations:
            - method: GET
              name: get-health
              description: Get service health
              call: openmercantil.get-health
              outputParameters:
                - type: object
                  mapping: $.
    - type: mcp
      port: 9090
      namespace: openmercantil-mcp
      transport: http
      description: MCP server exposing OpenMercantil Spanish company intelligence to AI agents
      tools:
        - name: search-companies
          description: Search Spanish companies by name, alias or CIF using OpenMercantil's public index
          hints:
            readOnly: true
            openWorld: false
          call: openmercantil.search-companies
          outputParameters:
            - type: object
              mapping: $.
        - name: get-company
          description: Retrieve the OpenMercantil company report (BORME-derived) for a given slug
          hints:
            readOnly: true
            openWorld: false
          call: openmercantil.get-company
          outputParameters:
            - type: object
              mapping: $.
        - name: get-company-events
          description: List BORME registry events for a company, optionally filtered by year
          hints:
            readOnly: true
            openWorld: false
          call: openmercantil.get-company-events
          outputParameters:
            - type: object
              mapping: $.
        - name: get-company-officers
          description: List officers (administrators, apoderados) for a company
          hints:
            readOnly: true
            openWorld: false
          call: openmercantil.get-company-officers
          outputParameters:
            - type: object
              mapping: $.
        - name: get-company-trust-score
          description: Get the OpenMercantil v1.4 cross-source trust score for a company
          hints:
            readOnly: true
            openWorld: false
          call: openmercantil.get-company-trust-score
          outputParameters:
            - type: object
              mapping: $.
        - name: get-company-sanctions
          description: List sanctions hits associated with a company (OpenSanctions, CNMC)
          hints:
            readOnly: true
            openWorld: false
          call: openmercantil.get-company-sanctions
          outputParameters:
            - type: object
              mapping: $.
        - name: get-company-grants
          description: List BDNS public grants associated with a company
          hints:
            readOnly: true
            openWorld: false
          call: openmercantil.get-company-grants
          outputParameters:
            - type: object
              mapping: $.
        - name: geocode-company
          description: Resolve a company's registered address to coordinates via cached Nominatim lookup
          hints:
            readOnly: true
            openWorld: true
          call: openmercantil.geocode-company
          outputParameters:
            - type: object
              mapping: $.
        - name: search-persons
          description: Search persons (officers, administrators) by name in OpenMercantil
          hints:
            readOnly: true
            openWorld: false
          call: openmercantil.search-persons
          outputParameters:
            - type: object
              mapping: $.
        - name: get-person
          description: Get the OpenMercantil person report including roles and historical positions
          hints:
            readOnly: true
            openWorld: false
          call: openmercantil.get-person
          outputParameters:
            - type: object
              mapping: $.
        - name: get-daily-summary
          description: Get the daily BORME summary for a given ISO date
          hints:
            readOnly: true
            openWorld: false
          call: openmercantil.get-daily-summary
          outputParameters:
            - type: object
              mapping: $.
        - name: get-sources-status
          description: Get freshness and status of OpenMercantil's integrated public-data sources
          hints:
            readOnly: true
            openWorld: false
          call: openmercantil.get-sources-status
          outputParameters:
            - type: object
              mapping: $.
        - name: get-health
          description: Get OpenMercantil service health and dataset counters
          hints:
            readOnly: true
            openWorld: false
          call: openmercantil.get-health
          outputParameters:
            - type: object
              mapping: $.