@12-apps/fiscal 1.0.0 → 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.
Files changed (140) hide show
  1. package/README.md +152 -7
  2. package/dist/chunk-27B4HNO6.js +574 -0
  3. package/dist/chunk-27B4HNO6.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-ALABGVPO.js +247 -0
  7. package/dist/chunk-ALABGVPO.js.map +1 -0
  8. package/dist/chunk-FOFIN5M7.js +14 -0
  9. package/dist/chunk-FOFIN5M7.js.map +1 -0
  10. package/dist/chunk-HQ2NXSTX.js +85 -0
  11. package/dist/chunk-HQ2NXSTX.js.map +1 -0
  12. package/dist/chunk-PNTKG3DZ.js +47 -0
  13. package/dist/chunk-PNTKG3DZ.js.map +1 -0
  14. package/dist/chunk-RRFKYVLZ.js +192 -0
  15. package/dist/chunk-RRFKYVLZ.js.map +1 -0
  16. package/dist/chunk-V5ZQAAJT.js +210 -0
  17. package/dist/chunk-V5ZQAAJT.js.map +1 -0
  18. package/dist/chunk-X6MRDUYH.js +21 -0
  19. package/dist/chunk-X6MRDUYH.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 +169 -0
  33. package/dist/documents/index.js +1228 -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 +73 -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 +243 -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 +216 -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 +149 -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 +401 -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 +383 -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 +41 -0
  109. package/src/documents/helpers.ts +128 -0
  110. package/src/documents/index.ts +39 -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 +296 -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 +264 -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 +292 -0
  139. package/src/sidecar/index.ts +9 -0
  140. package/src/sidecar/types.ts +243 -0
@@ -0,0 +1,149 @@
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
+ ## Errors
60
+
61
+ Every failure is `{ error: { class, code, message, details, accessKey, signedXml, sefazReply, outcomeUnknown } }`:
62
+
63
+ | class | HTTP | when |
64
+ |---|---|---|
65
+ | `REJECTED` | 422 | SEFAZ said no; `code` is its `cStat`. The number is not spent (a denial answers `DENIED`, not an error). |
66
+ | `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. |
67
+ | `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". |
68
+ | `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. |
69
+ | `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. |
70
+ | `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. |
71
+
72
+ When the call got as far as signing, `accessKey` and `signedXml` come back
73
+ with the error: the key is spoken for, and an NFC-e can be signed offline.
74
+
75
+ ## Stateless, and quiet about secrets
76
+
77
+ - The certificate, its password and the CSC arrive with each call and leave
78
+ with it. The kernel is built per request; no class holds static state.
79
+ - Nothing is written to disk. sped-common's own SOAP transport writes the
80
+ private key to a temporary folder before every request; this service gives
81
+ cURL the key in memory instead (`CURLOPT_SSLKEY_BLOB`). The image runs with a
82
+ read-only root filesystem (Apache's pid needs a tmpfs at `/var/run/apache2`).
83
+ - The request log is one JSON line per call on stderr: time, method, path,
84
+ status, duration, error class and SEFAZ code. Nothing read from the body is
85
+ ever in it, and stack traces carry no arguments
86
+ (`zend.exception_ignore_args`).
87
+
88
+ ## Configuration
89
+
90
+ | variable | default | |
91
+ |---|---|---|
92
+ | `FISCAL_SEFAZ_TIMEOUT_SECONDS` | `30` | connect timeout, TLS handshake included; the whole request gets 20 s more |
93
+ | `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. |
94
+ | `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. |
95
+
96
+ The image listens on 8080 as `www-data`, and its `HEALTHCHECK` calls `/health`.
97
+ Apache prefork runs at most four workers and PHP caps a request at 128M
98
+ (`docker/mpm.conf` argues the numbers: a 990-item NF-e peaks at 36 MB), so the
99
+ service needs at most about 512M; a compose memory limit of 640M leaves Apache
100
+ its parent process.
101
+ OpenSSL's legacy provider is on, because most A1 files issued before 2023 are
102
+ encrypted with RC2-40.
103
+
104
+ **Follow-up: ICP-Brasil root v13.** ITI has published a v13 root that is not
105
+ in `docker/icp-brasil.pem`: its fingerprint could not yet be checked against a
106
+ source independent of the download. Add it, with the new sha256 in the
107
+ Dockerfile, once it is.
108
+
109
+ ## A second library
110
+
111
+ Each library is a `Module` that registers its own paths
112
+ (`src/Nfe/NfeModule.php`). An NFS-e library is a second module, with its
113
+ `/nfse/...` paths, appended in `Kernel::modules()`; the router refuses a path
114
+ registered twice.
115
+
116
+ ## Tests
117
+
118
+ ```bash
119
+ composer install # in this folder
120
+ vendor/bin/phpunit --testsuite unit
121
+ vendor/bin/phpunit --testsuite live # skips without the variables below
122
+ ```
123
+
124
+ The unit suite needs no certificate: it makes a throwaway self-signed A1 in
125
+ the test (never written to the repository), validates the signed XML against
126
+ the schema package's XSD, plays recorded SEFAZ replies
127
+ (`tests/fixtures/sefaz/`), boots the service with `php -S` to read its request
128
+ log after a wrong password, checks that no call writes a file, and drives the
129
+ real cURL transport against a local TLS server that never accepts, drops or
130
+ hangs after the upload, or refuses the client certificate. CI runs it on every
131
+ change under `sidecar/`, and builds the image.
132
+
133
+ The live suite runs the acceptance against SEFAZ homologação with a real A1 of
134
+ a CNPJ accredited for NFC-e: `FISCAL_TEST_PFX_BASE64`,
135
+ `FISCAL_TEST_PFX_PASSWORD`, `FISCAL_TEST_CSC`, `FISCAL_TEST_CSC_ID`,
136
+ `FISCAL_TEST_CNPJ`, `FISCAL_TEST_UF`; optionally `FISCAL_TEST_IE`,
137
+ `FISCAL_TEST_MUNICIPALITY_IBGE`, `FISCAL_TEST_MUNICIPALITY`,
138
+ `FISCAL_TEST_TAX_REGIME`, `FISCAL_TEST_SERIES` (default 889), and
139
+ `FISCAL_TEST_BASE_URL` to drive a running service. It runs with SEFAZ's
140
+ certificate verified, so its first pass also proves the trust store. Mutual
141
+ TLS cannot cross an intercepting proxy, so run it where the machine reaches
142
+ SEFAZ directly.
143
+
144
+ ## Versions
145
+
146
+ sped-nfe `5.2.9`, schema package `PL_010_V1.30` (Pacote de Liberação 010f: NT
147
+ 2025.002 v1.50 and NT 2026.007 v1.00). NT 2026.008's `vProdLiq` and
148
+ `vProdLiqTot`, needed when the IBS/CBS move inside `vProd` in 2027, are on
149
+ 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
+ }