@12-apps/fiscal 1.0.0 → 1.2.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.
Files changed (140) hide show
  1. package/README.md +164 -7
  2. package/dist/chunk-2LBQRYPV.js +21 -0
  3. package/dist/chunk-2LBQRYPV.js.map +1 -0
  4. package/dist/chunk-3SDXLSG4.js +24 -0
  5. package/dist/chunk-3SDXLSG4.js.map +1 -0
  6. package/dist/chunk-5S2PJHAE.js +85 -0
  7. package/dist/chunk-5S2PJHAE.js.map +1 -0
  8. package/dist/chunk-G3V7IYNF.js +192 -0
  9. package/dist/chunk-G3V7IYNF.js.map +1 -0
  10. package/dist/chunk-JVQKJNOC.js +14 -0
  11. package/dist/chunk-JVQKJNOC.js.map +1 -0
  12. package/dist/chunk-N5DCKYFR.js +610 -0
  13. package/dist/chunk-N5DCKYFR.js.map +1 -0
  14. package/dist/chunk-NVRYAAQ4.js +212 -0
  15. package/dist/chunk-NVRYAAQ4.js.map +1 -0
  16. package/dist/chunk-PNTKG3DZ.js +47 -0
  17. package/dist/chunk-PNTKG3DZ.js.map +1 -0
  18. package/dist/chunk-WTGASIZE.js +247 -0
  19. package/dist/chunk-WTGASIZE.js.map +1 -0
  20. package/dist/chunk-XQGW5HUG.js +30 -0
  21. package/dist/chunk-XQGW5HUG.js.map +1 -0
  22. package/dist/context-ChnWR4Kb.d.ts +455 -0
  23. package/dist/danfe/en-US.d.ts +12 -0
  24. package/dist/danfe/en-US.js +51 -0
  25. package/dist/danfe/en-US.js.map +1 -0
  26. package/dist/danfe/index.d.ts +50 -0
  27. package/dist/danfe/index.js +18 -0
  28. package/dist/danfe/index.js.map +1 -0
  29. package/dist/danfe/pt-BR.d.ts +11 -0
  30. package/dist/danfe/pt-BR.js +51 -0
  31. package/dist/danfe/pt-BR.js.map +1 -0
  32. package/dist/documents/index.d.ts +181 -0
  33. package/dist/documents/index.js +1234 -0
  34. package/dist/documents/index.js.map +1 -0
  35. package/dist/engine/index.d.ts +3 -246
  36. package/dist/http.d.ts +75 -0
  37. package/dist/http.js +16 -0
  38. package/dist/http.js.map +1 -0
  39. package/dist/issuer/index.d.ts +43 -0
  40. package/dist/issuer/index.js +131 -0
  41. package/dist/issuer/index.js.map +1 -0
  42. package/dist/jobs.d.ts +74 -0
  43. package/dist/jobs.js +22 -0
  44. package/dist/jobs.js.map +1 -0
  45. package/dist/labels-BNvflT0h.d.ts +44 -0
  46. package/dist/manifest/index.d.ts +30 -16
  47. package/dist/manifest/index.js +11 -17
  48. package/dist/manifest/index.js.map +1 -1
  49. package/dist/manifest/server.d.ts +57 -0
  50. package/dist/manifest/server.js +25 -0
  51. package/dist/manifest/server.js.map +1 -0
  52. package/dist/notifications.d.ts +93 -0
  53. package/dist/notifications.js +41 -0
  54. package/dist/notifications.js.map +1 -0
  55. package/dist/port-DpRFK56U.d.ts +238 -0
  56. package/dist/sale/index.d.ts +269 -0
  57. package/dist/sale/index.js +1 -0
  58. package/dist/sale/index.js.map +1 -0
  59. package/dist/service-KTjH7AxW.d.ts +139 -0
  60. package/dist/sidecar/index.d.ts +218 -0
  61. package/dist/sidecar/index.js +8 -0
  62. package/dist/sidecar/index.js.map +1 -0
  63. package/dist/types-B1b8LIWX.d.ts +247 -0
  64. package/package.json +63 -5
  65. package/prisma/fiscal.prisma +158 -0
  66. package/prisma/migrations/20261113220000_fiscal_documents/migration.sql +201 -0
  67. package/sidecar/.dockerignore +5 -0
  68. package/sidecar/Dockerfile +68 -0
  69. package/sidecar/README.md +162 -0
  70. package/sidecar/composer.json +30 -0
  71. package/sidecar/composer.lock +2224 -0
  72. package/sidecar/docker/apache.conf +14 -0
  73. package/sidecar/docker/icp-brasil.pem +8031 -0
  74. package/sidecar/docker/mpm.conf +17 -0
  75. package/sidecar/docker/openssl.cnf +16 -0
  76. package/sidecar/docker/php.ini +19 -0
  77. package/sidecar/public/index.php +15 -0
  78. package/sidecar/schema/sale-for-document.schema.json +422 -0
  79. package/sidecar/src/ErrorClass.php +31 -0
  80. package/sidecar/src/Http/Request.php +48 -0
  81. package/sidecar/src/Http/Response.php +32 -0
  82. package/sidecar/src/Http/Router.php +59 -0
  83. package/sidecar/src/Kernel.php +99 -0
  84. package/sidecar/src/Module.php +31 -0
  85. package/sidecar/src/Nfe/Classifier.php +89 -0
  86. package/sidecar/src/Nfe/Credentials.php +52 -0
  87. package/sidecar/src/Nfe/DocumentMapper.php +428 -0
  88. package/sidecar/src/Nfe/DocumentSchema.php +39 -0
  89. package/sidecar/src/Nfe/Input.php +125 -0
  90. package/sidecar/src/Nfe/Model.php +17 -0
  91. package/sidecar/src/Nfe/NfeModule.php +62 -0
  92. package/sidecar/src/Nfe/NfeService.php +504 -0
  93. package/sidecar/src/Nfe/Sefaz.php +49 -0
  94. package/sidecar/src/Nfe/SefazReply.php +81 -0
  95. package/sidecar/src/Nfe/Transport/CurlTransport.php +198 -0
  96. package/sidecar/src/Nfe/Transport/SoapAdapter.php +57 -0
  97. package/sidecar/src/Nfe/Transport/Transport.php +20 -0
  98. package/sidecar/src/Nfe/Transport/TransportFailure.php +42 -0
  99. package/sidecar/src/RequestLog.php +54 -0
  100. package/sidecar/src/ServiceError.php +69 -0
  101. package/src/danfe/en-US.ts +53 -0
  102. package/src/danfe/index.ts +11 -0
  103. package/src/danfe/labels.ts +49 -0
  104. package/src/danfe/pt-BR.ts +52 -0
  105. package/src/danfe/render.ts +265 -0
  106. package/src/danfe/xml.ts +45 -0
  107. package/src/documents/context.ts +260 -0
  108. package/src/documents/errors.ts +48 -0
  109. package/src/documents/helpers.ts +177 -0
  110. package/src/documents/index.ts +40 -0
  111. package/src/documents/lines.ts +63 -0
  112. package/src/documents/machine-steps.ts +260 -0
  113. package/src/documents/machine.ts +128 -0
  114. package/src/documents/memory.ts +138 -0
  115. package/src/documents/nfe-proc.ts +51 -0
  116. package/src/documents/ports.ts +130 -0
  117. package/src/documents/profile-input.ts +168 -0
  118. package/src/documents/profile.ts +98 -0
  119. package/src/documents/service-profile.ts +104 -0
  120. package/src/documents/service.ts +299 -0
  121. package/src/documents/settle.ts +121 -0
  122. package/src/documents/signing.ts +61 -0
  123. package/src/documents/sql-rows.ts +180 -0
  124. package/src/documents/sql-store.ts +242 -0
  125. package/src/documents/sql.ts +18 -0
  126. package/src/documents/steps.ts +173 -0
  127. package/src/documents/tests/integration/pglite.ts +73 -0
  128. package/src/documents/types.ts +193 -0
  129. package/src/http.ts +266 -0
  130. package/src/issuer/index.ts +9 -0
  131. package/src/issuer/port.ts +109 -0
  132. package/src/issuer/sidecar.ts +171 -0
  133. package/src/jobs.ts +115 -0
  134. package/src/manifest/index.ts +25 -16
  135. package/src/manifest/server.ts +20 -0
  136. package/src/notifications.ts +120 -0
  137. package/src/sale/index.ts +8 -0
  138. package/src/sale/types.ts +318 -0
  139. package/src/sidecar/index.ts +9 -0
  140. package/src/sidecar/types.ts +245 -0
@@ -0,0 +1,318 @@
1
+ /**
2
+ * The neutral document shape: one sale, host-agnostic, as the fiscal service
3
+ * (`sidecar/`) accepts it and as the issuer port maps a host's sale into it.
4
+ *
5
+ * Money is integer CENTS, rates integer BASIS POINTS (1 bp = 0.01%) — the
6
+ * engine's conventions (`@12-apps/fiscal/engine`) — and quantities carry at
7
+ * most four decimals. Every field is required; an absent value is `null`,
8
+ * never a missing key, so a host cannot forget one silently. The two
9
+ * exceptions came with the return document (FUT-2238), `operation` and
10
+ * `referencedDocuments`: they are optional so that a document built before
11
+ * them stays valid and yields the same XML, byte for byte.
12
+ *
13
+ * The JSON schema the service validates against is
14
+ * `@12-apps/fiscal/sidecar/schema/sale-for-document.schema.json`; a test keeps
15
+ * it and these types in step. Whether the sale becomes an NF-e (model 55) or
16
+ * an NFC-e (model 65) is the request path's choice, never this document's.
17
+ */
18
+
19
+ /** The 27 federative units. */
20
+ export type Uf =
21
+ | "AC" | "AL" | "AM" | "AP" | "BA" | "CE" | "DF" | "ES" | "GO" | "MA" | "MG" | "MS" | "MT" | "PA"
22
+ | "PB" | "PE" | "PI" | "PR" | "RJ" | "RN" | "RO" | "RR" | "RS" | "SC" | "SE" | "SP" | "TO";
23
+
24
+ /** A postal address. `postalCode` is required on the issuer's. */
25
+ export interface Address {
26
+ readonly street: string;
27
+ readonly number: string;
28
+ readonly complement: string | null;
29
+ readonly district: string;
30
+ /** The 7-digit IBGE municipality code. */
31
+ readonly municipalityIbge: string;
32
+ readonly municipalityName: string;
33
+ readonly uf: Uf;
34
+ /** CEP, 8 digits. */
35
+ readonly postalCode: string | null;
36
+ readonly phone: string | null;
37
+ }
38
+
39
+ /** The issuer's tax regime on the document (`CRT` 1, 2, 3, 4). */
40
+ export type IssuerTaxRegime = "SIMPLES" | "SIMPLES_EXCESS" | "NORMAL" | "MEI";
41
+
42
+ export interface DocumentIssuer {
43
+ /** 14 characters; the 2026 alphanumeric CNPJ is accepted. */
44
+ readonly cnpj: string;
45
+ /** IE digits, or `ISENTO`. */
46
+ readonly stateRegistration: string;
47
+ readonly legalName: string;
48
+ readonly tradeName: string | null;
49
+ readonly taxRegime: IssuerTaxRegime;
50
+ readonly address: Address & { readonly postalCode: string };
51
+ }
52
+
53
+ export type BuyerDocument =
54
+ | { readonly kind: "CPF"; readonly number: string }
55
+ | { readonly kind: "CNPJ"; readonly number: string }
56
+ | { readonly kind: "FOREIGN"; readonly number: string };
57
+
58
+ /** `indIEDest` 1, 2, 9. */
59
+ export type StateRegistrationStatus = "CONTRIBUTOR" | "EXEMPT" | "NON_CONTRIBUTOR";
60
+
61
+ export interface DocumentBuyer {
62
+ readonly document: BuyerDocument;
63
+ readonly name: string | null;
64
+ readonly stateRegistrationStatus: StateRegistrationStatus;
65
+ readonly stateRegistration: string | null;
66
+ readonly email: string | null;
67
+ readonly address: Address | null;
68
+ }
69
+
70
+ /** The goods' origin (`orig`), 0–8. */
71
+ export type GoodsOrigin = 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8;
72
+
73
+ /** ICMS of a Simples Nacional issuer, without a credit. */
74
+ export interface IcmsSimples {
75
+ readonly regime: "SIMPLES";
76
+ readonly origin: GoodsOrigin;
77
+ readonly csosn: "102" | "103" | "300" | "400" | "500";
78
+ }
79
+
80
+ /** ICMS of a Simples Nacional issuer that grants the buyer a credit (CSOSN 101). */
81
+ export interface IcmsSimplesWithCredit {
82
+ readonly regime: "SIMPLES";
83
+ readonly origin: GoodsOrigin;
84
+ readonly csosn: "101";
85
+ readonly creditRateBp: number;
86
+ readonly creditCents: number;
87
+ }
88
+
89
+ /** ICMS fully taxed (CST 00). */
90
+ export interface IcmsTaxed {
91
+ readonly regime: "NORMAL";
92
+ readonly origin: GoodsOrigin;
93
+ readonly cst: "00";
94
+ readonly baseCents: number;
95
+ readonly rateBp: number;
96
+ readonly amountCents: number;
97
+ }
98
+
99
+ /** ICMS exempt, not taxed, suspended (40, 41, 50) or collected before by substitution (60). */
100
+ export interface IcmsUntaxed {
101
+ readonly regime: "NORMAL";
102
+ readonly origin: GoodsOrigin;
103
+ readonly cst: "40" | "41" | "50" | "60";
104
+ }
105
+
106
+ export type LineIcms = IcmsSimples | IcmsSimplesWithCredit | IcmsTaxed | IcmsUntaxed;
107
+
108
+ /** The PIS and COFINS situation codes the layout accepts on an outgoing document. */
109
+ export type ContributionCst =
110
+ | "01" | "02" | "04" | "05" | "06" | "07" | "08" | "09" | "49" | "50" | "51" | "52" | "53" | "54"
111
+ | "55" | "56" | "60" | "61" | "62" | "63" | "64" | "65" | "66" | "67" | "70" | "71" | "72" | "73"
112
+ | "74" | "75" | "98" | "99";
113
+
114
+ /**
115
+ * PIS or COFINS. CST 01/02 write the base, the rate and the amount; 04–09
116
+ * write none (send zeros); 49–99 write all three.
117
+ */
118
+ export interface LineContribution {
119
+ readonly cst: ContributionCst;
120
+ readonly baseCents: number;
121
+ readonly rateBp: number;
122
+ readonly amountCents: number;
123
+ }
124
+
125
+ /**
126
+ * The IBS/CBS figures of one line — what the engine's `LineTax` carries:
127
+ * `vBC` and, per tax, the NOMINAL rate and the amount. `reductionBp` applies
128
+ * to all three rates (`pRedAliq`; the effective rate is written beside it).
129
+ */
130
+ export interface IbsCbsFigures {
131
+ readonly baseCents: number;
132
+ readonly reductionBp: number;
133
+ readonly cbsRateBp: number;
134
+ readonly cbsCents: number;
135
+ readonly ibsUfRateBp: number;
136
+ readonly ibsUfCents: number;
137
+ readonly ibsMunRateBp: number;
138
+ readonly ibsMunCents: number;
139
+ }
140
+
141
+ /** The IBS/CBS group of a line. `figures: null` writes the CST and class only (immunity, say). */
142
+ export interface LineIbsCbs {
143
+ /** `CST` of the IBS/CBS, 3 digits. */
144
+ readonly cst: string;
145
+ /** `cClassTrib`, 6 digits. */
146
+ readonly classCode: string;
147
+ readonly figures: IbsCbsFigures | null;
148
+ }
149
+
150
+ /** One item of the document. */
151
+ export interface SaleLine {
152
+ /** The host's id; quoted back in a mapping error. */
153
+ readonly id: string;
154
+ /** `cProd`. */
155
+ readonly code: string;
156
+ /** GTIN/EAN, or `null` for "SEM GTIN". */
157
+ readonly gtin: string | null;
158
+ readonly description: string;
159
+ readonly ncm: string;
160
+ readonly cest: string | null;
161
+ readonly cfop: string;
162
+ /** `uCom` and `uTrib`. */
163
+ readonly unit: string;
164
+ /** `qCom` and `qTrib`: positive, at most four decimals. */
165
+ readonly quantity: number;
166
+ /** `vProd`: every unit, BEFORE the line's discount. The unit value is derived. */
167
+ readonly valueCents: number;
168
+ /** `vDesc`. */
169
+ readonly discountCents: number;
170
+ /** `vTotTrib` (the approximate tax of the transparency law), or `null`. */
171
+ readonly approximateTaxCents: number | null;
172
+ /** `infAdProd`. */
173
+ readonly additionalInfo: string | null;
174
+ readonly icms: LineIcms;
175
+ readonly pis: LineContribution;
176
+ readonly cofins: LineContribution;
177
+ /** `null` writes no IBS/CBS group — a regime the engine answered `NONE` for. */
178
+ readonly ibsCbs: LineIbsCbs | null;
179
+ }
180
+
181
+ /** `tPag`. */
182
+ export type PaymentMethod =
183
+ | "CASH"
184
+ | "CHECK"
185
+ | "CREDIT_CARD"
186
+ | "DEBIT_CARD"
187
+ | "STORE_CREDIT"
188
+ | "FOOD_VOUCHER"
189
+ | "MEAL_VOUCHER"
190
+ | "GIFT_VOUCHER"
191
+ | "FUEL_VOUCHER"
192
+ | "BANK_SLIP"
193
+ | "BANK_DEPOSIT"
194
+ | "PIX_DYNAMIC"
195
+ | "TRANSFER"
196
+ | "LOYALTY"
197
+ | "PIX_STATIC"
198
+ | "NO_PAYMENT"
199
+ | "OTHER";
200
+
201
+ export interface CardDetails {
202
+ /** `tpIntegra`: whether the payment went through an integrated terminal. */
203
+ readonly integrated: boolean;
204
+ readonly acquirerCnpj: string | null;
205
+ /** `tBand`, 2 digits. */
206
+ readonly brand: string | null;
207
+ /** `cAut`. */
208
+ readonly authorizationCode: string | null;
209
+ }
210
+
211
+ export interface SalePayment {
212
+ readonly method: PaymentMethod;
213
+ readonly amountCents: number;
214
+ /** Required by the layout for a card and for a Pix; `null` otherwise. */
215
+ readonly card: CardDetails | null;
216
+ /** `xPag`: required when `method` is `OTHER`. */
217
+ readonly description: string | null;
218
+ }
219
+
220
+ /** `finNFe` 1–4. */
221
+ export type DocumentPurpose = "NORMAL" | "COMPLEMENTARY" | "ADJUSTMENT" | "RETURN";
222
+ /**
223
+ * `tpNF`: `OUT` (1) a sale or any outgoing document; `IN` (0) an entry, such as
224
+ * a buyer's goods coming back. An NFC-e is always `OUT`.
225
+ */
226
+ export type DocumentOperation = "OUT" | "IN";
227
+ /** `NFref/refNFe`: an earlier NF-e or NFC-e this document refers to. */
228
+ export interface ReferencedDocument {
229
+ /** The 44-character access key (`isValidAccessKey` in `@12-apps/fiscal/documents`). */
230
+ readonly accessKey: string;
231
+ }
232
+ /** `idDest` 1–3. */
233
+ export type OperationDestination = "INTERNAL" | "INTERSTATE" | "FOREIGN";
234
+ /** `indPres` 1, 2, 3, 4, 5, 9. */
235
+ export type BuyerPresence =
236
+ | "IN_PERSON"
237
+ | "INTERNET"
238
+ | "TELEPHONE"
239
+ | "HOME_DELIVERY"
240
+ | "IN_PERSON_OFF_PREMISES"
241
+ | "OTHER";
242
+ /** `modFrete` 0, 1, 2, 3, 4, 9. */
243
+ export type FreightMode =
244
+ | "BY_ISSUER"
245
+ | "BY_RECIPIENT"
246
+ | "BY_THIRD_PARTY"
247
+ | "OWN_BY_ISSUER"
248
+ | "OWN_BY_RECIPIENT"
249
+ | "NONE";
250
+
251
+ /** `infIntermed`: the third-party platform the sale went through. */
252
+ export interface SaleIntermediary {
253
+ readonly cnpj: string;
254
+ /** `idCadIntTran`: the seller's id on that platform. */
255
+ readonly userId: string;
256
+ }
257
+
258
+ /** `infRespTec`: the software house responsible for the issuing system. */
259
+ export interface TechnicalResponsible {
260
+ readonly cnpj: string;
261
+ readonly contactName: string;
262
+ readonly email: string;
263
+ readonly phone: string;
264
+ }
265
+
266
+ /** One sale, ready to become an NF-e or an NFC-e. */
267
+ export interface SaleForDocument {
268
+ readonly version: 1;
269
+ /** `serie`, 0–999. */
270
+ readonly series: number;
271
+ /** `nNF`, 1–999999999. The package's counter owns it. */
272
+ readonly number: number;
273
+ /**
274
+ * `cNF`: the 8-digit code inside the access key. The caller draws it ONCE and
275
+ * keeps it with the document, so a retried call yields the same key.
276
+ */
277
+ readonly keyCode: string;
278
+ /** `dhEmi`: ISO 8601 with the UTC offset, `2026-11-20T12:30:00-03:00`. */
279
+ readonly issuedAt: string;
280
+ /** `natOp`. */
281
+ readonly operationNature: string;
282
+ readonly purpose: DocumentPurpose;
283
+ /**
284
+ * `tpNF`. Absent is `OUT`. A buyer's return is an NF-e (model 55) with
285
+ * `purpose: "RETURN"` and `operation: "IN"`; an NFC-e has neither.
286
+ */
287
+ readonly operation?: DocumentOperation;
288
+ /**
289
+ * `NFref`, at most 500, in order. Absent is none. A `RETURN` quotes the
290
+ * document it returns here, or it is refused (`RETURN_NEEDS_REFERENCE`); an
291
+ * NFC-e quotes none (SEFAZ 708). For a buyer's return the host sets CFOP
292
+ * 1202 (within the state) or 2202 (between states) on every line, and a
293
+ * single `NO_PAYMENT` payment; the package checks neither.
294
+ */
295
+ readonly referencedDocuments?: readonly ReferencedDocument[];
296
+ readonly destination: OperationDestination;
297
+ readonly presence: BuyerPresence;
298
+ /** `indFinal`. */
299
+ readonly finalConsumer: boolean;
300
+ readonly intermediary: SaleIntermediary | null;
301
+ readonly issuer: DocumentIssuer;
302
+ /** `null` on an NFC-e with no identified buyer. */
303
+ readonly buyer: DocumentBuyer | null;
304
+ /** 1–990 items. */
305
+ readonly lines: readonly SaleLine[];
306
+ readonly freight: FreightMode;
307
+ /** 1–100 payments. */
308
+ readonly payments: readonly SalePayment[];
309
+ /** `vTroco`. */
310
+ readonly changeCents: number;
311
+ readonly additionalInfo: {
312
+ /** `infCpl`. */
313
+ readonly forTaxpayer: string | null;
314
+ /** `infAdFisco`. */
315
+ readonly forTaxAuthority: string | null;
316
+ };
317
+ readonly technicalResponsible: TechnicalResponsible | null;
318
+ }
@@ -0,0 +1,9 @@
1
+ /**
2
+ * `@12-apps/fiscal/sidecar` — the wire contract of the fiscal service that
3
+ * ships in this package's `sidecar/` folder (PHP over sped-nfe, with its own
4
+ * Dockerfile): the request and answer bodies of each endpoint and the error
5
+ * classes a failed call is sorted into.
6
+ */
7
+
8
+ export { SIDECAR_ERROR_CLASSES } from "./types";
9
+ export type * from "./types";
@@ -0,0 +1,245 @@
1
+ /**
2
+ * The wire contract of the fiscal service (`sidecar/` in this package): a
3
+ * stateless HTTP door in front of sped-nfe. JSON in, JSON out.
4
+ *
5
+ * Stateless means every call carries what it needs: the signing certificate
6
+ * (an A1 `.pfx` as base64 and its password) and, for an NFC-e, the CSC. The
7
+ * service keeps nothing between calls, writes nothing to disk and never logs
8
+ * any of the three.
9
+ */
10
+
11
+ import type { SaleForDocument } from "../sale/types";
12
+
13
+ /** The path segment of a document model: `nfe` is model 55, `nfce` model 65. */
14
+ export type DocumentModelPath = "nfe" | "nfce";
15
+
16
+ /** The SEFAZ environment (`tpAmb` 2 and 1). */
17
+ export type SefazEnvironment = "homologacao" | "producao";
18
+
19
+ /** The A1 certificate, per call. */
20
+ export interface SigningCertificate {
21
+ /** The `.pfx` (PKCS#12) bytes, base64. */
22
+ readonly pfxBase64: string;
23
+ readonly password: string;
24
+ }
25
+
26
+ /** The NFC-e's Código de Segurança do Contribuinte and its id. */
27
+ export interface Csc {
28
+ readonly id: string;
29
+ readonly token: string;
30
+ }
31
+
32
+ interface Authenticated {
33
+ readonly environment: SefazEnvironment;
34
+ readonly certificate: SigningCertificate;
35
+ }
36
+
37
+ /**
38
+ * `POST /<model>/issue`: builds, signs and transmits. `csc` is required for
39
+ * `nfce` and refused for `nfe`.
40
+ */
41
+ export interface IssueRequest extends Authenticated {
42
+ readonly csc: Csc | null;
43
+ readonly document: SaleForDocument;
44
+ }
45
+
46
+ /** Why and since when the caixa issues offline (`dhCont`, `xJust`). */
47
+ export interface ContingencyEntry {
48
+ /** ISO 8601 with the UTC offset. */
49
+ readonly since: string;
50
+ /** 15–256 characters. */
51
+ readonly reason: string;
52
+ }
53
+
54
+ /** `POST /nfce/sign-contingency`: builds and signs with `tpEmis = 9`; does NOT transmit. */
55
+ export interface SignContingencyRequest extends IssueRequest {
56
+ readonly contingency: ContingencyEntry;
57
+ }
58
+
59
+ /** `POST /<model>/transmit`: an already signed XML (from `/nfce/sign-contingency`, say). */
60
+ export interface TransmitRequest extends Authenticated {
61
+ readonly signedXml: string;
62
+ }
63
+
64
+ /** `POST /<model>/cancel`: the UF and the issuer come from the access key. */
65
+ export interface CancelRequest extends Authenticated {
66
+ readonly accessKey: string;
67
+ /** The authorisation protocol (`nProt`). */
68
+ readonly protocol: string;
69
+ /** 15–255 characters. */
70
+ readonly reason: string;
71
+ }
72
+
73
+ /**
74
+ * `POST /nfce/cancel-substitution`: the NFC-e "cancelamento por substituição"
75
+ * (event 110112) — an online NFC-e found authorised after its sale was issued
76
+ * again in contingency, cancelled naming the substitute. Answers as `/cancel`.
77
+ */
78
+ export interface CancelBySubstitutionRequest extends CancelRequest {
79
+ /** The contingency document that replaced it (`chNFeRef`). */
80
+ readonly substituteAccessKey: string;
81
+ }
82
+
83
+ /** `POST /<model>/lookup`. */
84
+ export interface LookupRequest extends Authenticated {
85
+ readonly accessKey: string;
86
+ }
87
+
88
+ /** `POST /inutilize`: voids a range of unused numbers. */
89
+ export interface InutilizeRequest extends Authenticated {
90
+ readonly model: DocumentModelPath;
91
+ readonly uf: string;
92
+ readonly cnpj: string;
93
+ /** The year of the numbers, four digits. */
94
+ readonly year: number;
95
+ readonly series: number;
96
+ readonly from: number;
97
+ readonly to: number;
98
+ /** 15–255 characters. */
99
+ readonly reason: string;
100
+ }
101
+
102
+ /** What SEFAZ answered, as the service read it. */
103
+ export interface SefazAnswer {
104
+ /** `cStat`. */
105
+ readonly statusCode: string;
106
+ /** `xMotivo`. */
107
+ readonly statusReason: string;
108
+ /** The SOAP body SEFAZ returned, verbatim. */
109
+ readonly sefazReply: string;
110
+ }
111
+
112
+ /**
113
+ * `/issue` and `/transmit`: SEFAZ's final answer on the document.
114
+ *
115
+ * - `AUTHORIZED` (100, 120, 150).
116
+ * - `DENIED` (110, 301, 302, 303): a denial of use. The number is SPENT and
117
+ * the denial is kept like an authorisation (its `authorizedXml` carries the
118
+ * denial protocol); it is not a rejection, which leaves the number free.
119
+ *
120
+ * A retried call answers the same: SEFAZ's "already authorised" (204) and
121
+ * "already denied" (205), and a request sent with no answer, are settled by
122
+ * looking the key up, so a retry never turns an authorised document into an error.
123
+ */
124
+ export interface IssuedDocument extends SefazAnswer {
125
+ readonly status: "AUTHORIZED" | "DENIED";
126
+ readonly accessKey: string;
127
+ readonly protocol: string;
128
+ /** `dhRecbto` of the protocol. */
129
+ readonly authorizedAt: string;
130
+ readonly signedXml: string;
131
+ /** The `nfeProc`: the signed XML with its protocol (of authorisation or of denial), what is stored. */
132
+ readonly authorizedXml: string;
133
+ }
134
+
135
+ /** `/nfce/sign-contingency`. */
136
+ export interface ContingencySignedDocument {
137
+ readonly status: "SIGNED";
138
+ readonly accessKey: string;
139
+ /** Carries `tpEmis = 9` and the QR code; transmit it later through `/nfce/transmit`. */
140
+ readonly signedXml: string;
141
+ }
142
+
143
+ /**
144
+ * `/cancel`. A retried cancel (SEFAZ's 218 "already cancelled" or 573
145
+ * "duplicate event", or a cancel sent with no answer) is settled by looking
146
+ * the key up, and answers CANCELLED with what the lookup carries: the event's
147
+ * protocol and XML when SEFAZ returns them, `null` when it does not.
148
+ */
149
+ export interface CancelledDocument extends SefazAnswer {
150
+ readonly status: "CANCELLED";
151
+ readonly accessKey: string;
152
+ /** The event's protocol. */
153
+ readonly protocol: string | null;
154
+ readonly registeredAt: string | null;
155
+ /** The `procEventoNFe`. */
156
+ readonly eventXml: string | null;
157
+ }
158
+
159
+ /** `/lookup`: what SEFAZ knows of the key. `NOT_FOUND` is an answer, not an error. */
160
+ export interface LookedUpDocument extends SefazAnswer {
161
+ readonly status: "AUTHORIZED" | "CANCELLED" | "DENIED" | "NOT_FOUND";
162
+ readonly accessKey: string;
163
+ readonly protocol: string | null;
164
+ }
165
+
166
+ /**
167
+ * `/inutilize`. A retried inutilização (563, "a request for the same range
168
+ * already exists") answers INUTILIZED too, with `protocol` and
169
+ * `inutilizationXml` `null`: the range is void at SEFAZ, and SEFAZ offers no
170
+ * query that would return the first protocol.
171
+ */
172
+ export interface InutilizedRange extends SefazAnswer {
173
+ readonly status: "INUTILIZED";
174
+ readonly protocol: string | null;
175
+ readonly registeredAt: string | null;
176
+ /** The signed request with its reply (`procInutNFe`). */
177
+ readonly inutilizationXml: string | null;
178
+ }
179
+
180
+ /**
181
+ * How a failed call is classified — the issuer port's own classes:
182
+ *
183
+ * - `REJECTED`: SEFAZ refused the document or the event; `code` is its `cStat`.
184
+ * The number is NOT spent (a denial is not an error: it answers `DENIED`).
185
+ * - `RETRYABLE`: try the same call again later. When `outcomeUnknown` is true
186
+ * the request went out and neither it nor the lookup that would settle it
187
+ * was answered: look the key up before sending it again.
188
+ * - `CONTINGENCY`: SEFAZ is unavailable. For an NFC-e being issued, nothing
189
+ * reached SEFAZ (or the lookup after an unanswered request could not reach
190
+ * it): go offline through `/nfce/sign-contingency`. For an NF-e (model 55)
191
+ * the service has no offline path (no SVC, no EPEC): treat it as RETRYABLE.
192
+ * - `AUTH`: the certificate is unreadable, the password wrong, the certificate
193
+ * expired, or SEFAZ refused it.
194
+ * - `INVALID`: the request itself is malformed (the schema, a missing CSC, an
195
+ * XML the layout refuses, a document the layout version cannot express).
196
+ * Fix the input; never retry it as is.
197
+ * - `INTERNAL`: a defect of the service, or a 4xx other than 403/408/429 from
198
+ * the verified SEFAZ host (a wrong web-service address). A retry would only repeat it.
199
+ */
200
+ export type SidecarErrorClass = "REJECTED" | "RETRYABLE" | "CONTINGENCY" | "AUTH" | "INVALID" | "INTERNAL";
201
+
202
+ export const SIDECAR_ERROR_CLASSES: readonly SidecarErrorClass[] = [
203
+ "REJECTED",
204
+ "RETRYABLE",
205
+ "CONTINGENCY",
206
+ "AUTH",
207
+ "INVALID",
208
+ "INTERNAL",
209
+ ];
210
+
211
+ /** The body of every non-2xx answer. */
212
+ export interface SidecarErrorBody {
213
+ readonly error: {
214
+ readonly class: SidecarErrorClass;
215
+ /**
216
+ * The SEFAZ `cStat` when SEFAZ answered (always for `REJECTED`); for
217
+ * `INVALID`, a named code where one applies (`NT_2026_008_NOT_SUPPORTED`:
218
+ * a document issued on or after 2027-01-01, which needs NT 2026.008's
219
+ * `vProdLiq`; `RETURN_ON_NFCE`: a return asked of an NFC-e, which has no
220
+ * return purpose; `RETURN_NEEDS_REFERENCE`: a return quoting no
221
+ * `referencedDocuments`); `null` otherwise.
222
+ */
223
+ readonly code: string | null;
224
+ readonly message: string;
225
+ /** Per-field problems of an `INVALID` request. */
226
+ readonly details: readonly string[];
227
+ /** When the call got as far as building and signing: keep it, the key is now spoken for. */
228
+ readonly accessKey: string | null;
229
+ readonly signedXml: string | null;
230
+ readonly sefazReply: string | null;
231
+ /** The request went out and its outcome is still unknown: look the key up before sending it again. */
232
+ readonly outcomeUnknown: boolean;
233
+ };
234
+ }
235
+
236
+ /** `GET /health`. */
237
+ export interface SidecarHealth {
238
+ readonly status: "ok";
239
+ /** The libraries the service runs, by name, with the version installed. */
240
+ readonly libraries: Readonly<Record<string, string>>;
241
+ /** The schema package the NF-e layout is validated against. */
242
+ readonly nfeSchemas: string;
243
+ /** Whether SEFAZ's server certificate is verified; `false` only with `FISCAL_SEFAZ_TLS_VERIFY=off`. */
244
+ readonly sefazTlsVerify: boolean;
245
+ }