@pairus/product-data 1.5.0 → 1.7.0

package/README.md

@@ -70,7 +70,7 @@ console.log(enriched.palavras_chave); // Otimizadas para e-commerce
 ```typescript
 const resultado = await client.products.search('refrigerante zero açucar lata');
 for (const item of resultado.produtos) {
-  console.log(`[Score: ${item.score}] ${item.gtin} - ${item.xProd}`);
+  console.log(`[Score: ${item.score}] ${item.gtin} - ${item.xProd} (${item.marca})`);
 }
 ```
 
@@ -100,19 +100,22 @@ const predicao = await client.fiscal.predict({
 });
 
 const trib = predicao.dados_tributarios!;
-console.log(`CFOP: ${trib.cfop} | CST/CSOSN: ${trib.icms_cst_csosn}`);
+// CFOP interno (mesma UF) e externo (interestadual): use o que corresponde à operação
+console.log(`CFOP: ${trib.cfop_interno} / ${trib.cfop_externo} | CST/CSOSN: ${trib.icms_cst_csosn}`);
 console.log(`IBS Efetivo: ${trib.ibscbs.ibs_aliquota_efetiva}% | CBS: ${trib.ibscbs.cbs_aliquota_efetiva}%`);
+if (trib.is?.incidencia) console.log(`Imposto Seletivo: CST ${trib.is.CSTIS} (${trib.is.pIS}%)`);
+console.log(trib.avisos_fiscais);
 ```
 
 #### Saneamento Fiscal em Lote
 ```typescript
 const lote = await client.fiscal.sanitize([
-  { ncm: '22021000', descricao: 'Refrigerante Cola' },
-  { ncm: '22030000', descricao: 'Cerveja Pilsen' },
+  { NCM: '22021000', xProd: 'Refrigerante Cola', id: 'SKU-001' },
+  { NCM: '22030000', CEST: '0302100', xProd: 'Cerveja Pilsen' },
 ]);
 
 for (const item of lote.itens) {
-  console.log(`NCM: ${item.ncm} | CEST Sugerido: ${item.cest_sugerido}`);
+  console.log(`NCM: ${item.NCM_informado} | Vigente: ${item.auditoria_fiscal.ncm_vigente} | CEST: ${item.auditoria_fiscal.cest_sugerido}`);
 }
 ```
 
@@ -170,6 +173,13 @@ devolve essa mesma nota (`repeticao_idempotente: true`, sem novo faturamento) em
 identificador da venda quando o PDV puder reenviá-la depois de reiniciar. A chave vale por 24 h e é liberada se a
 nota for rejeitada, para você corrigir e reenviar.
 
+**Contingência off-line da NFC-e**: com a opção ativada na conta (tela de emissão da Área do Cliente), a venda
+não trava quando a SEFAZ não responde: a resposta vem com `sucesso` verdadeiro, `status_sefaz` igual a `CONTINGENCIA`
+(cStat 9, código da PAIRUS) e o DANFE com a tarja de contingência e a via do estabelecimento, sem consumir créditos.
+A nota é transmitida automaticamente depois, e o desfecho chega por webhook (`nfe.autorizada`,
+`nfe.contingencia_rejeitada`, `nfe.substituida_cancelada`, `nfe.substituida_inutilizada`,
+`nfe.regularizacao_manual`). Para recusar a contingência numa venda, envie `permitir_contingencia: false`.
+
 #### Forma 3: Simulação Gratuita (Custo ZERO de créditos)
 ```typescript
 const simulacao = await client.emissao.simular({

package/dist/index.d.mts

@@ -46,6 +46,12 @@ interface DocumentoDFe {
     tipo_documento?: string;
     manifestacao_status?: string;
     tem_xml_completo?: boolean;
+    /** Protocolo de autorização da NF-e (resNFe). */
+    protocolo?: string;
+    cnpj_destinatario?: string;
+    ie_emitente?: string;
+    ambiente?: string;
+    [campo: string]: any;
 }
 interface SincronizarDFeInput {
     cnpj: string;
@@ -72,12 +78,15 @@ interface ListarDocumentosDFeResponse {
     total: number;
     ult_nsu: string;
     max_nsu: string;
+    /** Data e hora da última sincronização com a SEFAZ. */
+    ultima_sincronizacao?: string | null;
     documentos: DocumentoDFe[];
 }
 interface ManifestarDFeInput {
     cnpj: string;
     chave_acesso: string;
     tipo_evento: TipoManifestacaoDFe | string;
+    /** Obrigatória apenas no 210240 (15 a 255 caracteres); a API a descarta nos demais eventos. */
     justificativa?: string;
     ambiente?: 'producao' | 'homologacao';
 }
@@ -87,6 +96,9 @@ interface ManifestarDFeResponse {
     xmotivo: string;
     protocolo?: string;
     tipo_evento?: string;
+    chave_acesso?: string;
+    /** 'ciencia', 'confirmada', 'desconhecida' ou 'nao_realizada'. */
+    manifestacao_status?: string;
     detalhes?: Record<string, any>;
 }
 
@@ -198,6 +210,8 @@ interface EmissaoNFeInput {
     informacoes_complementares?: string;
     id_token_csc?: string;
     codigo_csc?: string;
+    /** NFC-e: false impede a contingência off-line nesta venda; omitido segue a configuração da conta. */
+    permitir_contingencia?: boolean;
     [key: string]: any;
 }
 /** Opções de envio da emissão. */
@@ -210,7 +224,7 @@ interface EmissaoOptions {
 }
 interface EmissaoNFeResponse {
     sucesso: boolean;
-    /** 'AUTORIZADA', 'REJEITADA', 'PENDENTE_RETORNO', 'DENEGADA' ou 'SIMULADA'. */
+    /** 'AUTORIZADA', 'REJEITADA', 'PENDENTE_RETORNO', 'DENEGADA', 'CONTINGENCIA' ou 'SIMULADA'. */
     status_sefaz: string;
     cStat: number;
     xMotivo: string;
@@ -289,6 +303,12 @@ declare class EmissaoResource extends BaseResource {
     inutilizar(params: InutilizacaoInput): Promise<EventoNFeResponse>;
 }
 
+/**
+ * Tipos da predição fiscal (/v2/fiscal/predict) e do saneamento em lote (/v2/fiscal/sanitize).
+ *
+ * Espelham o contrato da API. Os nomes usados até a 1.5 (`cfop`, `avisos`, `imposto_seletivo` e
+ * `aliquota_efetiva_unificada` na raiz) continuam preenchidos pelo SDK a partir dos oficiais.
+ */
 interface IBSCBSData {
     cst: string;
     cClassTrib: string;
@@ -296,16 +316,29 @@ interface IBSCBSData {
     cbs_diferimento: number;
     cbs_reducao_aliquota: number;
     cbs_aliquota_efetiva: number;
+    aliquota_cbs_estimada?: number;
     ibs_aliquota_estadual: number;
     ibs_aliquota_municipal: number;
     ibs_diferimento: number;
     ibs_reducao_aliquota: number;
+    ibs_reducao_aliquota_estadual?: number;
+    ibs_reducao_aliquota_municipal?: number;
     ibs_aliquota_efetiva: number;
+    aliquota_ibs_estimada?: number;
+    aliquota_efetiva_unificada?: number;
+    vTotDFe_obrigatorio?: boolean;
 }
+/** Imposto Seletivo: chega na chave `is` de `dados_tributarios`. */
 interface SelectiveTaxData {
-    cst: string;
-    cClassTribIS: string;
-    aliquota: number;
+    incidencia?: boolean;
+    CSTIS?: string | null;
+    cClassTribIS?: string | null;
+    pIS?: number;
+    nota?: string | null;
+    /** @deprecated Use `CSTIS`. */
+    cst?: string | null;
+    /** @deprecated Use `pIS`. */
+    aliquota?: number;
 }
 interface FuelData {
     codigo_anp: string;
@@ -317,30 +350,55 @@ interface FuelData {
 }
 interface TaxPredictionData {
     ncm_sugerido: string;
-    cest_sugerido?: string;
-    cfop: string;
-    cfop_devolucao?: string;
+    cest_sugerido?: string | null;
+    origem_mercadoria?: string;
+    origem_mercadoria_descricao?: string;
+    cfop_interno?: string;
+    cfop_externo?: string;
+    cfop_devolucao_interno?: string | null;
+    cfop_devolucao_externo?: string | null;
     icms_cst_csosn: string;
     icms_aliquota: number;
-    icms_aliquota_st: number;
-    icms_mva_st: number;
     icms_reducao_bc: number;
+    icms_sujeito_st?: boolean;
+    icms_mva_st: number;
+    icms_aliquota_st: number;
     icms_reducao_bc_st: number;
-    icms_modalidade_bc: string;
-    icms_modalidade_bc_st: string;
+    icms_modalidade_bc?: string | null;
+    icms_modalidade_bc_st?: string | null;
+    icms_credito_aliquota_sn?: number;
+    dados_desoneracao_suframa?: Record<string, any> | null;
     pis_cst: string;
     pis_aliquota: number;
     cofins_cst: string;
     cofins_aliquota: number;
-    ipi_cst?: string;
+    ipi_cst?: string | null;
     ipi_aliquota?: number;
+    extipi?: string | null;
+    reforma_tributaria_nota?: string;
     ibscbs: IBSCBSData;
+    /** Imposto Seletivo (nome oficial da chave na API). */
+    is?: SelectiveTaxData;
+    combustivel_sujeito_anp?: boolean;
+    dados_combustivel?: FuelData | null;
+    diagnostico_anti_rejeicao?: Array<Record<string, string>>;
+    otimizacao_tributaria?: Record<string, any> | null;
+    difal?: Record<string, any> | null;
+    motor_ia: string;
+    avisos_fiscais?: string[];
+    disclaimer?: string;
+    /** @deprecated Use `cfop_interno` ou `cfop_externo` conforme a UF de destino (preenchido com `cfop_interno`). */
+    cfop?: string;
+    /** @deprecated Use `cfop_devolucao_interno` / `cfop_devolucao_externo`. */
+    cfop_devolucao?: string | null;
+    /** @deprecated Use `is`. */
     imposto_seletivo?: SelectiveTaxData;
-    dados_combustivel?: FuelData;
+    /** @deprecated Use `ibscbs.aliquota_efetiva_unificada`. */
+    aliquota_efetiva_unificada?: number;
+    /** @deprecated Use `avisos_fiscais`. */
+    avisos?: string[];
+    /** @deprecated Não é devolvido pela API. */
     beneficio_fiscal?: string;
-    aliquota_efetiva_unificada: number;
-    motor_ia: string;
-    avisos: string[];
 }
 interface TaxPredictionItemInput {
     xProd?: string;
@@ -354,6 +412,10 @@ interface TaxPredictionParams {
     ufDestino?: string;
     finalidade?: 'revenda' | 'consumo_final' | 'industrializacao' | string;
     destinatarioContribuinte?: boolean;
+    /** Alíquota de crédito de ICMS do Simples Nacional (pCredSN). */
+    aliquotaCreditoIcmsSn?: number;
+    destinatarioSuframa?: boolean;
+    inscricaoSuframa?: string;
     xProd?: string;
     gtin?: string;
     ncm?: string;
@@ -362,38 +424,49 @@ interface TaxPredictionParams {
 }
 interface TaxPredictionItemResult {
     item_index: number;
-    xProd?: string;
+    xProd?: string | null;
     dados_tributarios: TaxPredictionData;
 }
 interface TaxPredictionResponse {
     status: string;
     provider: string;
-    xProd?: string;
-    dados_tributarios?: TaxPredictionData;
-    resultados?: TaxPredictionItemResult[];
+    timestamp?: string;
+    motor_ia?: string | null;
+    xProd?: string | null;
+    dados_tributarios?: TaxPredictionData | null;
+    resultados?: TaxPredictionItemResult[] | null;
 }
+/**
+ * Item do saneamento. A API exige `NCM`/`CEST` em maiúsculas; os nomes `ncm`, `cest`,
+ * `descricao` e `gtin` da 1.5 continuam aceitos e são convertidos pelo SDK.
+ */
 interface FiscalSanitizeItemInput {
-    ncm: string;
+    NCM?: string;
+    CEST?: string;
+    xProd?: string;
+    id?: string;
+    /** @deprecated Use `NCM`. */
+    ncm?: string;
+    /** @deprecated Use `CEST`. */
     cest?: string;
+    /** @deprecated Use `xProd`. */
     descricao?: string;
+    /** @deprecated Use `id`. */
     gtin?: string;
 }
 interface FiscalSanitizeItemResult {
-    ncm: string;
-    ncm_valido: boolean;
-    descricao_ncm?: string;
-    cest_informado?: string;
-    cest_sugerido?: string;
-    sujeito_st: boolean;
-    aliquotas_sugeridas?: Record<string, any>;
-    avisos?: string[];
+    id?: string;
+    xProd?: string;
+    NCM_informado?: string;
+    CEST_informado?: string | null;
+    auditoria_fiscal: Record<string, any>;
 }
 interface FiscalSanitizeResponse {
     status: string;
     provider: string;
     timestamp?: string;
     total_itens: number;
-    itens: Array<Record<string, any>>;
+    itens: FiscalSanitizeItemResult[];
 }
 
 declare class FiscalResource extends BaseResource {
@@ -403,8 +476,9 @@ declare class FiscalResource extends BaseResource {
     predict(params: TaxPredictionParams): Promise<TaxPredictionResponse>;
     /**
      * Audita e higieniza uma lista de produtos em lote perante as tabelas fiscais vigentes.
+     * Cada item precisa de `NCM` (aceita também `ncm`); `CEST`, `xProd` e `id` são opcionais.
      */
-    sanitize(itens: Array<Record<string, any>>): Promise<any>;
+    sanitize(itens: FiscalSanitizeItemInput[]): Promise<FiscalSanitizeResponse>;
 }
 
 interface EnderecoNFSeInput {
@@ -450,6 +524,14 @@ interface RetencoesFederaisInput {
     aliquota_inss?: number;
     valor_inss?: number;
 }
+/** Campos da Reforma Tributária (IBS e CBS) sobre serviços (LC 214/2025). */
+interface ReformaTributariaServicoInput {
+    cst_ibs_cbs?: string;
+    cClassTrib?: string;
+    aliquota_ibs_estadual?: number;
+    aliquota_ibs_municipal?: number;
+    aliquota_cbs?: number;
+}
 interface ServicoNFSeInput {
     item_lista_servico: string;
     discriminacao: string;
@@ -462,8 +544,10 @@ interface ServicoNFSeInput {
     valor_desconto_condicionado?: number;
     iss_retido?: boolean;
     aliquota_iss?: number;
+    /** '1' Exigível, '2' Não incidência, '3' Isenção, '4' Exportação, '5' Imunidade, '6'/'7' Suspensa. */
     exigibilidade_iss?: string;
     retencoes_federais?: RetencoesFederaisInput;
+    reforma_tributaria?: ReformaTributariaServicoInput;
 }
 interface NFSeEmissaoInput {
     prestador: PrestadorNFSeInput | Record<string, any>;
@@ -486,6 +570,8 @@ interface NFSeEmissaoResponse {
     data_emissao?: string;
     link_visualizacao?: string;
     danfse_pdf_base64?: string;
+    /** Alias de danfse_pdf_base64 devolvido pela API. */
+    danfse_base64?: string;
     xml_nfse?: string;
     valor_servicos: number;
     valor_iss: number;
@@ -494,7 +580,13 @@ interface NFSeEmissaoResponse {
     valor_liquido: number;
     erros?: string[];
     alertas?: string[];
-    trilha_auditoria?: Record<string, any>[];
+    trilha_auditoria?: Array<{
+        autor: string;
+        acao: string;
+        justificativa_legal: string;
+        campos_alterados?: Record<string, any>;
+        timestamp: string;
+    }>;
     creditos_cobrados: number;
     tempo_processamento_ms: number;
 }
@@ -504,6 +596,7 @@ interface CancelamentoNFSeInput {
     inscricao_municipal: string;
     codigo_municipio_ibge: string;
     justificativa: string;
+    /** '1' Erro de emissão, '2' Serviço não prestado, '3' Duplicidade, '9' Outros. */
     motivo_codigo?: string;
     codigo_verificacao?: string;
     chave_acesso_nacional?: string;
@@ -535,6 +628,11 @@ declare class NFSeResource extends BaseResource {
     consultar(chaveOuNumero: string): Promise<Record<string, any>>;
 }
 
+/**
+ * Tipos de produto do SDK. A API devolve o produto no layout da NF-e (`GTIN`, `NCM`, `CEST`) com
+ * marca, categoria, imagem e pesos em `infoAdicional` e a IA em `enriquecimentoIA`/`tributacaoIA`;
+ * o `ProductsResource` converte esse contrato para os tipos abaixo.
+ */
 interface ProductDetails {
     gtin: string;
     xProd: string;
@@ -549,10 +647,16 @@ interface ProductDetails {
     quantidadeEmbalagem?: number;
     dataCadastro?: string;
     dataAtualizacao?: string;
+    tpGTIN?: string;
+    fonte?: string;
+    /** Bloco `infoAdicional` original da API. */
+    infoAdicional?: Record<string, any>;
 }
 interface ProductResponse {
     status: string;
     provider: string;
+    cStat?: string;
+    xMotivo?: string;
     produto?: ProductDetails;
     raw_data?: Record<string, any>;
 }
@@ -562,6 +666,8 @@ interface ProductSearchResultItem {
     marca?: string;
     categoria?: string;
     score?: number;
+    /** Explicação da correspondência semântica. */
+    justificativa?: string;
     ncm?: string;
     cest?: string;
     imagem_url?: string;
@@ -571,12 +677,17 @@ interface ProductSearchResponse {
     provider: string;
     total_encontrados: number;
     termo_buscado: string;
+    motor_busca?: string;
     produtos: ProductSearchResultItem[];
 }
 interface ProductEnrichedDetails {
     gtin: string;
     xProd: string;
+    /** Nome saneado pela IA. */
+    xProd_higienizado?: string;
+    /** Descrição otimizada para SEO (`enriquecimentoIA.descricao_seo`). */
     descricao_completa?: string;
+    /** Atributos técnicos extraídos pela IA (`enriquecimentoIA.atributos`). */
     ficha_tecnica?: Record<string, any>;
     palavras_chave?: string[];
     ncm?: string;
@@ -586,7 +697,13 @@ interface ProductEnrichedDetails {
     imagem_url?: string;
     peso_bruto?: number;
     peso_liquido?: number;
+    /** Nó `tributacaoIA` da API. */
     dados_tributarios_sugeridos?: Record<string, any>;
+    tpGTIN?: string;
+    fonte?: string;
+    infoAdicional?: Record<string, any>;
+    enriquecimentoIA?: Record<string, any>;
+    tributacaoIA?: Record<string, any>;
 }
 
 declare class ProductsResource extends BaseResource {
@@ -672,4 +789,4 @@ declare class NetworkError extends PairusError {
     constructor(message: string);
 }
 
-export { AuthenticationError, type CancelamentoInput, type CancelamentoNFSeInput, type CancelamentoNFSeResponse, type CartaCorrecaoInput, DEFAULT_BASE_URL, DEFAULT_MAX_RETRIES, DEFAULT_TIMEOUT_MS, DFeResource, type DocumentoDFe, type EmissaoDestinatarioInput, type EmissaoItemInput, type EmissaoNFeInput, type EmissaoNFeResponse, type EmissaoOptions, type EmissaoPagamentoInput, EmissaoResource, type EnderecoNFSeInput, type EventoNFeResponse, FiscalResource, type FiscalSanitizeItemInput, type FiscalSanitizeItemResult, type FiscalSanitizeResponse, type FuelData, type IBSCBSData, type InutilizacaoInput, InvalidSignatureError, type ListarDocumentosDFeParams, type ListarDocumentosDFeResponse, type ManifestarDFeInput, type ManifestarDFeResponse, type NFSeEmissaoInput, type NFSeEmissaoResponse, NFSeResource, NetworkError, PairusAPIError, type PairusClientOptions, PairusError, PairusProductData, type PrestadorNFSeInput, type ProductDetails, type ProductEnrichedDetails, type ProductResponse, type ProductSearchResponse, type ProductSearchResultItem, ProductsResource, RateLimitError, type RetencoesFederaisInput, type SelectiveTaxData, type ServicoNFSeInput, type SincronizarDFeInput, type SincronizarDFeResponse, type TaxPredictionData, type TaxPredictionItemInput, type TaxPredictionItemResult, type TaxPredictionParams, type TaxPredictionResponse, type TipoManifestacaoDFe, type TomadorNFSeInput, type WebhookEvent, Webhooks };
+export { AuthenticationError, type CancelamentoInput, type CancelamentoNFSeInput, type CancelamentoNFSeResponse, type CartaCorrecaoInput, DEFAULT_BASE_URL, DEFAULT_MAX_RETRIES, DEFAULT_TIMEOUT_MS, DFeResource, type DocumentoDFe, type EmissaoDestinatarioInput, type EmissaoItemInput, type EmissaoNFeInput, type EmissaoNFeResponse, type EmissaoOptions, type EmissaoPagamentoInput, EmissaoResource, type EnderecoNFSeInput, type EventoNFeResponse, FiscalResource, type FiscalSanitizeItemInput, type FiscalSanitizeItemResult, type FiscalSanitizeResponse, type FuelData, type IBSCBSData, type InutilizacaoInput, InvalidSignatureError, type ListarDocumentosDFeParams, type ListarDocumentosDFeResponse, type ManifestarDFeInput, type ManifestarDFeResponse, type NFSeEmissaoInput, type NFSeEmissaoResponse, NFSeResource, NetworkError, PairusAPIError, type PairusClientOptions, PairusError, PairusProductData, type PrestadorNFSeInput, type ProductDetails, type ProductEnrichedDetails, type ProductResponse, type ProductSearchResponse, type ProductSearchResultItem, ProductsResource, RateLimitError, type ReformaTributariaServicoInput, type RetencoesFederaisInput, type SelectiveTaxData, type ServicoNFSeInput, type SincronizarDFeInput, type SincronizarDFeResponse, type TaxPredictionData, type TaxPredictionItemInput, type TaxPredictionItemResult, type TaxPredictionParams, type TaxPredictionResponse, type TipoManifestacaoDFe, type TomadorNFSeInput, type WebhookEvent, Webhooks };