Official Company Signals

Endpoints REST y créditos

Cada ruta es relativa al endpoint base. No se cobra una petición que falla, no es válida o no encuentra ninguna empresa.

Las comunidades de bienes y las sociedades civiles (NIF que empieza por E o J) pueden identificar a sus miembros, por lo que nunca se perfilan: el endpoint de actividad las rechaza con personal_data_entity y el resumen devuelve sus registros con activity a null y activity_unavailable explicando el motivo.

curl -H "Authorization: Bearer $FORMA_API_KEY" \
  "https://<forma-host>/api/v1/company-signals/companies/{cif}/overview?limit=10"

{
  "data": {
    "company": {
      "id": "6f1a2b3c-0000-4000-8000-000000000001",
      "cif": "DEMO-NIF-0001",
      "name": "Ejemplo Servicios SL",
      "province": null,
      "sector": null,
      "legal_form": "Sociedad de responsabilidad limitada",
      "may_identify_individuals": false
    },
    "activity": {
      "as_of": "2026-10-15T09:00:00.000Z",
      "awards": {
        "total": 14,
        "last_12_months": 5,
        "previous_12_months": 3,
        "first_at": "2019-03-12T00:00:00+00:00",
        "last_at": "2026-09-30T00:00:00+00:00",
        "months_since_last": 0,
        "active_years": 6,
        "distinct_procedures": 12,
        "corrected_or_withdrawn": 1
      },
      "awarded_amount": {
        "currency": "EUR",
        "awards_with_amount": 12,
        "total": 412500,
        "last_12_months": 98000,
        "previous_12_months": 61000,
        "median": 18250
      },
      "award_trend": "up",
      "track_record": "established",
      "method_version": "2026-10-05"
    },
    "activity_unavailable": null,
    "recent_signals": [
      {
        "id": "6f1a2b3c-0000-4000-8000-000000000002",
        "type": "public_contract_award",
        "title": "Servicio de mantenimiento del alumbrado público",
        "summary": "Figura como adjudicataria (lote 2).",
        "published_at": "2026-09-30T00:00:00+00:00",
        "source_id": "placsp",
        "source_url": "https://example.invalid/placsp/entry",
        "external_id": "demo-entry#lot:2#DEMO-NIF-0001",
        "evidence": {
          "amount": {
            "value": 12500,
            "currency": "EUR"
          },
          "lot_id": "2",
          "buyer_name": "Ayuntamiento de Villa Ejemplo",
          "buyer_id": "DEMO-DIR3-0001",
          "buyer_id_scheme": "DIR3"
        },
        "created_at": "2026-10-01T04:10:00+00:00",
        "source": {
          "id": "placsp",
          "name": "Public procurement platform",
          "url": "https://contrataciondelestado.es/",
          "status": "active",
          "last_synced_at": "2026-10-15T05:00:00+00:00"
        }
      }
    ],
    "next_cursor": "WyIyMDI2LTA5LTMwVDAwOjAwOjAwKzAwOjAwIiwiLi4uIl0",
    "corrections_count": 1,
    "sources": [
      {
        "id": "placsp",
        "name": "Public procurement platform",
        "url": "https://contrataciondelestado.es/",
        "status": "active",
        "last_synced_at": "2026-10-15T05:00:00+00:00"
      }
    ],
    "notice": "Descriptive figures computed from official public-procurement awards. This is not a credit, solvency or risk assessment, does not predict payment behaviour, and must not be the sole basis of a decision about any company or person. Verify against the official sources. Data from official sources, collected and processed automatically by Forma. It may contain errors, omissions or delays. Verify each record against its official source (source_url) before relying on it, and report problems with the report_issue MCP tool or the Report button in Forma.",
    "attribution": [
      {
        "source_id": "placsp",
        "publisher": "Ministerio de Hacienda — Plataforma de Contratación del Sector Público",
        "statement": "Origen de los datos: Ministerio de Hacienda",
        "terms_url": "https://www.hacienda.gob.es/es-ES/Paginas/AvisoLegal.aspx"
      }
    ]
  },
  "meta": {
    "credits": 2,
    "request_id": "…",
    "notice": "Data from official sources, collected and processed automatically by Forma. It may contain errors, omissions or delays. Verify each record against its official source (source_url) before relying on it, and report problems with the report_issue MCP tool or the Report button in Forma."
  }
}

Evidencia de cada adjudicación

Cada adjudicación de contrato público incluye evidencia estructurada del anuncio oficial. Una clave solo aparece cuando la fuente la publica.

• contract_folder_id, lot_id, contract_ids: Identificadores del expediente, el lote y los contratos.
• winner_name, winner_nif: La empresa adjudicataria tal como la nombra el anuncio.
• amount: Importe adjudicado y moneda; no aparece en los acuerdos marco sin importe fijo.
• buyer_name, buyer_id, buyer_id_scheme: El órgano de contratación que adjudicó: su nombre oficial y, cuando se publica, su código de unidad DIR3 o su NIF. Nunca se incluyen los datos de contacto de su personal.

Filtros y paginación

• since, until: Fechas ISO (2025-01-31) o fechas y horas con desfase, ambas inclusivas; una fecha abarca todo su día UTC.
• type: Repítelo o separa con comas para quedarte solo con esos tipos de registro, por ejemplo public_contract_award.
• limit: Registros por página, de 1 a 200, 25 por defecto.
• cursor: El next_cursor de la página anterior, devuelto sin cambios con los mismos filtros. Es null en la última página. Los registros corregidos o retirados solo llegan con la primera página.

# First page: awards published in 2025, 50 per page
curl -H "Authorization: Bearer $FORMA_API_KEY" \
  "https://<forma-host>/api/v1/company-signals/companies/{cif}/signals?since=2025-01-01&until=2025-12-31&limit=50"

# Next page: same filters plus the next_cursor of the previous response
curl -H "Authorization: Bearer $FORMA_API_KEY" \
  "https://<forma-host>/api/v1/company-signals/companies/{cif}/signals?since=2025-01-01&until=2025-12-31&limit=50&cursor=<next_cursor>"

Herramientas MCP

Endpoint Streamable HTTP para clientes MCP que pueden enviar la cabecera bearer. Las herramientas cobran los mismos créditos que REST. Cada resultado incluye contenido estructurado validado por el esquema de salida de la herramienta y un breve resumen en texto con los registros principales, sus enlaces oficiales y la siguiente llamada que hacer.

POST /mcp/company-signals
Authorization: Bearer forma_live_••••••••••••

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_company_signals",
    "arguments": {
      "cif": "{cif}",
      "since": "2025-01-01",
      "limit": 50
    }
  }
}

Ejemplo Servicios SL (NIF DEMO-NIF-0001, Sociedad de responsabilidad limitada): 50 official records, newest first.
- 2026-09-30 public_contract_award: Servicio de mantenimiento del alumbrado público · 12,500 EUR · buyer: Ayuntamiento de Villa Ejemplo · https://example.invalid/placsp/entry
- …
- … 40 more in the structured result.
Top buyers (contracting bodies) in these 50 records: Ayuntamiento de Villa Ejemplo (18 awards, 214,300 EUR); Consorcio Demo de Aguas (9 awards, 96,000 EUR); Diputación Provincial Ejemplo (6 awards); 7 more.
More: call get_company_signals again with the same filters and cursor "<next_cursor>" (1 credit per page).
Attribution (reproduce if you republish): Origen de los datos: Ministerio de Hacienda.
Notice: Data from official sources, collected and processed automatically by Forma. It may contain errors, omissions or delays. Verify each record against its official source (source_url) before relying on it, and report problems with the report_issue MCP tool or the Report button in Forma.

Errores

REST responde con un estado HTTP y un cuerpo {"error": {"code", "message"}}. Las herramientas MCP devuelven el mismo código y mensaje como resultado de error, seguidos de qué hacer a continuación.

Exactitud de los datos

Datos de fuentes oficiales, recogidos y procesados automáticamente por Forma. Pueden contener errores, omisiones o retrasos. Comprueba cada registro en su fuente oficial (source_url) antes de basarte en él y comunica cualquier problema con la herramienta MCP report_issue o el botón Reportar de Forma.

Cada respuesta REST repite este aviso en meta.notice y cada resultado MCP en notice. Las cifras de actividad son recuentos e importes descriptivos, nunca una evaluación de crédito, solvencia o riesgo.