# Divr API

> La API de la bolsa española: dividendos, calendario, resultados, cuentas anuales y ratios de las empresas cotizadas en BME, leídos de los registros oficiales de la CNMV. JSON en UTF-8; cada cifra dice de qué documento sale, con qué fórmula se calculó o por qué falta.

- Todo es GET bajo /v1/ y pide la cabecera `Authorization: Bearer <clave>`. La clave nunca va en la URL.
- Plan gratuito: 100 peticiones al día por clave (00:00 UTC). Cabeceras X-RateLimit-Limit, X-RateLimit-Remaining y X-RateLimit-Reset; al pasarse, 429 rate_limited con Retry-After.
- Clave gratis al momento en /docs#clave.
- Fechas en AAAA-MM-DD; horas en RFC 3339, UTC.
- Una cifra nunca es un escalar: {"value", "origin", ...} o {"value": null, "reason"}. origin es "reported" (apunta a doc y concept del XBRL) o "derived" (con formula e inputs).
- Errores: {"error": {"code", "message", "ticker"}}. Códigos: issuer_unknown (404), issuer_no_source (404, permanente), issuer_not_ingested (404, transitorio), events_not_scanned (404), bad_request (400), unauthorized (401), plan_not_allowed (403), rate_limited (429), not_found (404), method_not_allowed (405), not_implemented (501), internal_error (500).
- Las cifras de los ejemplos de la documentación son inventadas; sólo las respuestas reales de la API son datos.

## Recursos

- GET /v1/issuers: catálogo de emisores del mercado continuo (ticker, isin, nif, lei, name, ingestion, coverage). De aquí salen los id del resto.
- GET /v1/issuers/{id}/annual: cuentas anuales por ejercicio desde el XBRL de la CNMV (revenue, ebitda, net_income, eps_basic, total_debt, free_cash_flow, dividend_per_share…). id = ticker (TEF.MC), ISIN o NIF.
- GET /v1/issuers/{id}/results: resultados por periodo (H1, H2, FY y, si hay, Q1–Q4).
- GET /v1/issuers/{id}/ratios: márgenes, ROE, ROA, deuda neta, deuda neta/EBITDA, payout y crecimiento, con formula e inputs.
- GET /v1/issuers/{id}/dividends: dividendos de un emisor en tres bloques: events (anunciados a la CNMV, con la frase de la que sale cada fecha), market (calendario de BME) y estimates (ventana estimada a partir de años anteriores).
- GET /v1/events?from=AAAA-MM-DD&to=AAAA-MM-DD: calendario del mercado español entre dos fechas (máximo 400 días): events, market, estimates, bonus_issues (scrip) y results_dates (presentaciones de resultados anunciadas).
- GET /v1/filings?from=&to=&id=&topic=&register=&limit=: hechos relevantes, cada comunicación de los registros de la CNMV (OIR e IP), como el 8-K de EE. UU.: register, registro, published_at, issuer (o null), entity, title, category, topics (dividendo, resultados, junta, consejo, recompra) y url. Por defecto la última semana; limit hasta 500; truncated dice si había más.
- GET /v1/issuers/{id}/filings: lo mismo para un emisor; por defecto el último año.
- GET /v1/us/dividends?symbol=&from=&to=: calendario de dividendos de EE. UU. (Nasdaq), por ex-date.
- GET /v1/market/dividends?symbol=: dividendos de cualquier valor de NYSE, Londres u otros mercados (symbol obligatorio, con sufijo fuera de EE. UU., p. ej. DGE.L).
- GET /v1/issuers/{id}/facts: reservada; responde 501 not_implemented.
- GET /health: sin clave; 200 {"status":"ok"} si el servicio llega a su base de datos.

## Documentación

- /docs: documentación completa, explorador en el navegador y formulario de clave gratis.
- /precios: planes.