# Status & Session

These endpoints establish that the SDC is ready and unlock signing for the session.

## GET /api/v3/attention

Lightweight health check. Returns whether the SDC is available and which card readers are connected.

```
GET /api/v3/attention

200 OK
{
  "available": true,
  "readers": ["ACS ACR39U ICC Reader 0"]
}
```

## GET /api/v3/status

The E-SDC status document. Read this before signing.

<table id="bkmrk-fieldmeaning-ispinre"><thead><tr><th>Field</th><th>Meaning</th></tr></thead><tbody><tr><td>`isPinRequired`</td><td>`true` if a PIN must be verified before signing.</td></tr><tr><td>`auditRequired`</td><td>`true` when the Secure Element has reached its limit and an audit is due.</td></tr><tr><td>`sdcDateTime`</td><td>The SDC's current date/time (use this as the fiscal clock).</td></tr><tr><td>`protocolVersion`</td><td>POS-to-SDC protocol version.</td></tr><tr><td>`secureElementVersion`</td><td>SE applet version.</td></tr><tr><td>`make`, `model`, `softwareVersion`, `hardwareVersion`, `deviceSerialNumber`</td><td>Device identity.</td></tr><tr><td>`uid`</td><td>Secure Element UID.</td></tr><tr><td>`currentTaxRates`</td><td>The tax-rate group currently in force (the labels/categories you may use on items).</td></tr><tr><td>`allTaxRates`</td><td>All known tax-rate groups (including future-dated).</td></tr><tr><td>`gsc`</td><td>Status codes, e.g. `1300` (SE not present), `2400` (SE limit reached).</td></tr></tbody></table>

## POST /api/v3/pin

Verifies the operator PIN on the Secure Element and caches it in memory for the session. **The request body is the PIN as plain text** (digits) — not JSON. The response is a 4-digit text response code.

```
POST /api/v3/pin
Content-Type: text/plain

3456

200 OK
0100
```

<table id="bkmrk-responsemeaning-0100"><thead><tr><th>Response</th><th>Meaning</th></tr></thead><tbody><tr><td>`0100`</td><td>PIN verified — signing is unlocked.</td></tr><tr><td>`2100`</td><td>PIN incorrect / no usable PIN supplied.</td></tr><tr><td>`2110`</td><td>Blocked, or only one attempt remains (the SDC refuses the last attempt to avoid locking the card).</td></tr><tr><td>`1300`</td><td>Secure Element not present / unreadable.</td></tr></tbody></table>

**Card safety:** the SDC will not spend the final PIN attempt. If only one try remains it returns `2110` rather than risk permanently locking the card — resolve the correct PIN before retrying.

## Secure Element helpers (read-only)

Useful for status displays and pre-flight checks; none of these sign or consume a PIN attempt.

<table id="bkmrk-endpointreturns-get-"><thead><tr><th>Endpoint</th><th>Returns</th></tr></thead><tbody><tr><td>`GET /api/v3/se/identity`</td><td>Seller identity from the SE certificate: `uid`, `tin`, `businessName`, `locationName`, `address`, `state`, `validFrom`, `validTo`, TaxCore URL.</td></tr><tr><td>`GET /api/v3/se/amount-status`</td><td>`saleRefund` (amount accumulated) and `limit`.</td></tr><tr><td>`GET /api/v3/se/pin-tries`</td><td>`triesLeft`.</td></tr><tr><td>`GET /api/v3/se/safety`</td><td>A safety snapshot: PIN tries left, whether blocked, amount used/limit/remaining, used fraction.</td></tr><tr><td>`GET /api/v3/se/version`</td><td>SE applet `version`.</td></tr></tbody></table>