@12-apps/fiscal 1.6.0 → 1.7.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/dist/{chunk-ZKWVKCGJ.js → chunk-P5EDTNWE.js} +1 -1
- package/dist/{chunk-ZKWVKCGJ.js.map → chunk-P5EDTNWE.js.map} +1 -1
- package/dist/{context-Cyvfr2YB.d.ts → context-D71ETH--.d.ts} +2 -2
- package/dist/documents/index.d.ts +11 -8
- package/dist/documents/index.js +1 -0
- package/dist/documents/index.js.map +1 -1
- package/dist/http.d.ts +4 -4
- package/dist/issuer/index.d.ts +3 -3
- package/dist/issuer/index.js +1 -1
- package/dist/jobs.d.ts +4 -4
- package/dist/manifest/server.d.ts +4 -4
- package/dist/notifications.d.ts +3 -3
- package/dist/sale/index.d.ts +17 -4
- package/dist/sale/index.js.map +1 -1
- package/dist/{service-BCK9aXop.d.ts → service-DyA64Jc6.d.ts} +3 -3
- package/dist/sidecar/index.d.ts +1 -1
- package/dist/sidecar/index.js +1 -1
- package/dist/{types-Sk010Em2.d.ts → types-6OiBrmZy.d.ts} +1 -1
- package/dist/{types-Z5E14EPw.d.ts → types-BbTxBzsv.d.ts} +1 -3
- package/package.json +1 -1
- package/sidecar/README.md +18 -9
- package/sidecar/schema/sale-for-document.schema.json +4 -0
- package/sidecar/src/Nfe/DocumentMapper.php +27 -22
- package/src/documents/lines.ts +6 -2
- package/src/sale/types.ts +17 -4
- package/src/sidecar/types.ts +1 -3
package/dist/http.d.ts
CHANGED
|
@@ -1,9 +1,9 @@
|
|
|
1
1
|
import { D as DanfeNfceLabels } from './labels-BNvflT0h.js';
|
|
2
|
-
import { D as DocumentStorage } from './context-
|
|
3
|
-
import { F as FiscalDocuments } from './service-
|
|
4
|
-
import './types-
|
|
2
|
+
import { D as DocumentStorage } from './context-D71ETH--.js';
|
|
3
|
+
import { F as FiscalDocuments } from './service-DyA64Jc6.js';
|
|
4
|
+
import './types-6OiBrmZy.js';
|
|
5
5
|
import './sale/index.js';
|
|
6
|
-
import './types-
|
|
6
|
+
import './types-BbTxBzsv.js';
|
|
7
7
|
import './types-BLdkww6G.js';
|
|
8
8
|
|
|
9
9
|
/**
|
package/dist/issuer/index.d.ts
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
|
-
import { I as Issuer } from '../types-
|
|
2
|
-
export { C as CancelBySubstitutionCall, a as CancelCall, b as InutilizeCall, c as IssueCall, d as IssuerFailure, e as IssuerOutcome, L as LinkPaymentCall, f as LookupCall, S as SignContingencyCall, g as SigningMaterial, T as TransmitCall, m as modelPath } from '../types-
|
|
1
|
+
import { I as Issuer } from '../types-6OiBrmZy.js';
|
|
2
|
+
export { C as CancelBySubstitutionCall, a as CancelCall, b as InutilizeCall, c as IssueCall, d as IssuerFailure, e as IssuerOutcome, L as LinkPaymentCall, f as LookupCall, S as SignContingencyCall, g as SigningMaterial, T as TransmitCall, m as modelPath } from '../types-6OiBrmZy.js';
|
|
3
3
|
import '../sale/index.js';
|
|
4
|
-
import '../types-
|
|
4
|
+
import '../types-BbTxBzsv.js';
|
|
5
5
|
|
|
6
6
|
/**
|
|
7
7
|
* The Issuer adapter over the fiscal service in this package's `sidecar/`
|
package/dist/issuer/index.js
CHANGED
package/dist/jobs.d.ts
CHANGED
|
@@ -1,9 +1,9 @@
|
|
|
1
1
|
import * as _12_apps_wiring from '@12-apps/wiring';
|
|
2
|
-
import { F as FiscalStore, a as FiscalNotifyPort } from './context-
|
|
3
|
-
import { F as FiscalDocuments } from './service-
|
|
4
|
-
import './types-
|
|
2
|
+
import { F as FiscalStore, a as FiscalNotifyPort } from './context-D71ETH--.js';
|
|
3
|
+
import { F as FiscalDocuments } from './service-DyA64Jc6.js';
|
|
4
|
+
import './types-6OiBrmZy.js';
|
|
5
5
|
import './sale/index.js';
|
|
6
|
-
import './types-
|
|
6
|
+
import './types-BbTxBzsv.js';
|
|
7
7
|
import './types-BLdkww6G.js';
|
|
8
8
|
|
|
9
9
|
interface FiscalJobDeps {
|
|
@@ -1,12 +1,12 @@
|
|
|
1
1
|
import * as _12_apps_wiring from '@12-apps/wiring';
|
|
2
2
|
import { FiscalJobDeps } from '../jobs.js';
|
|
3
3
|
import { createApiFiscal } from '../http.js';
|
|
4
|
-
import '../context-
|
|
5
|
-
import '../types-
|
|
4
|
+
import '../context-D71ETH--.js';
|
|
5
|
+
import '../types-6OiBrmZy.js';
|
|
6
6
|
import '../sale/index.js';
|
|
7
|
-
import '../types-
|
|
7
|
+
import '../types-BbTxBzsv.js';
|
|
8
8
|
import '../types-BLdkww6G.js';
|
|
9
|
-
import '../service-
|
|
9
|
+
import '../service-DyA64Jc6.js';
|
|
10
10
|
import '../labels-BNvflT0h.js';
|
|
11
11
|
|
|
12
12
|
declare const fiscalServerManifest: {
|
package/dist/notifications.d.ts
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
|
-
export { b as FISCAL_CERTIFICATE_EXPIRING, c as FISCAL_CONTINGENCY_DEADLINE, d as FISCAL_DOCUMENT_NEEDS_ATTENTION, e as FISCAL_DOCUMENT_REJECTED } from './context-
|
|
2
|
-
import { F as FiscalDocumentModel, h as FiscalDocumentStatus, N as NumberVoid } from './types-
|
|
1
|
+
export { b as FISCAL_CERTIFICATE_EXPIRING, c as FISCAL_CONTINGENCY_DEADLINE, d as FISCAL_DOCUMENT_NEEDS_ATTENTION, e as FISCAL_DOCUMENT_REJECTED } from './context-D71ETH--.js';
|
|
2
|
+
import { F as FiscalDocumentModel, h as FiscalDocumentStatus, N as NumberVoid } from './types-6OiBrmZy.js';
|
|
3
3
|
import './sale/index.js';
|
|
4
|
-
import './types-
|
|
4
|
+
import './types-BbTxBzsv.js';
|
|
5
5
|
import './types-BLdkww6G.js';
|
|
6
6
|
|
|
7
7
|
/**
|
package/dist/sale/index.d.ts
CHANGED
|
@@ -5,10 +5,14 @@
|
|
|
5
5
|
* Money is integer CENTS, rates integer BASIS POINTS (1 bp = 0.01%) — the
|
|
6
6
|
* engine's conventions (`@12-apps/fiscal/engine`) — and quantities carry at
|
|
7
7
|
* most four decimals. Every field is required; an absent value is `null`,
|
|
8
|
-
* never a missing key, so a host cannot forget one silently. The
|
|
9
|
-
*
|
|
10
|
-
* `referencedDocuments
|
|
11
|
-
*
|
|
8
|
+
* never a missing key, so a host cannot forget one silently. The exceptions
|
|
9
|
+
* are the fields added after version 1 shipped — `operation` and
|
|
10
|
+
* `referencedDocuments` (the return document, FUT-2238), a payment's
|
|
11
|
+
* `linkedTransaction` (NT 2026.006, FUT-2239) and a line's `netValueCents`
|
|
12
|
+
* (NT 2026.008, FUT-4924): they are optional so that a document built before
|
|
13
|
+
* them stays valid and yields the same XML, byte for byte, and `version`
|
|
14
|
+
* stays 1 so that a service image older than a field still reads every
|
|
15
|
+
* document that does not use it.
|
|
12
16
|
*
|
|
13
17
|
* The JSON schema the service validates against is
|
|
14
18
|
* `@12-apps/fiscal/sidecar/schema/sale-for-document.schema.json`; a test keeps
|
|
@@ -152,6 +156,15 @@ interface SaleLine {
|
|
|
152
156
|
readonly valueCents: number;
|
|
153
157
|
/** `vDesc`. */
|
|
154
158
|
readonly discountCents: number;
|
|
159
|
+
/**
|
|
160
|
+
* `vProdLiq` (NT 2026.008 v1.00): the line's value WITHOUT the IBS/CBS, in a
|
|
161
|
+
* period whose IBS/CBS sit inside `vProd` (from 2027) — the engine's
|
|
162
|
+
* `LineTax.netValueCents`, written as given, at most `valueCents`. The
|
|
163
|
+
* service derives `vUnComLiq` (this over `quantity`, ten decimals) and
|
|
164
|
+
* `vProdLiqTot` (the sum over the lines). Absent or `null`: neither is
|
|
165
|
+
* written, as before 2027. Every line carries it or none does.
|
|
166
|
+
*/
|
|
167
|
+
readonly netValueCents?: number | null;
|
|
155
168
|
/** `vTotTrib` (the approximate tax of the transparency law), or `null`. */
|
|
156
169
|
readonly approximateTaxCents: number | null;
|
|
157
170
|
/** `infAdProd`. */
|
package/dist/sale/index.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"sources":["../../src/sale/types.ts"],"sourcesContent":["/**\n * The neutral document shape: one sale, host-agnostic, as the fiscal service\n * (`sidecar/`) accepts it and as the issuer port maps a host's sale into it.\n *\n * Money is integer CENTS, rates integer BASIS POINTS (1 bp = 0.01%) — the\n * engine's conventions (`@12-apps/fiscal/engine`) — and quantities carry at\n * most four decimals. Every field is required; an absent value is `null`,\n * never a missing key, so a host cannot forget one silently. The two\n * exceptions came with the return document (FUT-2238), `operation` and\n * `referencedDocuments`: they are optional so that a document built before\n * them stays valid and yields the same XML, byte for byte.\n *\n * The JSON schema the service validates against is\n * `@12-apps/fiscal/sidecar/schema/sale-for-document.schema.json`; a test keeps\n * it and these types in step. Whether the sale becomes an NF-e (model 55) or\n * an NFC-e (model 65) is the request path's choice, never this document's.\n */\n\n/** The 27 federative units. */\nexport type Uf =\n | \"AC\" | \"AL\" | \"AM\" | \"AP\" | \"BA\" | \"CE\" | \"DF\" | \"ES\" | \"GO\" | \"MA\" | \"MG\" | \"MS\" | \"MT\" | \"PA\"\n | \"PB\" | \"PE\" | \"PI\" | \"PR\" | \"RJ\" | \"RN\" | \"RO\" | \"RR\" | \"RS\" | \"SC\" | \"SE\" | \"SP\" | \"TO\";\n\n/** A postal address. `postalCode` is required on the issuer's. */\nexport interface Address {\n readonly street: string;\n readonly number: string;\n readonly complement: string | null;\n readonly district: string;\n /** The 7-digit IBGE municipality code. */\n readonly municipalityIbge: string;\n readonly municipalityName: string;\n readonly uf: Uf;\n /** CEP, 8 digits. */\n readonly postalCode: string | null;\n readonly phone: string | null;\n}\n\n/** The issuer's tax regime on the document (`CRT` 1, 2, 3, 4). */\nexport type IssuerTaxRegime = \"SIMPLES\" | \"SIMPLES_EXCESS\" | \"NORMAL\" | \"MEI\";\n\nexport interface DocumentIssuer {\n /** 14 characters; the 2026 alphanumeric CNPJ is accepted. */\n readonly cnpj: string;\n /** IE digits, or `ISENTO`. */\n readonly stateRegistration: string;\n readonly legalName: string;\n readonly tradeName: string | null;\n readonly taxRegime: IssuerTaxRegime;\n readonly address: Address & { readonly postalCode: string };\n}\n\nexport type BuyerDocument =\n | { readonly kind: \"CPF\"; readonly number: string }\n | { readonly kind: \"CNPJ\"; readonly number: string }\n | { readonly kind: \"FOREIGN\"; readonly number: string };\n\n/** `indIEDest` 1, 2, 9. */\nexport type StateRegistrationStatus = \"CONTRIBUTOR\" | \"EXEMPT\" | \"NON_CONTRIBUTOR\";\n\nexport interface DocumentBuyer {\n readonly document: BuyerDocument;\n readonly name: string | null;\n readonly stateRegistrationStatus: StateRegistrationStatus;\n readonly stateRegistration: string | null;\n readonly email: string | null;\n readonly address: Address | null;\n}\n\n/** The goods' origin (`orig`), 0–8. */\nexport type GoodsOrigin = 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8;\n\n/** ICMS of a Simples Nacional issuer, without a credit. */\nexport interface IcmsSimples {\n readonly regime: \"SIMPLES\";\n readonly origin: GoodsOrigin;\n readonly csosn: \"102\" | \"103\" | \"300\" | \"400\" | \"500\";\n}\n\n/** ICMS of a Simples Nacional issuer that grants the buyer a credit (CSOSN 101). */\nexport interface IcmsSimplesWithCredit {\n readonly regime: \"SIMPLES\";\n readonly origin: GoodsOrigin;\n readonly csosn: \"101\";\n readonly creditRateBp: number;\n readonly creditCents: number;\n}\n\n/** ICMS fully taxed (CST 00). */\nexport interface IcmsTaxed {\n readonly regime: \"NORMAL\";\n readonly origin: GoodsOrigin;\n readonly cst: \"00\";\n readonly baseCents: number;\n readonly rateBp: number;\n readonly amountCents: number;\n}\n\n/** ICMS exempt, not taxed, suspended (40, 41, 50) or collected before by substitution (60). */\nexport interface IcmsUntaxed {\n readonly regime: \"NORMAL\";\n readonly origin: GoodsOrigin;\n readonly cst: \"40\" | \"41\" | \"50\" | \"60\";\n}\n\nexport type LineIcms = IcmsSimples | IcmsSimplesWithCredit | IcmsTaxed | IcmsUntaxed;\n\n/** The PIS and COFINS situation codes the layout accepts on an outgoing document. */\nexport type ContributionCst =\n | \"01\" | \"02\" | \"04\" | \"05\" | \"06\" | \"07\" | \"08\" | \"09\" | \"49\" | \"50\" | \"51\" | \"52\" | \"53\" | \"54\"\n | \"55\" | \"56\" | \"60\" | \"61\" | \"62\" | \"63\" | \"64\" | \"65\" | \"66\" | \"67\" | \"70\" | \"71\" | \"72\" | \"73\"\n | \"74\" | \"75\" | \"98\" | \"99\";\n\n/**\n * PIS or COFINS. CST 01/02 write the base, the rate and the amount; 04–09\n * write none (send zeros); 49–99 write all three.\n */\nexport interface LineContribution {\n readonly cst: ContributionCst;\n readonly baseCents: number;\n readonly rateBp: number;\n readonly amountCents: number;\n}\n\n/**\n * The IBS/CBS figures of one line — what the engine's `LineTax` carries:\n * `vBC` and, per tax, the NOMINAL rate and the amount. `reductionBp` applies\n * to all three rates (`pRedAliq`; the effective rate is written beside it).\n */\nexport interface IbsCbsFigures {\n readonly baseCents: number;\n readonly reductionBp: number;\n readonly cbsRateBp: number;\n readonly cbsCents: number;\n readonly ibsUfRateBp: number;\n readonly ibsUfCents: number;\n readonly ibsMunRateBp: number;\n readonly ibsMunCents: number;\n}\n\n/** The IBS/CBS group of a line. `figures: null` writes the CST and class only (immunity, say). */\nexport interface LineIbsCbs {\n /** `CST` of the IBS/CBS, 3 digits. */\n readonly cst: string;\n /** `cClassTrib`, 6 digits. */\n readonly classCode: string;\n readonly figures: IbsCbsFigures | null;\n}\n\n/** One item of the document. */\nexport interface SaleLine {\n /** The host's id; quoted back in a mapping error. */\n readonly id: string;\n /** `cProd`. */\n readonly code: string;\n /** GTIN/EAN, or `null` for \"SEM GTIN\". */\n readonly gtin: string | null;\n readonly description: string;\n readonly ncm: string;\n readonly cest: string | null;\n readonly cfop: string;\n /** `uCom` and `uTrib`. */\n readonly unit: string;\n /** `qCom` and `qTrib`: positive, at most four decimals. */\n readonly quantity: number;\n /** `vProd`: every unit, BEFORE the line's discount. The unit value is derived. */\n readonly valueCents: number;\n /** `vDesc`. */\n readonly discountCents: number;\n /** `vTotTrib` (the approximate tax of the transparency law), or `null`. */\n readonly approximateTaxCents: number | null;\n /** `infAdProd`. */\n readonly additionalInfo: string | null;\n readonly icms: LineIcms;\n readonly pis: LineContribution;\n readonly cofins: LineContribution;\n /** `null` writes no IBS/CBS group — a regime the engine answered `NONE` for. */\n readonly ibsCbs: LineIbsCbs | null;\n}\n\n/** `tPag`. */\nexport type PaymentMethod =\n | \"CASH\"\n | \"CHECK\"\n | \"CREDIT_CARD\"\n | \"DEBIT_CARD\"\n | \"STORE_CREDIT\"\n | \"FOOD_VOUCHER\"\n | \"MEAL_VOUCHER\"\n | \"GIFT_VOUCHER\"\n | \"FUEL_VOUCHER\"\n | \"BANK_SLIP\"\n | \"BANK_DEPOSIT\"\n | \"PIX_DYNAMIC\"\n | \"TRANSFER\"\n | \"LOYALTY\"\n | \"PIX_STATIC\"\n | \"NO_PAYMENT\"\n | \"OTHER\";\n\nexport interface CardDetails {\n /** `tpIntegra`: whether the payment went through an integrated terminal. */\n readonly integrated: boolean;\n readonly acquirerCnpj: string | null;\n /** `tBand`, 2 digits. */\n readonly brand: string | null;\n /** `cAut`. */\n readonly authorizationCode: string | null;\n}\n\n/**\n * `tpMeioPgto` (Informe Técnico 2026.001 v1.01): the means a linked payment\n * transaction moved by — 15 boleto, 17 Pix QR dinâmico, 18 TED, 20 Pix by key\n * or static QR, 23 Pix automático, 24 TEF. A card and cash have none.\n */\nexport const PAYMENT_LINK_MEANS = [\"15\", \"17\", \"18\", \"20\", \"23\", \"24\"] as const;\nexport type PaymentLinkMeans = (typeof PAYMENT_LINK_MEANS)[number];\n\n/**\n * `gPgtoVinc/gPgto` (NT 2026.006 v1.00): a payment transaction started before\n * the document — a Pix QR raised, a boleto generated — linked by its id, so the\n * split payment can find the document. The event 110300 links one after the fact.\n */\nexport interface LinkedTransaction {\n /** `idTransacao`, 2–35 characters: the Pix txid, the boleto's or the transfer's id. */\n readonly transactionId: string;\n readonly meansCode: PaymentLinkMeans;\n /** `CNPJBasePSP`: the 8-character CNPJ base of the receiver's payment institution. */\n readonly pspCnpjBase: string;\n /** `CNPJReceb`: who receives the money (the issuer, or a platform receiving for it). */\n readonly receiverCnpj: string;\n}\n\nexport interface SalePayment {\n readonly method: PaymentMethod;\n readonly amountCents: number;\n /** Required by the layout for a card and for a Pix; `null` otherwise. */\n readonly card: CardDetails | null;\n /** `xPag`: required when `method` is `OTHER`. */\n readonly description: string | null;\n /**\n * The transaction this payment was started as, written in `gPgtoVinc` with\n * `nPag` = its position. Absent or `null`: no link. The host decides whether\n * the environment accepts the group (optional in the layout; its production\n * activation is the fisco's).\n */\n readonly linkedTransaction?: LinkedTransaction | null;\n}\n\n/** `finNFe` 1–4. */\nexport type DocumentPurpose = \"NORMAL\" | \"COMPLEMENTARY\" | \"ADJUSTMENT\" | \"RETURN\";\n/**\n * `tpNF`: `OUT` (1) a sale or any outgoing document; `IN` (0) an entry, such as\n * a buyer's goods coming back. An NFC-e is always `OUT`.\n */\nexport type DocumentOperation = \"OUT\" | \"IN\";\n/** `NFref/refNFe`: an earlier NF-e or NFC-e this document refers to. */\nexport interface ReferencedDocument {\n /** The 44-character access key (`isValidAccessKey` in `@12-apps/fiscal/documents`). */\n readonly accessKey: string;\n}\n/** `idDest` 1–3. */\nexport type OperationDestination = \"INTERNAL\" | \"INTERSTATE\" | \"FOREIGN\";\n/** `indPres` 1, 2, 3, 4, 5, 9. */\nexport type BuyerPresence =\n | \"IN_PERSON\"\n | \"INTERNET\"\n | \"TELEPHONE\"\n | \"HOME_DELIVERY\"\n | \"IN_PERSON_OFF_PREMISES\"\n | \"OTHER\";\n/** `modFrete` 0, 1, 2, 3, 4, 9. */\nexport type FreightMode =\n | \"BY_ISSUER\"\n | \"BY_RECIPIENT\"\n | \"BY_THIRD_PARTY\"\n | \"OWN_BY_ISSUER\"\n | \"OWN_BY_RECIPIENT\"\n | \"NONE\";\n\n/** `infIntermed`: the third-party platform the sale went through. */\nexport interface SaleIntermediary {\n readonly cnpj: string;\n /** `idCadIntTran`: the seller's id on that platform. */\n readonly userId: string;\n}\n\n/** `infRespTec`: the software house responsible for the issuing system. */\nexport interface TechnicalResponsible {\n readonly cnpj: string;\n readonly contactName: string;\n readonly email: string;\n readonly phone: string;\n}\n\n/** One sale, ready to become an NF-e or an NFC-e. */\nexport interface SaleForDocument {\n readonly version: 1;\n /** `serie`, 0–999. */\n readonly series: number;\n /** `nNF`, 1–999999999. The package's counter owns it. */\n readonly number: number;\n /**\n * `cNF`: the 8-digit code inside the access key. The caller draws it ONCE and\n * keeps it with the document, so a retried call yields the same key.\n */\n readonly keyCode: string;\n /** `dhEmi`: ISO 8601 with the UTC offset, `2026-11-20T12:30:00-03:00`. */\n readonly issuedAt: string;\n /** `natOp`. */\n readonly operationNature: string;\n readonly purpose: DocumentPurpose;\n /**\n * `tpNF`. Absent is `OUT`. A buyer's return is an NF-e (model 55) with\n * `purpose: \"RETURN\"` and `operation: \"IN\"`; an NFC-e has neither.\n */\n readonly operation?: DocumentOperation;\n /**\n * `NFref`, at most 500, in order. Absent is none. A `RETURN` quotes the\n * document it returns here, or it is refused (`RETURN_NEEDS_REFERENCE`); an\n * NFC-e quotes none (SEFAZ 708). For a buyer's return the host sets CFOP\n * 1202 (within the state) or 2202 (between states) on every line, and a\n * single `NO_PAYMENT` payment; the package checks neither.\n */\n readonly referencedDocuments?: readonly ReferencedDocument[];\n readonly destination: OperationDestination;\n readonly presence: BuyerPresence;\n /** `indFinal`. */\n readonly finalConsumer: boolean;\n readonly intermediary: SaleIntermediary | null;\n readonly issuer: DocumentIssuer;\n /** `null` on an NFC-e with no identified buyer. */\n readonly buyer: DocumentBuyer | null;\n /** 1–990 items. */\n readonly lines: readonly SaleLine[];\n readonly freight: FreightMode;\n /** 1–100 payments. */\n readonly payments: readonly SalePayment[];\n /** `vTroco`. */\n readonly changeCents: number;\n readonly additionalInfo: {\n /** `infCpl`. */\n readonly forTaxpayer: string | null;\n /** `infAdFisco`. */\n readonly forTaxAuthority: string | null;\n };\n readonly technicalResponsible: TechnicalResponsible | null;\n}\n"],"mappings":";;;AAuNO,IAAM,qBAAqB,CAAC,MAAM,MAAM,MAAM,MAAM,MAAM,IAAI;","names":[]}
|
|
1
|
+
{"version":3,"sources":["../../src/sale/types.ts"],"sourcesContent":["/**\n * The neutral document shape: one sale, host-agnostic, as the fiscal service\n * (`sidecar/`) accepts it and as the issuer port maps a host's sale into it.\n *\n * Money is integer CENTS, rates integer BASIS POINTS (1 bp = 0.01%) — the\n * engine's conventions (`@12-apps/fiscal/engine`) — and quantities carry at\n * most four decimals. Every field is required; an absent value is `null`,\n * never a missing key, so a host cannot forget one silently. The exceptions\n * are the fields added after version 1 shipped — `operation` and\n * `referencedDocuments` (the return document, FUT-2238), a payment's\n * `linkedTransaction` (NT 2026.006, FUT-2239) and a line's `netValueCents`\n * (NT 2026.008, FUT-4924): they are optional so that a document built before\n * them stays valid and yields the same XML, byte for byte, and `version`\n * stays 1 so that a service image older than a field still reads every\n * document that does not use it.\n *\n * The JSON schema the service validates against is\n * `@12-apps/fiscal/sidecar/schema/sale-for-document.schema.json`; a test keeps\n * it and these types in step. Whether the sale becomes an NF-e (model 55) or\n * an NFC-e (model 65) is the request path's choice, never this document's.\n */\n\n/** The 27 federative units. */\nexport type Uf =\n | \"AC\" | \"AL\" | \"AM\" | \"AP\" | \"BA\" | \"CE\" | \"DF\" | \"ES\" | \"GO\" | \"MA\" | \"MG\" | \"MS\" | \"MT\" | \"PA\"\n | \"PB\" | \"PE\" | \"PI\" | \"PR\" | \"RJ\" | \"RN\" | \"RO\" | \"RR\" | \"RS\" | \"SC\" | \"SE\" | \"SP\" | \"TO\";\n\n/** A postal address. `postalCode` is required on the issuer's. */\nexport interface Address {\n readonly street: string;\n readonly number: string;\n readonly complement: string | null;\n readonly district: string;\n /** The 7-digit IBGE municipality code. */\n readonly municipalityIbge: string;\n readonly municipalityName: string;\n readonly uf: Uf;\n /** CEP, 8 digits. */\n readonly postalCode: string | null;\n readonly phone: string | null;\n}\n\n/** The issuer's tax regime on the document (`CRT` 1, 2, 3, 4). */\nexport type IssuerTaxRegime = \"SIMPLES\" | \"SIMPLES_EXCESS\" | \"NORMAL\" | \"MEI\";\n\nexport interface DocumentIssuer {\n /** 14 characters; the 2026 alphanumeric CNPJ is accepted. */\n readonly cnpj: string;\n /** IE digits, or `ISENTO`. */\n readonly stateRegistration: string;\n readonly legalName: string;\n readonly tradeName: string | null;\n readonly taxRegime: IssuerTaxRegime;\n readonly address: Address & { readonly postalCode: string };\n}\n\nexport type BuyerDocument =\n | { readonly kind: \"CPF\"; readonly number: string }\n | { readonly kind: \"CNPJ\"; readonly number: string }\n | { readonly kind: \"FOREIGN\"; readonly number: string };\n\n/** `indIEDest` 1, 2, 9. */\nexport type StateRegistrationStatus = \"CONTRIBUTOR\" | \"EXEMPT\" | \"NON_CONTRIBUTOR\";\n\nexport interface DocumentBuyer {\n readonly document: BuyerDocument;\n readonly name: string | null;\n readonly stateRegistrationStatus: StateRegistrationStatus;\n readonly stateRegistration: string | null;\n readonly email: string | null;\n readonly address: Address | null;\n}\n\n/** The goods' origin (`orig`), 0–8. */\nexport type GoodsOrigin = 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8;\n\n/** ICMS of a Simples Nacional issuer, without a credit. */\nexport interface IcmsSimples {\n readonly regime: \"SIMPLES\";\n readonly origin: GoodsOrigin;\n readonly csosn: \"102\" | \"103\" | \"300\" | \"400\" | \"500\";\n}\n\n/** ICMS of a Simples Nacional issuer that grants the buyer a credit (CSOSN 101). */\nexport interface IcmsSimplesWithCredit {\n readonly regime: \"SIMPLES\";\n readonly origin: GoodsOrigin;\n readonly csosn: \"101\";\n readonly creditRateBp: number;\n readonly creditCents: number;\n}\n\n/** ICMS fully taxed (CST 00). */\nexport interface IcmsTaxed {\n readonly regime: \"NORMAL\";\n readonly origin: GoodsOrigin;\n readonly cst: \"00\";\n readonly baseCents: number;\n readonly rateBp: number;\n readonly amountCents: number;\n}\n\n/** ICMS exempt, not taxed, suspended (40, 41, 50) or collected before by substitution (60). */\nexport interface IcmsUntaxed {\n readonly regime: \"NORMAL\";\n readonly origin: GoodsOrigin;\n readonly cst: \"40\" | \"41\" | \"50\" | \"60\";\n}\n\nexport type LineIcms = IcmsSimples | IcmsSimplesWithCredit | IcmsTaxed | IcmsUntaxed;\n\n/** The PIS and COFINS situation codes the layout accepts on an outgoing document. */\nexport type ContributionCst =\n | \"01\" | \"02\" | \"04\" | \"05\" | \"06\" | \"07\" | \"08\" | \"09\" | \"49\" | \"50\" | \"51\" | \"52\" | \"53\" | \"54\"\n | \"55\" | \"56\" | \"60\" | \"61\" | \"62\" | \"63\" | \"64\" | \"65\" | \"66\" | \"67\" | \"70\" | \"71\" | \"72\" | \"73\"\n | \"74\" | \"75\" | \"98\" | \"99\";\n\n/**\n * PIS or COFINS. CST 01/02 write the base, the rate and the amount; 04–09\n * write none (send zeros); 49–99 write all three.\n */\nexport interface LineContribution {\n readonly cst: ContributionCst;\n readonly baseCents: number;\n readonly rateBp: number;\n readonly amountCents: number;\n}\n\n/**\n * The IBS/CBS figures of one line — what the engine's `LineTax` carries:\n * `vBC` and, per tax, the NOMINAL rate and the amount. `reductionBp` applies\n * to all three rates (`pRedAliq`; the effective rate is written beside it).\n */\nexport interface IbsCbsFigures {\n readonly baseCents: number;\n readonly reductionBp: number;\n readonly cbsRateBp: number;\n readonly cbsCents: number;\n readonly ibsUfRateBp: number;\n readonly ibsUfCents: number;\n readonly ibsMunRateBp: number;\n readonly ibsMunCents: number;\n}\n\n/** The IBS/CBS group of a line. `figures: null` writes the CST and class only (immunity, say). */\nexport interface LineIbsCbs {\n /** `CST` of the IBS/CBS, 3 digits. */\n readonly cst: string;\n /** `cClassTrib`, 6 digits. */\n readonly classCode: string;\n readonly figures: IbsCbsFigures | null;\n}\n\n/** One item of the document. */\nexport interface SaleLine {\n /** The host's id; quoted back in a mapping error. */\n readonly id: string;\n /** `cProd`. */\n readonly code: string;\n /** GTIN/EAN, or `null` for \"SEM GTIN\". */\n readonly gtin: string | null;\n readonly description: string;\n readonly ncm: string;\n readonly cest: string | null;\n readonly cfop: string;\n /** `uCom` and `uTrib`. */\n readonly unit: string;\n /** `qCom` and `qTrib`: positive, at most four decimals. */\n readonly quantity: number;\n /** `vProd`: every unit, BEFORE the line's discount. The unit value is derived. */\n readonly valueCents: number;\n /** `vDesc`. */\n readonly discountCents: number;\n /**\n * `vProdLiq` (NT 2026.008 v1.00): the line's value WITHOUT the IBS/CBS, in a\n * period whose IBS/CBS sit inside `vProd` (from 2027) — the engine's\n * `LineTax.netValueCents`, written as given, at most `valueCents`. The\n * service derives `vUnComLiq` (this over `quantity`, ten decimals) and\n * `vProdLiqTot` (the sum over the lines). Absent or `null`: neither is\n * written, as before 2027. Every line carries it or none does.\n */\n readonly netValueCents?: number | null;\n /** `vTotTrib` (the approximate tax of the transparency law), or `null`. */\n readonly approximateTaxCents: number | null;\n /** `infAdProd`. */\n readonly additionalInfo: string | null;\n readonly icms: LineIcms;\n readonly pis: LineContribution;\n readonly cofins: LineContribution;\n /** `null` writes no IBS/CBS group — a regime the engine answered `NONE` for. */\n readonly ibsCbs: LineIbsCbs | null;\n}\n\n/** `tPag`. */\nexport type PaymentMethod =\n | \"CASH\"\n | \"CHECK\"\n | \"CREDIT_CARD\"\n | \"DEBIT_CARD\"\n | \"STORE_CREDIT\"\n | \"FOOD_VOUCHER\"\n | \"MEAL_VOUCHER\"\n | \"GIFT_VOUCHER\"\n | \"FUEL_VOUCHER\"\n | \"BANK_SLIP\"\n | \"BANK_DEPOSIT\"\n | \"PIX_DYNAMIC\"\n | \"TRANSFER\"\n | \"LOYALTY\"\n | \"PIX_STATIC\"\n | \"NO_PAYMENT\"\n | \"OTHER\";\n\nexport interface CardDetails {\n /** `tpIntegra`: whether the payment went through an integrated terminal. */\n readonly integrated: boolean;\n readonly acquirerCnpj: string | null;\n /** `tBand`, 2 digits. */\n readonly brand: string | null;\n /** `cAut`. */\n readonly authorizationCode: string | null;\n}\n\n/**\n * `tpMeioPgto` (Informe Técnico 2026.001 v1.01): the means a linked payment\n * transaction moved by — 15 boleto, 17 Pix QR dinâmico, 18 TED, 20 Pix by key\n * or static QR, 23 Pix automático, 24 TEF. A card and cash have none.\n */\nexport const PAYMENT_LINK_MEANS = [\"15\", \"17\", \"18\", \"20\", \"23\", \"24\"] as const;\nexport type PaymentLinkMeans = (typeof PAYMENT_LINK_MEANS)[number];\n\n/**\n * `gPgtoVinc/gPgto` (NT 2026.006 v1.00): a payment transaction started before\n * the document — a Pix QR raised, a boleto generated — linked by its id, so the\n * split payment can find the document. The event 110300 links one after the fact.\n */\nexport interface LinkedTransaction {\n /** `idTransacao`, 2–35 characters: the Pix txid, the boleto's or the transfer's id. */\n readonly transactionId: string;\n readonly meansCode: PaymentLinkMeans;\n /** `CNPJBasePSP`: the 8-character CNPJ base of the receiver's payment institution. */\n readonly pspCnpjBase: string;\n /** `CNPJReceb`: who receives the money (the issuer, or a platform receiving for it). */\n readonly receiverCnpj: string;\n}\n\nexport interface SalePayment {\n readonly method: PaymentMethod;\n readonly amountCents: number;\n /** Required by the layout for a card and for a Pix; `null` otherwise. */\n readonly card: CardDetails | null;\n /** `xPag`: required when `method` is `OTHER`. */\n readonly description: string | null;\n /**\n * The transaction this payment was started as, written in `gPgtoVinc` with\n * `nPag` = its position. Absent or `null`: no link. The host decides whether\n * the environment accepts the group (optional in the layout; its production\n * activation is the fisco's).\n */\n readonly linkedTransaction?: LinkedTransaction | null;\n}\n\n/** `finNFe` 1–4. */\nexport type DocumentPurpose = \"NORMAL\" | \"COMPLEMENTARY\" | \"ADJUSTMENT\" | \"RETURN\";\n/**\n * `tpNF`: `OUT` (1) a sale or any outgoing document; `IN` (0) an entry, such as\n * a buyer's goods coming back. An NFC-e is always `OUT`.\n */\nexport type DocumentOperation = \"OUT\" | \"IN\";\n/** `NFref/refNFe`: an earlier NF-e or NFC-e this document refers to. */\nexport interface ReferencedDocument {\n /** The 44-character access key (`isValidAccessKey` in `@12-apps/fiscal/documents`). */\n readonly accessKey: string;\n}\n/** `idDest` 1–3. */\nexport type OperationDestination = \"INTERNAL\" | \"INTERSTATE\" | \"FOREIGN\";\n/** `indPres` 1, 2, 3, 4, 5, 9. */\nexport type BuyerPresence =\n | \"IN_PERSON\"\n | \"INTERNET\"\n | \"TELEPHONE\"\n | \"HOME_DELIVERY\"\n | \"IN_PERSON_OFF_PREMISES\"\n | \"OTHER\";\n/** `modFrete` 0, 1, 2, 3, 4, 9. */\nexport type FreightMode =\n | \"BY_ISSUER\"\n | \"BY_RECIPIENT\"\n | \"BY_THIRD_PARTY\"\n | \"OWN_BY_ISSUER\"\n | \"OWN_BY_RECIPIENT\"\n | \"NONE\";\n\n/** `infIntermed`: the third-party platform the sale went through. */\nexport interface SaleIntermediary {\n readonly cnpj: string;\n /** `idCadIntTran`: the seller's id on that platform. */\n readonly userId: string;\n}\n\n/** `infRespTec`: the software house responsible for the issuing system. */\nexport interface TechnicalResponsible {\n readonly cnpj: string;\n readonly contactName: string;\n readonly email: string;\n readonly phone: string;\n}\n\n/** One sale, ready to become an NF-e or an NFC-e. */\nexport interface SaleForDocument {\n readonly version: 1;\n /** `serie`, 0–999. */\n readonly series: number;\n /** `nNF`, 1–999999999. The package's counter owns it. */\n readonly number: number;\n /**\n * `cNF`: the 8-digit code inside the access key. The caller draws it ONCE and\n * keeps it with the document, so a retried call yields the same key.\n */\n readonly keyCode: string;\n /** `dhEmi`: ISO 8601 with the UTC offset, `2026-11-20T12:30:00-03:00`. */\n readonly issuedAt: string;\n /** `natOp`. */\n readonly operationNature: string;\n readonly purpose: DocumentPurpose;\n /**\n * `tpNF`. Absent is `OUT`. A buyer's return is an NF-e (model 55) with\n * `purpose: \"RETURN\"` and `operation: \"IN\"`; an NFC-e has neither.\n */\n readonly operation?: DocumentOperation;\n /**\n * `NFref`, at most 500, in order. Absent is none. A `RETURN` quotes the\n * document it returns here, or it is refused (`RETURN_NEEDS_REFERENCE`); an\n * NFC-e quotes none (SEFAZ 708). For a buyer's return the host sets CFOP\n * 1202 (within the state) or 2202 (between states) on every line, and a\n * single `NO_PAYMENT` payment; the package checks neither.\n */\n readonly referencedDocuments?: readonly ReferencedDocument[];\n readonly destination: OperationDestination;\n readonly presence: BuyerPresence;\n /** `indFinal`. */\n readonly finalConsumer: boolean;\n readonly intermediary: SaleIntermediary | null;\n readonly issuer: DocumentIssuer;\n /** `null` on an NFC-e with no identified buyer. */\n readonly buyer: DocumentBuyer | null;\n /** 1–990 items. */\n readonly lines: readonly SaleLine[];\n readonly freight: FreightMode;\n /** 1–100 payments. */\n readonly payments: readonly SalePayment[];\n /** `vTroco`. */\n readonly changeCents: number;\n readonly additionalInfo: {\n /** `infCpl`. */\n readonly forTaxpayer: string | null;\n /** `infAdFisco`. */\n readonly forTaxAuthority: string | null;\n };\n readonly technicalResponsible: TechnicalResponsible | null;\n}\n"],"mappings":";;;AAoOO,IAAM,qBAAqB,CAAC,MAAM,MAAM,MAAM,MAAM,MAAM,IAAI;","names":[]}
|
|
@@ -1,8 +1,8 @@
|
|
|
1
|
-
import { f as DocumentPolicy, S as SigningIdentityKind, g as FiscalDocumentsConfig, C as Cipher, h as ContingencyGap, E as EmitterProfile, I as IssuingPoint, i as ContingencyBlock, j as SaleDraft, k as ContingencyBlockFate, l as ContingencyBlockState } from './context-
|
|
2
|
-
import { F as FiscalDocumentModel, d as IssuerFailure, i as FiscalDocument, j as CancelOrReturnInput, k as CancelOrReturnResult, l as FiscalDocumentEvent } from './types-
|
|
1
|
+
import { f as DocumentPolicy, S as SigningIdentityKind, g as FiscalDocumentsConfig, C as Cipher, h as ContingencyGap, E as EmitterProfile, I as IssuingPoint, i as ContingencyBlock, j as SaleDraft, k as ContingencyBlockFate, l as ContingencyBlockState } from './context-D71ETH--.js';
|
|
2
|
+
import { F as FiscalDocumentModel, d as IssuerFailure, i as FiscalDocument, j as CancelOrReturnInput, k as CancelOrReturnResult, l as FiscalDocumentEvent } from './types-6OiBrmZy.js';
|
|
3
3
|
import { IssuerTaxRegime, Address, LinkedTransaction } from './sale/index.js';
|
|
4
4
|
import { T as TaxRegime } from './types-BLdkww6G.js';
|
|
5
|
-
import { l as SefazEnvironment, i as LookedUpDocument } from './types-
|
|
5
|
+
import { l as SefazEnvironment, i as LookedUpDocument } from './types-BbTxBzsv.js';
|
|
6
6
|
|
|
7
7
|
/**
|
|
8
8
|
* Reading the emitter profile and the certificate upload off a request body:
|
package/dist/sidecar/index.d.ts
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
export { C as CancelBySubstitutionRequest, a as CancelRequest, b as CancelledDocument, c as ContingencyEntry, d as ContingencySignedDocument, e as Csc, D as DocumentModelPath, I as InutilizeRequest, f as InutilizedRange, g as IssueRequest, h as IssuedDocument, L as LinkPaymentRequest, i as LookedUpDocument, j as LookupRequest, R as RegisteredPaymentLink, S as SIDECAR_ERROR_CLASSES, k as SefazAnswer, l as SefazEnvironment, m as SidecarErrorBody, n as SidecarErrorClass, o as SidecarHealth, p as SignContingencyRequest, q as SigningCertificate, T as TransmitRequest } from '../types-
|
|
1
|
+
export { C as CancelBySubstitutionRequest, a as CancelRequest, b as CancelledDocument, c as ContingencyEntry, d as ContingencySignedDocument, e as Csc, D as DocumentModelPath, I as InutilizeRequest, f as InutilizedRange, g as IssueRequest, h as IssuedDocument, L as LinkPaymentRequest, i as LookedUpDocument, j as LookupRequest, R as RegisteredPaymentLink, S as SIDECAR_ERROR_CLASSES, k as SefazAnswer, l as SefazEnvironment, m as SidecarErrorBody, n as SidecarErrorClass, o as SidecarHealth, p as SignContingencyRequest, q as SigningCertificate, T as TransmitRequest } from '../types-BbTxBzsv.js';
|
|
2
2
|
import '../sale/index.js';
|
|
3
3
|
|
|
4
4
|
/**
|
package/dist/sidecar/index.js
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
import { SaleForDocument, LinkedTransaction } from './sale/index.js';
|
|
2
|
-
import { m as SidecarErrorBody, l as SefazEnvironment, q as SigningCertificate, e as Csc, h as IssuedDocument, c as ContingencyEntry, d as ContingencySignedDocument, b as CancelledDocument, i as LookedUpDocument, R as RegisteredPaymentLink, f as InutilizedRange, o as SidecarHealth, n as SidecarErrorClass } from './types-
|
|
2
|
+
import { m as SidecarErrorBody, l as SefazEnvironment, q as SigningCertificate, e as Csc, h as IssuedDocument, c as ContingencyEntry, d as ContingencySignedDocument, b as CancelledDocument, i as LookedUpDocument, R as RegisteredPaymentLink, f as InutilizedRange, o as SidecarHealth, n as SidecarErrorClass } from './types-BbTxBzsv.js';
|
|
3
3
|
|
|
4
4
|
/**
|
|
5
5
|
* The Issuer port: what the document service asks of whoever talks to SEFAZ.
|
|
@@ -222,9 +222,7 @@ interface SidecarErrorBody {
|
|
|
222
222
|
readonly class: SidecarErrorClass;
|
|
223
223
|
/**
|
|
224
224
|
* The SEFAZ `cStat` when SEFAZ answered (always for `REJECTED`); for
|
|
225
|
-
* `INVALID`, a named code where one applies (`
|
|
226
|
-
* a document issued on or after 2027-01-01, which needs NT 2026.008's
|
|
227
|
-
* `vProdLiq`; `RETURN_ON_NFCE`: a return asked of an NFC-e, which has no
|
|
225
|
+
* `INVALID`, a named code where one applies (`RETURN_ON_NFCE`: a return asked of an NFC-e, which has no
|
|
228
226
|
* return purpose; `RETURN_NEEDS_REFERENCE`: a return quoting no
|
|
229
227
|
* `referencedDocuments`); `null` otherwise.
|
|
230
228
|
*/
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@12-apps/fiscal",
|
|
3
|
-
"version": "1.
|
|
3
|
+
"version": "1.7.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.",
|
package/sidecar/README.md
CHANGED
|
@@ -52,10 +52,20 @@ reach SEFAZ either does an NFC-e being issued answer `CONTINGENCY` (with
|
|
|
52
52
|
`outcomeUnknown: true`); everywhere else it is `RETRYABLE`. A blind
|
|
53
53
|
contingency could put a second document on the same sale.
|
|
54
54
|
|
|
55
|
-
**
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
55
|
+
**The net value (NT 2026.008).** From 2027 the IBS/CBS go inside `vProd` and
|
|
56
|
+
the price without them travels in `vProdLiq`. A line's optional
|
|
57
|
+
`netValueCents` is that figure (the engine's `LineTax.netValueCents`), written
|
|
58
|
+
as given; `vUnComLiq` is derived from it over `quantity` with ten decimals, as
|
|
59
|
+
`vUnCom` is, and `vProdLiqTot` is their sum. The service derives the unit
|
|
60
|
+
value itself (half-up to ten decimals) rather than taking the engine's
|
|
61
|
+
`netUnitValue` string (exact, half-even), so the two may differ in the tenth
|
|
62
|
+
decimal only: `vUnComLiq × qCom` stays far inside I11c-20's ±0,01 of
|
|
63
|
+
`vProdLiq`. Absent or `null` writes none of
|
|
64
|
+
the three, byte for byte the document it was before. It is `INVALID` to carry
|
|
65
|
+
it on some lines only, or above the line's `valueCents`. Whether a period puts
|
|
66
|
+
the tax inside the price is the engine's rate table's call; the service
|
|
67
|
+
refuses no date (the `NT_2026_008_NOT_SUPPORTED` refusal of sped-nfe 5.2.9 is
|
|
68
|
+
gone with the bump to 5.2.11).
|
|
59
69
|
|
|
60
70
|
**A return document.** `operation` maps to `tpNF` (`OUT` 1, `IN` 0) and
|
|
61
71
|
`referencedDocuments[].accessKey` to `NFref/refNFe`, in order. Both are
|
|
@@ -80,7 +90,7 @@ Every failure is `{ error: { class, code, message, details, accessKey, signedXml
|
|
|
80
90
|
| `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. |
|
|
81
91
|
| `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". |
|
|
82
92
|
| `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. |
|
|
83
|
-
| `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
|
|
93
|
+
| `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 net value (`netValueCents`) on some lines only or above the line's `valueCents`. Never retry it as is. |
|
|
84
94
|
| `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. |
|
|
85
95
|
|
|
86
96
|
When the call got as far as signing, `accessKey` and `signedXml` come back
|
|
@@ -208,7 +218,6 @@ SEFAZ directly.
|
|
|
208
218
|
|
|
209
219
|
## Versions
|
|
210
220
|
|
|
211
|
-
sped-nfe `5.2.
|
|
212
|
-
2025.002 v1.50 and NT 2026.007 v1.00)
|
|
213
|
-
`vProdLiqTot
|
|
214
|
-
sped-nfe's `master` after 5.2.9 and arrive with its next release.
|
|
221
|
+
sped-nfe `5.2.11`, schema package `PL_010_V1.30` (Pacote de Liberação 010f: NT
|
|
222
|
+
2025.002 v1.50 and NT 2026.007 v1.00), which carries NT 2026.008's
|
|
223
|
+
`vUnComLiq`/`vProdLiq`/`vProdLiqTot` and NT 2026.006's `gPgtoVinc`.
|
|
@@ -362,6 +362,10 @@
|
|
|
362
362
|
"minimum": 1
|
|
363
363
|
},
|
|
364
364
|
"discountCents": { "$ref": "#/definitions/cents" },
|
|
365
|
+
"netValueCents": {
|
|
366
|
+
"description": "vProdLiq (NT 2026.008 v1.00): the line's value without the IBS/CBS, where they sit inside vProd (from 2027); at most valueCents. vUnComLiq and vProdLiqTot are derived from it. Absent or null: none of the three is written. Every line carries it or none does.",
|
|
367
|
+
"oneOf": [{ "type": "null" }, { "$ref": "#/definitions/cents" }]
|
|
368
|
+
},
|
|
365
369
|
"approximateTaxCents": { "oneOf": [{ "type": "null" }, { "$ref": "#/definitions/cents" }] },
|
|
366
370
|
"additionalInfo": { "oneOf": [{ "type": "null" }, { "type": "string", "minLength": 1, "maxLength": 500 }] },
|
|
367
371
|
"icms": { "$ref": "#/definitions/icms" },
|
|
@@ -66,19 +66,6 @@ final class DocumentMapper
|
|
|
66
66
|
|
|
67
67
|
public const PROCESS_VERSION = 'fiscal-sidecar-1';
|
|
68
68
|
|
|
69
|
-
/**
|
|
70
|
-
* From 2027 the IBS/CBS go INSIDE `vProd`, and the price without tax
|
|
71
|
-
* travels in NT 2026.008's `vProdLiq`/`vUnComLiq`/`vProdLiqTot` (source: NT
|
|
72
|
-
* 2026.008 v1.00 itself: from 2027 the IBS, CBS and IS values "deverão ser
|
|
73
|
-
* acrescidos ao valor do produto ou serviço, compondo o valor informado no
|
|
74
|
-
* campo vProd"). sped-nfe 5.2.9 cannot write those fields, and document
|
|
75
|
-
* version 1 does not carry them, so a document issued on or after this day
|
|
76
|
-
* is refused rather than emitted wrong. Lifted by the sped-nfe bump that
|
|
77
|
-
* brings NT 2026.008, with document version 2.
|
|
78
|
-
*/
|
|
79
|
-
public const LAYOUT_LIMIT = '2027-01-01';
|
|
80
|
-
public const LAYOUT_LIMIT_CODE = 'NT_2026_008_NOT_SUPPORTED';
|
|
81
|
-
|
|
82
69
|
/** A return (`finNFe` 4) quotes the document it returns (`NFref`); one without a reference is refused. */
|
|
83
70
|
public const RETURN_NEEDS_REFERENCE_CODE = 'RETURN_NEEDS_REFERENCE';
|
|
84
71
|
|
|
@@ -127,20 +114,23 @@ final class DocumentMapper
|
|
|
127
114
|
/** @param array<string, mixed> $document */
|
|
128
115
|
private static function refuseWhatThisLayoutCannotSay(array $document): void
|
|
129
116
|
{
|
|
130
|
-
if (substr((string) $document['issuedAt'], 0, 10) >= self::LAYOUT_LIMIT) {
|
|
131
|
-
throw new ServiceError(
|
|
132
|
-
\Fiscal\Sidecar\ErrorClass::INVALID,
|
|
133
|
-
'A document issued on or after ' . self::LAYOUT_LIMIT . ' needs NT 2026.008 (vProdLiq), '
|
|
134
|
-
. 'which this service\'s sped-nfe does not write yet.',
|
|
135
|
-
self::LAYOUT_LIMIT_CODE,
|
|
136
|
-
);
|
|
137
|
-
}
|
|
138
117
|
$details = [];
|
|
118
|
+
$withNetValue = 0;
|
|
139
119
|
foreach (array_values($document['lines']) as $index => $line) {
|
|
140
120
|
$quantity = (float) $line['quantity'];
|
|
141
121
|
if (abs(round($quantity, 4) - $quantity) > 1e-9) {
|
|
142
122
|
$details[] = "lines[$index].quantity: at most four decimals (qCom)";
|
|
143
123
|
}
|
|
124
|
+
$net = $line['netValueCents'] ?? null;
|
|
125
|
+
if ($net !== null) {
|
|
126
|
+
$withNetValue++;
|
|
127
|
+
if ($net > $line['valueCents']) {
|
|
128
|
+
$details[] = "lines[$index].netValueCents: at most valueCents (vProdLiq is vProd without the IBS/CBS)";
|
|
129
|
+
}
|
|
130
|
+
}
|
|
131
|
+
}
|
|
132
|
+
if ($withNetValue !== 0 && $withNetValue !== count($document['lines'])) {
|
|
133
|
+
$details[] = 'lines: netValueCents on every line or on none (vProdLiqTot sums them all)';
|
|
144
134
|
}
|
|
145
135
|
if ($details !== []) {
|
|
146
136
|
throw ServiceError::invalid('The document does not fit the NF-e layout.', $details);
|
|
@@ -263,10 +253,23 @@ final class DocumentMapper
|
|
|
263
253
|
];
|
|
264
254
|
}
|
|
265
255
|
|
|
266
|
-
/**
|
|
256
|
+
/**
|
|
257
|
+
* From 2027 the IBS/CBS go INSIDE `vProd`, and the price without tax
|
|
258
|
+
* travels in NT 2026.008's `vProdLiq`/`vUnComLiq`/`vProdLiqTot` (source: NT
|
|
259
|
+
* 2026.008 v1.00 itself: from 2027 the IBS, CBS and IS values "deverão ser
|
|
260
|
+
* acrescidos ao valor do produto ou serviço, compondo o valor informado no
|
|
261
|
+
* campo vProd"). A line's `netValueCents` is the engine's `vProdLiq`,
|
|
262
|
+
* written as given; `vUnComLiq` is derived from it as `vUnCom` is from
|
|
263
|
+
* `vProd`, and sped-nfe (5.2.11) sums `vProdLiqTot` from the items. Whether
|
|
264
|
+
* a period puts the tax inside the price is the engine's rate table's
|
|
265
|
+
* call, never a date here.
|
|
266
|
+
*
|
|
267
|
+
* @param array<string, mixed> $line
|
|
268
|
+
*/
|
|
267
269
|
private function line(Make $make, int $item, array $line): void
|
|
268
270
|
{
|
|
269
271
|
$gtin = $line['gtin'] ?? 'SEM GTIN';
|
|
272
|
+
$net = $line['netValueCents'] ?? null;
|
|
270
273
|
$make->tagprod((object) [
|
|
271
274
|
'item' => $item,
|
|
272
275
|
'cProd' => $line['code'],
|
|
@@ -283,6 +286,8 @@ final class DocumentMapper
|
|
|
283
286
|
'uTrib' => $line['unit'],
|
|
284
287
|
'qTrib' => self::quantity($line['quantity']),
|
|
285
288
|
'vUnTrib' => self::unitValue($line['valueCents'], $line['quantity']),
|
|
289
|
+
'vUnComLiq' => $net === null ? null : self::unitValue($net, $line['quantity']),
|
|
290
|
+
'vProdLiq' => $net === null ? null : self::reais($net),
|
|
286
291
|
'vDesc' => $line['discountCents'] > 0 ? self::reais($line['discountCents']) : null,
|
|
287
292
|
'indTot' => 1,
|
|
288
293
|
]);
|
package/src/documents/lines.ts
CHANGED
|
@@ -11,7 +11,10 @@
|
|
|
11
11
|
* taxed item under the class the host passed;
|
|
12
12
|
* - the IBS/CBS group from the line's figures (`vBC`, the nominal rates, the
|
|
13
13
|
* reduction, the amounts), or no group at all where the engine answered
|
|
14
|
-
* `NONE` (MEI, não contribuinte)
|
|
14
|
+
* `NONE` (MEI, não contribuinte);
|
|
15
|
+
* - the net value (`vProdLiq`, NT 2026.008) where the period puts the tax
|
|
16
|
+
* inside the price (from 2027), and no key at all where it does not, so a
|
|
17
|
+
* 2026 document is the one it was before the field existed.
|
|
15
18
|
*
|
|
16
19
|
* What the engine does not know — the product code, NCM, CFOP, unit, the
|
|
17
20
|
* ICMS, PIS and COFINS — arrives per line id from the host. A breakdown line
|
|
@@ -23,7 +26,7 @@ import type { LineIbsCbs, SaleLine } from "../sale/types";
|
|
|
23
26
|
import { FiscalDocumentError } from "./errors";
|
|
24
27
|
|
|
25
28
|
/** Everything a document line needs that the breakdown does not carry. */
|
|
26
|
-
export type LineDetails = Omit<SaleLine, "id" | "quantity" | "valueCents" | "ibsCbs">;
|
|
29
|
+
export type LineDetails = Omit<SaleLine, "id" | "quantity" | "valueCents" | "netValueCents" | "ibsCbs">;
|
|
27
30
|
|
|
28
31
|
const SEGREGATED = new Set<LineTax["source"]>(["GORJETA_EXCLUDED", "INTERMEDIATION_EXCLUDED"]);
|
|
29
32
|
|
|
@@ -57,6 +60,7 @@ export function documentLines(breakdown: TaxBreakdown, details: Readonly<Record<
|
|
|
57
60
|
id: line.lineId,
|
|
58
61
|
quantity: line.quantity,
|
|
59
62
|
valueCents: line.valueCents,
|
|
63
|
+
...(line.netValueCents === null ? {} : { netValueCents: line.netValueCents }),
|
|
60
64
|
ibsCbs: ibsCbsOf(line, breakdown),
|
|
61
65
|
};
|
|
62
66
|
});
|
package/src/sale/types.ts
CHANGED
|
@@ -5,10 +5,14 @@
|
|
|
5
5
|
* Money is integer CENTS, rates integer BASIS POINTS (1 bp = 0.01%) — the
|
|
6
6
|
* engine's conventions (`@12-apps/fiscal/engine`) — and quantities carry at
|
|
7
7
|
* most four decimals. Every field is required; an absent value is `null`,
|
|
8
|
-
* never a missing key, so a host cannot forget one silently. The
|
|
9
|
-
*
|
|
10
|
-
* `referencedDocuments
|
|
11
|
-
*
|
|
8
|
+
* never a missing key, so a host cannot forget one silently. The exceptions
|
|
9
|
+
* are the fields added after version 1 shipped — `operation` and
|
|
10
|
+
* `referencedDocuments` (the return document, FUT-2238), a payment's
|
|
11
|
+
* `linkedTransaction` (NT 2026.006, FUT-2239) and a line's `netValueCents`
|
|
12
|
+
* (NT 2026.008, FUT-4924): they are optional so that a document built before
|
|
13
|
+
* them stays valid and yields the same XML, byte for byte, and `version`
|
|
14
|
+
* stays 1 so that a service image older than a field still reads every
|
|
15
|
+
* document that does not use it.
|
|
12
16
|
*
|
|
13
17
|
* The JSON schema the service validates against is
|
|
14
18
|
* `@12-apps/fiscal/sidecar/schema/sale-for-document.schema.json`; a test keeps
|
|
@@ -167,6 +171,15 @@ export interface SaleLine {
|
|
|
167
171
|
readonly valueCents: number;
|
|
168
172
|
/** `vDesc`. */
|
|
169
173
|
readonly discountCents: number;
|
|
174
|
+
/**
|
|
175
|
+
* `vProdLiq` (NT 2026.008 v1.00): the line's value WITHOUT the IBS/CBS, in a
|
|
176
|
+
* period whose IBS/CBS sit inside `vProd` (from 2027) — the engine's
|
|
177
|
+
* `LineTax.netValueCents`, written as given, at most `valueCents`. The
|
|
178
|
+
* service derives `vUnComLiq` (this over `quantity`, ten decimals) and
|
|
179
|
+
* `vProdLiqTot` (the sum over the lines). Absent or `null`: neither is
|
|
180
|
+
* written, as before 2027. Every line carries it or none does.
|
|
181
|
+
*/
|
|
182
|
+
readonly netValueCents?: number | null;
|
|
170
183
|
/** `vTotTrib` (the approximate tax of the transparency law), or `null`. */
|
|
171
184
|
readonly approximateTaxCents: number | null;
|
|
172
185
|
/** `infAdProd`. */
|
package/src/sidecar/types.ts
CHANGED
|
@@ -252,9 +252,7 @@ export interface SidecarErrorBody {
|
|
|
252
252
|
readonly class: SidecarErrorClass;
|
|
253
253
|
/**
|
|
254
254
|
* The SEFAZ `cStat` when SEFAZ answered (always for `REJECTED`); for
|
|
255
|
-
* `INVALID`, a named code where one applies (`
|
|
256
|
-
* a document issued on or after 2027-01-01, which needs NT 2026.008's
|
|
257
|
-
* `vProdLiq`; `RETURN_ON_NFCE`: a return asked of an NFC-e, which has no
|
|
255
|
+
* `INVALID`, a named code where one applies (`RETURN_ON_NFCE`: a return asked of an NFC-e, which has no
|
|
258
256
|
* return purpose; `RETURN_NEEDS_REFERENCE`: a return quoting no
|
|
259
257
|
* `referencedDocuments`); `null` otherwise.
|
|
260
258
|
*/
|