OpenMercantil Sources API
Source catalog metadata, freshness and integration status
OpenAPI Specification
openapi: 3.1.0
info:
title: OpenMercantil Sources API
version: 1.9.3
summary: Versioned public-read, browser-account, billing, support and provider-callback contracts.
description: 'Public JSON API for Spanish company information derived from BORME and other public sources.
OpenMercantil is an independent informational service; it is NOT the BOE, BORME or Registro Mercantil
and does NOT replace official certificates or registry extracts.
**Rate limits.** Free: 60 req/min y 200 req/día por IP. Planes superiores (Profesional 5.000 req/día,
MAX 50.000 req/día, Enterprise 500.000+ req/día) según cuenta y API key. Cabeceras `X-RateLimit-Limit`,
`X-RateLimit-Remaining`, `X-RateLimit-Reset`, `X-OpenMercantil-Plan`, `Retry-After`.
**License and attribution.** Source-specific metadata in each response and the active versioned source
catalog prevails. OpenMercantil does not relicense upstream content under a blanket license. Unknown,
review and restricted datasets are omitted or return `503 legal_layer_unavailable`. BOE/BORME material
is re-used under Ley 37/2007 and its official version remains boe.es. Court judgments are not exposed;
CENDOJ remains citation-index only under CGPJ Reglamento 3/2010.
**Machine-readable catalog (DCAT-AP-ES):** https://openmercantil.es/catalog.rdf'
termsOfService: https://openmercantil.es/terminos-de-uso
contact:
name: OpenMercantil
url: https://openmercantil.es/soporte
email: social@openmercantil.es
license:
name: Source-specific upstream terms; see response catalog metadata
url: https://openmercantil.es/terminos-de-uso
x-publisher:
name: OpenMercantil
url: https://openmercantil.es/
email: social@openmercantil.es
x-spatial: http://publications.europa.eu/resource/authority/country/ESP
x-temporal: 2009-01-01/..
x-language: es
x-dcat-catalog: https://openmercantil.es/catalog.rdf
x-rate-limit:
free:
per_min: 60
per_day: 200
kind: anonymous-ip
profesional:
per_min: 120
per_day: 5000
kind: api-key
max:
per_min: 600
per_day: 50000
kind: api-key
enterprise:
per_min: 1200
per_day: 500000
kind: contract
x-methodology: https://openmercantil.es/metodologia
x-sources: https://openmercantil.es/fuentes
x-corrections: https://openmercantil.es/correcciones
x-contract-status: Public read, browser-account and provider-callback surfaces are explicitly separated
in this contract. Operator/admin routes are excluded. The public MCP consumes only the allowlisted
GET read plane.
x-account-segment-contract:
projection: company_public_v2 immutable corporate sidecar
synchronous_row_cap: 500
bounded_count_cap: 50001
count_semantics: The segment run response count is the number of rows returned, never a global total.
Dataset preview uses total_is_lower_bound=true and total_lower_bound when the bounded count reaches
50001.
related_web_dataset_surface:
preview_path: /mi-cuenta/datasets/preview
export_path: /mi-cuenta/datasets/export.csv
synchronous_export_max_rows: 500
overflow_status: 503
overflow_error: async_export_required
x-company-identity-contract:
version: '1.0'
projection: company_public_v2 immutable generation-bound corporate sidecar
applies_to: Every /api/v1/company/{slug}*, /api/v1/empresa/{slug}* and /api/v1/grafo/{slug} read before
any report, cache, graph or dataset lookup. /api/v1/companies/compare resolves both requested subjects
in one bounded company_public_v2 batch before either row is exposed; MCP company tools inherit these
preflights through REST.
resolution:
published: canonical corporate slug admitted
safe_alias: internally canonicalized and Content-Location emitted
withheld: neutral 404; includes absent, personal and ambiguous/quarantined identities
unavailable: 503 with no-store; clients must not infer absence
search: Exact corporate CIF, exact canonical/safe-alias slug, or bounded name_prefix2 pool scored
in application code. DNI/NIE and ambiguous CIFs return zero items.
public_company_count: company_public_projection_state.row_count
servers:
- url: https://openmercantil.es
description: Production
tags:
- name: Sources
description: Source catalog metadata, freshness and integration status
paths:
/api/v1/sources/freshness:
get:
operationId: getSourcesFreshness
parameters:
- $ref: '#/components/parameters/IfNoneMatchHeader'
tags:
- Sources
summary: Per-source freshness map
description: Return a minimized freshness projection only for sources authorized by the versioned
public-source catalog. The timestamp comes from the offline projection, never request time. Its
ETag is bound to the shared asv1 stats generation and uses 60-second must-revalidate caching.
Unknown, review and restricted sources are omitted. Connector health, errors, schedules and row
counts are never exposed.
security:
- {}
- apiKey: []
- bearerAuth: []
x-api-credential-scope: integrations:read
x-rate-limit: plan policy (see info.x-rate-limit)
responses:
'200':
description: Freshness map
headers:
X-Data-Sources:
$ref: '#/components/headers/XDataSources'
X-Source-Catalog-Version:
$ref: '#/components/headers/XSourceCatalogVersion'
X-Attribution-Required:
$ref: '#/components/headers/XAttributionRequired'
ETag:
$ref: '#/components/headers/EntityTag'
X-OpenMercantil-Stats-Generation:
$ref: '#/components/headers/StatsGeneration'
Cache-Control:
schema:
type: string
const: public, max-age=60, must-revalidate
content:
application/json:
schema:
type: object
description: Fail-closed public projection. Operational ingestion telemetry is intentionally
absent.
properties:
generated_at:
type:
- string
- 'null'
format: date-time
description: Offline projection generation time; null only for a legacy cache without
provenance.
global:
type: object
properties:
date:
type:
- string
- 'null'
format: date-time
label:
type:
- string
- 'null'
status:
type: string
enum:
- current
- stale
- unknown
source_catalog_version:
type: string
sources:
type: array
items:
$ref: '#/components/schemas/PublicSourceMetadata'
count:
type: integer
_legal_notice:
type: string
'304':
description: The authorized freshness representation and shared stats generation have not changed
headers:
ETag:
$ref: '#/components/headers/EntityTag'
X-OpenMercantil-Stats-Generation:
$ref: '#/components/headers/StatsGeneration'
Cache-Control:
schema:
type: string
const: public, max-age=60, must-revalidate
'429':
$ref: '#/components/responses/TooManyRequests'
'503':
description: The required offline freshness projection is absent, or the public-source legal
policy cannot produce an authorized projection. This endpoint fails closed and never falls
back to live connector telemetry.
headers:
Retry-After:
description: Seconds before retrying when the offline projection is absent.
schema:
type: integer
minimum: 0
content:
application/json:
schema:
$ref: '#/components/schemas/OfflineProjectionError'
examples:
projection_required:
value:
error: offline_projection_required
projection: sources_freshness_v5
legal_layer_unavailable:
value:
error: legal_layer_unavailable
/api/v1/sources/status:
get:
operationId: getSourcesStatus
parameters:
- $ref: '#/components/parameters/IfNoneMatchHeader'
tags:
- Sources
summary: Minimized public source metadata
description: Return only public catalog metadata and a coarse data date/freshness. Its ETag is bound
to the shared asv1 stats generation and uses 60-second must-revalidate caching. This endpoint
is not an operator health probe and does not expose connector status, errors, schedules, source
URLs or item counts.
x-rate-limit: free 60/min · 200/day
responses:
'200':
description: Fail-closed public source projection
headers:
X-Data-Sources:
$ref: '#/components/headers/XDataSources'
X-Source-Catalog-Version:
$ref: '#/components/headers/XSourceCatalogVersion'
X-Attribution-Required:
$ref: '#/components/headers/XAttributionRequired'
ETag:
$ref: '#/components/headers/EntityTag'
X-OpenMercantil-Stats-Generation:
$ref: '#/components/headers/StatsGeneration'
Cache-Control:
schema:
type: string
const: public, max-age=60, must-revalidate
content:
application/json:
schema:
$ref: '#/components/schemas/PublicSourceStatusResponse'
'304':
description: The minimized source-status representation and shared stats generation have not
changed
headers:
ETag:
$ref: '#/components/headers/EntityTag'
X-OpenMercantil-Stats-Generation:
$ref: '#/components/headers/StatsGeneration'
Cache-Control:
schema:
type: string
const: public, max-age=60, must-revalidate
'429':
$ref: '#/components/responses/TooManyRequests'
'503':
$ref: '#/components/responses/PublicReadUnavailable'
components:
headers:
EntityTag:
description: Strong generation-bound entity tag for conditional GET.
schema:
type: string
pattern: ^"[a-f0-9]{64}"$
StatsGeneration:
description: Exact shared generation of the active CCAA, sector, sources and global-counters bundle.
schema:
type: string
pattern: ^asv1-[a-f0-9]{64}$
XAttributionRequired:
description: Optional. When present, comma-separated public source aliases whose attribution terms
must accompany reuse.
schema:
type: string
minLength: 1
pattern: ^[a-z0-9][a-z0-9_.-]*(,[a-z0-9][a-z0-9_.-]*)*$
example: placsp
XDataSources:
description: Comma-separated aliases from the active public source catalog that contributed to the
response. Omitted only when a valid exact filter returns an empty representation with zero contributing
sources.
schema:
type: string
minLength: 1
pattern: ^[a-z0-9][a-z0-9_.-]*(,[a-z0-9][a-z0-9_.-]*)*$
example: borme,placsp
XSourceCatalogVersion:
description: Mandatory on every successful public GET. Exact version of the legal source catalog
used to authorize the response.
schema:
type: string
minLength: 1
example: 2026-07-12.2
parameters:
IfNoneMatchHeader:
name: If-None-Match
in: header
required: false
description: Optional RFC 9110 entity-tag validator. Weak validators, comma-separated validator
lists and `*` are accepted.
schema:
type: string
minLength: 1
maxLength: 8192
responses:
PublicReadUnavailable:
description: The public read failed closed because its legal source catalog, subject classification,
bounded projection, database helper or required artifact is unavailable. Clients must not infer
an empty result.
headers:
Cache-Control:
description: Unavailable public reads are never cacheable.
schema:
type: string
const: no-store
Retry-After:
description: Optional number of seconds to wait before retrying.
schema:
type: integer
minimum: 1
content:
application/json:
schema:
anyOf:
- $ref: '#/components/schemas/ProjectionUnavailableError'
- $ref: '#/components/schemas/ErrorResponse'
examples:
legal_layer:
value:
error: legal_layer_unavailable
company_identity:
value:
error: company_public_projection_unavailable
projection:
value:
error: projection_unavailable
detail: La proyección pública requerida no está disponible.
projection: wikidata_company_v1
TooManyRequests:
description: Rate limit exceeded
headers:
Retry-After:
description: Seconds to wait before retrying.
schema:
type: integer
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
schemas:
ErrorResponse:
type: object
description: Closed compatibility envelope for public/account errors. Route-specific schemas narrow
these fields further where required.
required:
- error
properties:
error:
type: string
minLength: 1
message:
type: string
detail:
type: string
code:
type: string
status:
type:
- integer
- string
projection:
type: string
reason:
type: string
source_catalog_version:
type: string
allowed_parameters:
type: array
uniqueItems: true
items:
type: string
slug:
type: string
key:
type: string
maximum:
type: integer
minimum: 1
parameter:
type: string
fields:
type: array
items:
type: string
max_bytes:
type: integer
minimum: 1
allowed:
type: array
items:
$ref: '#/components/schemas/JsonValue'
valid:
type: array
items:
$ref: '#/components/schemas/JsonValue'
date:
type: string
login_url:
type: string
plan:
type: string
limited_by:
type: string
enum:
- minute
- day
daily_limit:
type: integer
minimum: 1
reset_at:
type: integer
minimum: 1
reset_at_human:
type: string
format: date-time
retry_after_s:
type: integer
minimum: 1
retry_after:
type: integer
minimum: 1
upgrade:
type: string
format: uri
upgrade_url:
type: string
action:
type: string
limit:
type: integer
minimum: 0
remaining:
type: integer
minimum: 0
needed:
type: integer
minimum: 0
shortfall:
type: integer
minimum: 0
ok:
type: boolean
_alias_of:
type: string
additionalProperties: false
JsonValue:
description: A JSON value used only inside explicitly documented extension maps.
oneOf:
- type:
- string
- number
- boolean
- 'null'
- type: array
items:
$ref: '#/components/schemas/JsonValue'
- type: object
additionalProperties:
$ref: '#/components/schemas/JsonValue'
OfflineProjectionError:
type: object
required:
- error
properties:
error:
type: string
projection:
type:
- string
- 'null'
derivation:
type:
- string
- 'null'
detail:
type:
- string
- 'null'
additionalProperties: false
ProjectionUnavailableError:
type: object
description: Fail-closed projection outage. Clients must not reinterpret this response as an empty
or negative result.
required:
- error
- detail
- projection
properties:
error:
type: string
const: projection_unavailable
detail:
type: string
projection:
type: string
additionalProperties: false
PublicSourceMetadata:
type: object
additionalProperties: false
required:
- slug
- name
- license
- attribution_required
- reuse_conditions
- policy_effective_date
- catalog_version
- freshness
properties:
slug:
type: string
name:
type: string
license:
type: string
license_url:
type:
- string
- 'null'
format: uri
attribution_required:
type: boolean
attribution_text:
type:
- string
- 'null'
official_url:
type:
- string
- 'null'
format: uri
reuse_conditions:
type: string
description: Condiciones de reutilizacion que el consumidor debe conservar al presentar o transformar
el dato.
policy_effective_date:
type: string
format: date
reviewed_at:
type:
- string
- 'null'
format: date
data_updated_at:
type:
- string
- 'null'
format: date-time
catalog_version:
type: string
freshness:
type: string
enum:
- current
- stale
- unknown
PublicSourceStatusResponse:
type: object
additionalProperties: false
required:
- generated_at
- source_catalog_version
- count
- sources
- _legal_notice
properties:
generated_at:
type: string
format: date-time
source_catalog_version:
type: string
count:
type: integer
minimum: 0
sources:
type: array
items:
$ref: '#/components/schemas/PublicSourceMetadata'
_legal_notice:
type: string
securitySchemes:
apiKey:
type: apiKey
in: header
name: X-API-Key
description: Optional opaque omk_* API credential for public GETs. Anonymous access remains valid;
a credential with the operation's x-api-credential-scope (or public:read) selects its account
quota. Never place credentials in query strings.
bearerAuth:
type: http
scheme: bearer
bearerFormat: opaque omk_* credential
description: 'Optional Authorization: Bearer transport for the same opaque omk_* API credential
accepted by X-API-Key. It is not a JWT or OAuth access token.'