# HowToRomania

> Data from Romanian public registries for AI agents: companies (ANAF, ONRC), courts, e-Factura, legislation. REST + MCP. Prepaid credits, 1 credit = €0.005 at the smallest pack, 100 free credits.

Base URL: https://api.howtoromania.io · MCP (streamable HTTP): https://api.howtoromania.io/mcp · OpenAPI: https://api.howtoromania.io/openapi.json · Docs: https://api.howtoromania.io/docs

## Services (credits per successful call)
- GET /v1/company/{cui} · MCP lookup_company · 1 cr · ANAF registry data by CUI/VAT id: name, address, status, VAT, e-Factura, BNR EUR/RON
- GET /v1/company/{cui}/financials · MCP get_company_financials · 5 cr · Up to 5 years of filed accounts + ratios (RON)
- GET /v1/company/{cui}/representatives · MCP get_company_representatives · 2 cr · Trade-register status, CAEN codes, representatives (name, role)
- GET /v1/company/{cui}/risk-report · MCP get_company_risk_report · 8 cr · Status + financials + court cases + registry, score 0-100 with explained flags
- GET /v1/company/{cui}/court-cases · MCP get_company_court_cases · 3 cr · Cases where the company is a party (portal.just.ro), summary + list
- GET /v1/court-cases/{caseNumber} · MCP get_court_case · 1 cr · Parties, hearings, outcomes, appeals
- POST /v1/efactura/validate · MCP validate_efactura · 1 cr · validated with ANAF's public validation service (CIUS-RO) + local checks, rule codes
- POST /v1/efactura/generate · MCP generate_efactura · 2 cr · CIUS-RO UBL from simple JSON; parties auto-filled from CUI; validated with ANAF's public validation service
- POST /v1/efactura/parse · MCP parse_efactura · 1 cr · UBL Invoice/CreditNote -> English JSON
- POST /v1/efactura/pdf · MCP efactura_to_pdf · 1 cr · rendered with ANAF's public PDF service
- GET /v1/legislation/search · MCP search_legislation · 1 cr · By citation ('Legea 31/1990') or title words
- GET /v1/legislation/act/{id} · MCP get_legal_act · 1 cr · Current consolidated text, split by article
- GET /v1/legislation/act/{id}/article/{n} · MCP get_legal_article · 1 cr · One article + dated amendment notes
- GET /v1/legislation/act/{id}/history · MCP get_legal_act_history · 2 cr · Consolidation dates, dated amendments per article
- GET /v1/legislation/new · MCP get_new_legal_acts · 1 cr · Acts in force since a date (max 35 days)

## Pricing
€5 = 1,000 credits (€0.005/credit) · €20 = 5,000 · €100 = 30,000. 100 free credits per key. Errors and not-found are never billed.

## Keys
- Free key (100 credits): POST https://api.howtoromania.io/v1/keys {"email":"you@example.com","accept_terms":true} → {"apiKey":"htr_…"} (shown once)
- Public demo key: `htr_demo`, no signup, 20 calls/day per IP, only: company.lookup, court.case, efactura.validate, efactura.parse, legislation.search, legislation.article, legislation.new
- Send as `x-api-key: <key>` or `Authorization: Bearer <key>`. MCP initialize/tools/list work without a key.
- Out of credits → HTTP 402 with checkout links. Balance: GET /v1/me. Prices: GET /v1/pricing.

## Examples
- Company lookup: curl -H "x-api-key: htr_demo" "https://api.howtoromania.io/v1/company/14399840"
- Financial statements: curl -H "x-api-key: htr_demo" "https://api.howtoromania.io/v1/company/14399840/financials?years=3"
- Legal representatives (ONRC): curl -H "x-api-key: htr_demo" "https://api.howtoromania.io/v1/company/14399840/representatives"
- Risk report (KYB): curl -H "x-api-key: htr_demo" "https://api.howtoromania.io/v1/company/14399840/risk-report"
- Company court cases: curl -H "x-api-key: htr_demo" "https://api.howtoromania.io/v1/company/14399840/court-cases?limit=20"
- Court case by number: curl -H "x-api-key: htr_demo" "https://api.howtoromania.io/v1/court-cases/9430%2F271%2F2025"
- Validate invoice XML: curl -X POST -H "x-api-key: <key>" -H "content-type: application/xml" --data-binary @invoice.xml https://api.howtoromania.io/v1/efactura/validate
- Generate invoice XML: curl -X POST -H "x-api-key: <key>" -H "content-type: application/xml" --data-binary @invoice.xml https://api.howtoromania.io/v1/efactura/generate
- Parse invoice XML: curl -X POST -H "x-api-key: <key>" -H "content-type: application/xml" --data-binary @invoice.xml https://api.howtoromania.io/v1/efactura/parse
- Invoice PDF: curl -X POST -H "x-api-key: <key>" -H "content-type: application/xml" --data-binary @invoice.xml https://api.howtoromania.io/v1/efactura/pdf
- Search acts: curl -H "x-api-key: htr_demo" "https://api.howtoromania.io/v1/legislation/search?q=Codul%20fiscal"
- Act (in force): curl -H "x-api-key: htr_demo" "https://api.howtoromania.io/v1/legislation/act/171282?limit=5"
- Article (in force): curl -H "x-api-key: htr_demo" "https://api.howtoromania.io/v1/legislation/act/171282/article/291"
- Amendment history: curl -H "x-api-key: htr_demo" "https://api.howtoromania.io/v1/legislation/act/171282/history?article=291"
- New acts: curl -H "x-api-key: htr_demo" "https://api.howtoromania.io/v1/legislation/new"

## e-Factura generate body (JSON)
{"number":"INV-1","seller":{"vatId":"DE123456789","name":"Acme GmbH","street":"Hauptstr 1","city":"Berlin","country":"DE"},"buyer":{"cui":"14399840"},"currency":"EUR","vatToRonRate":5.09,"lines":[{"name":"Consulting","quantity":10,"unitCode":"HUR","unitPrice":120,"vatCategory":"AE","vatRate":0}]}

## Example agent tasks
- KYB on a Romanian supplier: "Before we sign with supplier RO14399840, check it's active, VAT-registered, and summarize risk flags." → get_company_risk_report (8)
- Verify a VAT id on an invoice: "Is RO14399840 a valid, active Romanian VAT payer? Return legal name and registered address." → lookup_company (1)
- Who can sign for the company: "List the legal representatives of CUI 14399840 and their roles." → get_company_representatives (2)
- Financial health check: "Show turnover, net profit and employees for CUI 14399840 for the last 3 years, with YoY growth." → get_company_financials (5)
- Litigation screen: "Is CUI 14399840 a defendant in any insolvency or pending civil cases since 2024?" → get_company_court_cases (3)
- Invoice a Romanian client (cross-border): "Create an e-Factura invoice from our German company DE123456789 to RO14399840: 10 hours consulting at €120, reverse charge." → generate_efactura (2)
- Fix a rejected e-Factura: "ANAF rejected this XML. Validate it and tell me exactly which rules fail and how to fix them." → validate_efactura (1)
- Read an incoming Romanian invoice: "Parse this e-Factura XML and give me supplier, totals, VAT and IBAN in JSON for our ERP." → parse_efactura (1)
- Current Romanian VAT rate: "What VAT rates apply in Romania today per Codul fiscal art. 291, and when did they last change?" → get_legal_article (1) + get_legal_act_history (2)
- Monitor new Romanian law: "List Romanian acts that entered into force this week that affect taxes or companies." → get_new_legal_acts (1)

## Notes
- CUI = Romanian fiscal code (digits, optional RO prefix), checksum-validated.
- Legislation ids: Codul fiscal 171282, Codul muncii 41627, Codul civil 175630, Codul de procedură civilă 140271, Codul de procedură fiscală 170007, Legea 31/1990 798. Consolidated text is informational; only Monitorul Oficial is authentic.
- Court data: natural persons masked. Risk report is informational, not credit advice.
- Contact: hello@howtoromania.io