@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.
- package/README.md +152 -7
- 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-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 +3 -246
- 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 +30 -16
- package/dist/manifest/index.js +11 -17
- package/dist/manifest/index.js.map +1 -1
- 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 +63 -5
- 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/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 +25 -16
- 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
|
@@ -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
|
+
}
|