@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,162 @@
1
+ # The fiscal service (`sidecar/`)
2
+
3
+ A thin, stateless HTTP door in front of
4
+ [`nfephp-org/sped-nfe`](https://github.com/nfephp-org/sped-nfe), a PHP library
5
+ that builds, signs and transmits NF-e (model 55) and NFC-e (model 65). It ships
6
+ inside `@12-apps/fiscal` with its own `Dockerfile`, so a host builds the image
7
+ from the version it pins:
8
+
9
+ ```bash
10
+ docker build -t fiscal-sidecar node_modules/@12-apps/fiscal/sidecar
11
+ ```
12
+
13
+ The TypeScript side of the contract is in the same package:
14
+ `@12-apps/fiscal/sale` (the document, `SaleForDocument`),
15
+ `@12-apps/fiscal/sidecar` (each endpoint's request and answer, the error
16
+ classes) and `@12-apps/fiscal/sidecar/schema/sale-for-document.schema.json`
17
+ (the JSON schema this service validates every document against).
18
+
19
+ ## Endpoints
20
+
21
+ JSON in, JSON out. `<model>` is `nfe` or `nfce`. Every call that talks to
22
+ SEFAZ carries `environment` (`homologacao` | `producao`) and `certificate`
23
+ (`{ pfxBase64, password }`, the A1).
24
+
25
+ | endpoint | does | answers |
26
+ |---|---|---|
27
+ | `POST /<model>/issue` | `{ environment, certificate, csc, document }`: builds, signs and transmits. `csc` (`{ id, token }`) is required for `nfce` and must be `null` for `nfe`. | `AUTHORIZED` or `DENIED` (a denial of use: the number is spent): `accessKey`, `protocol`, `authorizedAt`, `signedXml`, `authorizedXml` (the `nfeProc`), `statusCode`, `statusReason`, `sefazReply` |
28
+ | `POST /nfce/sign-contingency` | the same, plus `contingency: { since, reason }`; builds and signs with `tpEmis = 9`, sends nothing | `SIGNED`: `accessKey`, `signedXml` |
29
+ | `POST /<model>/transmit` | `{ environment, certificate, signedXml }` | as `/issue` |
30
+ | `POST /<model>/cancel` | `{ environment, certificate, accessKey, protocol, reason }` | `CANCELLED`: the event's `protocol`, `registeredAt`, `eventXml` (each `null` when a retried cancel is settled by a lookup that does not carry them) |
31
+ | `POST /nfce/cancel-substitution` | the cancel's body plus `substituteAccessKey`: the NFC-e "cancelamento por substituição" (event 110112), for an online NFC-e found authorised after its sale was issued again in contingency | as `/cancel` |
32
+ | `POST /<model>/lookup` | `{ environment, certificate, accessKey }` | `AUTHORIZED`, `CANCELLED`, `DENIED` or `NOT_FOUND`, with the authorisation `protocol` |
33
+ | `POST /inutilize` | `{ environment, certificate, model, uf, cnpj, year, series, from, to, reason }` | `INUTILIZED`: `protocol`, `registeredAt`, `inutilizationXml` (`protocol` and the XML `null` on a retry SEFAZ answers 563) |
34
+ | `GET /health` | | `{ status: "ok", libraries, nfeSchemas, sefazTlsVerify }` |
35
+
36
+ The UF and the issuer of `cancel` and `lookup` are read from the access key.
37
+ The `document.keyCode` (`cNF`) is the caller's, drawn once and kept, so a
38
+ retried `issue` yields the same key.
39
+
40
+ **Retrying is safe, and answers like the first call.** SEFAZ's "already done"
41
+ codes are settled, not reported: 204 (the key is already authorised) and 205
42
+ (already denied) on `issue`/`transmit` look the key up and answer `AUTHORIZED`
43
+ or `DENIED` (a different document under the same key stays `REJECTED`); 218
44
+ (already cancelled) and 573 (duplicate event) on `cancel` answer `CANCELLED`;
45
+ 563 (same range already requested) on `/inutilize` answers `INUTILIZED`.
46
+
47
+ **A request that went out and got no answer** (an empty reply, a receive
48
+ error or a timeout after the upload, HTTP 5xx) is settled by looking the key
49
+ up FIRST, and the lookup's answer is the answer. Only when the lookup cannot
50
+ reach SEFAZ either does an NFC-e being issued answer `CONTINGENCY` (with
51
+ `outcomeUnknown: true`); everywhere else it is `RETRYABLE`. A blind
52
+ contingency could put a second document on the same sale.
53
+
54
+ **Layout limit.** A document issued on or after 2027-01-01 is refused as
55
+ `INVALID` with code `NT_2026_008_NOT_SUPPORTED`: from 2027 the IBS/CBS go
56
+ inside `vProd` and the net price travels in NT 2026.008's `vProdLiq`, which
57
+ sped-nfe 5.2.9 cannot write.
58
+
59
+ **A return document.** `operation` maps to `tpNF` (`OUT` 1, `IN` 0) and
60
+ `referencedDocuments[].accessKey` to `NFref/refNFe`, in order. Both are
61
+ optional: a document without them is `tpNF` 1 with no `NFref`, byte for byte
62
+ what it built before they existed. A buyer's return is an NF-e of entry
63
+ (`/nfe/issue`, `purpose: "RETURN"`, `operation: "IN"`) that references the
64
+ NFC-e. `INVALID` with code `RETURN_ON_NFCE` refuses a return asked of an NFC-e
65
+ (an NFC-e has no return purpose), and with code `RETURN_NEEDS_REFERENCE` a
66
+ return quoting no document; an NFC-e of entry, and an NFC-e with any
67
+ `referencedDocuments` (SEFAZ rejects `NFref` on a model 65 with 708), are
68
+ `INVALID` too. The caller sets CFOP 1202 (within the state) or 2202 (between
69
+ states) on every line, and a single `NO_PAYMENT` payment; the service checks
70
+ neither.
71
+
72
+ ## Errors
73
+
74
+ Every failure is `{ error: { class, code, message, details, accessKey, signedXml, sefazReply, outcomeUnknown } }`:
75
+
76
+ | class | HTTP | when |
77
+ |---|---|---|
78
+ | `REJECTED` | 422 | SEFAZ said no; `code` is its `cStat`. The number is not spent (a denial answers `DENIED`, not an error). |
79
+ | `RETRYABLE` | 503 | try again: nothing reached SEFAZ outside NFC-e issuing, a receipt with no protocol yet (103, 105), SEFAZ unable to reach a revocation list (286, 296), rate limiting (656), 999, SEFAZ stopped (108, 109) outside issuing, a reply with no status, a 4xx that is not SEFAZ's. With `outcomeUnknown: true`, look the key up before sending again. |
80
+ | `CONTINGENCY` | 503 | issuing an NFC-e: nothing reached SEFAZ, or SEFAZ is stopped (108, 109), or a request with no answer could not be settled by a lookup. Go offline through `/nfce/sign-contingency`. **On an NF-e (model 55)** there is no offline path in this service (no SVC, no EPEC): only 108/109 answer `CONTINGENCY` there, and the host treats it as "retry later". |
81
+ | `AUTH` | 401 | the `.pfx` does not open (wrong password, not PKCS#12), the certificate expired, the client certificate was refused at the TLS handshake or by an HTTP 403 from a verified SEFAZ host, or by code (213, 280–285, 290–295). Codes from sped-nfe's `storage/cstat.json`. An HTTP refusal's message names the IIS substatus (403.6 is an IP block, 403.7 a missing client certificate) or quotes the start of SEFAZ's page. |
82
+ | `INVALID` | 400 | the request is malformed: the schema, a missing CSC, an XML the layout's XSD refuses, a quantity with more than four decimals, a document past the layout limit. Never retry it as is. |
83
+ | `INTERNAL` | 500 | a defect of the service, or a 4xx other than 403/408/429 from the verified SEFAZ host (a wrong web-service address); a retry would repeat it. |
84
+
85
+ When the call got as far as signing, `accessKey` and `signedXml` come back
86
+ with the error: the key is spoken for, and an NFC-e can be signed offline.
87
+
88
+ ## Stateless, and quiet about secrets
89
+
90
+ - The certificate, its password and the CSC arrive with each call and leave
91
+ with it. The kernel is built per request; no class holds static state.
92
+ - Nothing is written to disk. sped-common's own SOAP transport writes the
93
+ private key to a temporary folder before every request; this service gives
94
+ cURL the key in memory instead (`CURLOPT_SSLKEY_BLOB`). The image runs with a
95
+ read-only root filesystem (Apache's pid needs a tmpfs at `/var/run/apache2`).
96
+ - The request log is one JSON line per call on stderr: time, method, path,
97
+ status, duration, error class and SEFAZ code. Nothing read from the body is
98
+ ever in it, and stack traces carry no arguments
99
+ (`zend.exception_ignore_args`).
100
+
101
+ ## Configuration
102
+
103
+ | variable | default | |
104
+ |---|---|---|
105
+ | `FISCAL_SEFAZ_TIMEOUT_SECONDS` | `30` | connect timeout, TLS handshake included; the whole request gets 20 s more |
106
+ | `FISCAL_SEFAZ_TLS_VERIFY` | on | SEFAZ's server certificate is verified. `off` is the only value that turns it off, and `/health` then reports `sefazTlsVerify: false`. Unverified, anyone on the path reads every document and can forge SEFAZ's answers. |
107
+ | `FISCAL_SEFAZ_CA_BUNDLE` | the image's | a PEM replacing the trust store. The image builds `/etc/ssl/fiscal-sidecar-ca.pem` from its Mozilla bundle plus `docker/icp-brasil.pem` (the ICP-Brasil roots and intermediates ITI publishes, sha256-checked in the Dockerfile): some SEFAZ hosts present ICP-Brasil server certificates, others public ones. Outside the image the system bundle plus that PEM are used. |
108
+
109
+ The image listens on 8080 as `www-data`, and its `HEALTHCHECK` calls `/health`.
110
+ Apache prefork runs at most four workers and PHP caps a request at 128M
111
+ (`docker/mpm.conf` argues the numbers: a 990-item NF-e peaks at 36 MB), so the
112
+ service needs at most about 512M; a compose memory limit of 640M leaves Apache
113
+ its parent process.
114
+ OpenSSL's legacy provider is on, because most A1 files issued before 2023 are
115
+ encrypted with RC2-40.
116
+
117
+ **Follow-up: ICP-Brasil root v13.** ITI has published a v13 root that is not
118
+ in `docker/icp-brasil.pem`: its fingerprint could not yet be checked against a
119
+ source independent of the download. Add it, with the new sha256 in the
120
+ Dockerfile, once it is.
121
+
122
+ ## A second library
123
+
124
+ Each library is a `Module` that registers its own paths
125
+ (`src/Nfe/NfeModule.php`). An NFS-e library is a second module, with its
126
+ `/nfse/...` paths, appended in `Kernel::modules()`; the router refuses a path
127
+ registered twice.
128
+
129
+ ## Tests
130
+
131
+ ```bash
132
+ composer install # in this folder
133
+ vendor/bin/phpunit --testsuite unit
134
+ vendor/bin/phpunit --testsuite live # skips without the variables below
135
+ ```
136
+
137
+ The unit suite needs no certificate: it makes a throwaway self-signed A1 in
138
+ the test (never written to the repository), validates the signed XML against
139
+ the schema package's XSD, plays recorded SEFAZ replies
140
+ (`tests/fixtures/sefaz/`), boots the service with `php -S` to read its request
141
+ log after a wrong password, checks that no call writes a file, and drives the
142
+ real cURL transport against a local TLS server that never accepts, drops or
143
+ hangs after the upload, or refuses the client certificate. CI runs it on every
144
+ change under `sidecar/`, and builds the image.
145
+
146
+ The live suite runs the acceptance against SEFAZ homologação with a real A1 of
147
+ a CNPJ accredited for NFC-e: `FISCAL_TEST_PFX_BASE64`,
148
+ `FISCAL_TEST_PFX_PASSWORD`, `FISCAL_TEST_CSC`, `FISCAL_TEST_CSC_ID`,
149
+ `FISCAL_TEST_CNPJ`, `FISCAL_TEST_UF`; optionally `FISCAL_TEST_IE`,
150
+ `FISCAL_TEST_MUNICIPALITY_IBGE`, `FISCAL_TEST_MUNICIPALITY`,
151
+ `FISCAL_TEST_TAX_REGIME`, `FISCAL_TEST_SERIES` (default 889), and
152
+ `FISCAL_TEST_BASE_URL` to drive a running service. It runs with SEFAZ's
153
+ certificate verified, so its first pass also proves the trust store. Mutual
154
+ TLS cannot cross an intercepting proxy, so run it where the machine reaches
155
+ SEFAZ directly.
156
+
157
+ ## Versions
158
+
159
+ sped-nfe `5.2.9`, schema package `PL_010_V1.30` (Pacote de Liberação 010f: NT
160
+ 2025.002 v1.50 and NT 2026.007 v1.00). NT 2026.008's `vProdLiq` and
161
+ `vProdLiqTot`, needed when the IBS/CBS move inside `vProd` in 2027, are on
162
+ sped-nfe's `master` after 5.2.9 and arrive with its next release.
@@ -0,0 +1,30 @@
1
+ {
2
+ "name": "12-apps/fiscal-sidecar",
3
+ "description": "A stateless HTTP door in front of sped-nfe: build, sign, transmit, cancel, look up and void NF-e and NFC-e.",
4
+ "type": "project",
5
+ "license": "MIT",
6
+ "require": {
7
+ "php": "~8.3.0",
8
+ "ext-curl": "*",
9
+ "ext-dom": "*",
10
+ "ext-json": "*",
11
+ "ext-libxml": "*",
12
+ "ext-openssl": "*",
13
+ "nfephp-org/sped-nfe": "5.2.9"
14
+ },
15
+ "require-dev": {
16
+ "phpunit/phpunit": "^11.5"
17
+ },
18
+ "autoload": {
19
+ "psr-4": { "Fiscal\\Sidecar\\": "src/" }
20
+ },
21
+ "autoload-dev": {
22
+ "psr-4": { "Fiscal\\Sidecar\\Tests\\": "tests/" }
23
+ },
24
+ "config": {
25
+ "platform": { "php": "8.3.6" },
26
+ "sort-packages": true,
27
+ "optimize-autoloader": true,
28
+ "allow-plugins": false
29
+ }
30
+ }