{"_id":"@araitek/smartdocjs","_rev":"5-ff8d1159bee2a4ee5a8ee243efae5011","name":"@araitek/smartdocjs","dist-tags":{"latest":"0.3.0"},"versions":{"0.1.0":{"name":"@araitek/smartdocjs","version":"0.1.0","keywords":["smartdoc","facturacion-electronica","paraguay","dnit","set","sifen","factura-electronica"],"license":"MIT","_id":"@araitek/smartdocjs@0.1.0","maintainers":[{"name":"enriquepy","email":"enjugoac@gmail.com"}],"homepage":"https://www.smartdoc.com.py/","dist":{"shasum":"a2490b3edf34661f4cb4ea684010ce5eb6590d48","tarball":"https://registry.npmjs.org/@araitek/smartdocjs/-/smartdocjs-0.1.0.tgz","fileCount":233,"integrity":"sha512-1pbUsyJR55CA5Hf/MtWJFLE6HUIhjnKpYly3DCUBmRpTM5LcJ0iR48SA5zKYRzRA3ouQaG5uDetDLw0ZLuHDCA==","signatures":[{"sig":"MEQCIACHYxUtd1QnZRCPgBKf2TyebvZh3z/eXXXCU+UXOOXBAiBvQia02rJHmU5L+6fnNREDdJ594gOXIkuz7ld6Ow1pCw==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":1324199},"main":"./dist/cjs/index.js","type":"module","types":"./dist/esm/index.d.ts","module":"./dist/esm/index.js","engines":{"node":">=18"},"exports":{".":{"types":"./dist/esm/index.d.ts","import":"./dist/esm/index.js","require":"./dist/cjs/index.js"},"./package.json":"./package.json"},"gitHead":"48a176ff5e6c8524b0b0fa8fb0f139e7aa762751","scripts":{"e2e":"npm run build && node --test \"test/e2e/*.test.mjs\"","test":"npm run build && node --test \"test/*.test.mjs\"","build":"npm run build:esm && npm run build:cjs && node scripts/finish-build.mjs","clean":"node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\"","docs:dev":"npm run docs:reference && vitepress dev docs","build:cjs":"tsc -p tsconfig.cjs.json","build:esm":"tsc -p tsconfig.build.json","test:only":"node --test \"test/*.test.mjs\"","typecheck":"tsc -p tsconfig.json --noEmit","docs:build":"npm run docs:reference && vitepress build docs","embed-data":"node scripts/embed-data.mjs","docs:preview":"vitepress preview docs","sync-version":"node scripts/sync-version.mjs","docs:reference":"node scripts/build-reference.mjs","prepublishOnly":"npm run clean && npm run build"},"_npmUser":{"name":"enriquepy","email":"enjugoac@gmail.com"},"_npmVersion":"10.9.8","description":"SDK de Node.js para SmartDoc — facturación electrónica en Paraguay (DNIT/SIFEN)","directories":{},"_nodeVersion":"22.23.2","publishConfig":{"access":"public","registry":"https://registry.npmjs.org"},"_hasShrinkwrap":false,"devDependencies":{"typedoc":"^0.28.20","vitepress":"^1.6.4","typescript":"^5.7.0","@types/node":"^22.10.0","typedoc-plugin-markdown":"^4.12.0"},"_npmOperationalInternal":{"tmp":"tmp/smartdocjs_0.1.0_1786969652292_0.8537256783788194","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"@araitek/smartdocjs","version":"0.1.1","keywords":["smartdoc","facturacion-electronica","paraguay","dnit","set","sifen","factura-electronica"],"license":"MIT","_id":"@araitek/smartdocjs@0.1.1","maintainers":[{"name":"enriquepy","email":"enjugoac@gmail.com"}],"homepage":"https://www.smartdoc.com.py/","dist":{"shasum":"0d55182edbedc0f5e0b60df77552d0a386a24f8a","tarball":"https://registry.npmjs.org/@araitek/smartdocjs/-/smartdocjs-0.1.1.tgz","fileCount":233,"integrity":"sha512-VGgzgA+MunSwJ/XB9MmrL908H9VErGHoMvQSqlGAKlRIfX6JAQvwU8rSUJH4mczXrL1xT+JqqMjItc/8CsXkaA==","signatures":[{"sig":"MEUCIQCZON+wW4vC113KBkwJDEf6IZYeBiNrl3PJUcsoU/G6XAIgKbxutuzKMxxBgVfJgsCs4ICTBum6GNO+MFrFPaa/aFA=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":1324498},"main":"./dist/cjs/index.js","type":"module","types":"./dist/esm/index.d.ts","module":"./dist/esm/index.js","engines":{"node":">=18"},"exports":{".":{"types":"./dist/esm/index.d.ts","import":"./dist/esm/index.js","require":"./dist/cjs/index.js"},"./package.json":"./package.json"},"gitHead":"aebf3908c4bbf3e087986979c28b09bbeadb73ae","scripts":{"e2e":"npm run build && node --test test/e2e/*.test.mjs","test":"npm run build && node --test test/*.test.mjs","build":"npm run build:esm && npm run build:cjs && node scripts/finish-build.mjs","clean":"node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\"","docs:dev":"npm run docs:reference && vitepress dev docs","build:cjs":"tsc -p tsconfig.cjs.json","build:esm":"tsc -p tsconfig.build.json","test:only":"node --test test/*.test.mjs","typecheck":"tsc -p tsconfig.json --noEmit","docs:build":"npm run docs:reference && vitepress build docs","embed-data":"node scripts/embed-data.mjs","docs:preview":"vitepress preview docs","sync-version":"node scripts/sync-version.mjs","docs:reference":"node scripts/build-reference.mjs","prepublishOnly":"npm run clean && npm run build"},"_npmUser":{"name":"GitLab CI/CD","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"gitlab","oidcConfigId":"oidc:3e3a3cb1-0db0-47df-813d-15ee8fdba252"}},"_npmVersion":"12.0.2","description":"SDK de Node.js para SmartDoc — facturación electrónica en Paraguay (DNIT/SIFEN)","directories":{},"_nodeVersion":"22.23.2","publishConfig":{"access":"public","registry":"https://registry.npmjs.org"},"_hasShrinkwrap":false,"devDependencies":{"typedoc":"^0.28.20","vitepress":"^1.6.4","typescript":"^5.7.0","@types/node":"^22.10.0","typedoc-plugin-markdown":"^4.12.0"},"_npmOperationalInternal":{"tmp":"tmp/smartdocjs_0.1.1_1786971017243_0.22706461331233085","host":"s3://npm-registry-packages-npm-production"}},"0.1.2":{"name":"@araitek/smartdocjs","version":"0.1.2","keywords":["smartdoc","facturacion-electronica","paraguay","dnit","set","sifen","factura-electronica"],"license":"MIT","_id":"@araitek/smartdocjs@0.1.2","maintainers":[{"name":"enriquepy","email":"enjugoac@gmail.com"}],"homepage":"https://www.smartdoc.com.py/","dist":{"shasum":"ac3566c27919d6facb2c59f9a923fb5069325f8f","tarball":"https://registry.npmjs.org/@araitek/smartdocjs/-/smartdocjs-0.1.2.tgz","fileCount":233,"integrity":"sha512-hftBT9wjCYTtN7Qe9cxWopvtmizQJR5Y+vh51glu5Tu5VdBgT2L0yf7HnJC8t6rpdntIOzsaHTV7vCD5iAKZYQ==","signatures":[{"sig":"MEYCIQCq9bkOhVZ+HWSd/jlGe+9Gjd7fJuLP/UhN1aTId6IwewIhAIEz33fGCihJPC8v3v30KLg0C1Nnv4A7F1ypgWAh+w0d","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":1324992},"main":"./dist/cjs/index.js","type":"module","types":"./dist/esm/index.d.ts","module":"./dist/esm/index.js","engines":{"node":">=18"},"exports":{".":{"types":"./dist/esm/index.d.ts","import":"./dist/esm/index.js","require":"./dist/cjs/index.js"},"./package.json":"./package.json"},"gitHead":"89cadd25cb984f75eb723e7cb849ac8a2594c6e1","scripts":{"e2e":"npm run build && node --test test/e2e/*.test.mjs","test":"npm run build && node --test test/*.test.mjs","build":"npm run build:esm && npm run build:cjs && node scripts/finish-build.mjs","clean":"node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\"","docs:dev":"npm run docs:reference && vitepress dev docs","build:cjs":"tsc -p tsconfig.cjs.json","build:esm":"tsc -p tsconfig.build.json","test:only":"node --test test/*.test.mjs","typecheck":"tsc -p tsconfig.json --noEmit","docs:build":"npm run docs:reference && vitepress build docs","embed-data":"node scripts/embed-data.mjs","docs:preview":"vitepress preview docs","sync-version":"node scripts/sync-version.mjs","docs:reference":"node scripts/build-reference.mjs","prepublishOnly":"npm run clean && npm run build"},"_npmUser":{"name":"GitLab CI/CD","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"gitlab","oidcConfigId":"oidc:3e3a3cb1-0db0-47df-813d-15ee8fdba252"}},"_npmVersion":"12.0.2","description":"SDK de Node.js para SmartDoc — facturación electrónica en Paraguay (DNIT/SIFEN)","directories":{},"_nodeVersion":"22.23.2","publishConfig":{"access":"public","registry":"https://registry.npmjs.org"},"_hasShrinkwrap":false,"devDependencies":{"typedoc":"^0.28.20","vitepress":"^1.6.4","typescript":"^5.7.0","@types/node":"^22.10.0","typedoc-plugin-markdown":"^4.12.0"},"_npmOperationalInternal":{"tmp":"tmp/smartdocjs_0.1.2_1786978892903_0.7695821384932249","host":"s3://npm-registry-packages-npm-production"}},"0.2.0":{"name":"@araitek/smartdocjs","version":"0.2.0","keywords":["smartdoc","facturacion-electronica","paraguay","dnit","set","sifen","factura-electronica"],"license":"MIT","_id":"@araitek/smartdocjs@0.2.0","maintainers":[{"name":"enriquepy","email":"enjugoac@gmail.com"}],"homepage":"https://www.smartdoc.com.py/","dist":{"shasum":"d419b4893093868854e49abf1589b15eb8e412ab","tarball":"https://registry.npmjs.org/@araitek/smartdocjs/-/smartdocjs-0.2.0.tgz","fileCount":233,"integrity":"sha512-jgB7MAU1DsEG53KnlSEmdh50PSuTJgpS5TdBjS9y255Sav2zcqsUDfWELrM6svUw01hmDtYXSK++tCFbIRpFEA==","signatures":[{"sig":"MEUCIACXZLOWVpeyszk1m8ziZgx0SGAD4WlqGrqkPPrFUhZfAiEAmGx0MsNG1DJF25Nbmma+v+vzXgE9MxX8KyMw7IT51kU=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":1327730},"main":"./dist/cjs/index.js","type":"module","types":"./dist/esm/index.d.ts","module":"./dist/esm/index.js","engines":{"node":">=18"},"exports":{".":{"types":"./dist/esm/index.d.ts","import":"./dist/esm/index.js","require":"./dist/cjs/index.js"},"./package.json":"./package.json"},"gitHead":"86221866992eb602fb1ba27dda9a840ff5c34d76","scripts":{"e2e":"npm run build && node --test test/e2e/*.test.mjs","test":"npm run build && node --test test/*.test.mjs","build":"npm run build:esm && npm run build:cjs && node scripts/finish-build.mjs","clean":"node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\"","docs:dev":"npm run docs:reference && vitepress dev docs","build:cjs":"tsc -p tsconfig.cjs.json","build:esm":"tsc -p tsconfig.build.json","test:only":"node --test test/*.test.mjs","typecheck":"tsc -p tsconfig.json --noEmit","docs:build":"npm run docs:reference && vitepress build docs","embed-data":"node scripts/embed-data.mjs","docs:preview":"vitepress preview docs","sync-version":"node scripts/sync-version.mjs","docs:reference":"node scripts/build-reference.mjs","prepublishOnly":"npm run clean && npm run build"},"_npmUser":{"name":"GitLab CI/CD","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"gitlab","oidcConfigId":"oidc:3e3a3cb1-0db0-47df-813d-15ee8fdba252"}},"_npmVersion":"12.0.2","description":"SDK de Node.js para SmartDoc — facturación electrónica en Paraguay (DNIT/SIFEN)","directories":{},"_nodeVersion":"22.23.2","publishConfig":{"access":"public","registry":"https://registry.npmjs.org"},"_hasShrinkwrap":false,"devDependencies":{"typedoc":"^0.28.20","vitepress":"^1.6.4","typescript":"^5.7.0","@types/node":"^22.10.0","typedoc-plugin-markdown":"^4.12.0"},"_npmOperationalInternal":{"tmp":"tmp/smartdocjs_0.2.0_1788787293413_0.011885141748933403","host":"s3://npm-registry-packages-npm-production"}},"0.3.0":{"name":"@araitek/smartdocjs","version":"0.3.0","description":"SDK de Node.js para SmartDoc — facturación electrónica en Paraguay (DNIT/SIFEN)","keywords":["smartdoc","facturacion-electronica","paraguay","dnit","set","sifen","factura-electronica"],"license":"MIT","homepage":"https://www.smartdoc.com.py/","type":"module","engines":{"node":">=18"},"main":"./dist/cjs/index.js","module":"./dist/esm/index.js","types":"./dist/esm/index.d.ts","exports":{".":{"types":"./dist/esm/index.d.ts","import":"./dist/esm/index.js","require":"./dist/cjs/index.js"},"./package.json":"./package.json"},"publishConfig":{"access":"public","registry":"https://registry.npmjs.org"},"scripts":{"build":"npm run build:esm && npm run build:cjs && node scripts/finish-build.mjs","build:esm":"tsc -p tsconfig.build.json","build:cjs":"tsc -p tsconfig.cjs.json","clean":"node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\"","typecheck":"tsc -p tsconfig.json --noEmit","embed-data":"node scripts/embed-data.mjs","test":"npm run build && node --test test/*.test.mjs","test:only":"node --test test/*.test.mjs","e2e":"npm run build && node --test test/e2e/*.test.mjs","prepublishOnly":"npm run clean && npm run build","docs:reference":"node scripts/build-reference.mjs","docs:dev":"npm run docs:reference && vitepress dev docs","docs:build":"npm run docs:reference && vitepress build docs","docs:preview":"vitepress preview docs","sync-version":"node scripts/sync-version.mjs"},"devDependencies":{"@types/node":"^22.10.0","typedoc":"^0.28.20","typedoc-plugin-markdown":"^4.12.0","typescript":"^5.7.0","vitepress":"^1.6.4"},"gitHead":"aa8f9cf809914a950ed4f097c9704ed202c7888c","_id":"@araitek/smartdocjs@0.3.0","_nodeVersion":"22.23.2","_npmVersion":"12.0.2","dist":{"integrity":"sha512-1Wo6TrChX6qUfuXKUFcP3pNByxE1UdZBfac0TG/zAafU3RcOIHpLngVHz3Qag24zNdbJUQu1cBFyWrKdBMGs6w==","shasum":"6b081ba54b68a7d975934515ab0c9984325b1714","tarball":"https://registry.npmjs.org/@araitek/smartdocjs/-/smartdocjs-0.3.0.tgz","fileCount":233,"unpackedSize":1332811,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQD1Fce8MPNVvKTylL6cZk0IbbdA9ID1RTIPxmFZFI70wAIhAI1N1oKYPqE24ygqCNdRU+TbDvthAuUeqdQgdjFe+HEV"}]},"_npmUser":{"name":"GitLab CI/CD","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"gitlab","oidcConfigId":"oidc:3e3a3cb1-0db0-47df-813d-15ee8fdba252"}},"directories":{},"maintainers":[{"name":"enriquepy","email":"enjugoac@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/smartdocjs_0.3.0_1789046551337_0.17168497049812004"},"_hasShrinkwrap":false}},"time":{"created":"2026-08-17T12:27:31.818Z","modified":"2026-09-10T13:22:31.686Z","0.1.0":"2026-08-17T12:27:32.449Z","0.1.1":"2026-08-17T12:50:17.391Z","0.1.2":"2026-08-17T15:01:33.061Z","0.2.0":"2026-09-07T13:21:33.583Z","0.3.0":"2026-09-10T13:22:31.481Z"},"license":"MIT","homepage":"https://www.smartdoc.com.py/","keywords":["smartdoc","facturacion-electronica","paraguay","dnit","set","sifen","factura-electronica"],"description":"SDK de Node.js para SmartDoc — facturación electrónica en Paraguay (DNIT/SIFEN)","maintainers":[{"name":"enriquepy","email":"enjugoac@gmail.com"}],"readme":"# @araitek/smartdocjs\n\nSDK de Node.js y TypeScript para [SmartDoc](https://www.smartdoc.com.py/), el sistema\nde facturación electrónica para Paraguay. Cubre la API pública v2 y la recepción\nde sus webhooks.\n\nDocumentación completa: <https://www.smartdoc.com.py/docs/node/>\n\n## Instalación\n\n```bash\nnpm install @araitek/smartdocjs\n```\n\nRequiere Node.js 18 o superior. **No tiene dependencias de terceros.**\n\nFunciona igual con ESM y con CommonJS, y trae sus propios tipos:\n\n```ts\nimport { Client, Item, Recipient } from '@araitek/smartdocjs';       // ESM / TypeScript\n```\n\n```js\nconst { Client, Item, Recipient } = require('@araitek/smartdocjs');  // CommonJS\n```\n\n## Emitir un documento\n\n```ts\nimport { Client, Item, Recipient } from '@araitek/smartdocjs';\n\nconst sd = new Client();          // toma la API Key del entorno\n\nlet factura = await sd.invoices.create({\n  recipient: Recipient.entity({\n    ruc: '80012345-1',\n    socialName: 'Cliente Ejemplo S.A.',\n    email: 'facturas@cliente.com.py',\n  }),\n  items: [\n    new Item('Consultoría de octubre', { quantity: 1, unitAmount: 1_100_000 }),\n  ],\n});\n\nfactura = await sd.invoices.waitUntilFinal(factura.id);\nconsole.log(factura.status, factura.cdc);\n```\n\nEl SDK completa los datos del emisor, la clave de idempotencia y el desglose de\nIVA. En Paraguay el IVA va **incluido** en el precio: sobre ese ejemplo emite\n1.000.000 de base gravada y 100.000 de IVA.\n\nEstán los seis tipos de documento electrónico, cada uno con sus acciones:\n\n| Recurso | Documento |\n|---|---|\n| `sd.invoices` | Factura |\n| `sd.receipts` | Recibo |\n| `sd.creditNotes` | Nota de crédito |\n| `sd.debitNotes` | Nota de débito |\n| `sd.remissionNotes` | Nota de remisión |\n| `sd.autoInvoices` | Autofactura |\n\n## Configuración\n\nLa API Key sale de `SMARTDOC_API_KEY`. La URL apunta a la instancia de\nproducción; solo hace falta `SMARTDOC_BASE_URL` con una instancia propia.\n\n```bash\nexport SMARTDOC_API_KEY=\"pk_...\"\n```\n\nCon más de un establecimiento o punto de expedición hay que decir cuál, porque el\nSDK no elige por su cuenta:\n\n```ts\nconst sd = new Client({ establishment: '001', dispatchPoint: '001' });\n```\n\no por llamada, si emitís desde varias sucursales:\n\n```ts\nawait sd.invoices.create({\n  recipient,\n  items,\n  establishment: '002',\n  dispatchPoint: '001',\n});\n```\n\n## Idempotencia\n\nCada `create()` va con una clave nueva que genera el SDK, así que reintentar\nnunca emite dos veces. Si preferís que la clave venga de tu sistema:\n\n```ts\nconst factura = await sd.invoices.create({\n  recipient,\n  items,\n  idempotencyKey: `venta-${venta.id}`,\n});\n```\n\nRepetir la llamada con la misma clave devuelve el documento ya creado.\n\n## Errores\n\n```ts\nimport { RateLimitError, ServerError, ValidationError } from '@araitek/smartdocjs';\n\ntry {\n  await sd.invoices.create({ recipient, items });\n} catch (error) {\n  if (error instanceof ValidationError) {\n    // datos mal armados; no sirve reintentar\n  } else if (error instanceof RateLimitError || error instanceof ServerError) {\n    // transitorio; el SDK ya reintentó\n  } else {\n    throw error;\n  }\n}\n```\n\nTodos heredan de `SmartDocError`. Las validaciones que el SDK puede hacer sin red\n—largos, catálogos cerrados, campos condicionales— fallan antes de salir, con el\nmensaje de qué corregir.\n\n## Webhooks\n\nEn producción conviene escuchar los eventos en vez de hacer polling.\n\n```ts\nimport express from 'express';\nimport { Event, Webhooks } from '@araitek/smartdocjs';\n\nconst webhooks = new Webhooks({ secret: process.env.SMARTDOC_WEBHOOK_SECRET });\n\nwebhooks.on(Event.INVOICE_APPROVED, async (evento) => {\n  await marcarAprobada(evento.entityId, evento.cdc);\n});\n\nwebhooks.onAnyError(async (evento) => {\n  await avisar(`${evento.errorCode}: ${evento.errorMessage}`);\n});\n\nconst app = express();\napp.post(\n  '/webhooks/smartdoc',\n  express.raw({ type: 'application/json' }),   // la firma va sobre el cuerpo crudo\n  webhooks.expressHandler(),\n);\n```\n\nHay adaptadores para Express y Fastify, y uno con `Request`/`Response` estándar\npara Hono, Next.js, Deno y Bun. Para desarrollo, `webhooks.serve({ port: 3000 })`\nlevanta un servidor mínimo.\n\nEl SDK verifica la firma HMAC sobre el cuerpo crudo, descarta las entregas\nrepetidas y rechaza las que llegan fuera de la ventana de tolerancia.\n\n## Catálogos y geografía\n\nLos catálogos de SIFEN vienen validados. Un valor inválido falla antes de salir a\nla red:\n\n```ts\nimport { Iva, SaleType, geo } from '@araitek/smartdocjs';\n\nSaleType.CASH;                 // 'cash'\nIva.TEN;                       // '10_percent'\nSaleType.coerce('Contado');    // ValidationError: ¿Quisiste decir \"cash\"?\n\ngeo.findCity('Asunción');      // resuelve departamento, distrito y ciudad\n```\n\n## Desarrollo\n\n```bash\nnpm install\nnpm run build        # ESM + CJS + tipos\nnpm test             # compila y corre la suite\nnpm run typecheck\nnpm run docs:dev     # el sitio de documentación, en local\n```\n\nLos tests de integración corren contra una instancia real y se saltean si no hay\ncredenciales. Copiá `.env.example` a `.env` y completalo:\n\n```bash\nnpm run e2e\n```\n\nConviene apuntarlos a un contribuyente demo: ahí SmartDoc simula la respuesta de\nla DNIT en vez de enviarla.\n\nEn `examples/` hay tres programas completos —emitir una factura, recibir webhooks\ny el ciclo entero incluido el camino de error—. Para correrlos desde el repo, con\nel paquete construido:\n\n```bash\nnpm link                              # deja @araitek/smartdocjs resoluble\nnode examples/01-emitir-factura.mjs\n```\n\n## Licencia\n\nMIT.\n","readmeFilename":"README.md"}