@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.
Files changed (155) hide show
  1. package/README.md +269 -2
  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-7QVYU63E.js +7 -0
  7. package/dist/chunk-7QVYU63E.js.map +1 -0
  8. package/dist/chunk-ALABGVPO.js +247 -0
  9. package/dist/chunk-ALABGVPO.js.map +1 -0
  10. package/dist/chunk-FOFIN5M7.js +14 -0
  11. package/dist/chunk-FOFIN5M7.js.map +1 -0
  12. package/dist/chunk-HQ2NXSTX.js +85 -0
  13. package/dist/chunk-HQ2NXSTX.js.map +1 -0
  14. package/dist/chunk-PNTKG3DZ.js +47 -0
  15. package/dist/chunk-PNTKG3DZ.js.map +1 -0
  16. package/dist/chunk-RRFKYVLZ.js +192 -0
  17. package/dist/chunk-RRFKYVLZ.js.map +1 -0
  18. package/dist/chunk-V5ZQAAJT.js +210 -0
  19. package/dist/chunk-V5ZQAAJT.js.map +1 -0
  20. package/dist/chunk-X6MRDUYH.js +21 -0
  21. package/dist/chunk-X6MRDUYH.js.map +1 -0
  22. package/dist/chunk-XQGW5HUG.js +30 -0
  23. package/dist/chunk-XQGW5HUG.js.map +1 -0
  24. package/dist/context-ChnWR4Kb.d.ts +455 -0
  25. package/dist/danfe/en-US.d.ts +12 -0
  26. package/dist/danfe/en-US.js +51 -0
  27. package/dist/danfe/en-US.js.map +1 -0
  28. package/dist/danfe/index.d.ts +50 -0
  29. package/dist/danfe/index.js +18 -0
  30. package/dist/danfe/index.js.map +1 -0
  31. package/dist/danfe/pt-BR.d.ts +11 -0
  32. package/dist/danfe/pt-BR.js +51 -0
  33. package/dist/danfe/pt-BR.js.map +1 -0
  34. package/dist/documents/index.d.ts +169 -0
  35. package/dist/documents/index.js +1228 -0
  36. package/dist/documents/index.js.map +1 -0
  37. package/dist/engine/index.d.ts +118 -0
  38. package/dist/engine/index.js +591 -0
  39. package/dist/engine/index.js.map +1 -0
  40. package/dist/http.d.ts +73 -0
  41. package/dist/http.js +16 -0
  42. package/dist/http.js.map +1 -0
  43. package/dist/issuer/index.d.ts +43 -0
  44. package/dist/issuer/index.js +131 -0
  45. package/dist/issuer/index.js.map +1 -0
  46. package/dist/jobs.d.ts +74 -0
  47. package/dist/jobs.js +22 -0
  48. package/dist/jobs.js.map +1 -0
  49. package/dist/labels-BNvflT0h.d.ts +44 -0
  50. package/dist/manifest/index.d.ts +97 -0
  51. package/dist/manifest/index.js +27 -0
  52. package/dist/manifest/index.js.map +1 -0
  53. package/dist/manifest/server.d.ts +57 -0
  54. package/dist/manifest/server.js +25 -0
  55. package/dist/manifest/server.js.map +1 -0
  56. package/dist/notifications.d.ts +93 -0
  57. package/dist/notifications.js +41 -0
  58. package/dist/notifications.js.map +1 -0
  59. package/dist/port-DpRFK56U.d.ts +238 -0
  60. package/dist/sale/index.d.ts +243 -0
  61. package/dist/sale/index.js +1 -0
  62. package/dist/sale/index.js.map +1 -0
  63. package/dist/service-KTjH7AxW.d.ts +139 -0
  64. package/dist/sidecar/index.d.ts +216 -0
  65. package/dist/sidecar/index.js +8 -0
  66. package/dist/sidecar/index.js.map +1 -0
  67. package/dist/types-B1b8LIWX.d.ts +247 -0
  68. package/package.json +126 -4
  69. package/prisma/fiscal.prisma +158 -0
  70. package/prisma/migrations/20261113220000_fiscal_documents/migration.sql +201 -0
  71. package/sidecar/.dockerignore +5 -0
  72. package/sidecar/Dockerfile +68 -0
  73. package/sidecar/README.md +149 -0
  74. package/sidecar/composer.json +30 -0
  75. package/sidecar/composer.lock +2224 -0
  76. package/sidecar/docker/apache.conf +14 -0
  77. package/sidecar/docker/icp-brasil.pem +8031 -0
  78. package/sidecar/docker/mpm.conf +17 -0
  79. package/sidecar/docker/openssl.cnf +16 -0
  80. package/sidecar/docker/php.ini +19 -0
  81. package/sidecar/public/index.php +15 -0
  82. package/sidecar/schema/sale-for-document.schema.json +401 -0
  83. package/sidecar/src/ErrorClass.php +31 -0
  84. package/sidecar/src/Http/Request.php +48 -0
  85. package/sidecar/src/Http/Response.php +32 -0
  86. package/sidecar/src/Http/Router.php +59 -0
  87. package/sidecar/src/Kernel.php +99 -0
  88. package/sidecar/src/Module.php +31 -0
  89. package/sidecar/src/Nfe/Classifier.php +89 -0
  90. package/sidecar/src/Nfe/Credentials.php +52 -0
  91. package/sidecar/src/Nfe/DocumentMapper.php +383 -0
  92. package/sidecar/src/Nfe/DocumentSchema.php +39 -0
  93. package/sidecar/src/Nfe/Input.php +125 -0
  94. package/sidecar/src/Nfe/Model.php +17 -0
  95. package/sidecar/src/Nfe/NfeModule.php +62 -0
  96. package/sidecar/src/Nfe/NfeService.php +504 -0
  97. package/sidecar/src/Nfe/Sefaz.php +49 -0
  98. package/sidecar/src/Nfe/SefazReply.php +81 -0
  99. package/sidecar/src/Nfe/Transport/CurlTransport.php +198 -0
  100. package/sidecar/src/Nfe/Transport/SoapAdapter.php +57 -0
  101. package/sidecar/src/Nfe/Transport/Transport.php +20 -0
  102. package/sidecar/src/Nfe/Transport/TransportFailure.php +42 -0
  103. package/sidecar/src/RequestLog.php +54 -0
  104. package/sidecar/src/ServiceError.php +69 -0
  105. package/src/danfe/en-US.ts +53 -0
  106. package/src/danfe/index.ts +11 -0
  107. package/src/danfe/labels.ts +49 -0
  108. package/src/danfe/pt-BR.ts +52 -0
  109. package/src/danfe/render.ts +265 -0
  110. package/src/danfe/xml.ts +45 -0
  111. package/src/documents/context.ts +260 -0
  112. package/src/documents/errors.ts +41 -0
  113. package/src/documents/helpers.ts +128 -0
  114. package/src/documents/index.ts +39 -0
  115. package/src/documents/lines.ts +63 -0
  116. package/src/documents/machine-steps.ts +260 -0
  117. package/src/documents/machine.ts +128 -0
  118. package/src/documents/memory.ts +138 -0
  119. package/src/documents/nfe-proc.ts +51 -0
  120. package/src/documents/ports.ts +130 -0
  121. package/src/documents/profile-input.ts +168 -0
  122. package/src/documents/profile.ts +98 -0
  123. package/src/documents/service-profile.ts +104 -0
  124. package/src/documents/service.ts +296 -0
  125. package/src/documents/settle.ts +121 -0
  126. package/src/documents/signing.ts +61 -0
  127. package/src/documents/sql-rows.ts +180 -0
  128. package/src/documents/sql-store.ts +242 -0
  129. package/src/documents/sql.ts +18 -0
  130. package/src/documents/steps.ts +173 -0
  131. package/src/documents/tests/integration/pglite.ts +73 -0
  132. package/src/documents/types.ts +193 -0
  133. package/src/engine/compare.ts +68 -0
  134. package/src/engine/compute.ts +40 -0
  135. package/src/engine/errors.ts +28 -0
  136. package/src/engine/index.ts +20 -0
  137. package/src/engine/oracle.ts +81 -0
  138. package/src/engine/plan.ts +268 -0
  139. package/src/engine/rounding.ts +81 -0
  140. package/src/engine/types.ts +270 -0
  141. package/src/engine/validate.ts +222 -0
  142. package/src/http.ts +264 -0
  143. package/src/issuer/index.ts +9 -0
  144. package/src/issuer/port.ts +109 -0
  145. package/src/issuer/sidecar.ts +171 -0
  146. package/src/jobs.ts +115 -0
  147. package/src/manifest/index.ts +46 -0
  148. package/src/manifest/permissions.ts +28 -0
  149. package/src/manifest/server.ts +20 -0
  150. package/src/notifications.ts +120 -0
  151. package/src/sale/index.ts +8 -0
  152. package/src/sale/types.ts +292 -0
  153. package/src/sidecar/index.ts +9 -0
  154. package/src/sidecar/types.ts +243 -0
  155. package/tables/ibs-cbs-2026-11-13.json +156 -0
@@ -0,0 +1,201 @@
1
+ -- @12-apps/fiscal (FUT-2237): the emitter profile, issuing points, one number
2
+ -- counter per issuing point and series, fiscal documents and their events.
3
+ -- Additive only: five new tables. Host ids (owner, subject) are stored by
4
+ -- value, with no foreign key into the host's tables.
5
+
6
+ CREATE TABLE "fiscal_emitter_profiles" (
7
+ "owner_id" TEXT NOT NULL,
8
+ "cnpj" TEXT NOT NULL,
9
+ "state_registration" TEXT NOT NULL,
10
+ "municipal_registration" TEXT,
11
+ "cnae" TEXT,
12
+ "legal_name" TEXT NOT NULL,
13
+ "trade_name" TEXT,
14
+ "tax_regime" TEXT NOT NULL,
15
+ "regime" TEXT NOT NULL,
16
+ "regime_effective_from" DATE NOT NULL,
17
+ "restaurant_regime" BOOLEAN NOT NULL,
18
+ "address" JSONB NOT NULL,
19
+ "environment" TEXT NOT NULL,
20
+ "document_policy" TEXT NOT NULL,
21
+ "signing_identity" TEXT NOT NULL,
22
+ "certificate_ciphertext" TEXT,
23
+ "certificate_password_ciphertext" TEXT,
24
+ "certificate_expires_at" TIMESTAMP(3),
25
+ "csc_id" TEXT,
26
+ "csc_ciphertext" TEXT,
27
+ "consent_recorded_at" TIMESTAMP(3),
28
+ "updated_at" TIMESTAMP(3) NOT NULL,
29
+
30
+ CONSTRAINT "fiscal_emitter_profiles_pkey" PRIMARY KEY ("owner_id"),
31
+ CONSTRAINT "fiscal_emitter_profiles_cnpj_check" CHECK ("cnpj" ~ '^[0-9A-Z]{12}[0-9]{2}$'),
32
+ CONSTRAINT "fiscal_emitter_profiles_tax_regime_check"
33
+ CHECK ("tax_regime" IN ('SIMPLES', 'SIMPLES_EXCESS', 'NORMAL', 'MEI')),
34
+ CONSTRAINT "fiscal_emitter_profiles_regime_check"
35
+ CHECK ("regime" IN ('SIMPLES', 'SIMPLES_IBS_CBS_REGULAR', 'REGIME_REGULAR', 'MEI', 'NAO_CONTRIBUINTE')),
36
+ CONSTRAINT "fiscal_emitter_profiles_environment_check"
37
+ CHECK ("environment" IN ('homologacao', 'producao')),
38
+ CONSTRAINT "fiscal_emitter_profiles_document_policy_check"
39
+ CHECK ("document_policy" IN ('ISSUED_HERE', 'ISSUED_ELSEWHERE', 'NONE')),
40
+ CONSTRAINT "fiscal_emitter_profiles_signing_identity_check"
41
+ CHECK ("signing_identity" IN ('STORE_CERTIFICATE', 'PLATFORM')),
42
+ -- The certificate is both halves or neither, and its expiry comes with it.
43
+ CONSTRAINT "fiscal_emitter_profiles_certificate_check"
44
+ CHECK (
45
+ ("certificate_ciphertext" IS NULL AND "certificate_password_ciphertext" IS NULL AND "certificate_expires_at" IS NULL)
46
+ OR
47
+ ("certificate_ciphertext" IS NOT NULL AND "certificate_password_ciphertext" IS NOT NULL AND "certificate_expires_at" IS NOT NULL)
48
+ ),
49
+ CONSTRAINT "fiscal_emitter_profiles_csc_check"
50
+ CHECK ("csc_ciphertext" IS NULL OR "csc_id" IS NOT NULL)
51
+ );
52
+
53
+ CREATE INDEX "fiscal_emitter_profiles_certificate_expires_at_idx"
54
+ ON "fiscal_emitter_profiles"("certificate_expires_at");
55
+
56
+ CREATE TABLE "fiscal_issuing_points" (
57
+ "id" TEXT NOT NULL,
58
+ "owner_id" TEXT NOT NULL,
59
+ "model" TEXT NOT NULL,
60
+ "online_series" INTEGER NOT NULL,
61
+ "contingency_series" INTEGER,
62
+ "created_at" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
63
+
64
+ CONSTRAINT "fiscal_issuing_points_pkey" PRIMARY KEY ("id"),
65
+ CONSTRAINT "fiscal_issuing_points_model_check" CHECK ("model" IN ('NFE', 'NFCE')),
66
+ CONSTRAINT "fiscal_issuing_points_online_series_check" CHECK ("online_series" BETWEEN 0 AND 889),
67
+ -- No offline NF-e path in the fiscal service: only an NFC-e point has a contingency series.
68
+ CONSTRAINT "fiscal_issuing_points_contingency_series_check"
69
+ CHECK (
70
+ "contingency_series" IS NULL
71
+ OR ("model" = 'NFCE' AND "contingency_series" BETWEEN 0 AND 889 AND "contingency_series" <> "online_series")
72
+ )
73
+ );
74
+
75
+ CREATE INDEX "fiscal_issuing_points_owner_id_idx" ON "fiscal_issuing_points"("owner_id");
76
+
77
+ CREATE TABLE "fiscal_number_counters" (
78
+ "issuer_cnpj" TEXT NOT NULL,
79
+ "environment" TEXT NOT NULL,
80
+ "model" TEXT NOT NULL,
81
+ "series" INTEGER NOT NULL,
82
+ "issuing_point_id" TEXT NOT NULL,
83
+ "series_kind" TEXT NOT NULL,
84
+ "next_number" INTEGER NOT NULL,
85
+ "updated_at" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
86
+
87
+ -- One counter per series of a CNPJ, as SEFAZ numbers: a series belongs to
88
+ -- ONE issuing point, whichever owner (one CNPJ can serve several) holds it.
89
+ CONSTRAINT "fiscal_number_counters_pkey" PRIMARY KEY ("issuer_cnpj", "environment", "model", "series"),
90
+ CONSTRAINT "fiscal_number_counters_issuing_point_id_fkey"
91
+ FOREIGN KEY ("issuing_point_id") REFERENCES "fiscal_issuing_points"("id") ON DELETE RESTRICT ON UPDATE CASCADE,
92
+ CONSTRAINT "fiscal_number_counters_environment_check" CHECK ("environment" IN ('homologacao', 'producao')),
93
+ CONSTRAINT "fiscal_number_counters_model_check" CHECK ("model" IN ('NFE', 'NFCE')),
94
+ CONSTRAINT "fiscal_number_counters_series_kind_check" CHECK ("series_kind" IN ('ONLINE', 'CONTINGENCY')),
95
+ -- nNF is 1 to 999 999 999; the next number after the last one is the ceiling.
96
+ CONSTRAINT "fiscal_number_counters_next_number_check" CHECK ("next_number" BETWEEN 1 AND 1000000000)
97
+ );
98
+
99
+ CREATE INDEX "fiscal_number_counters_issuing_point_id_idx" ON "fiscal_number_counters"("issuing_point_id");
100
+
101
+ CREATE TABLE "fiscal_documents" (
102
+ "id" TEXT NOT NULL,
103
+ "owner_id" TEXT NOT NULL,
104
+ "issuer_cnpj" TEXT NOT NULL,
105
+ "subject_id" TEXT NOT NULL,
106
+ "issuing_point_id" TEXT NOT NULL,
107
+ "model" TEXT NOT NULL,
108
+ "environment" TEXT NOT NULL,
109
+ "series_kind" TEXT NOT NULL,
110
+ "series" INTEGER NOT NULL,
111
+ "number" INTEGER NOT NULL,
112
+ "key_code" TEXT NOT NULL,
113
+ "status" TEXT NOT NULL,
114
+ "sale" JSONB NOT NULL,
115
+ "totals" JSONB NOT NULL,
116
+ "buyer_tax_id" TEXT,
117
+ "access_key" TEXT,
118
+ "protocol" TEXT,
119
+ "status_code" TEXT,
120
+ "status_reason" TEXT,
121
+ "last_error_class" TEXT,
122
+ "outcome_unknown" BOOLEAN NOT NULL DEFAULT false,
123
+ "issued_at" TEXT NOT NULL,
124
+ "authorized_at" TEXT,
125
+ "contingency" JSONB,
126
+ "cancelled_at" TEXT,
127
+ "cancel_reason" TEXT,
128
+ "cancel_protocol" TEXT,
129
+ "replaced_by_id" TEXT,
130
+ "number_void" TEXT,
131
+ "xml_key" TEXT,
132
+ "event_xml_key" TEXT,
133
+ "attempts" INTEGER NOT NULL DEFAULT 0,
134
+ "failures" INTEGER NOT NULL DEFAULT 0,
135
+ "next_attempt_at" TIMESTAMP(3),
136
+ "attention" BOOLEAN NOT NULL DEFAULT false,
137
+ "deadline_warned_at" TIMESTAMP(3),
138
+ "created_at" TIMESTAMP(3) NOT NULL,
139
+ "updated_at" TIMESTAMP(3) NOT NULL,
140
+
141
+ CONSTRAINT "fiscal_documents_pkey" PRIMARY KEY ("id"),
142
+ CONSTRAINT "fiscal_documents_model_check" CHECK ("model" IN ('NFE', 'NFCE')),
143
+ CONSTRAINT "fiscal_documents_environment_check" CHECK ("environment" IN ('homologacao', 'producao')),
144
+ CONSTRAINT "fiscal_documents_series_kind_check" CHECK ("series_kind" IN ('ONLINE', 'CONTINGENCY')),
145
+ CONSTRAINT "fiscal_documents_number_check" CHECK ("number" BETWEEN 1 AND 999999999),
146
+ CONSTRAINT "fiscal_documents_failures_check" CHECK ("failures" >= 0),
147
+ CONSTRAINT "fiscal_documents_key_code_check" CHECK ("key_code" ~ '^[0-9]{8}$'),
148
+ CONSTRAINT "fiscal_documents_status_check"
149
+ CHECK ("status" IN ('PENDING', 'SUBMITTED', 'AUTHORIZED', 'REJECTED', 'DENIED', 'CONTINGENCY', 'CANCELLED', 'REPLACED')),
150
+ CONSTRAINT "fiscal_documents_number_void_check"
151
+ CHECK ("number_void" IS NULL OR "number_void" IN ('LOOKUP_FIRST', 'INUTILIZE', 'CANCEL', 'INUTILIZED', 'CANCELLED', 'DENIED')),
152
+ CONSTRAINT "fiscal_documents_last_error_class_check"
153
+ CHECK ("last_error_class" IS NULL OR "last_error_class" IN ('REJECTED', 'RETRYABLE', 'CONTINGENCY', 'AUTH', 'INVALID', 'INTERNAL')),
154
+ -- An authorised, denied or cancelled document carries its key and protocol.
155
+ CONSTRAINT "fiscal_documents_authorized_check"
156
+ CHECK ("status" NOT IN ('AUTHORIZED', 'DENIED', 'CANCELLED') OR ("access_key" IS NOT NULL AND "protocol" IS NOT NULL)),
157
+ CONSTRAINT "fiscal_documents_contingency_check"
158
+ CHECK ("status" <> 'CONTINGENCY' OR ("series_kind" = 'CONTINGENCY' AND "contingency" IS NOT NULL AND "xml_key" IS NOT NULL)),
159
+ CONSTRAINT "fiscal_documents_replaced_check"
160
+ CHECK ("status" <> 'REPLACED' OR ("replaced_by_id" IS NOT NULL AND "number_void" IS NOT NULL))
161
+ );
162
+
163
+ CREATE UNIQUE INDEX "fiscal_documents_access_key_key" ON "fiscal_documents"("access_key");
164
+ CREATE UNIQUE INDEX "fiscal_documents_number_key"
165
+ ON "fiscal_documents"("issuer_cnpj", "environment", "model", "series", "number");
166
+ CREATE INDEX "fiscal_documents_owner_id_subject_id_model_idx" ON "fiscal_documents"("owner_id", "subject_id", "model");
167
+ -- Prisma cannot express a partial unique index. This is the per-subject guard:
168
+ -- at most ONE live document per (owner, subject, model) — not a replaced one,
169
+ -- nor an online one SEFAZ rejected (its number is voided and the sale issued
170
+ -- again) unless a lookup had found it authorised (its protocol is kept); a
171
+ -- rejected contingency NFC-e stays live, for the store to resend.
172
+ CREATE UNIQUE INDEX "fiscal_documents_live_subject_key"
173
+ ON "fiscal_documents"("owner_id", "subject_id", "model")
174
+ WHERE "status" <> 'REPLACED'
175
+ AND NOT ("status" = 'REJECTED' AND "series_kind" = 'ONLINE' AND "protocol" IS NULL);
176
+ -- The sweep's and the transmission's queue: by next attempt, never a row waiting for a person.
177
+ CREATE INDEX "fiscal_documents_next_attempt_at_idx"
178
+ ON "fiscal_documents"("next_attempt_at") WHERE "attention" = false;
179
+
180
+ CREATE TABLE "fiscal_document_events" (
181
+ "id" TEXT NOT NULL,
182
+ "seq" BIGSERIAL NOT NULL,
183
+ "document_id" TEXT NOT NULL,
184
+ "kind" TEXT NOT NULL,
185
+ "from_status" TEXT NOT NULL,
186
+ "to_status" TEXT NOT NULL,
187
+ "at" TIMESTAMP(3) NOT NULL,
188
+ "error_class" TEXT,
189
+ "code" TEXT,
190
+ "answer" JSONB,
191
+
192
+ CONSTRAINT "fiscal_document_events_pkey" PRIMARY KEY ("id"),
193
+ CONSTRAINT "fiscal_document_events_document_id_fkey"
194
+ FOREIGN KEY ("document_id") REFERENCES "fiscal_documents"("id") ON DELETE RESTRICT ON UPDATE CASCADE,
195
+ CONSTRAINT "fiscal_document_events_kind_check"
196
+ CHECK ("kind" IN ('SUBMIT', 'AUTHORIZE', 'DENY', 'REJECT', 'RETRY', 'SIGN_OFFLINE', 'REPLACE', 'CANCEL', 'LOOKUP', 'INUTILIZE',
197
+ 'DEFER', 'RESIGN', 'RELEASE', 'WARN'))
198
+ );
199
+
200
+ CREATE UNIQUE INDEX "fiscal_document_events_seq_key" ON "fiscal_document_events"("seq");
201
+ CREATE INDEX "fiscal_document_events_document_id_at_idx" ON "fiscal_document_events"("document_id", "at");
@@ -0,0 +1,5 @@
1
+ vendor
2
+ tests
3
+ .phpunit.cache
4
+ phpunit.xml
5
+ .gitignore
@@ -0,0 +1,68 @@
1
+ # syntax=docker/dockerfile:1
2
+ #
3
+ # The fiscal service: PHP 8.3 + Apache over sped-nfe. Build context: this
4
+ # folder (`sidecar/`), as shipped inside the @12-apps/fiscal tarball.
5
+ #
6
+ # docker build -t fiscal-sidecar node_modules/@12-apps/fiscal/sidecar
7
+ #
8
+ # Both images are pinned BY DIGEST; the tag beside each digest is only a label.
9
+ # A digest is bumped on purpose, never by a rebuild.
10
+
11
+ # The dependencies are installed in Composer's own image (it has git and unzip)
12
+ # and only `vendor/` is carried over. The two requirements it cannot meet
13
+ # itself, PHP 8.3 and ext-soap, are the final image's, which has both.
14
+ FROM composer:2.8.12@sha256:5248900ab8b5f7f880c2d62180e40960cd87f60149ec9a1abfd62ac72a02577c AS vendor
15
+ WORKDIR /app
16
+ COPY composer.json composer.lock ./
17
+ # The service's own classes go into the authoritative classmap too.
18
+ COPY src ./src
19
+ RUN composer install \
20
+ --no-dev --no-interaction --no-progress --prefer-dist \
21
+ --classmap-authoritative --no-scripts \
22
+ --ignore-platform-req=php --ignore-platform-req=ext-soap
23
+
24
+ FROM php:8.3.36-apache-bookworm@sha256:a14446c32a3c8aeb9b4dac7fb73b03dfd8006e670d9b43ea7947e4030d3cbae6
25
+
26
+ # ext-soap is a declared requirement of sped-nfe (the service talks SOAP over
27
+ # its own cURL transport, but the library's constants come from the extension).
28
+ RUN set -eux; \
29
+ apt-get update; \
30
+ apt-get install -y --no-install-recommends libxml2-dev; \
31
+ docker-php-ext-install -j"$(nproc)" soap; \
32
+ apt-get purge -y --auto-remove libxml2-dev; \
33
+ rm -rf /var/lib/apt/lists/*
34
+
35
+ COPY docker/php.ini /usr/local/etc/php/conf.d/zz-fiscal-sidecar.ini
36
+ COPY docker/openssl.cnf /etc/ssl/fiscal-sidecar-openssl.cnf
37
+ COPY docker/apache.conf /etc/apache2/sites-available/000-default.conf
38
+ COPY docker/mpm.conf /etc/apache2/mods-available/mpm_prefork.conf
39
+ # The trust store SEFAZ's server certificate is verified against: the image's
40
+ # Mozilla bundle (ca-certificates) plus the ICP-Brasil chain, the public roots
41
+ # and intermediates ITI publishes (acraiz.icpbrasil.gov.br; see the PEM's own
42
+ # per-certificate comments). Some SEFAZ hosts present ICP-Brasil server
43
+ # certificates, others public ones, so both are needed. The PEM is checked
44
+ # against this sha256; replacing it means changing this line too.
45
+ COPY docker/icp-brasil.pem /tmp/icp-brasil.pem
46
+ RUN set -eux; \
47
+ echo "9374b11042655df7c226fa7de2b1321f4024263572419b491e7fbd5c76c09a99 /tmp/icp-brasil.pem" | sha256sum -c -; \
48
+ cat /etc/ssl/certs/ca-certificates.crt /tmp/icp-brasil.pem > /etc/ssl/fiscal-sidecar-ca.pem; \
49
+ rm /tmp/icp-brasil.pem
50
+ # A1 certificates issued before OpenSSL 3 are encrypted with RC2/3DES, which
51
+ # only the legacy provider reads. The config turns it on beside the default.
52
+ ENV OPENSSL_CONF=/etc/ssl/fiscal-sidecar-openssl.cnf
53
+ RUN set -eux; \
54
+ cp /usr/local/etc/php/php.ini-production /usr/local/etc/php/php.ini; \
55
+ sed -ri 's/^Listen 80$/Listen 8080/' /etc/apache2/ports.conf; \
56
+ printf 'ServerTokens Prod\nServerSignature Off\nTraceEnable Off\n' > /etc/apache2/conf-available/zz-fiscal-sidecar.conf; \
57
+ a2enconf zz-fiscal-sidecar
58
+
59
+ WORKDIR /app
60
+ COPY --from=vendor /app/vendor ./vendor
61
+ COPY public ./public
62
+ COPY src ./src
63
+ COPY schema ./schema
64
+
65
+ USER www-data
66
+ EXPOSE 8080
67
+ HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \
68
+ CMD php -r 'exit(@file_get_contents("http://127.0.0.1:8080/health") === false ? 1 : 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
+ }