Skip to content

Commit c30eb8b

Browse files
andrekutianskiandrekutianski
committed
feat(tax): implementa recursos de cálculo de impostos e códigos auxiliares
Adiciona suporte completo ao Motor de Cálculo de Tributos (calculo-impostos-v1) com dois novos resources no SDK: taxCalculation e taxCodes. ## Novos Resources ### TaxCalculationResource (nfe.taxCalculation) - calculate(tenantId, request) → CalculateResponse - Calcula ICMS, ICMS-ST, PIS, COFINS, IPI, II para operações com produtos - Validação de tenantId e campos obrigatórios do request - URL encoding e trim do tenantId - Endpoint: POST /tax-rules/{tenantId}/engine/calculate (api.nfse.io) ### TaxCodesResource (nfe.taxCodes) - listOperationCodes() — códigos de natureza de operação - listAcquisitionPurposes() — finalidades de aquisição - listIssuerTaxProfiles() — perfis fiscais do emissor - listRecipientTaxProfiles() — perfis fiscais do destinatário - Paginação via pageIndex/pageCount (1-based, difere do OData $skip/$top) - Endpoints: GET /tax-codes/* (api.nfse.io) ## Tipos Adicionados (src/core/types.ts) - Enums: TaxOperationType, TaxOrigin, TaxCalcTaxRegime - Componentes tributários: TaxIcms (~45 campos), TaxIcmsUfDest, TaxPis, TaxCofins, TaxIpi, TaxIi - Request: CalculateRequest, CalculateRequestIssuer/Recipient, CalculateItemRequest - Response: CalculateResponse, CalculateItemResponse - Códigos: TaxCode, TaxCodePaginatedResponse, TaxCodeListOptions - Nota: TaxCalcTaxRegime usa PascalCase (RealProfit) para evitar conflito com o TaxRegime existente (LucroReal) das notas de serviço ## Integração no NfeClient - Lazy getters: nfe.taxCalculation e nfe.taxCodes - Ambos usam getCteHttpClient() (api.nfse.io) com resolveDataApiKey() - Exports públicos adicionados em src/index.ts ## Testes (38 novos testes) - tax-calculation.test.ts: 13 testes (calculate, validação, erros) - tax-codes.test.ts: 15 testes (4 métodos, paginação, erros) - tax-types.test.ts: 10 testes (verificação de tipos compile-time + runtime) ## Documentação - README.md: seções Cálculo de Impostos e Códigos Auxiliares com exemplos - docs/API.md: referência completa (métodos, parâmetros, tipos, erros) - examples/tax-calculation.js: exemplo completo com listagem e cálculo - examples/README.md: entrada do novo exemplo ## Arquivos Modificados - src/core/types.ts (+439 linhas) - src/core/client.ts (imports, cache fields, lazy getters) - src/core/resources/index.ts (exports) - src/index.ts (type re-exports, resource exports) - openapi/spec/calculo-impostos-v1.yaml (host field) - src/generated/*.ts (timestamps da regeneração) Ref: openspec/changes/implement-calculo-impostos (30/30 tasks)
1 parent 0f5cd51 commit c30eb8b

22 files changed

Lines changed: 1931 additions & 8 deletions

‎README.md‎

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -634,6 +634,59 @@ console.log('Situação Cadastral:', result.status);
634634

635635
> **Nota:** A API de Consulta CPF usa um host separado (`naturalperson.api.nfe.io`). Você pode configurar uma chave API específica com `dataApiKey`, ou o SDK usará `apiKey` como fallback.
636636
637+
#### 🧮 Cálculo de Impostos (`nfe.taxCalculation`)
638+
639+
Calcular todos os tributos aplicáveis (ICMS, ICMS-ST, PIS, COFINS, IPI, II) para operações com produtos usando o Motor de Cálculo de Tributos:
640+
641+
```typescript
642+
// Calcular impostos de uma operação de venda
643+
const resultado = await nfe.taxCalculation.calculate('tenant-id', {
644+
operationType: 'Outgoing',
645+
issuer: { state: 'SP', taxRegime: 'RealProfit' },
646+
recipient: { state: 'RJ' },
647+
items: [{
648+
id: 'item-1',
649+
operationCode: 121,
650+
origin: 'National',
651+
ncm: '61091000',
652+
quantity: 10,
653+
unitAmount: 100.00
654+
}]
655+
});
656+
657+
for (const item of resultado.items ?? []) {
658+
console.log(`Item ${item.id}: CFOP ${item.cfop}`);
659+
console.log(` ICMS: CST=${item.icms?.cst}, valor=${item.icms?.vICMS}`);
660+
console.log(` PIS: CST=${item.pis?.cst}, valor=${item.pis?.vPIS}`);
661+
console.log(` COFINS: CST=${item.cofins?.cst}, valor=${item.cofins?.vCOFINS}`);
662+
}
663+
```
664+
665+
> **Nota:** A API de Cálculo de Impostos usa o host `api.nfse.io`. Configure `dataApiKey` para uma chave específica, ou o SDK usará `apiKey` como fallback.
666+
667+
#### 📋 Códigos Auxiliares de Impostos (`nfe.taxCodes`)
668+
669+
Consultar tabelas de referência necessárias para o cálculo de impostos:
670+
671+
```typescript
672+
// Listar códigos de operação (natureza de operação)
673+
const codigos = await nfe.taxCodes.listOperationCodes({ pageIndex: 1, pageCount: 20 });
674+
for (const cod of codigos.items ?? []) {
675+
console.log(`${cod.code} - ${cod.description}`);
676+
}
677+
678+
// Listar finalidades de aquisição
679+
const finalidades = await nfe.taxCodes.listAcquisitionPurposes();
680+
681+
// Listar perfis fiscais do emissor
682+
const perfisEmissor = await nfe.taxCodes.listIssuerTaxProfiles();
683+
684+
// Listar perfis fiscais do destinatário
685+
const perfisDestinatario = await nfe.taxCodes.listRecipientTaxProfiles();
686+
```
687+
688+
> **Nota:** Todas as listagens suportam paginação via `pageIndex` (1-based) e `pageCount` (padrão: 50).
689+
637690
---
638691

639692
### Opções de Configuração

‎docs/API.md‎

Lines changed: 150 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,8 @@ Complete API reference for the NFE.io Node.js SDK v3.
2121
- [Consumer Invoice Query (Consulta CFe-SAT)](#consumer-invoice-query-consulta-cfe-sat)
2222
- [Legal Entity Lookup (Consulta CNPJ)](#legal-entity-lookup-consulta-cnpj)
2323
- [Natural Person Lookup (Consulta CPF)](#natural-person-lookup-consulta-cpf)
24+
- [Tax Calculation (Cálculo de Impostos)](#tax-calculation-cálculo-de-impostos)
25+
- [Tax Codes (Códigos Auxiliares)](#tax-codes-códigos-auxiliares)
2426
- [Types](#types)
2527
- [Error Handling](#error-handling)
2628
- [Advanced Usage](#advanced-usage)
@@ -2301,6 +2303,154 @@ interface NaturalPersonStatusResponse {
23012303
23022304
---
23032305

2306+
### Tax Calculation (Cálculo de Impostos)
2307+
2308+
**Resource:** `nfe.taxCalculation`
2309+
**API Host:** `api.nfse.io`
2310+
**Authentication:** Uses `dataApiKey` (falls back to `apiKey`)
2311+
2312+
Compute all applicable Brazilian taxes (ICMS, ICMS-ST, PIS, COFINS, IPI, II) for product operations using the Tax Calculation Engine (Motor de Cálculo de Tributos).
2313+
2314+
#### `calculate(tenantId: string, request: CalculateRequest): Promise<CalculateResponse>`
2315+
2316+
Submit an operation with issuer, recipient, operation type, and product items to compute per-item tax breakdowns.
2317+
2318+
```typescript
2319+
const result = await nfe.taxCalculation.calculate('tenant-id', {
2320+
operationType: 'Outgoing',
2321+
issuer: { state: 'SP', taxRegime: 'RealProfit' },
2322+
recipient: { state: 'RJ' },
2323+
items: [{
2324+
id: 'item-1',
2325+
operationCode: 121,
2326+
origin: 'National',
2327+
ncm: '61091000',
2328+
quantity: 10,
2329+
unitAmount: 100.00
2330+
}]
2331+
});
2332+
2333+
for (const item of result.items ?? []) {
2334+
console.log(`Item ${item.id}: CFOP ${item.cfop}`);
2335+
console.log(` ICMS CST: ${item.icms?.cst}, value: ${item.icms?.vICMS}`);
2336+
}
2337+
```
2338+
2339+
**Parameters:**
2340+
2341+
| Parameter | Type | Required | Description |
2342+
|-----------|------|----------|-------------|
2343+
| `tenantId` | `string` | Yes | Subscription/account ID that scopes the tax rules |
2344+
| `request` | `CalculateRequest` | Yes | Tax calculation request payload |
2345+
2346+
**Returns:** `CalculateResponse` — Per-item tax breakdowns including CFOP, ICMS, PIS, COFINS, IPI, II.
2347+
2348+
**Throws:**
2349+
- `ValidationError` if `tenantId` is empty
2350+
- `ValidationError` if required fields are missing (issuer, recipient, operationType, items)
2351+
- `AuthenticationError` if API key is invalid (HTTP 401)
2352+
- `BadRequestError` if the API rejects the payload (HTTP 400)
2353+
2354+
#### Types
2355+
2356+
```typescript
2357+
type TaxOperationType = 'Outgoing' | 'Incoming';
2358+
2359+
type TaxOrigin =
2360+
| 'National' | 'ForeignDirectImport' | 'ForeignInternalMarket'
2361+
| 'NationalWith40To70Import' | 'NationalPpb' | 'NationalWithLess40Import'
2362+
| 'ForeignDirectImportWithoutNationalSimilar'
2363+
| 'ForeignInternalMarketWithoutNationalSimilar'
2364+
| 'NationalWithGreater70Import';
2365+
2366+
type TaxCalcTaxRegime =
2367+
| 'NationalSimple' | 'RealProfit' | 'PresumedProfit'
2368+
| 'NationalSimpleSublimitExceeded' | 'IndividualMicroEnterprise' | 'Exempt';
2369+
2370+
interface CalculateRequest {
2371+
collectionId?: string;
2372+
issuer: CalculateRequestIssuer; // required: state, taxRegime
2373+
recipient: CalculateRequestRecipient; // required: state
2374+
operationType: TaxOperationType;
2375+
items: CalculateItemRequest[]; // required: id, operationCode, origin, quantity, unitAmount
2376+
isProductRegistration?: boolean;
2377+
}
2378+
2379+
interface CalculateResponse {
2380+
items?: CalculateItemResponse[]; // per-item: cfop, icms, pis, cofins, ipi, ii, icmsUfDest
2381+
}
2382+
```
2383+
2384+
> See [src/core/types.ts](../src/core/types.ts) for the complete type definitions including all tax component interfaces (TaxIcms, TaxPis, TaxCofins, TaxIpi, TaxIi, TaxIcmsUfDest).
2385+
2386+
---
2387+
2388+
### Tax Codes (Códigos Auxiliares)
2389+
2390+
**Resource:** `nfe.taxCodes`
2391+
**API Host:** `api.nfse.io`
2392+
**Authentication:** Uses `dataApiKey` (falls back to `apiKey`)
2393+
2394+
Paginated listings of auxiliary tax code reference tables needed as inputs for the Tax Calculation Engine.
2395+
2396+
#### `listOperationCodes(options?: TaxCodeListOptions): Promise<TaxCodePaginatedResponse>`
2397+
2398+
List operation codes (natureza de operação) — e.g., 121 = "Venda de mercadoria".
2399+
2400+
```typescript
2401+
const result = await nfe.taxCodes.listOperationCodes({ pageIndex: 1, pageCount: 20 });
2402+
console.log(`Total: ${result.totalCount}, Page ${result.currentPage} of ${result.totalPages}`);
2403+
for (const code of result.items ?? []) {
2404+
console.log(`${code.code} - ${code.description}`);
2405+
}
2406+
```
2407+
2408+
#### `listAcquisitionPurposes(options?: TaxCodeListOptions): Promise<TaxCodePaginatedResponse>`
2409+
2410+
List acquisition purposes (finalidade de aquisição).
2411+
2412+
#### `listIssuerTaxProfiles(options?: TaxCodeListOptions): Promise<TaxCodePaginatedResponse>`
2413+
2414+
List issuer tax profiles (perfil fiscal do emissor).
2415+
2416+
#### `listRecipientTaxProfiles(options?: TaxCodeListOptions): Promise<TaxCodePaginatedResponse>`
2417+
2418+
List recipient tax profiles (perfil fiscal do destinatário).
2419+
2420+
**All methods accept:**
2421+
2422+
| Parameter | Type | Required | Description |
2423+
|-----------|------|----------|-------------|
2424+
| `options.pageIndex` | `number` | No | Page index, 1-based (default: 1) |
2425+
| `options.pageCount` | `number` | No | Items per page (default: 50) |
2426+
2427+
**Returns:** `TaxCodePaginatedResponse` — Paginated list of tax codes.
2428+
2429+
#### Types
2430+
2431+
```typescript
2432+
interface TaxCode {
2433+
code?: string;
2434+
description?: string;
2435+
}
2436+
2437+
interface TaxCodePaginatedResponse {
2438+
items?: TaxCode[];
2439+
currentPage?: number;
2440+
totalPages?: number;
2441+
totalCount?: number;
2442+
}
2443+
2444+
interface TaxCodeListOptions {
2445+
pageIndex?: number;
2446+
pageCount?: number;
2447+
}
2448+
```
2449+
2450+
> See [src/core/types.ts](../src/core/types.ts) for the complete type definitions.
2451+
2452+
---
2453+
23042454
## Types
23052455

23062456
### Core Types

‎examples/README.md‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -165,6 +165,18 @@ Demonstra todos os recursos disponíveis no SDK.
165165
### **jsdoc-intellisense-demo.ts** - IntelliSense Demo
166166
Demonstra autocompletar e tipos do editor.
167167

168+
### **tax-calculation.js** - Cálculo de Impostos 🧮
169+
Demonstra o Motor de Cálculo de Tributos para operações com produtos:
170+
- ✅ Listar códigos de operação e perfis fiscais disponíveis
171+
- ✅ Enviar requisição de cálculo de impostos
172+
- ✅ Inspecionar detalhamento por item (ICMS, PIS, COFINS, IPI, II)
173+
174+
```bash
175+
node examples/tax-calculation.js
176+
```
177+
178+
**Requer**: `NFE_TENANT_ID` no `.env.test` com o ID da subscription/conta.
179+
168180
---
169181

170182
## 📖 Ordem Recomendada de Execução

0 commit comments

Comments
 (0)