@12-apps/fiscal 0.0.0-stage → 1.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +269 -2
- package/dist/chunk-27B4HNO6.js +574 -0
- package/dist/chunk-27B4HNO6.js.map +1 -0
- package/dist/chunk-3SDXLSG4.js +24 -0
- package/dist/chunk-3SDXLSG4.js.map +1 -0
- package/dist/chunk-7QVYU63E.js +7 -0
- package/dist/chunk-7QVYU63E.js.map +1 -0
- package/dist/chunk-ALABGVPO.js +247 -0
- package/dist/chunk-ALABGVPO.js.map +1 -0
- package/dist/chunk-FOFIN5M7.js +14 -0
- package/dist/chunk-FOFIN5M7.js.map +1 -0
- package/dist/chunk-HQ2NXSTX.js +85 -0
- package/dist/chunk-HQ2NXSTX.js.map +1 -0
- package/dist/chunk-PNTKG3DZ.js +47 -0
- package/dist/chunk-PNTKG3DZ.js.map +1 -0
- package/dist/chunk-RRFKYVLZ.js +192 -0
- package/dist/chunk-RRFKYVLZ.js.map +1 -0
- package/dist/chunk-V5ZQAAJT.js +210 -0
- package/dist/chunk-V5ZQAAJT.js.map +1 -0
- package/dist/chunk-X6MRDUYH.js +21 -0
- package/dist/chunk-X6MRDUYH.js.map +1 -0
- package/dist/chunk-XQGW5HUG.js +30 -0
- package/dist/chunk-XQGW5HUG.js.map +1 -0
- package/dist/context-ChnWR4Kb.d.ts +455 -0
- package/dist/danfe/en-US.d.ts +12 -0
- package/dist/danfe/en-US.js +51 -0
- package/dist/danfe/en-US.js.map +1 -0
- package/dist/danfe/index.d.ts +50 -0
- package/dist/danfe/index.js +18 -0
- package/dist/danfe/index.js.map +1 -0
- package/dist/danfe/pt-BR.d.ts +11 -0
- package/dist/danfe/pt-BR.js +51 -0
- package/dist/danfe/pt-BR.js.map +1 -0
- package/dist/documents/index.d.ts +169 -0
- package/dist/documents/index.js +1228 -0
- package/dist/documents/index.js.map +1 -0
- package/dist/engine/index.d.ts +118 -0
- package/dist/engine/index.js +591 -0
- package/dist/engine/index.js.map +1 -0
- package/dist/http.d.ts +73 -0
- package/dist/http.js +16 -0
- package/dist/http.js.map +1 -0
- package/dist/issuer/index.d.ts +43 -0
- package/dist/issuer/index.js +131 -0
- package/dist/issuer/index.js.map +1 -0
- package/dist/jobs.d.ts +74 -0
- package/dist/jobs.js +22 -0
- package/dist/jobs.js.map +1 -0
- package/dist/labels-BNvflT0h.d.ts +44 -0
- package/dist/manifest/index.d.ts +97 -0
- package/dist/manifest/index.js +27 -0
- package/dist/manifest/index.js.map +1 -0
- package/dist/manifest/server.d.ts +57 -0
- package/dist/manifest/server.js +25 -0
- package/dist/manifest/server.js.map +1 -0
- package/dist/notifications.d.ts +93 -0
- package/dist/notifications.js +41 -0
- package/dist/notifications.js.map +1 -0
- package/dist/port-DpRFK56U.d.ts +238 -0
- package/dist/sale/index.d.ts +243 -0
- package/dist/sale/index.js +1 -0
- package/dist/sale/index.js.map +1 -0
- package/dist/service-KTjH7AxW.d.ts +139 -0
- package/dist/sidecar/index.d.ts +216 -0
- package/dist/sidecar/index.js +8 -0
- package/dist/sidecar/index.js.map +1 -0
- package/dist/types-B1b8LIWX.d.ts +247 -0
- package/package.json +126 -4
- package/prisma/fiscal.prisma +158 -0
- package/prisma/migrations/20261113220000_fiscal_documents/migration.sql +201 -0
- package/sidecar/.dockerignore +5 -0
- package/sidecar/Dockerfile +68 -0
- package/sidecar/README.md +149 -0
- package/sidecar/composer.json +30 -0
- package/sidecar/composer.lock +2224 -0
- package/sidecar/docker/apache.conf +14 -0
- package/sidecar/docker/icp-brasil.pem +8031 -0
- package/sidecar/docker/mpm.conf +17 -0
- package/sidecar/docker/openssl.cnf +16 -0
- package/sidecar/docker/php.ini +19 -0
- package/sidecar/public/index.php +15 -0
- package/sidecar/schema/sale-for-document.schema.json +401 -0
- package/sidecar/src/ErrorClass.php +31 -0
- package/sidecar/src/Http/Request.php +48 -0
- package/sidecar/src/Http/Response.php +32 -0
- package/sidecar/src/Http/Router.php +59 -0
- package/sidecar/src/Kernel.php +99 -0
- package/sidecar/src/Module.php +31 -0
- package/sidecar/src/Nfe/Classifier.php +89 -0
- package/sidecar/src/Nfe/Credentials.php +52 -0
- package/sidecar/src/Nfe/DocumentMapper.php +383 -0
- package/sidecar/src/Nfe/DocumentSchema.php +39 -0
- package/sidecar/src/Nfe/Input.php +125 -0
- package/sidecar/src/Nfe/Model.php +17 -0
- package/sidecar/src/Nfe/NfeModule.php +62 -0
- package/sidecar/src/Nfe/NfeService.php +504 -0
- package/sidecar/src/Nfe/Sefaz.php +49 -0
- package/sidecar/src/Nfe/SefazReply.php +81 -0
- package/sidecar/src/Nfe/Transport/CurlTransport.php +198 -0
- package/sidecar/src/Nfe/Transport/SoapAdapter.php +57 -0
- package/sidecar/src/Nfe/Transport/Transport.php +20 -0
- package/sidecar/src/Nfe/Transport/TransportFailure.php +42 -0
- package/sidecar/src/RequestLog.php +54 -0
- package/sidecar/src/ServiceError.php +69 -0
- package/src/danfe/en-US.ts +53 -0
- package/src/danfe/index.ts +11 -0
- package/src/danfe/labels.ts +49 -0
- package/src/danfe/pt-BR.ts +52 -0
- package/src/danfe/render.ts +265 -0
- package/src/danfe/xml.ts +45 -0
- package/src/documents/context.ts +260 -0
- package/src/documents/errors.ts +41 -0
- package/src/documents/helpers.ts +128 -0
- package/src/documents/index.ts +39 -0
- package/src/documents/lines.ts +63 -0
- package/src/documents/machine-steps.ts +260 -0
- package/src/documents/machine.ts +128 -0
- package/src/documents/memory.ts +138 -0
- package/src/documents/nfe-proc.ts +51 -0
- package/src/documents/ports.ts +130 -0
- package/src/documents/profile-input.ts +168 -0
- package/src/documents/profile.ts +98 -0
- package/src/documents/service-profile.ts +104 -0
- package/src/documents/service.ts +296 -0
- package/src/documents/settle.ts +121 -0
- package/src/documents/signing.ts +61 -0
- package/src/documents/sql-rows.ts +180 -0
- package/src/documents/sql-store.ts +242 -0
- package/src/documents/sql.ts +18 -0
- package/src/documents/steps.ts +173 -0
- package/src/documents/tests/integration/pglite.ts +73 -0
- package/src/documents/types.ts +193 -0
- package/src/engine/compare.ts +68 -0
- package/src/engine/compute.ts +40 -0
- package/src/engine/errors.ts +28 -0
- package/src/engine/index.ts +20 -0
- package/src/engine/oracle.ts +81 -0
- package/src/engine/plan.ts +268 -0
- package/src/engine/rounding.ts +81 -0
- package/src/engine/types.ts +270 -0
- package/src/engine/validate.ts +222 -0
- package/src/http.ts +264 -0
- package/src/issuer/index.ts +9 -0
- package/src/issuer/port.ts +109 -0
- package/src/issuer/sidecar.ts +171 -0
- package/src/jobs.ts +115 -0
- package/src/manifest/index.ts +46 -0
- package/src/manifest/permissions.ts +28 -0
- package/src/manifest/server.ts +20 -0
- package/src/notifications.ts +120 -0
- package/src/sale/index.ts +8 -0
- package/src/sale/types.ts +292 -0
- package/src/sidecar/index.ts +9 -0
- package/src/sidecar/types.ts +243 -0
- package/tables/ibs-cbs-2026-11-13.json +156 -0
package/README.md
CHANGED
|
@@ -1,3 +1,270 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @12-apps/fiscal
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Brazilian consumption-tax machinery and fiscal documents for any host that
|
|
4
|
+
sells: the **IBS/CBS engine**, the neutral sale document, the fiscal service
|
|
5
|
+
over sped-nfe, and the **fiscal document module** that issues through it.
|
|
6
|
+
|
|
7
|
+
| subpath | what it is |
|
|
8
|
+
|---|---|
|
|
9
|
+
| `@12-apps/fiscal/engine` | `computeTax(input) → TaxBreakdown`: pure, no I/O, no clock, no defaults. Plus `computeTaxWithOracle` over an injected `OfficialCalculator` port, and `compareBreakdowns`. |
|
|
10
|
+
| `@12-apps/fiscal/tables/<file>.json` | Versioned rate tables — DATA, never code. The engine stamps the table's `version` on every result. |
|
|
11
|
+
| `@12-apps/fiscal/documents` | The fiscal document: its state machine, the emitter profile and issuing points, the ports a host implements (store, storage, cipher, sale source), the signing identity, the per-series number draw (`FISCAL_NEXT_NUMBER_SQL`), the engine-to-document line mapping and `createFiscalDocuments`, the service. |
|
|
12
|
+
| `@12-apps/fiscal/issuer` | The Issuer port and its first adapter, `createSidecarIssuer`, over the fiscal service's HTTP contract. |
|
|
13
|
+
| `@12-apps/fiscal/danfe` | The DANFE NFC-e as ESC/POS-ready lines for 58 and 80 mm; `./danfe/pt-BR` carries the Manual's own words. |
|
|
14
|
+
| `@12-apps/fiscal/http`, `/jobs`, `/notifications` | The wiring capabilities: the routes, the job blueprints, the notification blueprints over host copy. |
|
|
15
|
+
| `@12-apps/fiscal/manifest` | The `@12-apps/wiring` manifest: permissions, db, observability, `server: ["http", "jobs"]` (`./manifest/server`). |
|
|
16
|
+
| `@12-apps/fiscal/sale` | `SaleForDocument`, the neutral document shape: one sale, host-agnostic, as the fiscal service accepts it. Types only; its JSON schema is `@12-apps/fiscal/sidecar/schema/sale-for-document.schema.json`. |
|
|
17
|
+
| `@12-apps/fiscal/sidecar` | The fiscal service's wire contract: each endpoint's request and answer, and the error classes (`REJECTED`, `RETRYABLE`, `CONTINGENCY`, `AUTH`, `INVALID`). |
|
|
18
|
+
| `sidecar/` (folder) | The fiscal service itself: PHP over sped-nfe, stateless, with its `Dockerfile` (images pinned by digest). Issues, signs offline, transmits, cancels, looks up and inutilizes NF-e and NFC-e. See [sidecar/README.md](./sidecar/README.md). |
|
|
19
|
+
|
|
20
|
+
## The engine
|
|
21
|
+
|
|
22
|
+
```ts
|
|
23
|
+
import { computeTax } from "@12-apps/fiscal/engine";
|
|
24
|
+
import tables from "@12-apps/fiscal/tables/ibs-cbs-2026-11-13.json" with { type: "json" };
|
|
25
|
+
|
|
26
|
+
const breakdown = computeTax({
|
|
27
|
+
lines: [
|
|
28
|
+
{
|
|
29
|
+
id: "item-1",
|
|
30
|
+
valueCents: 3990, // what the buyer pays for the line, after its allocated discount
|
|
31
|
+
quantity: 1, // qCom, at most four decimals
|
|
32
|
+
foodAndDrink: true,
|
|
33
|
+
taxClass: { cClassTrib: "200047", cstIbsCbs: "200", regimeEspecifico: "BARES_RESTAURANTES", reductionBp: 0 },
|
|
34
|
+
},
|
|
35
|
+
],
|
|
36
|
+
seller: { regime: "REGIME_REGULAR", regimeEffectiveFrom: "2026-01-01", restaurantRegime: true },
|
|
37
|
+
destinationIbge: "3550308", // the establishment, or for a delivered good the place of delivery
|
|
38
|
+
exclusions: { serviceCharge: null, retainedIntermediation: null },
|
|
39
|
+
tables,
|
|
40
|
+
supplyDate: "2026-11-20", // the local day of the supply, in the seller's clock
|
|
41
|
+
});
|
|
42
|
+
// breakdown.lines[i]: one NF-e item each — valueCents (vProd), taxBaseCents (vBC),
|
|
43
|
+
// cbsRateBp/cbsCents, ibsUfRateBp/ibsUfCents, ibsMunRateBp/ibsMunCents, reductionBp,
|
|
44
|
+
// taxCents, netValueCents (vProdLiq) and netUnitValue (vUnComLiq), the class snapshot
|
|
45
|
+
// breakdown: the sums, netValueCents (vProdLiqTot), gorjetaExcludedCents,
|
|
46
|
+
// intermediationExcludedCents, treatment, informative, provisional, taxInsidePrice,
|
|
47
|
+
// tablesVersion
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
Money is integer cents, rates integer basis points, dates `YYYY-MM-DD`. Any
|
|
51
|
+
value the engine cannot read — a missing object, an `undefined` where `null` is
|
|
52
|
+
required, a malformed table — is refused with a `FiscalEngineError` carrying a
|
|
53
|
+
`code`; nothing is defaulted.
|
|
54
|
+
|
|
55
|
+
### What a host passes as a line's value
|
|
56
|
+
|
|
57
|
+
Always **the price the buyer pays for the line** (all units, after the line's
|
|
58
|
+
share of an unconditional discount). The engine decides from the rate table
|
|
59
|
+
whether the tax is inside it:
|
|
60
|
+
|
|
61
|
+
- **A period with `taxInsidePrice: false` (2026).** The value is the base:
|
|
62
|
+
`vBC = value`, each tax is `vBC × rate`, and `netValueCents` /
|
|
63
|
+
`netUnitValue` are `null` — the tax is not part of `vProd` yet.
|
|
64
|
+
- **A period with `taxInsidePrice: true` (2027 on, where the IBS/CBS compose
|
|
65
|
+
`vProd`).** The value is tax-inclusive. The engine takes the taxes out: `vBC`
|
|
66
|
+
is the largest whole-cent base whose rounded taxes, added back, fit inside
|
|
67
|
+
the value; each tax is rounded on that `vBC`; `netValueCents` (`vProdLiq`) is
|
|
68
|
+
the value less the taxes, so `vProdLiq + Σ tax = vProd` to the cent; and
|
|
69
|
+
`netUnitValue` (`vUnComLiq`, reais with ten decimals) times the quantity is
|
|
70
|
+
within the layout's ±0,01 of `vProdLiq` (rule I11c-20). The price never
|
|
71
|
+
changes; the tax is a share of it.
|
|
72
|
+
|
|
73
|
+
### The rules it applies (LC 214/2025)
|
|
74
|
+
|
|
75
|
+
- **Rates by the date of the supply**, from the table's period covering it:
|
|
76
|
+
2026 CBS 0.9% and IBS 0.1% (arts. 343, 346), informative (art. 348 §1);
|
|
77
|
+
2027–2028 IBS 0.05% state + 0.05% municipal (art. 344); later years the
|
|
78
|
+
reference rates the table carries. A period whose figures are not yet law is
|
|
79
|
+
`status: "ESTIMATE"` and stamps its results `provisional: true`.
|
|
80
|
+
- **Destination** (art. 11 I): a state's or municipality's own rate where the
|
|
81
|
+
table lists one (`byUf`, `byMunicipality`), the reference rate elsewhere.
|
|
82
|
+
- **Regimes** (art. 41): regime regular and the Simples híbrido → `FULL`;
|
|
83
|
+
Simples inside the DAS → `INFORMATIVE`, carrying the figures a regime store
|
|
84
|
+
would show and no amount "por fora"; MEI and não contribuinte → `NONE`, zero
|
|
85
|
+
and not informative. In 2026 the test rates are not applied to Simples
|
|
86
|
+
optants (art. 348 III "c"), read from the period's `appliesToSimplesNacional`.
|
|
87
|
+
- **Bares e restaurantes**: in a store with `restaurantRegime`, a line whose
|
|
88
|
+
class is `BARES_RESTAURANTES` (prepared food, non-alcoholic drinks prepared
|
|
89
|
+
on the premises — art. 273; official class 200047) takes the table's 40%
|
|
90
|
+
reduction (art. 275); alcohol and resale carry `regimeEspecifico: null` and
|
|
91
|
+
the full rate (art. 273 §2). Outside the special regime a class's own
|
|
92
|
+
`reductionBp` applies (a cesta-básica zero rate is a 100% reduction).
|
|
93
|
+
- **Exclusions**, restaurant regime only (art. 274 par. único), each
|
|
94
|
+
**segregated as its own item** with no tax (RCBS art. 399 §2; without the
|
|
95
|
+
segregation the base is the full value, §4), under the table's
|
|
96
|
+
`exclusionClasses`:
|
|
97
|
+
- the service charge, when passed in full to the staff AND at most 15% of
|
|
98
|
+
the food and drink (I): one item, class 410019. Above 15%, or kept by the
|
|
99
|
+
store, nothing is excluded — the WHOLE charge is a taxed item under the
|
|
100
|
+
class the host passes. There is no partial exclusion.
|
|
101
|
+
- what a platform retained for delivery and intermediation (II): one item,
|
|
102
|
+
class 410020, passed as `retainedIntermediation` and NOT inside any line's
|
|
103
|
+
value. No goods line's base moves for it. Outside the restaurant regime it
|
|
104
|
+
is refused: there the amount belongs in the lines.
|
|
105
|
+
- **Rounding**: per item, per tax, to whole cents, **half-even** — what the
|
|
106
|
+
official calculator does (R$ 5,00 × 0,9% = 0,045 → 0,04), never a floor; the
|
|
107
|
+
reduction applies to the rate before the product is rounded, and every order
|
|
108
|
+
figure is the sum of its rounded items. The effective rate (`pAliqEfet`) is
|
|
109
|
+
not output: the product is computed exactly from the nominal rate and the
|
|
110
|
+
reduction, which equals `vBC × pAliqEfet` for any whole-percent reduction —
|
|
111
|
+
every reduction in the official table (V0066) is one: 30, 40, 50, 60, 70, 80
|
|
112
|
+
or 100%.
|
|
113
|
+
|
|
114
|
+
### The oracle mode
|
|
115
|
+
|
|
116
|
+
`computeTaxWithOracle(input, calculator)` takes the same input and asks an
|
|
117
|
+
`OfficialCalculator` port for each taxed item's rates, reduction and taxes; the
|
|
118
|
+
regime, the exclusions and the bases stay the engine's (in a tax-inside-price
|
|
119
|
+
period the base is taken out with the table's rates, since the calculator
|
|
120
|
+
takes a base). A host points the port at the official calculator's HTTP API.
|
|
121
|
+
The package's suite replays REAL recorded calculator answers for 2026
|
|
122
|
+
(`src/engine/__tests__/fixtures/calculator/`, version and date in
|
|
123
|
+
`recording.json`) and asserts `compareBreakdowns` finds nothing. The
|
|
124
|
+
calculator has no rates for 2027 and later yet, so those years' goldens are
|
|
125
|
+
the engine's own estimates, marked `provisional`.
|
|
126
|
+
|
|
127
|
+
## The fiscal documents
|
|
128
|
+
|
|
129
|
+
```ts
|
|
130
|
+
import { createFiscalDocuments, createPrismaFiscalStore, createSigningIdentities } from "@12-apps/fiscal/documents";
|
|
131
|
+
import { createSidecarIssuer } from "@12-apps/fiscal/issuer";
|
|
132
|
+
|
|
133
|
+
const documents = createFiscalDocuments({
|
|
134
|
+
store: createPrismaFiscalStore({ prisma }), // the package's own store: the host passes its Prisma client
|
|
135
|
+
|
|
136
|
+
issuer: createSidecarIssuer({ baseUrl: "http://fiscal-sidecar:8080", fetch, timeoutMs: 90_000 }),
|
|
137
|
+
signing: createSigningIdentities({ cipher }),
|
|
138
|
+
cipher, // the host's { encrypt, decrypt }: certificate, password and CSC at rest
|
|
139
|
+
readCertificate, // the host's: an A1's expiry, or a throw when it does not open
|
|
140
|
+
storage, // where the XMLs live
|
|
141
|
+
sales, // SaleSource: the host's sale as a SaleDraft (`documentLines` maps the engine's breakdown)
|
|
142
|
+
notify, // the host's notifier (never throws)
|
|
143
|
+
now: () => new Date(),
|
|
144
|
+
utcOffset: (ownerId, at) => "-03:00",
|
|
145
|
+
reasons: { contingency, inutilization, substitution }, // host words SEFAZ receives, 15–255 chars
|
|
146
|
+
staleAfterMs: 5 * 60_000, // the base of the backoff
|
|
147
|
+
nfceOnlineToleranceMs: 5 * 60_000, // SEFAZ's late-dhEmi limit (704), the state's
|
|
148
|
+
newId: () => crypto.randomUUID(),
|
|
149
|
+
});
|
|
150
|
+
await documents.issue({ ownerId, subjectId, issuingPointId, model: "NFCE" });
|
|
151
|
+
```
|
|
152
|
+
|
|
153
|
+
**One document is one number.** The state machine (`transition`) is pure:
|
|
154
|
+
|
|
155
|
+
```
|
|
156
|
+
PENDING ─SUBMIT→ SUBMITTED ─AUTHORIZE→ AUTHORIZED ─CANCEL→ CANCELLED
|
|
157
|
+
├─DENY→ DENIED ├─REJECT→ REJECTED └─RETRY→ SUBMITTED
|
|
158
|
+
PENDING | SUBMITTED ─REPLACE→ REPLACED
|
|
159
|
+
PENDING ─SIGN_OFFLINE→ CONTINGENCY ─AUTHORIZE | DENY | REJECT | RETRY→ …
|
|
160
|
+
```
|
|
161
|
+
|
|
162
|
+
Every step yields an event carrying the fiscal service's raw answer, with any
|
|
163
|
+
secret-named key scrubbed. `CANCELLED` is reached only from `AUTHORIZED`, and
|
|
164
|
+
nothing leaves `REJECTED`, `DENIED`, `REPLACED` or `CANCELLED` for `AUTHORIZED`
|
|
165
|
+
(a property suite walks random sequences).
|
|
166
|
+
|
|
167
|
+
- **The counters are the package's, and so is their store.**
|
|
168
|
+
`createPrismaFiscalStore({ prisma })` runs over the host's Prisma client
|
|
169
|
+
(raw SQL on the package's migration); a host keeps no counter and writes no
|
|
170
|
+
numbering transaction. A counter is keyed by the issuer's CNPJ, the model
|
|
171
|
+
and the series, as SEFAZ numbers (one CNPJ can serve several owners); a
|
|
172
|
+
series belongs to one issuing point. A number is drawn in the same
|
|
173
|
+
transaction as the document's insert (`FISCAL_NEXT_NUMBER_SQL`), so a failed
|
|
174
|
+
write gives it back.
|
|
175
|
+
- **One live document per subject.** The partial unique index
|
|
176
|
+
`fiscal_documents_live_subject_key` refuses a second live document for an
|
|
177
|
+
(owner, subject, model); `issue()` answers the existing one when a
|
|
178
|
+
concurrent call won.
|
|
179
|
+
- **Going offline is a second document, in one transaction.** When the
|
|
180
|
+
service answers `CONTINGENCY` for an NFC-e at a point with a contingency
|
|
181
|
+
series — or the sweep finds an online NFC-e past `nfceOnlineToleranceMs`,
|
|
182
|
+
which SEFAZ would refuse as late — the sale is numbered on that series AND
|
|
183
|
+
the online document is `REPLACED` in the same transaction, before anything
|
|
184
|
+
is signed. Signing follows (`tpEmis = 9`); the `transmit-contingency` job
|
|
185
|
+
sends it, and warns at 20 hours (the deadline is 24). Offline, the paper is
|
|
186
|
+
ONE copy, the consumer's.
|
|
187
|
+
- **Every number SEFAZ never used is settled.** `numberVoid` says what is
|
|
188
|
+
owed: a lookup first when a send went unanswered (`outcomeUnknown` is
|
|
189
|
+
sticky until a definitive answer or a lookup clears it — the package
|
|
190
|
+
computes every access key, so a lookup is always possible), the NFC-e
|
|
191
|
+
cancel BY SUBSTITUTION (event 110112, naming the contingency twin) when
|
|
192
|
+
SEFAZ authorised it after all, an inutilization otherwise; `DENIED` when
|
|
193
|
+
the lookup finds it denied (the denial spent it).
|
|
194
|
+
- **A rejected contingency NFC-e is never voided.** The buyer holds its
|
|
195
|
+
DANFE: it stays `REJECTED` with SEFAZ's code, the store corrects the sale,
|
|
196
|
+
and `resendContingency` signs it again under the same series, number and
|
|
197
|
+
key code (`POST …/resend`), with the corrected sale's totals. A correction
|
|
198
|
+
that changes the total or the buyer's document — what the DANFE the buyer
|
|
199
|
+
holds prints and its QR encodes — is refused (`RESEND_CHANGES_PRINTED_FIELDS`):
|
|
200
|
+
that sale needs a new note, issued by a person.
|
|
201
|
+
- **An authorised document always has its XML.** A lookup that finds a
|
|
202
|
+
SUBMITTED document authorised joins the signed XML the service returned to
|
|
203
|
+
the lookup's `protNFe`; without both, the document stays SUBMITTED (its
|
|
204
|
+
protocol kept, so it never goes offline) and the sweep sends the same call
|
|
205
|
+
again, which the service settles with the XML. A REPLACED number that was
|
|
206
|
+
ever SUBMITTED is always looked up before it is voided.
|
|
207
|
+
- **Nothing is retried silently.** Each failed step counts (`failures`) and
|
|
208
|
+
backs off (`nextAttemptAt`, doubling to 64 × `staleAfterMs`); the queues
|
|
209
|
+
are ordered by the next attempt, so a failing row never pins their head. A
|
|
210
|
+
refusal SEFAZ will repeat (241, 256, 501, a certificate refused), or
|
|
211
|
+
`MAX_FAILURES` in a row, hands the document to a person (`attention`, the
|
|
212
|
+
`fiscal.document-needs-attention` notification); `POST …/release` gives it
|
|
213
|
+
back to the sweep.
|
|
214
|
+
- **What the classes mean here.** `REJECTED`, `INVALID` and `INTERNAL` reject
|
|
215
|
+
(the same call fails again); `RETRYABLE`, `AUTH` and a `CONTINGENCY` with no
|
|
216
|
+
offline path retry, with the same number and key code.
|
|
217
|
+
- **Who signs** is the profile's `signingIdentity`: `STORE_CERTIFICATE` (the
|
|
218
|
+
store's A1, decrypted for one call) or `PLATFORM`, declared and answering
|
|
219
|
+
`NOT_SUPPORTED` until FUT-2229 q4 says how the platform signs.
|
|
220
|
+
- **Secrets** are encrypted through the host's cipher on arrival, decrypted by
|
|
221
|
+
the signing identity for one call, and never stored in clear, logged,
|
|
222
|
+
answered or put in an error. The CSC's id and token are saved together or
|
|
223
|
+
not at all.
|
|
224
|
+
|
|
225
|
+
**Not in this release** (FUT-4717): an offline register signing on a block of
|
|
226
|
+
the contingency series reserved in advance, recording what it signed, and
|
|
227
|
+
voiding the known rest of a finished block. The port it will build on is
|
|
228
|
+
declared, unimplemented: `ContingencyBlockSource`.
|
|
229
|
+
|
|
230
|
+
NFS-e is not covered: only the platform's own NFS-e is planned (FUT-2242).
|
|
231
|
+
|
|
232
|
+
## The DANFE NFC-e
|
|
233
|
+
|
|
234
|
+
`renderDanfeNfce({ xml, paperWidth: 58 | 80, labels })` reads the authorised
|
|
235
|
+
XML (or the signed XML of a document issued offline, which prints the
|
|
236
|
+
"EMITIDA EM CONTINGÊNCIA" variant) and answers lines in the Manual do DANFE
|
|
237
|
+
NFC-e's divisions I–VIII: the issuer, the title, every item, the totals and
|
|
238
|
+
payments, the fiscal message and the key, the consumer, the number and
|
|
239
|
+
protocol, and the QR code (a line carrying `qrCode`, for the host to
|
|
240
|
+
rasterise). Each line is `{ text, align, emphasis }`, the shape
|
|
241
|
+
`@12-apps/thermal-printing` encodes, at 32 or 48 columns.
|
|
242
|
+
|
|
243
|
+
## The manifest
|
|
244
|
+
|
|
245
|
+
`@12-apps/fiscal/manifest` declares the permissions `fiscal:read`,
|
|
246
|
+
`fiscal:manage`, `fiscal:issue` and `fiscal:cancel`, here and nowhere else;
|
|
247
|
+
the Prisma partial `prisma/fiscal.prisma` and its migrations; the `fiscal`
|
|
248
|
+
observability namespace; and `server: ["http", "jobs"]`:
|
|
249
|
+
|
|
250
|
+
| route (under the host's mount) | permission |
|
|
251
|
+
|---|---|
|
|
252
|
+
| `GET /fiscal/profile`, `GET /fiscal/issuing-points` | `fiscal:read` |
|
|
253
|
+
| `PUT /fiscal/profile`, `PUT /fiscal/profile/certificate`, `POST /fiscal/issuing-points` | `fiscal:manage` |
|
|
254
|
+
| `POST /fiscal/documents` | `fiscal:issue` |
|
|
255
|
+
| `GET /fiscal/documents/:documentId`, `POST …/lookup`, `GET …/danfe?paper=58\|80` (AUTHORIZED or CONTINGENCY only; 409 otherwise) | `fiscal:read` |
|
|
256
|
+
| `POST /fiscal/documents/:documentId/cancel` | `fiscal:cancel` |
|
|
257
|
+
| `POST /fiscal/documents/:documentId/resend` (a rejected contingency NFC-e), `POST …/release` (back from a person) | `fiscal:issue` |
|
|
258
|
+
|
|
259
|
+
The jobs are `fiscal.sweep` and `fiscal.transmit-contingency` (every five
|
|
260
|
+
minutes, a 30-minute lease and a batch sized so the worst run ends inside it) and `fiscal.certificate-expiry` (daily, telling owners on the
|
|
261
|
+
30th, 15th, 7th, 3rd and last day, and daily once expired). The alerts (certificate expiring, document rejected)
|
|
262
|
+
and the other two (needs attention, contingency deadline) ship as
|
|
263
|
+
`createFiscalNotificationBlueprints(copy)`, over the host's words. The
|
|
264
|
+
settings screen and the documents list (`web: ["surface"]`) come with their
|
|
265
|
+
screen tickets; `.wiring-conformance.json` argues each capability not
|
|
266
|
+
declared.
|
|
267
|
+
|
|
268
|
+
The RBAC bullet of the host's tax docs (which still places the four
|
|
269
|
+
permissions in the host's catalog) is corrected in the host's pull request that
|
|
270
|
+
bumps `@12-apps/fiscal`, not here.
|