Ajuda de campos e tipos

Consulte o contrato da sua instalação antes de preencher uma NF-e ou NFC-e. A ajuda funciona offline, sem runtime nativo, certificado A1 ou compilador. Ela lê os metadados incluídos no pacote e não executa operações fiscais.

O que está disponível em cada versão

Deslize a tabela para comparar todas as colunas.

Recurso	0.2.1	0.2.2 publicada no npm
help TAG caminho [--json]	Campos e coleções	Compatível; continua restrito a campos
describe TARGET	Indisponível	Campo ou tipo, em português
describe TARGET --json	Indisponível	Metadados de campo ou tipo
--help / -h	Ajuda global	Ajuda global ou por subcomando
--version / -V	Indisponível	Versão do SDK
--version --json	Indisponível	Objeto JSON com version

Disponível na 0.2.2

describe, --version e a ajuda por subcomando estão disponíveis em cosmemilton-acbr-node@0.2.2, publicada no npm. Atualize o SDK para usar esses comandos; uma instalação da 0.2.1 mantém a interface anterior. As fontes desta ajuda estão fixadas no commit 26562b356822, do PR #9.

A versão cosmemilton-acbr-node@0.2.2 é a referência dos exemplos atuais. O comando help TAG existe desde a 0.1.2. Os SDKs 0.2.1 e 0.2.2 usam o contrato ACBr 48590, com 204 tipos, e os runtimes 0.2.1. A evolução da ajuda pertence ao SDK e não exige recompilar o motor.

Instalação e primeira consulta

Depois da instalação, use o executável local do projeto:

npx --no-install acbr-node --help
npx --no-install acbr-node describe Ide.tpNF

Para reproduzir exatamente a versão verificada:

npm install cosmemilton-acbr-node@0.2.2

--no-install usa a CLI instalada no projeto. Assim, a consulta acompanha o mesmo pacote que sua aplicação importa.

Entender um campo e seu enum

Ide.tpNF é um campo do tipo TTipoNFe. A consulta mostra os valores de entrada tnEntrada e tnSaida e o padrão declarado tnSaida.

O padrão pertence ao campo. Ele descreve a declaração Pascal e não garante o comportamento do construtor nativo nem substitui as regras fiscais. Os valores textuais vêm dos fontes ACBr; não converta sua posição no enum em um código XML.

Na 0.2.1, help TAG consulta caminhos de campos. Um nome de tipo isolado, como TTipoNFe, termina com CAMPO_INEXISTENTE; consulte Ide.tpNF para obter o enum e seus valores nessa versão. A API pública do pacote também não expõe uma função de consulta de tipos nessa release.

Descrever campos e tipos

Disponível a partir da 0.2.2:

npx --no-install acbr-node describe --help
npx --no-install acbr-node describe Ide.tpNF
npx --no-install acbr-node describe TTipoNFe
npx --no-install acbr-node describe TTipoNFe --json

describe TARGET mostra texto em português. O campo Ide.tpNF mostra tnEntrada, tnSaida e seu padrão declarado tnSaida. A consulta ao tipo TTipoNFe mostra os mesmos valores, sem atribuir um padrão ou condição de somente leitura ao tipo.

npx --no-install acbr-node describe TNFe.Ide.tpNF
npx --no-install acbr-node describe TProd
npx --no-install acbr-node describe TDetCollection
npx --no-install acbr-node describe

Sem TARGET, describe consulta o tipo raiz TNFe. Objetos listam campos, listas mostram o tipo de item e enums apresentam seus nomes textuais. Os nomes distinguem maiúsculas de minúsculas. describe também aceita caminhos e índices como os exemplos de coleções abaixo.

JSON de campo e JSON de tipo

describe Ide.tpNF --json conserva o formato de campo usado por help TAG: tem path, readonly e, quando declarado, declaredDefault. Para um tipo, describe TTipoNFe --json usa name, e não inclui esses três metadados de campo. Trecho do JSON de tipo na 0.2.2:

{
  "sdkVersion": "0.2.2",
  "name": "TTipoNFe",
  "kind": "enum",
  "pascalType": "TTipoNFe",
  "inputType": "string",
  "values": ["tnEntrada", "tnSaida"]
}

A resposta completa também registra origem e hashes. inputType descreve o transporte JSON; decimais, por exemplo, usam strings. Para automação, distinga o alvo de tipo (name) do alvo de campo (path).

Versão e ajuda por subcomando

Disponível a partir da 0.2.2:

npx --no-install acbr-node --version
npx --no-install acbr-node -V
npx --no-install acbr-node --version --json
npx --no-install acbr-node describe -h
npx --no-install acbr-node help TAG --help
npx --no-install acbr-node init --help
npx --no-install acbr-node source --help
npx --no-install acbr-node source update --help
npx --no-install acbr-node source lock --help
npx --no-install acbr-node generate --help
npx --no-install acbr-node build --help
npx --no-install acbr-node check --help
npx --no-install acbr-node doctor --help

--version e -V mostram acbr-node 0.2.2 nesta versão. Com --json, o resultado é { "version": "0.2.2" }. --help e -h descrevem o uso sem executar o subcomando: consultar source update --help, por exemplo, não acessa o SVN nem altera fontes.

Compatibilidade com help TAG

help TAG mantém sua interface anterior e continua exigindo um caminho de campo, inclusive na 0.2.2. Para consultar um tipo como TTipoNFe, use describe. A ajuda descrita aqui pertence à CLI.

npx --no-install acbr-node help TAG Ide.tpNF
npx --no-install acbr-node help TAG 'Det[].Imposto.PIS.CST' --json

Saída JSON

Use --json para automação:

npx --no-install acbr-node describe 'Ide.tpNF' --json
npx --no-install acbr-node describe 'Det[].Imposto.PIS.CST' --json

Trecho do resultado para Ide.tpNF na 0.2.2:

{
  "sdkVersion": "0.2.2",
  "sourceRevision": 48590,
  "path": "TNFe.Ide.tpNF",
  "kind": "enum",
  "pascalType": "TTipoNFe",
  "inputType": "string",
  "readonly": false,
  "declaredDefault": "tnSaida",
  "values": ["tnEntrada", "tnSaida"]
}

A resposta completa inclui formatVersion, root, hashes de origem e contrato e, conforme o alvo, typeReference, members, itemType e constraints. O campo PIS informa pascalType: "TCstPis" e typeReference: "TCSTPis", com 33 valores textuais, incluindo pis99. Preserve a capitalização devolvida em cada propriedade. Metadados ausentes não autorizam inferir limites ou padrões.

Para salvar a descrição no terminal:

npx --no-install acbr-node describe Ide.tpNF --json > campo.json

Caminhos e coleções

O prefixo TNFe. é opcional. Os nomes dos campos distinguem maiúsculas e minúsculas. Um nome de campo isolado só é aceito quando identifica um caminho único; nomes exatos de tipos são aceitos por describe.

npx --no-install acbr-node describe TNFe.Ide.tpNF
npx --no-install acbr-node describe Det
npx --no-install acbr-node describe 'Det[].Prod.vProd'
npx --no-install acbr-node describe 'TNFe.Det[0].Prod.DI[].adi[2].nAdicao' --json

Det descreve a coleção e seu tipo de item. Use [] ou um índice não negativo para consultar um elemento. Índices como [0] e [2] são normalizados para []; a ajuda não acessa itens de uma nota real.

Consulta com describe	Resultado na 0.2.2
Ide.tpNF	Enum TTipoNFe, valores e padrão do campo
Det[].Imposto.PIS.CST	Enum com tipo Pascal TCstPis e referência TCSTPis
CST	CAMPO_AMBIGUO, com os caminhos possíveis
Det.Imposto	COLECAO_REQUER_INDICE: usar []
Ide[]	CAMPO_NAO_COLECAO
Ide.dhEmi	CAMPO_INEXISTENTE: o modelo usa Ide.dEmi
TTipoNFe	Enum com valores tnEntrada e tnSaida, sem metadados de campo

Os caminhos descrevem o modelo JSON do SDK; não são XPath nem nomes de tags XML. Veja os modelos TypeScript para preencher a estrutura e os resultados XML para interpretar a saída do motor.

Erros e automação

Situação	Saída	Código de término
Consulta válida	Texto em stdout; com --json, JSON em stdout	0
Erro de consulta	Mensagem em stderr; com --json, JSON em stderr	1
Uso inválido de help TAG	Mensagem em stderr; com --json, diagnóstico USO_INVALIDO em stderr	1

describe segue os mesmos canais: sucesso em stdout e saída 0; erro de consulta ou uso em stderr e saída 1, com stdout vazio. describe TARGET --json também escreve o JSON de erro em stderr. --help e --version válidos terminam com 0.

Em um erro de consulta com --json, stdout fica vazio. Leia error.code no JSON de stderr; não use a mensagem em português como protocolo.

{
  "ok": false,
  "error": {
    "code": "COLECAO_REQUER_INDICE",
    "message": "Use [] ou um índice para consultar campos do elemento da coleção."
  }
}

--config e --revision não se aplicam à ajuda de campos nem ao describe: eles sempre leem o contrato instalado. Para erros das operações fiscais, consulte erros e recuperação.

Contrato e limites da ajuda

O gerador emite generated/acbr/contract.json do mesmo IR dos modelos TypeScript. O build verifica origem e hash e distribui dist/contract.json. A CLI confere metadados, lock e validador gerado antes de apresentar os campos.

A consulta funciona sem dependências opcionais: não lê configuração do consumidor, certificado, runtime, compilador, SVN ou rede. Para executar operações fiscais, mantenha os runtimes opcionais da instalação normal.

A ajuda não determina obrigatoriedade, regras tributárias, validade do XML ou autorização fiscal. Gere um XML sintético offline, depois trate assinatura, schema e homologação como etapas próprias.

Fontes da 0.2.2 publicada: pacote npm, metadados públicos do registro, guia de ajuda, CLI e descrição de campos e tipos. Para comparar a interface anterior, consulte o pacote 0.2.1 e sua CLI versionada. Preserve as licenças e a origem dos artefatos ao redistribuir o SDK.