feat: NFS-e por chave e Simples Nacional

README.md

@@ -1,6 +1,6 @@
 # FiscalAPI — SDK Node.js / TypeScript
 
-Cliente JavaScript/TypeScript da [FiscalAPI](https://fiscalapi.com.br): Inscrição Estadual nos 27 estados, CNPJ, certidões (CND estadual, CND Federal, CNDT, CRF/FGTS), XML de NF-e por chave, SIGEF, CNIR e perfil do produtor rural.
+Cliente JavaScript/TypeScript da [FiscalAPI](https://fiscalapi.com.br): Inscrição Estadual nos 27 estados, CNPJ, certidões (CND estadual, CND Federal, CNDT, CRF/FGTS), XML de NF-e por chave, NFS-e por chave, Simples Nacional, SIGEF, CNIR e perfil do produtor rural.
 
 - Zero dependências: usa o `fetch` nativo (Node 18+, Bun, Deno, edge runtimes).
 - Tipado em TypeScript, com ESM e CommonJS.
@@ -53,6 +53,8 @@ const { FiscalAPI } = require('fiscalapi-br');
 | `consultarCndt({ cpf \| cnpj })` | `GET /api/consultar-cndt` | Certidão de débitos trabalhistas |
 | `consultarCrfFgts({ cpf \| cnpj })` | `GET /api/consultar-crf-fgts` | Regularidade do FGTS |
 | `consultarCertidoesTodas({ cpf \| cnpj, skipEstaduais? })` | `GET /api/certidoes-todas` | Todas as certidões em uma chamada |
+| `consultarSimplesNacional({ cnpj })` | `GET /api/consultar-simples-nacional` | Situação no Simples Nacional e SIMEI |
+| `consultarNfse({ chave, danfse? })` | `GET /api/consultar-nfse` | NFS-e (padrão nacional) por chave, sem certificado |
 | `consultarNfeXml({ chave, certificado, senha, manifestar? })` | `POST /api/consultar-nfe-xml` | XML completo da NF-e |
 | `consultarSigef({ cpf \| cnpj })` | `GET /api/consultar-sigef` | Parcelas certificadas no SIGEF/INCRA |
 | `consultarSigefParcela({ uuid, forceFresh? })` | `GET /api/consultar-sigef-parcela` | Uma parcela com polígono, vértices e confrontantes |
@@ -85,6 +87,25 @@ console.log(empresa.result?.razao_social, empresa.result?.situacao_cadastral);
 await api.consultarCnpj({ cnpj: '12345678000195', forceFresh: true });
 ```
 
+### Simples Nacional
+
+```ts
+const r = await api.consultarSimplesNacional({ cnpj: '11222333000181' });
+console.log(r.optante_simples, r.situacao_simei, r.regime_regular_ibs);
+```
+
+### NFS-e por chave
+
+```ts
+const nfse = await api.consultarNfse({
+  chave: '35503082211222333000181000000000012326100000045676',
+  danfse: true, // opcional: PDF do DANFSe em base64
+});
+console.log(nfse.emitente?.razao_social, nfse.tributacao_municipal?.valor_servico);
+```
+
+Uma consulta nova leva de 30 a 60 segundos. Só a NFS-e entregue é cobrada.
+
 ### Certidões com PDF
 
 ```ts

package.json

@@ -1,6 +1,6 @@
 {
   "name": "fiscalapi-br",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "SDK da FiscalAPI (Brasil): Inscrição Estadual, CNPJ, certidões, NF-e, SIGEF, CNIR e perfil do produtor rural.",
   "license": "MIT",
   "author": {

src/client.ts

@@ -17,9 +17,11 @@ import type {
   ConsultaIEResponse,
   ConsultaIETodosResponse,
   NfeXmlResponse,
+  NfseResponse,
   PerfilProdutorResponse,
   SigefParcelaResponse,
   SigefResponse,
+  SimplesNacionalResponse,
 } from './types.js';
 import { VERSION } from './version.js';
 
@@ -127,6 +129,12 @@ export class FiscalAPI {
     });
   }
 
+  /** Situação no Simples Nacional e SIMEI (`GET /api/consultar-simples-nacional`). */
+  consultarSimplesNacional(params: { cnpj: string }): Promise<SimplesNacionalResponse> {
+    if (!params.cnpj?.trim()) throw new Error('Informe o CNPJ.');
+    return this.get('/api/consultar-simples-nacional', { cnpj: params.cnpj.trim() });
+  }
+
   // --------------------------------------------------------- Certidões
 
   /** CND estadual (ICMS) em uma UF (`GET /api/consultar-cnd`). */
@@ -194,6 +202,17 @@ export class FiscalAPI {
     });
   }
 
+  /**
+   * NFS-e (padrão nacional) pela chave de acesso, sem certificado
+   * (`GET /api/consultar-nfse`). Com `danfse: true`, inclui o PDF em base64.
+   * Uma consulta nova pode levar de 30 a 60 segundos.
+   */
+  consultarNfse(params: { chave: string; danfse?: boolean }): Promise<NfseResponse> {
+    const chave = (params.chave ?? '').replace(/\D/g, '');
+    if (!chave) throw new Error('Informe a chave de acesso.');
+    return this.get('/api/consultar-nfse', { chave, danfse: params.danfse || undefined });
+  }
+
   // ------------------------------------------------------ Imóvel rural
 
   /** Parcelas certificadas no SIGEF/INCRA (`GET /api/consultar-sigef`). */

src/types.ts

@@ -245,3 +245,131 @@ export interface PerfilProdutorResponse {
   cnir?: CnirResponse | null;
   [extra: string]: unknown;
 }
+
+export interface SimplesNacionalEventoFuturo {
+  regime: string;
+  descricao: string;
+  data_efeito: string;
+}
+
+export interface SimplesNacionalPeriodoAnterior {
+  data_inicial: string;
+  data_final: string;
+  detalhamento: string;
+}
+
+export interface SimplesNacionalMaisInfo {
+  opcoes_periodos_anteriores?: string;
+  opcoes_periodos_anteriores_lista?: SimplesNacionalPeriodoAnterior[];
+  enquadramentos_simei_periodos_anteriores?: string;
+  enquadramentos_simei_periodos_anteriores_lista?: SimplesNacionalPeriodoAnterior[];
+  eventos_futuros_simples?: string;
+  eventos_futuros_simei?: string;
+  mei_tac?: string;
+}
+
+export interface SimplesNacionalResponse {
+  request_id: string;
+  cnpj: string;
+  /** Para filiais, a situação é a da matriz. */
+  cnpj_matriz: string;
+  nome_empresarial: string;
+  data_consulta: string;
+  situacao_simples: string;
+  optante_simples: boolean;
+  data_opcao_simples?: string | null;
+  situacao_simei: string;
+  enquadrado_simei: boolean;
+  regime_regular_ibs: string;
+  regime_regular_cbs: string;
+  eventos_futuros?: SimplesNacionalEventoFuturo[];
+  mais_info?: SimplesNacionalMaisInfo | null;
+  cached: boolean;
+}
+
+export interface NfseEndereco {
+  logradouro?: string | null;
+  numero?: string | null;
+  complemento?: string | null;
+  bairro?: string | null;
+  cep?: string | null;
+  municipio?: string | null;
+  uf?: string | null;
+}
+
+export interface NfseEmitente {
+  razao_social?: string | null;
+  cpf_cnpj?: string | null;
+  inscricao_municipal?: string | null;
+  situacao_simples_nacional?: string | null;
+  regime_especial_tributacao?: string | null;
+  endereco?: NfseEndereco | null;
+}
+
+export interface NfsePessoa {
+  cpf_cnpj?: string | null;
+  inscricao_municipal?: string | null;
+  nome?: string | null;
+}
+
+export interface NfseServico {
+  pais?: string | null;
+  municipio?: string | null;
+  codigo_tributacao_nacional?: string | null;
+  descricao_codigo?: string | null;
+  item_nbs?: string | null;
+  descricao?: string | null;
+}
+
+export interface NfseTributacaoMunicipal {
+  tributacao_issqn?: string | null;
+  municipio_incidencia?: string | null;
+  valor_servico?: number | null;
+  desconto_incondicionado?: number | null;
+  deducoes?: number | null;
+  beneficio_municipal?: number | null;
+  base_calculo?: number | null;
+  /** Percentual (2.5 = 2,5%). */
+  aliquota?: number | null;
+  valor_issqn?: number | null;
+  retencao?: string | null;
+}
+
+export interface NfseTributacaoFederal {
+  situacao_pis_cofins?: string | null;
+  base_calculo_pis_cofins?: number | null;
+  aliquota_pis?: number | null;
+  valor_pis?: number | null;
+  aliquota_cofins?: number | null;
+  valor_cofins?: number | null;
+  irrf?: number | null;
+  contribuicoes_sociais_retidas?: number | null;
+  contribuicao_previdenciaria_retida?: number | null;
+}
+
+export interface NfseResponse {
+  request_id: string;
+  chave: string;
+  numero_nfse?: string | null;
+  codigo_municipio_emissor?: string | null;
+  data_geracao?: string | null;
+  versao?: string | null;
+  dps?: { numero?: string | null; serie?: string | null; data_emissao?: string | null } | null;
+  /** `codigo` 100 gerada, 101 substituição, 102 decisão judicial, 103 avulsa. Não indica cancelamento. */
+  situacao?: { codigo?: string | null; descricao?: string | null } | null;
+  emitente?: NfseEmitente | null;
+  tomador?: NfsePessoa | null;
+  intermediario?: NfsePessoa | null;
+  servico?: NfseServico | null;
+  tributacao_municipal?: NfseTributacaoMunicipal | null;
+  tributacao_federal?: NfseTributacaoFederal | null;
+  total_tributos?: Array<{ descricao: string; valor?: number | null }>;
+  informacoes_complementares?: string | null;
+  ambiente_gerador?: string | null;
+  cached: boolean;
+  /** PDF do DANFSe em base64 (só com `danfse: true`). */
+  danfse_pdf_base64?: string | null;
+  /** Presente quando o PDF pedido não pôde ser obtido. */
+  aviso?: string | null;
+  [extra: string]: unknown;
+}

src/version.ts

@@ -1 +1 @@
-export const VERSION = '0.1.0';
+export const VERSION = '0.2.0';