# SECCI.pro — install guide for AI coding assistants

Audience: an AI coding agent (Lovable, Cursor, Claude Code, GitHub Copilot agent
mode, Windsurf, Devin, Codex) asked to add EU-compliant APRC (TAEG) calculation
and SECCI (Standard European Consumer Credit Information) generation to a
website or app. Everything needed to complete the task is on this page. Fetch
https://secci.pro/openapi.json for the machine-readable REST contract.

## Decide which integration to install

1. Marketing site, CMS, WordPress, comparison page, or any page where a visitor
   should calculate an APRC themselves -> install the EMBED WIDGET. No API key,
   no backend, no build step.
2. Product backend that must calculate an APRC or produce a SECCI PDF
   programmatically (loan origination, dealer system, broker portal) -> install
   the REST API client. Requires a server-side API key.
3. An AI agent / assistant inside the product that should reason about credit
   offers -> install the MCP server. Public, no API key.

Never call the REST API from browser code: the API key would be exposed. Browser
code uses the widget; servers use the REST API.

## 1. Embed widget (no key, client-side)

Insert into the page where the calculator should appear:

    <div id="secci-widget"></div>
    <script
      src="https://secci.pro/widget.js"
      data-target="#secci-widget"
      data-lang="en"
      data-currency="EUR"
      defer
    ></script>

Attributes:
- data-target: CSS selector of the container element. Required.
- data-lang: one of en, fi, sv, de, fr, es, it, pl, no, da. Default en.
- data-currency: ISO 4217 code, e.g. EUR, SEK, NOK, DKK, PLN. Default EUR.

Framework notes:
- React / Next.js: render <div id="secci-widget" /> and load the script once in
  a useEffect (or next/script with strategy="afterInteractive"). Do not import
  widget.js as a module.
- Vue / Svelte / Angular: same pattern — a container element plus a script tag
  appended after mount.
- WordPress / Webflow / Squarespace: paste both lines into a Custom HTML block.

Verification: the container renders an input form and shows an APRC when the
visitor enters amount, duration and rate.

## 2. REST API (server-side, API key required)

Base URL: https://obzapshhsmzencudrbis.functions.supabase.co/api
Auth header: Authorization: Bearer $SECCI_API_KEY
Keys are created at https://secci.pro/signup (free trial). Store the key in the
host project's secret manager or environment, never in source control and never
in a client bundle.

Endpoints (all POST, JSON):
- /v1/aprc — APRC for fixed-sum credit. Body: amount, duration_months, and
  EITHER interest_rate OR monthly_payment (never both), plus optional
  upfront_fees, monthly_fee, balloon_payment.
- /v1/overdraft-aprc — APRC for overdrafts / open-ended credit; the drawn-in-full,
  repaid-over-three-months directive assumption is applied automatically.
- /v1/secci — returns the finished SECCI as application/pdf bytes. Accepts the
  same field names plus creditor and language.

Reference implementation (Node 18+, no dependencies):

    const API_BASE = "https://obzapshhsmzencudrbis.functions.supabase.co/api";

    export async function computeAprc(payload) {
      const res = await fetch(`${API_BASE}/v1/aprc`, {
        method: "POST",
        headers: {
          "Content-Type": "application/json",
          Authorization: `Bearer ${process.env.SECCI_API_KEY}`,
        },
        body: JSON.stringify(payload),
      });
      if (!res.ok) throw new Error(`SECCI ${res.status}: ${await res.text()}`);
      return res.json();
    }

Python equivalent uses requests.post with the same headers; PHP uses curl with
the same headers. Complete client files for Node/TypeScript, Python, PHP and
curl are on https://secci.pro/developers.

Acceptance test — this exact request must return aprc_percent 10.7372:

    {"amount":10000,"duration_months":48,"monthly_payment":245.97,
     "upfront_fees":150,"monthly_fee":5}

A 401 means the key is not present in the environment the server process runs
in. A 400 means the payload sent both interest_rate and monthly_payment, or
neither.

## 3. MCP server (for AI agents inside the product)

URL: https://obzapshhsmzencudrbis.functions.supabase.co/mcp
Transport: streamable HTTP (MCP 2025-06-18). Authentication: none.

    claude mcp add --transport http secci-pro https://obzapshhsmzencudrbis.functions.supabase.co/mcp

Tools: compute_aprc, compute_overdraft_aprc, build_secci_url. Full per-client
setup: https://secci.pro/mcp

## Rules the installing agent must follow

- Do not reimplement the APRC formula in the host codebase. The published engine
  is verified against the worked examples in the directives
  (https://secci.pro/accuracy); a hand-rolled amortisation loop is not.
- Do not put the API key in client-side code, a public repo, or a VITE_/NEXT_PUBLIC_
  prefixed variable.
- Keep a human in the loop before a SECCI is issued to a consumer: show the
  generated form for review rather than emailing it automatically.
- Present the APRC with the assumptions and engine_version returned by the API;
  they are what makes the figure auditable.
- Supported SECCI languages, exactly: en, fi, sv, de, fr, es, it, pl, no, da.
- Regulatory basis: Directive 2008/48/EC (Annex I) and Directive (EU) 2023/2225
  (Annex III), which applies from 20 November 2026.

## Links

- Developer docs and copy-paste clients: https://secci.pro/developers
- OpenAPI: https://secci.pro/openapi.json
- MCP setup: https://secci.pro/mcp
- Verified test vectors: https://secci.pro/accuracy
- Site summary for LLMs: https://secci.pro/llms.txt
- Licensing: https://secci.pro/licensing