@useinvio/nfse-sdk 2.2.0 → 3.1.0

package/JSON_MAPPING.md

@@ -33,8 +33,9 @@ type DpsJsonRequest = {
 
 | Campo | Obrigatorio | Tipo | Descricao |
 | --- | --- | --- | --- |
-| `cnpj` | Sim | `string` | CNPJ do prestador. O SDK remove nao digitos e completa com zeros a esquerda ao montar o `Id` da DPS. |
-| `tpInsc` | Nao | `'1' \| '2' \| string` | Tipo de inscricao no `Id` da DPS. `1` = CPF, `2` = CNPJ. Quando ausente, usa `2`. |
+| `cnpj` | Alternativa a `cpf` | `string` | CNPJ com exatamente 14 digitos, sem pontuacao. Informe exatamente um identificador. |
+| `cpf` | Alternativa a `cnpj` | `string` | CPF com exatamente 11 digitos, sem pontuacao. |
+| `tpInsc` | Nao | `'1' \| '2' \| string` | Legado ignorado. O SDK deriva o tipo do documento: `1` = CPF, `2` = CNPJ. |
 | `cLocEmi` | Sim | `string` | Codigo IBGE do municipio de emissao. |
 | `serie` | Sim | `string` | Serie padrao da DPS. Pode ser sobrescrita por `emissao.serie`. |
 | `opSimpNac` | Sim | `string` | Opcao pelo Simples Nacional, serializada em `prest/regTrib/opSimpNac`. |
@@ -58,7 +59,7 @@ type DpsJsonRequest = {
 | `serie` | Nao | `string` | Serie desta DPS. Quando informado, sobrescreve `prestador.serie` apenas nesta emissao. |
 | `dhEmi` | Nao | `string` | Data e hora da emissao em ISO com offset, por exemplo `2026-06-15T10:30:00-03:00`. Quando ausente, usa a data/hora atual. |
 | `dCompet` | Nao | `string` | Data de competencia no formato `YYYY-MM-DD`. Quando ausente, usa a data de `dhEmi`. |
-| `valores` | Condicional | `Valores` | Valores do servico, descontos e deducoes. Para calcular `vServ`, informe `valores.vServ` ou `valores.vServMoeda` + `valores.cotacao`. |
+| `valores` | Condicional | `Valores` | Valores do servico. Descontos e deducoes ainda nao sao suportados. Para calcular `vServ`, informe `valores.vServ` ou `valores.vServMoeda` + `valores.cotacao`. |
 | `vServ` | Condicional | `string` | Atalho legado para o valor do servico. Usado quando `valores.vServ` nao foi informado. |
 | `vServMoeda` | Condicional | `string` | Atalho legado para valor em moeda estrangeira. Usado com `cotacao` quando `vServ` nao foi informado. |
 | `cotacao` | Condicional | `number` | Atalho legado para cotacao. Usado com `vServMoeda` quando `vServ` nao foi informado. |
@@ -88,7 +89,11 @@ type DpsJsonRequest = {
 Regra condicional: para gerar a DPS, o SDK precisa obter `vServ`. Informe
 `valores.vServ` ou informe o par `valores.vServMoeda` + `valores.cotacao`.
 Os atalhos `emissao.vServ`, `emissao.vServMoeda` e `emissao.cotacao` tambem sao
-aceitos, mas o formato com `valores` e preferencial.
+aceitos. A resolucao e por campo: `valores` prevalece sobre o atalho correspondente, permitindo entradas mistas. A mesma resolucao e usada na validacao e no XML.
+
+No modelo atual, nacional exige reais e proibe moeda/cotacao. Exportacao exige comercio exterior, valor estrangeiro e cotacao, mesmo quando ha `vServ` explicito. Informar somente o valor no bloco `comercioExterior` nao satisfaz essa exigencia.
+
+`vServ` explicito prevalece sobre a conversao. O valor estrangeiro do bloco `comercioExterior` prevalece na tag `comExt/vServMoeda`. Divergencias geram `CURRENCY_BRL_MISMATCH` e `CURRENCY_FOREIGN_MISMATCH` em `warnings`, comparadas em centavos, sem bloquear a emissao. A multiplicacao preserva a precisao original; a serializacao arredonda metade para cima em duas casas, inclusive `comExt.vServMoeda`. Valores de servico que arredondam para zero ou excedem 15 digitos inteiros sao rejeitados.
 
 ## `emissao.servico`
 
@@ -107,12 +112,12 @@ aceitos, mas o formato com `valores` e preferencial.
 | `NIF` | Nao | `string` | Numero de identificacao fiscal estrangeiro. |
 | `cNaoNIF` | Nao | `string` | Motivo/codigo de nao informacao do NIF. |
 | `xNome` | Sim, se `tomador` existir | `string` | Nome ou razao social do tomador. |
-| `end` | Nao | `Endereco` | Endereco. Veja `Endereco` abaixo. |
+| `end` | Sim, se `tomador` existir | `Endereco` | Endereco. Veja `Endereco` abaixo. |
 | `fone` | Nao | `string` | Telefone. |
 | `email` | Nao | `string` | Email. |
 
 Quando `tomador` for informado, use exatamente um identificador entre `CNPJ`,
-`CPF`, `NIF` e `cNaoNIF`.
+`CPF`, `NIF` e `cNaoNIF`. Nacional exige CPF/CNPJ e `endNac`; exterior exige NIF ou `cNaoNIF` (`1`/`2`) e `endExt`. Omitir todo o tomador continua permitido localmente.
 
 ### `Endereco`
 
@@ -176,7 +181,7 @@ Regras adicionais:
 | `pAliqCofins` | Nao | `string` | Aliquota de COFINS. Serializada com duas casas decimais. |
 | `vPis` | Nao | `string` | Valor de PIS. Serializado com duas casas decimais. |
 | `vCofins` | Nao | `string` | Valor de COFINS. Serializado com duas casas decimais. |
-| `tpRetPisCofins` | Nao | `string` | Tipo de retencao de PIS/COFINS. |
+| `tpRetPisCofins` | Nao | `string` | Tipo de retencao de PIS/COFINS, codigo de `0` a `9`. |
 
 ## `tribNac`
 
@@ -203,8 +208,8 @@ ainda nao implementa esse bloco.
 
 | Campo | Obrigatorio | Tipo | Descricao |
 | --- | --- | --- | --- |
-| `cObra` | Nao | `string` | Codigo da obra. |
-| `inscImobFisc` | Nao | `string` | Inscricao imobiliaria fiscal. |
+| `cObra` | Sim, se `obra` existir | `string` | Codigo da obra, 1 a 30 caracteres. |
+| `inscImobFisc` | Nao | `string` | Inscricao imobiliaria fiscal, 1 a 30 caracteres; serializada antes de `cObra`. |
 | `cCM` | Nao suportado | `string` | Campo legado bloqueado por validacao; nao existe como filho de `obra` no XSD v1.01. |
 
 ## `evento`
@@ -216,8 +221,7 @@ ainda nao implementa esse bloco.
 
 ## `totTrib`
 
-`totTrib` e um `xs:choice` no XSD: informe exatamente **um** dos quatro grupos
-abaixo. A SDK rejeita zero ou mais de um grupo preenchido.
+`totTrib` e um `xs:choice` no XSD. O validador JSON atual restringe a modalidade por regime: nao optante (`1`) exige os tres `pTotTribFed/Est/Mun`; MEI (`2`) exige somente `indTotTrib="0"`; ME/EPP (`3`) exige somente `pTotTribSN`. Misturas e grupos incompletos sao rejeitados.
 
 | Campo | Obrigatorio | Tipo | Descricao |
 | --- | --- | --- | --- |
@@ -227,19 +231,28 @@ abaixo. A SDK rejeita zero ou mais de um grupo preenchido.
 | `pTotTribFed` | Condicional | `string` | Percentual aproximado de tributos federais. Serializado com duas casas decimais. |
 | `pTotTribEst` | Condicional | `string` | Percentual aproximado de tributos estaduais. Serializado com duas casas decimais. |
 | `pTotTribMun` | Condicional | `string` | Percentual aproximado de tributos municipais. Serializado com duas casas decimais. |
-| `pTotTribSN` | Condicional | `string` | Percentual aproximado de tributos no Simples Nacional. Nao informe quando `prestador.opSimpNac = "1"`. |
-| `indTotTrib` | Condicional | `string` | Indicador oficial para nao informar valor estimado. Use `0` quando nao houver estimativa aproximada. |
+| `pTotTribSN` | Condicional | `string` | Percentual aproximado de tributos no Simples Nacional. Use somente quando `prestador.opSimpNac = "3"`. |
+| `indTotTrib` | Condicional | `string` | Indicador oficial para nao informar valor estimado. Use `0` somente para MEI no modelo JSON atual. |
 
-Informe ao menos uma forma de totalizacao: grupo `vTotTrib*` (Fed+Est+Mun),
-grupo `pTotTrib*` (Fed+Est+Mun), `pTotTribSN` ou `indTotTrib=0`. Ao escolher o
-grupo `vTotTrib*` ou `pTotTrib*`, os tres campos (Fed/Est/Mun) sao obrigatorios.
+Os campos `vTotTrib*` permanecem tipados por compatibilidade, mas nenhum dos regimes aceitos permite essa modalidade no JSON atual.
 
 ## Regras de formatacao
 
 - Valores monetarios sao serializados com duas casas decimais.
 - Aliquotas (`pAliq`, `pAliqPis`, `pAliqCofins`) sao serializadas com duas casas decimais.
 - Percentuais de carga tributaria em `totTrib` sao serializados com duas casas decimais.
-- Campos vazios, `undefined` ou `null` nao geram tags XML opcionais.
+- Campos opcionais ausentes ou `undefined` sao omitidos; `null`, strings vazias e tipos incorretos sao rejeitados antecipadamente.
 - Campos obrigatorios ausentes geram erro antes da DPS ser retornada.
 - `comercioExterior` tem prioridade sobre `comExt` quando os dois forem informados.
 - O XML gerado nos testes e validado contra `schemas/nfse/v1.01/Schemas/1.01/DPS_v1.01.xsd`.
+
+
+## Relatorio e limites estruturais
+
+`validateDpsJsonRequest` retorna `issues` com erros e `warnings` com avisos; somente erros tornam `valid=false`. `normalizedPayload` e uma copia independente com os valores e o alias de comercio exterior resolvidos, mantendo os campos legados. Estruturas invalidas retornam `INVALID_STRUCTURE`, sem acessos que lancem `TypeError`.
+
+`dhEmi` exige data de calendario valida entre 2000 e 2099, segundos sem fracao e offset de horas inteiras de -11:00 a +12:00; `Z` nao e aceito pelo leiaute local. `dCompet` exige data valida no mesmo intervalo de anos. Nao se impoe relacao fiscal entre as datas.
+
+Limites apos arredondamento: valores monetarios, 15 digitos inteiros; ISS, 1; aliquotas PIS/COFINS e `pTotTribSN`, 2; `pTotTribFed/Est/Mun`, 3. Esses limites sao estruturais, nao autorizacao fiscal de aliquotas. Retencoes federais podem ser zero, mas nao negativas.
+
+Dominios de comercio exterior: `mdPrestacao` 0–4; `vincPrest` 0–6 ou 9; `tpMoeda` tres digitos; `mecAFComexP` 00–08; `mecAFComexT` 00–26; `movTempBens` 0–3; `mdic` 0–1. Nao se consultam catalogos externos. Os dois aliases de comercio exterior nao sao combinados.

package/README.md

@@ -40,11 +40,11 @@ O SDK cuida da camada protocolar: certificado A1, montagem de DPS, validações
 - [Enviar evento](#enviar-evento-ex-cancelamento)
 - [Série e número da DPS](#série-e-número-da-dps)
 - [Ambientes](#ambientes)
+- [Agentes de IA e MCP](#agentes-de-ia-e-mcp)
 - [Referência da API](#referência-da-api)
 - [Desenvolvimento](#desenvolvimento)
 - [Publicação no npm](#publicação-no-npm)
-- [Divulgação e exemplos](#divulgação-e-exemplos)
-- [Assistente GPT](#assistente-gpt)
+- [Exemplos](#exemplos)
 
 ---
 
@@ -54,7 +54,7 @@ O SDK cuida da camada protocolar: certificado A1, montagem de DPS, validações
 npm install @useinvio/nfse-sdk
 ```
 
-> Node.js ≥ 20 é obrigatório.
+> Node.js ≥ 20 é obrigatório. Não precisa de `xmllint` nem de binários nativos: a validação XSD roda em WebAssembly.
 
 ---
 
@@ -63,15 +63,15 @@ npm install @useinvio/nfse-sdk
 O caminho mais comum: emitir uma nota a partir de JSON declarativo.
 
 ```ts
-import { emitirNfse, loadPfx, EmitirNotaError } from '@useinvio/nfse-sdk';
+import { emitirNfse, EmitirNotaError, NfseCertificate } from '@useinvio/nfse-sdk';
 
-const pfx = loadPfx('./certificado.pfx', process.env.PFX_PASSWORD!);
+// NFSE_CERT_PATH=./certificado.pfx e NFSE_CERT_PASSWORD=... (veja Certificado A1)
+const certificado = NfseCertificate.fromEnv();
 
 const nota = {
   ambiente: 'restrita' as const,
   prestador: {
     cnpj: '12345678000195',
-    tpInsc: '2',
     cLocEmi: '4106902',
     serie: '1601',
     opSimpNac: '1',
@@ -89,8 +89,7 @@ const nota = {
     dCompet: '2026-06-01',
     valores: { vServ: '1500.00' },
     tributacaoMunicipal: {
-      tribISSQN: '3',
-      cPaisResult: 'BR',
+      tribISSQN: '1',
       tpRetISSQN: '1',
     },
     tributacaoFederal: {
@@ -105,7 +104,7 @@ const nota = {
 };
 
 try {
-  const resultado = await emitirNfse(nota, pfx);
+  const resultado = await emitirNfse(nota, certificado);
   console.log(resultado.chaveAcesso); // chave de 50 dígitos
   console.log(resultado.nfseXml);    // XML autorizado pela SEFIN
 } catch (error) {
@@ -135,8 +134,8 @@ try {
 | Situação | O que usar |
 |---|---|
 | Quer uma API de cliente com `client.invoices.create(...)` | `new NfseClient(...)` |
-| Outro sistema já gera o XML da DPS | `emitirNfse(xmlString, pfx)` |
-| Você monta os dados e quer que a SDK construa o XML | `emitirNfse(notaJson, pfx)` |
+| Outro sistema já gera o XML da DPS | `emitirNfse(xmlString, certificado)` |
+| Você monta os dados e quer que a SDK construa o XML | `emitirNfse(notaJson, certificado)` |
 | Precisa inspecionar ou salvar o XML antes de enviar | `buildDpsFromJson(nota)` |
 | Fluxo customizado (assinar, compactar ou enviar separadamente) | funções de baixo nível |
 
@@ -152,18 +151,14 @@ O cliente usa os mesmos campos do JSON declarativo (`prestador`, `servico` e
 cada chamada.
 
 ```ts
-import { NfseClient } from '@useinvio/nfse-sdk';
+import { NfseCertificate, NfseClient } from '@useinvio/nfse-sdk';
 
 const client = new NfseClient({
   environment: 'sandbox',
-  certificate: {
-    content: process.env.NFSE_CERTIFICATE!, // PFX em base64
-    password: process.env.NFSE_CERTIFICATE_PASSWORD!,
-  },
+  certificate: NfseCertificate.fromEnv(),
   defaults: {
     prestador: {
       cnpj: '12345678000195',
-      tpInsc: '2',
       cLocEmi: '4106902',
       serie: '1601',
       opSimpNac: '1',
@@ -184,9 +179,13 @@ const invoice = await client.invoices.create({
     tomador: {
       CPF: '00000000000',
       xNome: 'Cliente Exemplo',
+      end: {
+        endNac: { cMun: '4106902', CEP: '80010000' },
+        xLgr: 'Rua Exemplo', nro: '100', xBairro: 'Centro',
+      },
     },
     tributacaoMunicipal: {
-      tribISSQN: '3',
+      tribISSQN: '1',
       tpRetISSQN: '1',
     },
     tributacaoFederal: {
@@ -205,9 +204,8 @@ console.log(invoice.nfseXml);
 ```
 
 `environment: 'sandbox'` é alias de `restrita`, e `production` é alias de
-`producao`. O campo `certificate.content` aceita o conteúdo binário do PFX em
-`Buffer` ou o PFX codificado em base64, formato comum para variáveis de
-ambiente.
+`producao`. `certificate` aceita um `NfseCertificate` ou, por compatibilidade,
+`{ content, password }` com o PFX em `Buffer` ou base64.
 
 Para inspecionar a DPS gerada sem assinar nem enviar:
 
@@ -219,31 +217,95 @@ const dps = client.invoices.buildDpsJson({
   emissao: {
     nDPS: '2',
     valores: { vServ: '2500.00' },
+    tributacaoMunicipal: { tribISSQN: '1', tpRetISSQN: '1' },
+    totTrib: { pTotTribFed: '0', pTotTribEst: '0', pTotTribMun: '5' },
   },
 });
 ```
 
 ---
 
+
+### Validacao e compatibilidade
+
+`validateDpsJsonRequest(entrada)` retorna `valid`, `issues` (erros), `warnings` (avisos) e uma copia `normalizedPayload`. Campos opcionais devem ser omitidos ou `undefined`; strings vazias, `null` e tipos incorretos sao rejeitados. Consulte [o mapeamento JSON](JSON_MAPPING.md) para os limites de datas e valores.
+
+Divergencias entre `vServ` e a conversao cambial geram avisos, preservando o valor explicito. O mesmo vale para o valor estrangeiro do bloco de comercio exterior. Todos os valores monetarios sao arredondados para duas casas, inclusive `comExt.vServMoeda`; valores de servico que arredondam para zero sao rejeitados. Leia `warnings` antes da emissao quando quiser apresentar esses avisos ao usuario.
+
+`prepararNota` verifica a vigencia do certificado antes de assinar; `transmitirNotaPreparada` verifica novamente antes do envio. `assertCertificateValidity(certificado, now?)` expoe essa verificacao. A checagem de titularidade continua explicita via `assertCertificateForProvider(certificado, documento, now?)`; o SDK nao resolve representacao fiscal.
+
+O ambiente para JSON segue `options.ambiente` → `request.ambiente` → `restrita`, tanto no XML quanto no destino. XML externo usa `tpAmb` e rejeita uma opcao divergente. Notas preparadas tambem precisam ter o mesmo ambiente no XML assinado e no envio.
+
+`client.invoices.get(chaveAcesso, { ambiente: 'producao' })` permite consultar uma emissao feita com sobrescrita de ambiente. Sem opcao, usa `defaults.ambiente` ou o ambiente do construtor. O cliente nao memoriza o ambiente da ultima emissao.
+
+HTTP 2xx sem XML NFS-e bem formado e chave de 50 digitos consistente gera `EmitirNotaError` com codigo `INVALID_AUTHORIZATION_RESPONSE`, preservando corpo, status e DPS. Isso nao confirma rejeicao fiscal: concilie a emissao antes de reenviar. Nao ha retentativa automatica nem verificacao da assinatura da NFS-e recebida.
+
+Veja [as correcoes e mudancas de comportamento](docs/CORRECOES_EMISSAO.md) e os [payloads nacional e exterior testados](examples/payloads.ts). Os exemplos declaram cenarios ilustrativos; a aplicacao escolhe o enquadramento aplicavel.
+
+> **Migracao para 3.0.0:** esta versao tem breaking changes de validacao e resposta de autorizacao. Leia o guia curto em [CORRECOES_EMISSAO.md](docs/CORRECOES_EMISSAO.md) antes de atualizar.
+
 ## Certificado A1
 
-### A partir de arquivo
+Use `NfseCertificate`. Ele lê o `.pfx`/`.p12` uma vez, mantém a chave privada fora do objeto e descarta a senha e os bytes do arquivo. `console.log(certificado)` e `JSON.stringify(certificado)` mostram só CNPJ/CPF, validade e fingerprint.
+
+### Variáveis de ambiente (recomendado)
+
+```bash
+NFSE_CERT_PATH=./certificado.pfx   # ou NFSE_CERT_BASE64=<PFX em base64>
+NFSE_CERT_PASSWORD=sua-senha       # ou NFSE_CERT_PASSWORD_FILE=/run/secrets/nfse_cert_password
+```
 
 ```ts
-import { loadPfx } from '@useinvio/nfse-sdk';
+import { NfseCertificate } from '@useinvio/nfse-sdk';
 
-const pfx = loadPfx('./certificado.pfx', process.env.PFX_PASSWORD!);
+const certificado = NfseCertificate.fromEnv();
+console.log(certificado.cnpj, certificado.notAfter, certificado.daysUntilExpiry());
 ```
 
-### A partir de buffer (ex.: certificado descriptografado do banco)
+`NFSE_CERT_PASSWORD_FILE` lê a senha de um arquivo, o formato de secrets do Docker e do Kubernetes. Nunca versione o `.pfx` nem a senha.
+
+### Outras origens
 
 ```ts
-import { loadPfxFromBuffer } from '@useinvio/nfse-sdk';
+NfseCertificate.fromFile('./certificado.pfx', senha);
+NfseCertificate.fromBase64(pfxBase64, senha);        // aceita quebras de linha e data: URLs
+NfseCertificate.fromPfx(pfxBuffer, senha);           // ex.: PFX vindo do seu cofre de segredos
+NfseCertificate.fromPem({ key, cert, passphrase });  // par extraído com openssl
+```
+
+### Vários emitentes (multi-tenant)
 
-const pfx = loadPfxFromBuffer(pfxBuffer, password);
+Crie um `NfseCertificate` por emitente e reaproveite-o. Cada certificado tem o próprio agente mTLS, então conexões nunca são compartilhadas entre emitentes. Guarde o PFX cifrado (KMS, Vault, Secrets Manager) e a senha em um segredo separado, e descriptografe só ao criar o objeto.
+
+```ts
+import { assertCertificateForProvider, NfseCertificate } from '@useinvio/nfse-sdk';
+
+const cache = new Map<string, NfseCertificate>();
+
+async function certificadoDoEmitente(cnpj: string): Promise<NfseCertificate> {
+  const cached = cache.get(cnpj);
+  if (cached?.isValidAt()) return cached;
+  const { pfx, senha } = await cofre.buscarCertificado(cnpj); // seu secret manager
+  const certificado = NfseCertificate.fromPfx(pfx, senha);
+  assertCertificateForProvider(certificado, cnpj);
+  cache.set(cnpj, certificado);
+  return certificado;
+}
 ```
 
-O objeto `pfx` retornado contém chave privada e certificado em PEM, pronto para assinar e fazer mTLS.
+### Erros de certificado
+
+Todos lançam `CertificateValidationError` com um `code` estável:
+
+| `code` | Quando |
+|---|---|
+| `CERTIFICATE_INVALID_PASSWORD` | Senha incorreta. |
+| `CERTIFICATE_UNREADABLE` | O conteúdo não é um PFX/PEM válido. |
+| `CERTIFICATE_MISSING`, `CERTIFICATE_PASSWORD_MISSING` | Variáveis de ambiente ausentes em `fromEnv`. |
+| `CERTIFICATE_NOT_YET_VALID`, `CERTIFICATE_EXPIRED` | Fora da vigência. Verificado antes de assinar e antes de enviar. |
+| `CERTIFICATE_HOLDER_MISMATCH` | `assertCertificateForProvider` com CPF/CNPJ diferente do titular. |
+
+> `loadPfx` e `loadPfxFromBuffer` continuam funcionando, mas retornam a chave privada em PEM dentro de um objeto comum. Prefira `NfseCertificate`.
 
 ---
 
@@ -252,21 +314,17 @@ O objeto `pfx` retornado contém chave privada e certificado em PEM, pronto para
 Use quando outro sistema (ERP, sistema legado) já gera o XML da DPS no layout nacional.
 
 ```ts
-import { emitirNfse, loadPfx } from '@useinvio/nfse-sdk';
+import { emitirNfse, NfseCertificate } from '@useinvio/nfse-sdk';
 
-const pfx = loadPfx('./certificado.pfx', process.env.PFX_PASSWORD!);
+const certificado = NfseCertificate.fromEnv();
 
-const resultado = await emitirNfse(dpsXml, pfx, { ambiente: 'restrita' });
+const resultado = await emitirNfse(dpsXml, certificado, { ambiente: 'restrita' });
 
 console.log(resultado.chaveAcesso);
 console.log(resultado.nfseXml);
 ```
 
-> O XML precisa ter o atributo `Id` em `<infDPS>`. Se não tiver, passe `options.dpsId` manualmente.
-
-```ts
-await emitirNfse(dpsXml, pfx, { dpsId: 'DPS0001', ambiente: 'restrita' });
-```
+> O XML precisa ter `Id` valido em `<infDPS>` e `tpAmb` consistente com o destino. `options.dpsId` apenas seleciona a referencia de assinatura; nao corrige um XML incompleto nem dispensa o XSD.
 
 ---
 
@@ -278,13 +336,12 @@ Para a referência completa de campos aceitos no JSON, consulte [JSON_MAPPING.md
 O builder valida formatos e combinações mínimas antes de gerar XML, mas não escolhe códigos fiscais por você. Campos como `tributacaoMunicipal` e `totTrib` precisam ser informados explicita[...]
 
 ```ts
-import { emitirNfse, loadPfx, type DpsJsonRequest } from '@useinvio/nfse-sdk';
+import { emitirNfse, NfseCertificate, type DpsJsonRequest } from '@useinvio/nfse-sdk';
 
 const nota: DpsJsonRequest = {
   ambiente: 'restrita',
   prestador: {
     cnpj: '12345678000195',
-    tpInsc: '2',
     cLocEmi: '4106902',
     serie: '1601',
     opSimpNac: '1',
@@ -302,8 +359,7 @@ const nota: DpsJsonRequest = {
     dCompet: '2026-06-01',
     valores: { vServ: '1500.00' },
     tributacaoMunicipal: {
-      tribISSQN: '3',
-      cPaisResult: 'BR',
+      tribISSQN: '1',
       tpRetISSQN: '1',
     },
     tributacaoFederal: {
@@ -317,8 +373,8 @@ const nota: DpsJsonRequest = {
   },
 };
 
-const pfx = loadPfx('./certificado.pfx', process.env.PFX_PASSWORD!);
-const resultado = await emitirNfse(nota, pfx);
+const certificado = NfseCertificate.fromEnv();
+const resultado = await emitirNfse(nota, certificado);
 ```
 
 > `pTotTribFed`, `pTotTribEst` e `pTotTribMun` são percentuais com duas casas decimais (ex.: `"5.00"`), diferentes das alíquotas com quatro casas (`pAliq`).
@@ -349,7 +405,7 @@ console.log(xml); // XML não assinado da DPS
 import { EmitirNotaError, emitirNfse } from '@useinvio/nfse-sdk';
 
 try {
-  await emitirNfse(nota, pfx);
+  await emitirNfse(nota, certificado);
 } catch (error) {
   if (!(error instanceof EmitirNotaError)) throw error;
 
@@ -371,7 +427,7 @@ try {
 ```ts
 import { consultarNfse } from '@useinvio/nfse-sdk';
 
-const resposta = await consultarNfse(chaveAcesso, pfx, 'restrita');
+const resposta = await consultarNfse(chaveAcesso, certificado, 'restrita');
 
 if (resposta.status === 200) {
   console.log(resposta.body);
@@ -387,10 +443,10 @@ if (resposta.status === 200) {
 ```ts
 import { enviarEvento, gzipBase64, signEnveloped } from '@useinvio/nfse-sdk';
 
-const signedEventXml = signEnveloped(pedRegXml, pedRegId, 'infPedReg', pfx);
+const signedEventXml = signEnveloped(pedRegXml, pedRegId, 'infPedReg', certificado);
 const pedRegXmlGZipB64 = gzipBase64(signedEventXml);
 
-const resposta = await enviarEvento(pedRegXmlGZipB64, pfx, chaveAcesso, 'restrita');
+const resposta = await enviarEvento(pedRegXmlGZipB64, certificado, chaveAcesso, 'restrita');
 ```
 
 ---
@@ -447,6 +503,34 @@ Leia o guia completo em [docs/METRICS.md](./docs/METRICS.md).
 
 ---
 
+## Agentes de IA e MCP
+
+O subpath `@useinvio/nfse-sdk/agent` expõe ferramentas neutras de framework para servidores MCP e agentes (OpenAI, LangChain, Vercel AI SDK). Cada ferramenta traz `name`, `description`, `inputSchema`/`outputSchema` em JSON Schema, `annotations` no formato MCP e um handler `run`.
+
+| Ferramenta | Efeito | Certificado |
+| --- | --- | --- |
+| `validate_dps` | Valida a requisição; nenhum efeito colateral. | Não |
+| `build_dps_xml` | Gera o XML não assinado e confere contra o XSD v1.01. | Não |
+| `get_nfse` | Consulta uma NFS-e pela chave de acesso. | Sim |
+
+```ts
+import { nfseAgentTools } from '@useinvio/nfse-sdk/agent';
+
+const context = { pfx: certificado, ambiente: 'restrita' as const }; // configuração do host
+for (const tool of nfseAgentTools) {
+  // registre tool.name, tool.description, tool.inputSchema e tool.annotations no seu framework
+  // e chame tool.run(argumentos, context) quando o modelo usar a ferramenta
+}
+```
+
+Certificado e ambiente ficam no `context` do host, nunca na entrada da ferramenta: o modelo não escolhe `producao` nem vê material de chave. Uma requisição com `ambiente` diferente do configurado gera `AMBIENTE_NOT_ALLOWED`. Falhas esperadas retornam `issues` com `code`, `path`, `severity`, `source` e `suggestion`; falhas de infraestrutura (rede, motor XSD) rejeitam a promise. `toAgentIssues(error)` converte erros do SDK (`DpsFiscalValidationError`, `DpsXsdValidationError`, `CertificateValidationError`, `EmitirNotaError`) para esse mesmo formato.
+
+`DPS_JSON_REQUEST_SCHEMA`, exportado também pela raiz do pacote, descreve o `DpsJsonRequest` canônico em JSON Schema 2020-12 com um subconjunto portável de palavras-chave. Ele cobre formatos e domínios de códigos, mas não as regras entre campos (regime × `totTrib`, nacional × exportação); `validateDpsJsonRequest` continua sendo a autoridade. Atalhos legados (`emissao.vServ`, `comExt`) e campos rejeitados pela validação ficam fora do schema; `validate_dps` aponta campos desconhecidos como `UNSUPPORTED_FIELD` em vez de ignorá-los.
+
+A emissão ainda não é exposta como ferramenta: ela exigirá confirmação explícita antes do envio.
+
+---
+
 ## Referência da API
 
 ### Funções principais
@@ -454,9 +538,9 @@ Leia o guia completo em [docs/METRICS.md](./docs/METRICS.md).
 | Função | Descrição |
 |---|---|
 | `new NfseClient(options)` | Cria cliente com ambiente, certificado e defaults no mesmo formato do JSON declarativo. |
-| `emitirNfse(input, pfx, options?)` | Emite uma NFS-e a partir de XML ou JSON. Retorna `ResultadoEmissaoNota`. |
-| `consultarNfse(chaveAcesso, pfx, ambiente?)` | Consulta uma NFS-e pela chave de acesso. |
-| `enviarEvento(xmlGzipB64, pfx, chaveAcesso, ambiente?)` | Envia evento fiscal (cancelamento, etc.). |
+| `emitirNfse(input, certificado, options?)` | Emite uma NFS-e a partir de XML ou JSON. Retorna `ResultadoEmissaoNota`. |
+| `consultarNfse(chaveAcesso, certificado, ambiente?)` | Consulta uma NFS-e pela chave de acesso. |
+| `enviarEvento(xmlGzipB64, certificado, chaveAcesso, ambiente?)` | Envia evento fiscal (cancelamento, etc.). |
 | `buildDpsFromJson(nota)` | Monta o XML da DPS sem assinar nem enviar. |
 | `setSefinRequestObserver(observer)` | Registra um hook para observar latência/status das chamadas à SEFIN. |
 | `createSefinLatencyTracker(options?)` | Agrega amostras recentes e pode calcular percentis quando `includePercentiles` estiver habilitado. |
@@ -465,16 +549,19 @@ Leia o guia completo em [docs/METRICS.md](./docs/METRICS.md).
 
 | Função | Descrição |
 |---|---|
-| `loadPfx(path, password)` | Carrega certificado A1 a partir de arquivo. |
-| `loadPfxFromBuffer(buffer, password)` | Carrega certificado A1 a partir de buffer. |
+| `assertCertificateValidity(certificado, now?)` | Verifica vigencia do certificado; aplicada na preparacao e no envio. |
+| `assertCertificateForProvider(certificado, documento, now?)` | Verifica explicitamente vigencia e correspondencia do titular. |
+| `NfseCertificate.fromEnv()` / `fromFile()` / `fromBase64()` / `fromPfx()` / `fromPem()` | Carrega o certificado A1 sem expor a chave privada. |
+| `loadPfx(path, password)` | Legado: retorna a chave em PEM. Prefira `NfseCertificate`. |
+| `loadPfxFromBuffer(buffer, password)` | Legado: retorna a chave em PEM. Prefira `NfseCertificate`. |
 
 ### Funções de baixo nível
 
 | Função | Descrição |
 |---|---|
-| `signDps(xml, dpsId, pfx)` | Assina XML de DPS com XMLDSIG. |
-| `signEnveloped(xml, id, ref, pfx)` | Assina XML genérico (eventos). |
-| `verifyDps(xml)` | Verifica assinatura de uma DPS. |
+| `signDps(xml, dpsId, certificado)` | Assina XML de DPS com XMLDSIG. |
+| `signEnveloped(xml, id, ref, certificado)` | Assina XML genérico (eventos). |
+| `verifyDps(xml, certPem)` | Verifica assinatura de uma DPS. |
 | `gzipBase64(xml)` | Compacta XML em GZip e codifica em Base64. |
 | `gunzipBase64(b64)` | Descompacta resposta GZip/Base64. |
 | `extrairErros(body)` | Normaliza erros oficiais de uma resposta da SEFIN. |
@@ -486,6 +573,7 @@ Leia o guia completo em [docs/METRICS.md](./docs/METRICS.md).
 import type {
   Ambiente,
   CreateInvoiceInput,
+  GetInvoiceOptions,
   DpsJsonInput,
   DpsJsonRequest,
   EmitirNotaOptions,
@@ -518,7 +606,7 @@ npm run build       # compila para dist/
 npm test            # build + tipos + testes unitários
 ```
 
-`npm test` também valida uma DPS gerada contra os XSD oficiais em `schemas/nfse/v1.01/Schemas/1.01`. Para compatibilidade com `xmllint`, o teste corrige em uma cópia temporária a âncora regex[...]
+`npm test` também valida as DPS geradas contra os XSD oficiais em `schemas/nfse/v1.01/Schemas/1.01` com o motor embutido (libxml2 em WebAssembly). Se o `xmllint` estiver instalado, como no CI, os testes também o usam como verificação cruzada.
 
 ### Uso local em outro projeto
 
@@ -548,19 +636,9 @@ O pacote usa `publishConfig.access = public`, necessário para publicar um pacot
 
 ---
 
-## Divulgação e exemplos
-
-- Exemplos copiáveis ficam em [`examples/`](./examples).
-- Material de lançamento, mensagens para redes e prompt de landing page ficam em [`docs/launch.md`](./docs/launch.md).
-
----
-
-## Assistente GPT
-
-Para criar um GPT que ajude outros devs a implementar e documentar esta SDK, use:
+## Exemplos
 
-- [`docs/gpt-assistant.md`](./docs/gpt-assistant.md): configuracao completa do GPT, instrucoes copiaveis, starters e testes de preview.
-- [`docs/gpt-knowledge.md`](./docs/gpt-knowledge.md): resumo compacto para subir como arquivo de Knowledge.
+Exemplos copiáveis ficam em [`examples/`](./examples).
 
 ---
 

package/dist/agent.d.ts

@@ -0,0 +1,86 @@
+import { type JsonSchema } from './dpsJsonSchema.js';
+import type { Ambiente } from './config.js';
+import type { DpsJsonRequest } from './dpsJson.js';
+import type { CertificateInput } from './certificate.js';
+export { DPS_JSON_REQUEST_SCHEMA } from './dpsJsonSchema.js';
+export type { JsonSchema } from './dpsJsonSchema.js';
+export type NfseAgentIssueSource = 'sdk' | 'invio' | 'schema' | 'xsd' | 'sefin' | 'certificate' | 'environment';
+/** One shape for validation, XSD, certificate and SEFIN problems. */
+export interface NfseAgentIssue {
+    code: string;
+    /** Dotted path inside the request (`emissao.` omitted, as in `DpsValidationIssue`); `$` when global. */
+    path: string;
+    severity: 'error' | 'warning';
+    source: NfseAgentIssueSource;
+    message: string;
+    suggestion?: string;
+}
+export interface NfseAgentContext {
+    /** Host-owned A1 certificate (`NfseCertificate` recommended). Required only by tools that talk to SEFIN. */
+    pfx?: CertificateInput;
+    /** Host-owned environment. Defaults to `restrita`; tool input cannot override it. */
+    ambiente?: Ambiente;
+}
+/** Same hints as MCP `ToolAnnotations`. */
+export interface NfseAgentToolAnnotations {
+    readOnlyHint: boolean;
+    destructiveHint: boolean;
+    idempotentHint: boolean;
+    openWorldHint: boolean;
+}
+export interface NfseAgentTool<Input = any, Output = any> {
+    name: string;
+    title: string;
+    description: string;
+    inputSchema: JsonSchema;
+    outputSchema: JsonSchema;
+    annotations: NfseAgentToolAnnotations;
+    requiresCertificate: boolean;
+    /**
+     * Expected failures (invalid input, rejection, missing certificate) resolve
+     * with `issues`. Infrastructure failures (XSD engine, network) reject.
+     */
+    run(input: Input, context?: NfseAgentContext): Promise<Output>;
+}
+export interface DpsRequestToolInput {
+    request: Omit<DpsJsonRequest, 'ambiente'>;
+}
+export interface ValidateDpsToolOutput {
+    valid: boolean;
+    schemaVersion: string;
+    ambiente: Ambiente;
+    issues: NfseAgentIssue[];
+    warnings: NfseAgentIssue[];
+}
+export interface BuildDpsXmlToolOutput {
+    ok: boolean;
+    ambiente: Ambiente;
+    dpsId?: string;
+    xml?: string;
+    issues: NfseAgentIssue[];
+    warnings: NfseAgentIssue[];
+}
+export interface GetNfseToolInput {
+    chaveAcesso: string;
+}
+export interface GetNfseToolOutput {
+    ok: boolean;
+    ambiente: Ambiente;
+    chaveAcesso: string;
+    status?: number;
+    nfseXml?: string;
+    body?: unknown;
+    issues: NfseAgentIssue[];
+}
+/**
+ * Converts known SDK errors to `NfseAgentIssue[]`. Returns `undefined` for
+ * anything else (transport, XSD engine, programming errors) so the caller can rethrow.
+ */
+export declare function toAgentIssues(error: unknown): NfseAgentIssue[] | undefined;
+/** `DPS_JSON_REQUEST_SCHEMA` without `ambiente`, which belongs to the host. */
+export declare const DPS_AGENT_REQUEST_SCHEMA: JsonSchema;
+export declare const validateDpsTool: NfseAgentTool<DpsRequestToolInput, ValidateDpsToolOutput>;
+export declare const buildDpsXmlTool: NfseAgentTool<DpsRequestToolInput, BuildDpsXmlToolOutput>;
+export declare const getNfseTool: NfseAgentTool<GetNfseToolInput, GetNfseToolOutput>;
+/** All tools, in the order an agent typically needs them. */
+export declare const nfseAgentTools: readonly NfseAgentTool[];