@12-apps/fiscal 1.3.0 → 1.5.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 +3 -0
- package/dist/{chunk-GKT3X5CF.js → chunk-3E3NBXSW.js} +11 -4
- package/dist/chunk-3E3NBXSW.js.map +1 -0
- package/dist/{chunk-MEBG7FGG.js → chunk-G6QNU4FD.js} +2 -2
- package/dist/{chunk-XQGW5HUG.js → chunk-GH452ITO.js} +1 -1
- package/dist/chunk-GH452ITO.js.map +1 -0
- package/dist/{chunk-GGYJPFBJ.js → chunk-HMTPJWXM.js} +2 -2
- package/dist/{chunk-V6G2OFLA.js → chunk-TJCUO6D6.js} +3 -3
- package/dist/{chunk-JVQKJNOC.js → chunk-ZKWVKCGJ.js} +1 -1
- package/dist/chunk-ZKWVKCGJ.js.map +1 -0
- package/dist/{context-yc1C2__K.d.ts → context-CwZiHLnY.d.ts} +14 -3
- package/dist/documents/index.d.ts +7 -5
- package/dist/documents/index.js +155 -8
- package/dist/documents/index.js.map +1 -1
- package/dist/http.d.ts +3 -3
- package/dist/http.js +3 -3
- package/dist/issuer/index.d.ts +2 -2
- package/dist/issuer/index.js +9 -1
- package/dist/issuer/index.js.map +1 -1
- package/dist/jobs.d.ts +3 -3
- package/dist/jobs.js +3 -3
- package/dist/manifest/server.d.ts +3 -3
- package/dist/manifest/server.js +5 -5
- package/dist/notifications.d.ts +2 -2
- package/dist/notifications.js +2 -2
- package/dist/sale/index.d.ts +29 -1
- package/dist/sale/index.js +7 -0
- package/dist/sale/index.js.map +1 -1
- package/dist/{service-BB9lWdyg.d.ts → service-Cz2O84Xr.d.ts} +46 -24
- package/dist/sidecar/index.d.ts +37 -1
- package/dist/sidecar/index.js +1 -1
- package/dist/{port-B1-ipIL4.d.ts → types-DSYwap42.d.ts} +128 -87
- package/package.json +1 -1
- package/prisma/migrations/20261118120000_fiscal_link_payment_event/migration.sql +9 -0
- package/sidecar/README.md +1 -0
- package/sidecar/composer.json +1 -1
- package/sidecar/composer.lock +7 -7
- package/sidecar/schema/sale-for-document.schema.json +18 -1
- package/sidecar/src/Nfe/DocumentMapper.php +27 -0
- package/sidecar/src/Nfe/Input.php +10 -0
- package/sidecar/src/Nfe/NfeModule.php +1 -0
- package/sidecar/src/Nfe/NfeService.php +120 -0
- package/sidecar/src/Nfe/SefazReply.php +21 -0
- package/src/documents/helpers.ts +2 -0
- package/src/documents/index.ts +2 -1
- package/src/documents/machine-steps.ts +12 -2
- package/src/documents/machine.ts +7 -0
- package/src/documents/payment-link.ts +156 -0
- package/src/documents/service.ts +20 -26
- package/src/documents/steps.ts +100 -4
- package/src/documents/types.ts +25 -1
- package/src/issuer/port.ts +24 -1
- package/src/issuer/sidecar.ts +10 -0
- package/src/sale/index.ts +1 -0
- package/src/sale/types.ts +30 -0
- package/src/sidecar/types.ts +38 -0
- package/dist/chunk-GKT3X5CF.js.map +0 -1
- package/dist/chunk-JVQKJNOC.js.map +0 -1
- package/dist/chunk-XQGW5HUG.js.map +0 -1
- /package/dist/{chunk-MEBG7FGG.js.map → chunk-G6QNU4FD.js.map} +0 -0
- /package/dist/{chunk-GGYJPFBJ.js.map → chunk-HMTPJWXM.js.map} +0 -0
- /package/dist/{chunk-V6G2OFLA.js.map → chunk-TJCUO6D6.js.map} +0 -0
|
@@ -1,5 +1,112 @@
|
|
|
1
|
-
import { SaleForDocument } from './sale/index.js';
|
|
2
|
-
import {
|
|
1
|
+
import { SaleForDocument, LinkedTransaction } from './sale/index.js';
|
|
2
|
+
import { SidecarErrorBody, SefazEnvironment, SigningCertificate, Csc, IssuedDocument, ContingencyEntry, ContingencySignedDocument, CancelledDocument, LookedUpDocument, RegisteredPaymentLink, InutilizedRange, SidecarHealth, SidecarErrorClass } from './sidecar/index.js';
|
|
3
|
+
|
|
4
|
+
/**
|
|
5
|
+
* The Issuer port: what the document service asks of whoever talks to SEFAZ.
|
|
6
|
+
* The first (and today only) adapter is the fiscal service in this package's
|
|
7
|
+
* `sidecar/` folder (`./sidecar`). A call never throws for a failure the
|
|
8
|
+
* service classified: it answers `{ ok: false, error }` with the service's
|
|
9
|
+
* class (`REJECTED`, `RETRYABLE`, `CONTINGENCY`, `AUTH`, `INVALID`,
|
|
10
|
+
* `INTERNAL`), and the document service maps that onto the state machine.
|
|
11
|
+
*
|
|
12
|
+
* The certificate and the CSC travel with each call (the service is
|
|
13
|
+
* stateless) inside {@link SigningMaterial}, built by the signing identity
|
|
14
|
+
* for this one call and dropped with it.
|
|
15
|
+
*/
|
|
16
|
+
|
|
17
|
+
/** What signs one call: the A1 and, for an NFC-e, the CSC. Never stored, never logged. */
|
|
18
|
+
interface SigningMaterial {
|
|
19
|
+
readonly certificate: SigningCertificate;
|
|
20
|
+
readonly csc: Csc | null;
|
|
21
|
+
}
|
|
22
|
+
/** A failed call, classified. The service's error body, verbatim. */
|
|
23
|
+
type IssuerFailure = SidecarErrorBody["error"];
|
|
24
|
+
type IssuerOutcome<T> = {
|
|
25
|
+
readonly ok: true;
|
|
26
|
+
readonly answer: T;
|
|
27
|
+
} | {
|
|
28
|
+
readonly ok: false;
|
|
29
|
+
readonly error: IssuerFailure;
|
|
30
|
+
};
|
|
31
|
+
interface Call {
|
|
32
|
+
readonly environment: SefazEnvironment;
|
|
33
|
+
readonly signing: SigningMaterial;
|
|
34
|
+
}
|
|
35
|
+
interface IssueCall extends Call {
|
|
36
|
+
readonly model: FiscalDocumentModel;
|
|
37
|
+
readonly document: SaleForDocument;
|
|
38
|
+
}
|
|
39
|
+
interface SignContingencyCall extends Call {
|
|
40
|
+
readonly document: SaleForDocument;
|
|
41
|
+
readonly contingency: ContingencyEntry;
|
|
42
|
+
}
|
|
43
|
+
interface TransmitCall extends Call {
|
|
44
|
+
readonly model: FiscalDocumentModel;
|
|
45
|
+
readonly signedXml: string;
|
|
46
|
+
}
|
|
47
|
+
interface CancelCall extends Call {
|
|
48
|
+
readonly model: FiscalDocumentModel;
|
|
49
|
+
readonly accessKey: string;
|
|
50
|
+
readonly protocol: string;
|
|
51
|
+
readonly reason: string;
|
|
52
|
+
}
|
|
53
|
+
/** NFC-e only: cancel an online document whose sale was issued again in contingency (event 110112). */
|
|
54
|
+
interface CancelBySubstitutionCall extends Call {
|
|
55
|
+
readonly accessKey: string;
|
|
56
|
+
readonly protocol: string;
|
|
57
|
+
readonly reason: string;
|
|
58
|
+
readonly substituteAccessKey: string;
|
|
59
|
+
}
|
|
60
|
+
/** The event 110300 "Vinculação Pagamento" (NT 2026.006 v1.00): one transaction linked to an authorised document. */
|
|
61
|
+
interface LinkPaymentCall extends Call {
|
|
62
|
+
readonly model: FiscalDocumentModel;
|
|
63
|
+
readonly accessKey: string;
|
|
64
|
+
readonly protocol: string;
|
|
65
|
+
/** `nSeqEvento`, 1–20. */
|
|
66
|
+
readonly sequence: number;
|
|
67
|
+
/**
|
|
68
|
+
* The transactions the event links. Exactly ONE today: the event's schema
|
|
69
|
+
* (`e110300_v1.00.xsd`) carries a single `gPgto`, so the service refuses any
|
|
70
|
+
* other count as INVALID; the list is the NT group's own shape.
|
|
71
|
+
*/
|
|
72
|
+
readonly payments: readonly LinkedTransaction[];
|
|
73
|
+
}
|
|
74
|
+
interface LookupCall extends Call {
|
|
75
|
+
readonly model: FiscalDocumentModel;
|
|
76
|
+
readonly accessKey: string;
|
|
77
|
+
}
|
|
78
|
+
interface InutilizeCall extends Call {
|
|
79
|
+
readonly model: FiscalDocumentModel;
|
|
80
|
+
readonly uf: string;
|
|
81
|
+
readonly cnpj: string;
|
|
82
|
+
readonly year: number;
|
|
83
|
+
readonly series: number;
|
|
84
|
+
readonly from: number;
|
|
85
|
+
readonly to: number;
|
|
86
|
+
readonly reason: string;
|
|
87
|
+
}
|
|
88
|
+
interface Issuer {
|
|
89
|
+
/** Build, sign and transmit. `AUTHORIZED` or `DENIED`. */
|
|
90
|
+
issue(call: IssueCall): Promise<IssuerOutcome<IssuedDocument>>;
|
|
91
|
+
/** NFC-e only: build and sign offline (`tpEmis = 9`); nothing is sent. */
|
|
92
|
+
signContingency(call: SignContingencyCall): Promise<IssuerOutcome<ContingencySignedDocument>>;
|
|
93
|
+
/** Send an already signed XML (a contingency document). */
|
|
94
|
+
transmit(call: TransmitCall): Promise<IssuerOutcome<IssuedDocument>>;
|
|
95
|
+
cancel(call: CancelCall): Promise<IssuerOutcome<CancelledDocument>>;
|
|
96
|
+
cancelBySubstitution(call: CancelBySubstitutionCall): Promise<IssuerOutcome<CancelledDocument>>;
|
|
97
|
+
lookup(call: LookupCall): Promise<IssuerOutcome<LookedUpDocument>>;
|
|
98
|
+
/**
|
|
99
|
+
* The event 110300. Optional on the port so an issuer written before it
|
|
100
|
+
* still satisfies the type; one that lacks it cannot link (the document
|
|
101
|
+
* service answers `NOT_SUPPORTED`), and a host may read its presence as
|
|
102
|
+
* "this issuer writes `gPgtoVinc`".
|
|
103
|
+
*/
|
|
104
|
+
linkPayment?(call: LinkPaymentCall): Promise<IssuerOutcome<RegisteredPaymentLink>>;
|
|
105
|
+
inutilize(call: InutilizeCall): Promise<IssuerOutcome<InutilizedRange>>;
|
|
106
|
+
health(): Promise<SidecarHealth>;
|
|
107
|
+
}
|
|
108
|
+
/** The path segment of a model on the service's routes. */
|
|
109
|
+
declare function modelPath(model: FiscalDocumentModel): "nfe" | "nfce";
|
|
3
110
|
|
|
4
111
|
/**
|
|
5
112
|
* The fiscal document record and its event log — the shape the package's
|
|
@@ -132,7 +239,7 @@ interface FiscalDocument {
|
|
|
132
239
|
readonly updatedAt: string;
|
|
133
240
|
}
|
|
134
241
|
/** What the state machine was fed: the kind of the input that made the event. */
|
|
135
|
-
type DocumentEventKind = "SUBMIT" | "AUTHORIZE" | "DENY" | "REJECT" | "RETRY" | "SIGN_OFFLINE" | "REPLACE" | "CANCEL" | "LOOKUP" | "INUTILIZE" | "DEFER" | "RESIGN" | "RELEASE" | "WARN";
|
|
242
|
+
type DocumentEventKind = "SUBMIT" | "AUTHORIZE" | "DENY" | "REJECT" | "RETRY" | "SIGN_OFFLINE" | "REPLACE" | "CANCEL" | "LOOKUP" | "INUTILIZE" | "DEFER" | "RESIGN" | "RELEASE" | "WARN" | "LINK_PAYMENT";
|
|
136
243
|
/**
|
|
137
244
|
* One transition, as stored. `answer` is what the fiscal service answered,
|
|
138
245
|
* verbatim but for any secret-named key (`scrubSecrets`), so the record is the
|
|
@@ -148,91 +255,25 @@ interface FiscalDocumentEvent {
|
|
|
148
255
|
readonly code: string | null;
|
|
149
256
|
readonly answer: unknown;
|
|
150
257
|
}
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
* `sidecar/` folder (`./sidecar`). A call never throws for a failure the
|
|
156
|
-
* service classified: it answers `{ ok: false, error }` with the service's
|
|
157
|
-
* class (`REJECTED`, `RETRYABLE`, `CONTINGENCY`, `AUTH`, `INVALID`,
|
|
158
|
-
* `INTERNAL`), and the document service maps that onto the state machine.
|
|
159
|
-
*
|
|
160
|
-
* The certificate and the CSC travel with each call (the service is
|
|
161
|
-
* stateless) inside {@link SigningMaterial}, built by the signing identity
|
|
162
|
-
* for this one call and dropped with it.
|
|
163
|
-
*/
|
|
164
|
-
|
|
165
|
-
/** What signs one call: the A1 and, for an NFC-e, the CSC. Never stored, never logged. */
|
|
166
|
-
interface SigningMaterial {
|
|
167
|
-
readonly certificate: SigningCertificate;
|
|
168
|
-
readonly csc: Csc | null;
|
|
169
|
-
}
|
|
170
|
-
/** A failed call, classified. The service's error body, verbatim. */
|
|
171
|
-
type IssuerFailure = SidecarErrorBody["error"];
|
|
172
|
-
type IssuerOutcome<T> = {
|
|
173
|
-
readonly ok: true;
|
|
174
|
-
readonly answer: T;
|
|
175
|
-
} | {
|
|
176
|
-
readonly ok: false;
|
|
177
|
-
readonly error: IssuerFailure;
|
|
178
|
-
};
|
|
179
|
-
interface Call {
|
|
180
|
-
readonly environment: SefazEnvironment;
|
|
181
|
-
readonly signing: SigningMaterial;
|
|
182
|
-
}
|
|
183
|
-
interface IssueCall extends Call {
|
|
184
|
-
readonly model: FiscalDocumentModel;
|
|
185
|
-
readonly document: SaleForDocument;
|
|
186
|
-
}
|
|
187
|
-
interface SignContingencyCall extends Call {
|
|
188
|
-
readonly document: SaleForDocument;
|
|
189
|
-
readonly contingency: ContingencyEntry;
|
|
190
|
-
}
|
|
191
|
-
interface TransmitCall extends Call {
|
|
192
|
-
readonly model: FiscalDocumentModel;
|
|
193
|
-
readonly signedXml: string;
|
|
194
|
-
}
|
|
195
|
-
interface CancelCall extends Call {
|
|
196
|
-
readonly model: FiscalDocumentModel;
|
|
197
|
-
readonly accessKey: string;
|
|
198
|
-
readonly protocol: string;
|
|
199
|
-
readonly reason: string;
|
|
200
|
-
}
|
|
201
|
-
/** NFC-e only: cancel an online document whose sale was issued again in contingency (event 110112). */
|
|
202
|
-
interface CancelBySubstitutionCall extends Call {
|
|
203
|
-
readonly accessKey: string;
|
|
204
|
-
readonly protocol: string;
|
|
205
|
-
readonly reason: string;
|
|
206
|
-
readonly substituteAccessKey: string;
|
|
207
|
-
}
|
|
208
|
-
interface LookupCall extends Call {
|
|
209
|
-
readonly model: FiscalDocumentModel;
|
|
210
|
-
readonly accessKey: string;
|
|
211
|
-
}
|
|
212
|
-
interface InutilizeCall extends Call {
|
|
213
|
-
readonly model: FiscalDocumentModel;
|
|
214
|
-
readonly uf: string;
|
|
215
|
-
readonly cnpj: string;
|
|
216
|
-
readonly year: number;
|
|
217
|
-
readonly series: number;
|
|
218
|
-
readonly from: number;
|
|
219
|
-
readonly to: number;
|
|
258
|
+
interface CancelOrReturnInput {
|
|
259
|
+
readonly ownerId: string;
|
|
260
|
+
readonly documentId: string;
|
|
261
|
+
/** SEFAZ's 15–255 characters, sent with the cancel. */
|
|
220
262
|
readonly reason: string;
|
|
263
|
+
/** The NF-e (model 55) issuing point a return is numbered on. */
|
|
264
|
+
readonly returnPointId: string;
|
|
221
265
|
}
|
|
222
|
-
interface
|
|
223
|
-
/**
|
|
224
|
-
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
health(): Promise<SidecarHealth>;
|
|
266
|
+
interface CancelOrReturnResult {
|
|
267
|
+
/**
|
|
268
|
+
* `CANCELLED` inside the window; `RETURNED` past it (the return may itself
|
|
269
|
+
* still be SUBMITTED: the sweep settles it like any document); `REFUSED`
|
|
270
|
+
* when the issuer refused the cancel for any other reason (nothing changed).
|
|
271
|
+
*/
|
|
272
|
+
readonly outcome: "CANCELLED" | "RETURNED" | "REFUSED";
|
|
273
|
+
/** The document asked about, as it stands: CANCELLED, or still AUTHORIZED beside its return. */
|
|
274
|
+
readonly document: FiscalDocument;
|
|
275
|
+
readonly returnDocument: FiscalDocument | null;
|
|
276
|
+
readonly failure: IssuerFailure | null;
|
|
234
277
|
}
|
|
235
|
-
/** The path segment of a model on the service's routes. */
|
|
236
|
-
declare function modelPath(model: FiscalDocumentModel): "nfe" | "nfce";
|
|
237
278
|
|
|
238
|
-
export { type CancelBySubstitutionCall as C, type DocumentEventKind as D, type FiscalDocumentModel as F, type Issuer as I, type
|
|
279
|
+
export { type CancelBySubstitutionCall as C, type DocumentEventKind as D, type FiscalDocumentModel as F, type Issuer as I, type LinkPaymentCall as L, type NumberVoid as N, OWED_VOIDS as O, type SignContingencyCall as S, type TransmitCall as T, type CancelCall as a, type InutilizeCall as b, type IssueCall as c, type IssuerFailure as d, type IssuerOutcome as e, type LookupCall as f, type SigningMaterial as g, type FiscalDocumentStatus as h, type FiscalDocument as i, type CancelOrReturnInput as j, type CancelOrReturnResult as k, type FiscalDocumentEvent as l, modelPath as m, type SeriesKind as n, type DocumentTotals as o, FISCAL_DOCUMENT_MODELS as p, FISCAL_DOCUMENT_STATUSES as q, isLive as r };
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@12-apps/fiscal",
|
|
3
|
-
"version": "1.
|
|
3
|
+
"version": "1.5.0",
|
|
4
4
|
"type": "module",
|
|
5
5
|
"sideEffects": false,
|
|
6
6
|
"description": "Brazilian consumption-tax machinery and fiscal documents for any host that sells. The IBS/CBS engine (./engine): a pure function from priced lines, the seller's regime, the destination, the exclusions, a versioned rate table and the date of the supply to a per-line and per-order breakdown. The neutral sale document (./sale) and a stateless HTTP service over sped-nfe that issues NF-e and NFC-e, shipped with its Dockerfile in sidecar/ (./sidecar types its wire contract). The fiscal document module (./documents): the state machine, the per-series number counters, the issuer port and its sidecar adapter (./issuer), the signing identity, and the DANFE NFC-e as ESC/POS-ready lines (./danfe). Implements @12-apps/wiring (./manifest): db, http, jobs, permissions.",
|
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
-- @domains: fiscal
|
|
2
|
+
-- @12-apps/fiscal (FUT-2239): a document's events may record the event 110300
|
|
3
|
+
-- "Vinculação Pagamento" (NT 2026.006 v1.00), kind LINK_PAYMENT. The check only
|
|
4
|
+
-- widens: every row the previous release writes still passes it.
|
|
5
|
+
|
|
6
|
+
ALTER TABLE "fiscal_document_events" DROP CONSTRAINT "fiscal_document_events_kind_check";
|
|
7
|
+
ALTER TABLE "fiscal_document_events" ADD CONSTRAINT "fiscal_document_events_kind_check"
|
|
8
|
+
CHECK ("kind" IN ('SUBMIT', 'AUTHORIZE', 'DENY', 'REJECT', 'RETRY', 'SIGN_OFFLINE', 'REPLACE', 'CANCEL', 'LOOKUP', 'INUTILIZE',
|
|
9
|
+
'DEFER', 'RESIGN', 'RELEASE', 'WARN', 'LINK_PAYMENT'));
|
package/sidecar/README.md
CHANGED
|
@@ -29,6 +29,7 @@ SEFAZ carries `environment` (`homologacao` | `producao`) and `certificate`
|
|
|
29
29
|
| `POST /<model>/transmit` | `{ environment, certificate, signedXml }` | as `/issue` |
|
|
30
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
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>/link-payment` | `{ environment, certificate, accessKey, protocol, sequence, payments: [one { transactionId, meansCode, pspCnpjBase, receiverCnpj }] }`: the event 110300 "Vinculação Pagamento" (NT 2026.006) at `nSeqEvento` = `sequence` | `REGISTERED`: `protocol`, `registeredAt`, `eventXml`, `transaction` (the `gPgto` SEFAZ holds at that sequence). On 573 the key is looked up and the event already there is answered, which may carry another transaction; a 573 the lookup does not show is `RETRYABLE` |
|
|
32
33
|
| `POST /<model>/lookup` | `{ environment, certificate, accessKey }` | `AUTHORIZED`, `CANCELLED`, `DENIED` or `NOT_FOUND`, with the authorisation `protocol` |
|
|
33
34
|
| `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
35
|
| `GET /health` | | `{ status: "ok", libraries, nfeSchemas, sefazTlsVerify }` |
|
package/sidecar/composer.json
CHANGED
package/sidecar/composer.lock
CHANGED
|
@@ -4,7 +4,7 @@
|
|
|
4
4
|
"Read more about it at https://getcomposer.org/doc/01-basic-usage.md#installing-dependencies",
|
|
5
5
|
"This file is @generated automatically"
|
|
6
6
|
],
|
|
7
|
-
"content-hash": "
|
|
7
|
+
"content-hash": "027ed9316c06b9379e46519353632da5",
|
|
8
8
|
"packages": [
|
|
9
9
|
{
|
|
10
10
|
"name": "justinrainbow/json-schema",
|
|
@@ -306,16 +306,16 @@
|
|
|
306
306
|
},
|
|
307
307
|
{
|
|
308
308
|
"name": "nfephp-org/sped-nfe",
|
|
309
|
-
"version": "v5.2.
|
|
309
|
+
"version": "v5.2.11",
|
|
310
310
|
"source": {
|
|
311
311
|
"type": "git",
|
|
312
312
|
"url": "https://github.com/nfephp-org/sped-nfe.git",
|
|
313
|
-
"reference": "
|
|
313
|
+
"reference": "4596b89e457d27ad2c114dda2b2ed04043f6327c"
|
|
314
314
|
},
|
|
315
315
|
"dist": {
|
|
316
316
|
"type": "zip",
|
|
317
|
-
"url": "https://api.github.com/repos/nfephp-org/sped-nfe/zipball/
|
|
318
|
-
"reference": "
|
|
317
|
+
"url": "https://api.github.com/repos/nfephp-org/sped-nfe/zipball/4596b89e457d27ad2c114dda2b2ed04043f6327c",
|
|
318
|
+
"reference": "4596b89e457d27ad2c114dda2b2ed04043f6327c",
|
|
319
319
|
"shasum": ""
|
|
320
320
|
},
|
|
321
321
|
"require": {
|
|
@@ -382,9 +382,9 @@
|
|
|
382
382
|
],
|
|
383
383
|
"support": {
|
|
384
384
|
"issues": "https://github.com/nfephp-org/sped-nfe/issues",
|
|
385
|
-
"source": "https://github.com/nfephp-org/sped-nfe/tree/v5.2.
|
|
385
|
+
"source": "https://github.com/nfephp-org/sped-nfe/tree/v5.2.11"
|
|
386
386
|
},
|
|
387
|
-
"time": "2026-
|
|
387
|
+
"time": "2026-11-13T20:31:48+00:00"
|
|
388
388
|
},
|
|
389
389
|
{
|
|
390
390
|
"name": "psr/log",
|
|
@@ -415,7 +415,24 @@
|
|
|
415
415
|
}
|
|
416
416
|
]
|
|
417
417
|
},
|
|
418
|
-
"description": { "oneOf": [{ "type": "null" }, { "type": "string", "minLength": 2, "maxLength": 60 }] }
|
|
418
|
+
"description": { "oneOf": [{ "type": "null" }, { "type": "string", "minLength": 2, "maxLength": 60 }] },
|
|
419
|
+
"linkedTransaction": {
|
|
420
|
+
"description": "gPgtoVinc (NT 2026.006 v1.00): the payment transaction started before the document, linked by its id. Absent or null: no link.",
|
|
421
|
+
"oneOf": [
|
|
422
|
+
{ "type": "null" },
|
|
423
|
+
{
|
|
424
|
+
"type": "object",
|
|
425
|
+
"additionalProperties": false,
|
|
426
|
+
"required": ["transactionId", "meansCode", "pspCnpjBase", "receiverCnpj"],
|
|
427
|
+
"properties": {
|
|
428
|
+
"transactionId": { "type": "string", "pattern": "^[\\x21-\\x7E]{2,35}$" },
|
|
429
|
+
"meansCode": { "enum": ["15", "17", "18", "20", "23", "24"] },
|
|
430
|
+
"pspCnpjBase": { "type": "string", "pattern": "^[A-Z0-9]{8}$" },
|
|
431
|
+
"receiverCnpj": { "$ref": "#/definitions/cnpj" }
|
|
432
|
+
}
|
|
433
|
+
}
|
|
434
|
+
]
|
|
435
|
+
}
|
|
419
436
|
}
|
|
420
437
|
}
|
|
421
438
|
}
|
|
@@ -379,6 +379,7 @@ final class DocumentMapper
|
|
|
379
379
|
'tpIntegra' => $card === null ? null : ($card['integrated'] ? 1 : 2),
|
|
380
380
|
]);
|
|
381
381
|
}
|
|
382
|
+
$this->paymentLinks($make, $d['payments']);
|
|
382
383
|
if ($d['intermediary'] !== null) {
|
|
383
384
|
$make->tagIntermed((object) [
|
|
384
385
|
'CNPJ' => $d['intermediary']['cnpj'],
|
|
@@ -400,6 +401,32 @@ final class DocumentMapper
|
|
|
400
401
|
}
|
|
401
402
|
}
|
|
402
403
|
|
|
404
|
+
/**
|
|
405
|
+
* `gPgtoVinc` (NT 2026.006 v1.00, YC01): every payment whose transaction was
|
|
406
|
+
* started before the document, linked by its id. `nPag` is the payment's
|
|
407
|
+
* position among the document's payments. The caller decides whether the
|
|
408
|
+
* environment accepts the group (it is optional in the layout, and the
|
|
409
|
+
* fisco's own production activation is announced for 2027).
|
|
410
|
+
*
|
|
411
|
+
* @param list<array<string, mixed>> $payments
|
|
412
|
+
*/
|
|
413
|
+
private function paymentLinks(Make $make, array $payments): void
|
|
414
|
+
{
|
|
415
|
+
foreach (array_values($payments) as $index => $payment) {
|
|
416
|
+
$link = $payment['linkedTransaction'] ?? null;
|
|
417
|
+
if ($link === null) {
|
|
418
|
+
continue;
|
|
419
|
+
}
|
|
420
|
+
$make->tagPgtoVinc((object) [
|
|
421
|
+
'nPag' => $index + 1,
|
|
422
|
+
'idTransacao' => $link['transactionId'],
|
|
423
|
+
'tpMeioPgto' => $link['meansCode'],
|
|
424
|
+
'CNPJReceb' => $link['receiverCnpj'],
|
|
425
|
+
'CNPJBasePSP' => $link['pspCnpjBase'],
|
|
426
|
+
]);
|
|
427
|
+
}
|
|
428
|
+
}
|
|
429
|
+
|
|
403
430
|
private static function reais(int $cents): string
|
|
404
431
|
{
|
|
405
432
|
return number_format($cents / 100, 2, '.', '');
|
|
@@ -105,6 +105,16 @@ final class Input
|
|
|
105
105
|
return $value;
|
|
106
106
|
}
|
|
107
107
|
|
|
108
|
+
/** @return list<mixed> */
|
|
109
|
+
public function list(string $field): array
|
|
110
|
+
{
|
|
111
|
+
$value = $this->body[$field] ?? null;
|
|
112
|
+
if (!is_array($value) || !array_is_list($value)) {
|
|
113
|
+
throw ServiceError::invalid("$field must be a list.");
|
|
114
|
+
}
|
|
115
|
+
return $value;
|
|
116
|
+
}
|
|
117
|
+
|
|
108
118
|
public function text(string $field, int $min, int $max): string
|
|
109
119
|
{
|
|
110
120
|
$value = $this->body[$field] ?? null;
|
|
@@ -33,6 +33,7 @@ final class NfeModule implements Module
|
|
|
33
33
|
$router->add('POST', "$prefix/transmit", fn (Request $r): Response => $this->service()->transmit($model, self::in($r)));
|
|
34
34
|
$router->add('POST', "$prefix/cancel", fn (Request $r): Response => $this->service()->cancel($model, self::in($r)));
|
|
35
35
|
$router->add('POST', "$prefix/lookup", fn (Request $r): Response => $this->service()->lookup($model, self::in($r)));
|
|
36
|
+
$router->add('POST', "$prefix/link-payment", fn (Request $r): Response => $this->service()->linkPayment($model, self::in($r)));
|
|
36
37
|
}
|
|
37
38
|
$router->add('POST', '/nfce/cancel-substitution', fn (Request $r): Response => $this->service()->cancelBySubstitution(self::in($r)));
|
|
38
39
|
$router->add('POST', '/nfce/sign-contingency', fn (Request $r): Response => $this->service()->signContingency(self::in($r)));
|
|
@@ -116,6 +116,126 @@ final class NfeService
|
|
|
116
116
|
);
|
|
117
117
|
}
|
|
118
118
|
|
|
119
|
+
/**
|
|
120
|
+
* `POST /<model>/link-payment`: NT 2026.006 v1.00's event 110300
|
|
121
|
+
* "Vinculação Pagamento", one payment transaction linked to an authorised
|
|
122
|
+
* document after the fact. One transaction per event (the schema's single
|
|
123
|
+
* `gPgto`), numbered by the caller's `sequence` (`nSeqEvento`, 1–20).
|
|
124
|
+
*
|
|
125
|
+
* 573 "Duplicidade de Evento" means SEFAZ already holds an event 110300 at
|
|
126
|
+
* that `sequence`: a retry of one whose recording was lost, or another
|
|
127
|
+
* transaction's. The key is looked up and the registered event answered with
|
|
128
|
+
* its own `procEventoNFe` and the `transaction` it carries, which the caller
|
|
129
|
+
* compares with the one it sent. A 573 the lookup cannot show is RETRYABLE.
|
|
130
|
+
*/
|
|
131
|
+
public function linkPayment(Model $model, Input $in): Response
|
|
132
|
+
{
|
|
133
|
+
$environment = $in->environment();
|
|
134
|
+
$key = self::keyOf($model, $in);
|
|
135
|
+
$protocol = $in->pattern('protocol', '/^[0-9]{15}$/', 'the 15-digit authorisation protocol');
|
|
136
|
+
$sequence = $in->digits('sequence', 1, 20);
|
|
137
|
+
$transaction = self::paymentOf($in);
|
|
138
|
+
$tagAdic = '<cOrgaoAutor>' . substr($key, 0, 2) . '</cOrgaoAutor><tpAutor>1</tpAutor>'
|
|
139
|
+
. '<verAplic>' . DocumentMapper::PROCESS_VERSION . '</verAplic>'
|
|
140
|
+
. "<nProt>$protocol</nProt>" . self::paymentGroup($transaction);
|
|
141
|
+
$tools = $this->toolsForKey($in, $model, $environment, $key);
|
|
142
|
+
$reply = $this->settled(
|
|
143
|
+
fn (): string => $tools->sefazEvento(UFList::getUFByCode((int) substr($key, 0, 2)), $key, Tools::EVT_VINCULACAO_PAGAMENTO, $sequence, $tagAdic),
|
|
144
|
+
false,
|
|
145
|
+
);
|
|
146
|
+
$status = $reply->status() === '128' ? (string) $reply->value('cStat', 'infEvento') : $reply->status();
|
|
147
|
+
if ($status === '573') {
|
|
148
|
+
return $this->linkSettledByLookup($tools, $key, $sequence, $reply);
|
|
149
|
+
}
|
|
150
|
+
if (!in_array($status, self::EVENT_REGISTERED, true)) {
|
|
151
|
+
throw Classifier::fromStatus($status, self::reasonOf($reply, 'infEvento'), $reply, false);
|
|
152
|
+
}
|
|
153
|
+
return new Response(200, self::answer($reply, $status, 'infEvento') + [
|
|
154
|
+
'status' => 'REGISTERED',
|
|
155
|
+
'accessKey' => $key,
|
|
156
|
+
'protocol' => (string) $reply->value('nProt', 'infEvento'),
|
|
157
|
+
'registeredAt' => (string) $reply->value('dhRegEvento', 'infEvento'),
|
|
158
|
+
'eventXml' => self::protocolled($tools->lastRequest, $reply->raw),
|
|
159
|
+
'transaction' => $transaction,
|
|
160
|
+
]);
|
|
161
|
+
}
|
|
162
|
+
|
|
163
|
+
/**
|
|
164
|
+
* A 573 settled by the key's own events: the 110300 SEFAZ holds at
|
|
165
|
+
* `$sequence`, with its `procEventoNFe` and the transaction it carries.
|
|
166
|
+
*/
|
|
167
|
+
private function linkSettledByLookup(Tools $tools, string $key, int $sequence, SefazReply $duplicate): Response
|
|
168
|
+
{
|
|
169
|
+
try {
|
|
170
|
+
$lookup = $this->exchange(fn (): string => $tools->sefazConsultaChave($key));
|
|
171
|
+
} catch (TransportFailure $failure) {
|
|
172
|
+
throw self::unsettled($failure, false, false);
|
|
173
|
+
}
|
|
174
|
+
foreach ($lookup->all('procEventoNFe') as $xml) {
|
|
175
|
+
$event = SefazReply::parse($xml);
|
|
176
|
+
if ($event->value('tpEvento') !== (string) Tools::EVT_VINCULACAO_PAGAMENTO || (int) $event->value('nSeqEvento') !== $sequence
|
|
177
|
+
|| !in_array((string) $event->value('cStat', 'retEvento'), self::EVENT_REGISTERED, true)) {
|
|
178
|
+
continue;
|
|
179
|
+
}
|
|
180
|
+
return new Response(200, self::answer($duplicate, '573', 'infEvento') + [
|
|
181
|
+
'status' => 'REGISTERED',
|
|
182
|
+
'accessKey' => $key,
|
|
183
|
+
'protocol' => $event->value('nProt', 'retEvento'),
|
|
184
|
+
'registeredAt' => $event->value('dhRegEvento', 'retEvento'),
|
|
185
|
+
'eventXml' => $xml,
|
|
186
|
+
'transaction' => [
|
|
187
|
+
'transactionId' => (string) $event->attribute('gPgto', 'idTransacao'),
|
|
188
|
+
'meansCode' => (string) $event->value('tpMeioPgto', 'gPgto'),
|
|
189
|
+
'receiverCnpj' => (string) $event->value('CNPJReceb', 'gPgto'),
|
|
190
|
+
'pspCnpjBase' => (string) $event->value('CNPJBasePSP', 'gPgto'),
|
|
191
|
+
],
|
|
192
|
+
]);
|
|
193
|
+
}
|
|
194
|
+
throw new ServiceError(
|
|
195
|
+
ErrorClass::RETRYABLE,
|
|
196
|
+
"SEFAZ calls the event 110300 #$sequence a duplicate, and the key's lookup does not show it yet: send it again.",
|
|
197
|
+
'573',
|
|
198
|
+
[],
|
|
199
|
+
null,
|
|
200
|
+
null,
|
|
201
|
+
$lookup->raw,
|
|
202
|
+
);
|
|
203
|
+
}
|
|
204
|
+
|
|
205
|
+
/**
|
|
206
|
+
* The one transaction the event links (schema `TEventoPgto`). `payments`
|
|
207
|
+
* holds exactly one entry, since the event's schema carries a single `gPgto`.
|
|
208
|
+
*
|
|
209
|
+
* @return array{transactionId: string, meansCode: string, receiverCnpj: string, pspCnpjBase: string}
|
|
210
|
+
*/
|
|
211
|
+
private static function paymentOf(Input $in): array
|
|
212
|
+
{
|
|
213
|
+
$payments = $in->list('payments');
|
|
214
|
+
if (count($payments) !== 1 || !is_array($payments[0])) {
|
|
215
|
+
throw ServiceError::invalid('payments must hold exactly one transaction: the event 110300 carries one gPgto.');
|
|
216
|
+
}
|
|
217
|
+
$one = new Input($payments[0]);
|
|
218
|
+
return [
|
|
219
|
+
'transactionId' => $one->pattern('transactionId', '/^[\x21-\x7E]{2,35}$/', '2 to 35 printable characters'),
|
|
220
|
+
'meansCode' => $one->pattern('meansCode', '/^(15|17|18|20|23|24)$/', 'an IT 2026.001 tpMeioPgto (15, 17, 18, 20, 23, 24)'),
|
|
221
|
+
'receiverCnpj' => $one->pattern('receiverCnpj', '/^[A-Z0-9]{12}[0-9]{2}$/', 'a 14-character CNPJ'),
|
|
222
|
+
'pspCnpjBase' => $one->pattern('pspCnpjBase', '/^[A-Z0-9]{8}$/', 'an 8-character CNPJ base'),
|
|
223
|
+
];
|
|
224
|
+
}
|
|
225
|
+
|
|
226
|
+
/**
|
|
227
|
+
* The event's `gPgto`: the transaction id is an attribute, then the means,
|
|
228
|
+
* the receiver, the PSP.
|
|
229
|
+
*
|
|
230
|
+
* @param array{transactionId: string, meansCode: string, receiverCnpj: string, pspCnpjBase: string} $transaction
|
|
231
|
+
*/
|
|
232
|
+
private static function paymentGroup(array $transaction): string
|
|
233
|
+
{
|
|
234
|
+
$id = htmlspecialchars($transaction['transactionId'], ENT_XML1 | ENT_QUOTES);
|
|
235
|
+
return "<gPgto idTransacao=\"$id\"><tpMeioPgto>{$transaction['meansCode']}</tpMeioPgto>"
|
|
236
|
+
. "<CNPJReceb>{$transaction['receiverCnpj']}</CNPJReceb><CNPJBasePSP>{$transaction['pspCnpjBase']}</CNPJBasePSP></gPgto>";
|
|
237
|
+
}
|
|
238
|
+
|
|
119
239
|
/** One cancel event, sent and settled: 218/573 and a request with no answer are looked up. */
|
|
120
240
|
private function sendCancel(Tools $tools, string $key, callable $send): Response
|
|
121
241
|
{
|
|
@@ -68,6 +68,27 @@ final class SefazReply
|
|
|
68
68
|
return $node === null ? null : (string) $this->dom->saveXML($node);
|
|
69
69
|
}
|
|
70
70
|
|
|
71
|
+
/**
|
|
72
|
+
* Every `$tag` element, serialised, in document order.
|
|
73
|
+
*
|
|
74
|
+
* @return list<string>
|
|
75
|
+
*/
|
|
76
|
+
public function all(string $tag): array
|
|
77
|
+
{
|
|
78
|
+
$found = [];
|
|
79
|
+
foreach ($this->dom->getElementsByTagName($tag) as $node) {
|
|
80
|
+
$found[] = (string) $this->dom->saveXML($node);
|
|
81
|
+
}
|
|
82
|
+
return $found;
|
|
83
|
+
}
|
|
84
|
+
|
|
85
|
+
/** The attribute `$name` of the first `$tag` element, or null. */
|
|
86
|
+
public function attribute(string $tag, string $name): ?string
|
|
87
|
+
{
|
|
88
|
+
$node = $this->group($tag);
|
|
89
|
+
return $node === null || !$node->hasAttribute($name) ? null : $node->getAttribute($name);
|
|
90
|
+
}
|
|
91
|
+
|
|
71
92
|
public function has(string $group): bool
|
|
72
93
|
{
|
|
73
94
|
return $this->group($group) !== null;
|
package/src/documents/helpers.ts
CHANGED
|
@@ -77,6 +77,8 @@ export const xmlKeys = {
|
|
|
77
77
|
`fiscal/${accessKey}/signed-${trimEnd(digest.replace(/\+/g, "-").replace(/\//g, "_"), "=")}.xml`,
|
|
78
78
|
authorized: (accessKey: string) => `fiscal/${accessKey}/authorized.xml`,
|
|
79
79
|
cancel: (accessKey: string) => `fiscal/${accessKey}/cancel.xml`,
|
|
80
|
+
/** The event 110300 of `nSeqEvento` `sequence`. */
|
|
81
|
+
linkPayment: (accessKey: string, sequence: number) => `fiscal/${accessKey}/link-payment-${sequence}.xml`,
|
|
80
82
|
inutilization: (document: FiscalDocument) =>
|
|
81
83
|
`fiscal/inutilization/${document.environment}/${document.model}/${document.ownerId}/${document.series}-${document.number}.xml`,
|
|
82
84
|
};
|
package/src/documents/index.ts
CHANGED
|
@@ -30,7 +30,8 @@ export {
|
|
|
30
30
|
} from "./context";
|
|
31
31
|
export type { FiscalDocumentsConfig, FiscalNotifyPort, FiscalReasons } from "./context";
|
|
32
32
|
export { CONTINGENCY_WARNING_AFTER_MS, LATE_CANCEL_CODES, createFiscalDocuments } from "./service";
|
|
33
|
-
export type { CancelOrReturnInput, CancelOrReturnResult, CertificateFacts, FiscalDocuments, FiscalDocumentsServiceConfig, IssueInput, SweepReport } from "./service";
|
|
33
|
+
export type { CancelOrReturnInput, CancelOrReturnResult, CertificateFacts, FiscalDocuments, FiscalDocumentsServiceConfig, IssueInput, LinkPaymentInput, LinkPaymentResult, SweepReport } from "./service";
|
|
34
|
+
export { MAX_PAYMENT_LINKS } from "./payment-link";
|
|
34
35
|
export { createMemoryFiscalStore } from "./memory";
|
|
35
36
|
export type { MemoryFiscalStore } from "./memory";
|
|
36
37
|
export { FISCAL_NEXT_NUMBER_SQL } from "./sql";
|
|
@@ -11,9 +11,10 @@ import type {
|
|
|
11
11
|
InutilizedRange,
|
|
12
12
|
IssuedDocument,
|
|
13
13
|
LookedUpDocument,
|
|
14
|
+
RegisteredPaymentLink,
|
|
14
15
|
SidecarErrorBody,
|
|
15
16
|
} from "../sidecar/types";
|
|
16
|
-
import type { SaleForDocument } from "../sale/types";
|
|
17
|
+
import type { LinkedTransaction, SaleForDocument } from "../sale/types";
|
|
17
18
|
import { FiscalDocumentError } from "./errors";
|
|
18
19
|
import { type DocumentEventKind, type DocumentTotals, type FiscalDocument, type NumberVoid, isLive } from "./types";
|
|
19
20
|
|
|
@@ -63,7 +64,15 @@ export type DocumentInput =
|
|
|
63
64
|
/** A person took a document back from `attention`: the sweep may try again. */
|
|
64
65
|
| { readonly kind: "RELEASE" }
|
|
65
66
|
/** The 24-hour contingency deadline warning went out. */
|
|
66
|
-
| { readonly kind: "WARN" }
|
|
67
|
+
| { readonly kind: "WARN" }
|
|
68
|
+
/** SEFAZ registered the event 110300 #`sequence` linking `payment` to the document; its XML is at `eventXmlKey`. */
|
|
69
|
+
| {
|
|
70
|
+
readonly kind: "LINK_PAYMENT";
|
|
71
|
+
readonly answer: RegisteredPaymentLink;
|
|
72
|
+
readonly payment: LinkedTransaction;
|
|
73
|
+
readonly sequence: number;
|
|
74
|
+
readonly eventXmlKey: string | null;
|
|
75
|
+
};
|
|
67
76
|
|
|
68
77
|
type InputOf<K extends DocumentEventKind> = Extract<DocumentInput, { kind: K }>;
|
|
69
78
|
type Step = { readonly [K in DocumentEventKind]: (document: FiscalDocument, input: InputOf<K>) => Partial<FiscalDocument> };
|
|
@@ -257,4 +266,5 @@ export const STEPS: Step = {
|
|
|
257
266
|
},
|
|
258
267
|
// `deadlineWarnedAt` is the transition's own time, set by `transition`.
|
|
259
268
|
WARN: () => ({}),
|
|
269
|
+
LINK_PAYMENT: () => ({}),
|
|
260
270
|
};
|