# info.description
Real-time due-diligence data on Lithuanian legal entities, retrieved on demand from the state
registers administered by VĮ Registrų centras (JAR, JADIS, JANGIS, NTR) and from the Lithuanian
court information system (LITEKO), normalized to JSON and delivered machine-to-machine.

The service is provided as a legal service by a Lithuanian advokatas. It is **not public**:
production keys are issued only after the client signs the engagement agreement (TPS) with a
qualified electronic signature. The TPS carries the data-protection framework: purpose limitation,
the legitimate-interest attestation for beneficial-owner data, and retention terms. See Get access.

## Response tiers
  * **Plain JSON** (default): `application/json`, integrity by TLS. Every response envelope
    carries `meta.responseId` and the retrieval timestamp.
  * **Signed JSON**: `?sign=jades-t` or `?sign=jades-lt` returns `application/jose+json` - the
    same JSON envelope wrapped in a JAdES signature (ETSI TS 119 182-1, flattened JWS JSON
    serialization) created with the qualified electronic signature of the responsible advokatas
    and a qualified timestamp (level T); level LT additionally embeds the certificate chain and
    revocation material for long-term validation. Verifiable with the EU DSS library.
  * **Evidence container**: `?format=asice` returns `application/vnd.etsi.asic-e+zip` - an
    ASiC-E container holding the normalized JSON, the raw source XML exactly as returned by the
    register, and a qualified signature at LT level with a qualified timestamp. Suitable for
    audit files and court use; validates with standard EU validators.

Signing is inline and synchronous; a signed tier typically adds 0.5-1.5 s to the response time.
`sign` and `format=asice` are mutually exclusive.

## What the signature means
  The signature certifies **provenance and integrity**: that the identified advokatas relayed
  this data unmodified from the named official source at the stated time, as part of a legal
  service. A response is NOT an official document issued by VĮ Registrų centras; official
  RC-issued documents are a separate deliverable of the Tvarka platform.

## Billing
  Pay-per-use, metered per successful data delivery: one `dd.pull.<product>` usage event per
  answered call, plus `dd.sign.jades_t` / `dd.sign.jades_lt` / `dd.sign.asice` for signed tiers.
  A no-data answer (404 with problem type ending `/no-data`) and upstream register failures
  (502) are NOT billed. Prices are published on the docs page; volume tiers apply to the plain
  tier.

## Beneficial-owner (UBO) data
  JANGIS beneficial-owner data is served under the legitimate-interest regime. The client's
  standing legal basis is attested in the TPS; each UBO call MUST carry a `purpose`, which is
  logged per call.

## Get access
  Sandbox keys (fixture data, zero-rated) are self-serve after a short review. Production keys
  require BOTH acceptance of the Terms of Service (https://api.tvarka.pro/terms) and a
  QES-signed TPS; a 403 names whichever is missing. The same surface is also exposed as an MCP server for agent
  integrations; tool names mirror the `operationId`s of this contract. MCP tools take the
  Lithuanian legal-entity code as their key input; the property-object-by-unique-number
  operation is REST-only.

# info.x-status
v0.1.0 (2026-08-11). PLAIN TIER IMPLEMENTED (tvarka/dd_api/), behind FEATURE_DD_API_ENABLED, not yet deployed: key auth with TPS-gated production access, per-call metering with the ratified price table, sandbox environment answering synthetic payloads at zero price, and the six register-backed products plus the composite report over the production rc_broker path (ActionTypes 17/249/437 and the NTR pair 90+95/190) and the litigation archive. SIGNED TIERS FAIL CLOSED: sign / format=asice answer 503 until the unattended PKCS#11 signing worker exists, and the feature flag alone cannot serve an unsigned body at a signed price. Personal codes are exposed on production keys (owner decision 2026-08-11). Signing host is staged: operator workstation first (existing Tvarka middleware in high-risk non-interactive PIN mode as the polling worker), then a dedicated Ubuntu box on the same worker protocol. Seizures (TAAR) answers 503 product-unavailable until its ActionType is confirmed from the broker catalog (info.php); never guess ActionTypes. Not yet wired into docs publication or scripts/check_atk_openapi.py.

# servers[].description
Production. Final host is set at implementation; sandbox is selected by key type on the same host.

# tags[].description
Registry data on a Lithuanian legal entity, addressed by its JAR code.

# tags[].description
Real Property Register data, legal-entity scope only.

# paths./v1/entities/{code}.get.summary
Entity profile - core JAR attributes and current management.

# paths./v1/entities/{code}.get.description
Extended JAR data: name, legal form, status, registered address, registration dates, capital, activities, and current management members. Source product JAR_ISPLESTINIS.

# paths./v1/entities/{code}.get.responses.200.content.application/json.example.meta.disclaimer
Real-time data relay by Tvarka, provided as a legal service by a Lithuanian advokatas. Not an official document issued by VĮ Registrų centras.

# paths./v1/entities/{code}/ubo.get.summary
Beneficial owners declared in JANGIS (legitimate-interest gated).

# paths./v1/entities/{code}/ubo.get.description
Beneficial-owner declarations. Requires a `purpose` on every call; the standing legal basis is attested in the client's TPS. Source product JANGIS_NAUDOS_GAVEJAI.

# paths./v1/entities/{code}/ubo.get.responses.200.description
Beneficial-owner declaration in the requested tier.

# paths./v1/entities/{code}/real-estate.get.summary
Real property held by the legal entity, with rights summary.

# paths./v1/entities/{code}/real-estate.get.description
Objects and rights registered to the legal entity in the Real Property Register. Legal-entity scope only; natural-person property searches are not offered. Source product NTR_JA_TURTAS.

# paths./v1/real-estate/{uniqueNumber}.get.summary
Full register extract for one property object, by unique number.

# paths./v1/real-estate/{uniqueNumber}.get.description
Resolves the object and returns the full register extract (register data, objects, persons, rights, and the register's own labeled technical detail). Internally a two-step register chain; billed as one product. Source product NTR_OBJEKTAS.

# paths./v1/entities/{code}/cases.get.summary
Court-case involvement from the LITEKO hearing calendar.

# paths./v1/entities/{code}/cases.get.description
Hearings and case participation where the entity appears as a party, from the LITEKO court-hearing calendar (weekly full refresh plus on-demand freshening). Field mapping is PRELIMINARY until the litigation model mapping is finalized.

# paths./v1/entities/{code}/seizures.get.summary
Property seizure acts pertinent to the entity (Turto arešto aktų registras).

# paths./v1/entities/{code}/seizures.get.description
Seizure acts where the entity appears, from the Property Seizure Acts Register administered by VĮ Registrų centras, with the parties and the seized assets recorded on each act. An entity with no acts is a clean record, not a no-data answer, and is answered and billed as such. Source product TAAR_ISRASAS.

# paths./v1/entities/{code}/dd-report.get.summary
Composite due-diligence report - profile, participants, UBO, property, seizures, cases.

# paths./v1/entities/{code}/dd-report.get.description
One call, one billable bundle: entity profile, participants, beneficial owners, real property with rights, seizure acts, and case involvement. Requires `purpose` because the bundle contains beneficial-owner data.

# components.securitySchemes.apiKey.description
Per-client API key, issued after TPS signature (production) or docs-page review (sandbox). Send as `Authorization: Bearer <key>`.

# components.parameters.EntityCode.description
Lithuanian legal-entity code (JAR kodas).

# components.parameters.UniqueNumber.description
Real Property Register unique object number (unikalus numeris), e.g. 4400-2038-0234.

# components.parameters.Sign.description
Signature tier for the JSON envelope. `jades-t` adds a qualified signature and qualified timestamp; `jades-lt` additionally embeds revocation material for long-term validation. Mutually exclusive with `format=asice`.

# components.parameters.Format.description
`asice` returns the evidence container (normalized JSON + raw register XML + qualified LT-level signature) instead of a JSON body. Mutually exclusive with `sign`.

# components.parameters.Purpose.description
Purpose of processing for this call; logged. The standing basis is attested in the TPS.

# components.parameters.PurposeNote.description
Free-text clarification, expected when purpose is OTHER.

# components.responses.BadRequest.description
Validation problem (bad code format, conflicting sign/format, missing purpose).

# components.responses.Forbidden.description
Production access is not (yet) open for this client. The problem type says which precondition is missing: `/tps-required` when the engagement agreement is not signed, `/terms-acceptance-required` when the Terms of Service have not been accepted. Also returned when the key's scope does not cover this product or data category.

# components.responses.NotFound.description
Unknown entity or the register returned no data (problem type ends `/no-data`). Not billed.

# components.responses.UpstreamUnavailable.description
The source register did not answer. Not billed.

# components.schemas.Meta.properties.source.description
The source register(s) behind this answer, e.g. "VĮ Registrų centras", "LITEKO", or both for the composite report. Sandbox responses read "Sandbox (synthetic data)" so synthetic data can never be mistaken for a register answer.

# components.schemas.Meta.properties.disclaimer.description
Fixed wording: a real-time data relay provided as a legal service by a Lithuanian advokatas, and not an official document issued by VĮ Registrų centras.

# components.schemas.JadesJson.description
JAdES flattened JWS JSON serialization (ETSI TS 119 182-1). The `payload` is the same JSON envelope served by the plain tier, byte-for-byte. Flattened JSON rather than compact because every level we ship carries unsigned properties (`etsiU`), which a compact JWS cannot hold. Verify with the EU DSS library; note that the signature is computed over the SHA-256 of the JWS signing input, so verification must treat it as prehashed.

# components.schemas.JadesJson.properties.protected.description
base64url of the signed header (alg RS256, x5c chain, x5t#S256, and the critical `sigT` claimed signing time).

# components.schemas.JadesJson.properties.header.properties.etsiU.description
base64url-encoded JAdES unsigned components, in order: `sigTst` (the qualified signature timestamp) always; for the LT level also `xVals` (certificate chain) and `rVals` (OCSP revocation values, fetched after the timestamp).

# components.schemas.AsiceContainer.description
ASiC-E evidence container. payload.json (normalized envelope), source.xml (raw register response), and the qualified LT-level signature with qualified timestamp.

# components.schemas.ManagementMember.properties.personalCode.description
Personal code (asmens kodas), returned on production keys. Processing basis is the client's TPS; UBO and dd-report calls additionally log the declared purpose.

# components.schemas.EntityProfile.properties.euid.description
European Unique Identifier as used in BRIS, when derivable.

# components.schemas.EntityProfile.properties.lei.description
Legal Entity Identifier, when one exists.

# components.schemas.Participant.properties.personalCode.description
Personal code of a natural-person participant

# components.schemas.RealEstateObjectData.properties.sections.description
The register's own labeled technical detail for the object, preserved as returned.

# components.schemas.CaseItem.description
PRELIMINARY mapping from the LITEKO hearing calendar.

# components.schemas.SeizureActAsset.properties.typeCode.description
Register's asset-type code. Passed through as a code because the register publishes no label set for it; inventing names would mean guessing.

# components.schemas.SeizureActAsset.properties.details.description
The register returns asset attributes positionally, and their meaning depends on the asset type (for a vehicle: make and model, VIN, registration plate). They are published in the order given rather than under invented field names.

# components.schemas.SeizureAct.properties.actName.description
Act title as registered, usually including the enforcement case number.

# components.schemas.SeizureAct.properties.issuingAuthority.description
The institution that imposed the seizure, typically a bailiff.

# components.schemas.SeizureAct.properties.legalBasis.description
The court order or other instrument the seizure rests on.

# components.schemas.SeizureAct.properties.amount.description
Secured amount as recorded, e.g. "28149,31 Eur".

# components.schemas.SeizureAct.properties.priority.description
Creditor priority queue, e.g. "III eilė".