--- title: "Inclusão de Nota Fiscal Completa" method: POST path: "/v1/vendas/nfe" tags: ["Vendas NF-e"] --- # Inclusão de Nota Fiscal Completa `POST /v1/vendas/nfe` ## Request - Base URL: `https://api.sankhya.com.br` - URL: `https://api.sankhya.com.br/v1/vendas/nfe` - Auth: API key in header `Authorization` Importa uma NF-e própria (modelo 55) já autorizada externamente (ex.: Magis5, Mercado Livre Full), gravando diretamente Cabeçalho, Itens, Financeiro e, opcionalmente, o XML autorizado. Restrições importantes desta operação: - **Sem transmissão à SEFAZ e sem recálculo de impostos** — os valores fiscais informados no payload são gravados como enviados. - **Sem validação de saldo de estoque** — o estoque é movimentado conforme a Tipo de Operação informada. - **Somente NF-e aprovada** (`statusNFe = "A"`) pode ser importada. - A `chaveNFe` não pode já existir em uma nota ativa nem em uma nota cancelada — chaves duplicadas são rejeitadas. - O somatório de `valorParcela` em `financeiros` deve fechar com `valorNota` (tolerância de 0,01). - Em `financeiros`, apenas os campos `tipoPagamento`, `dataVencimento`, `valorParcela` e `cartao` são processados por este endpoint; `cheque` e `idTransacao` são reservados para consulta (GET) e não são persistidos aqui. - Os totais do objeto `reformaTributaria` (IBS/CBS/IS) são calculados automaticamente a partir dos impostos informados em `itens[].impostos[]` — não é necessário (nem persistido) enviá-los no cabeçalho. - **Sem validação do XML enviado** — a API não valida chave de acesso, `cStat`, assinatura ou qualquer outro conteúdo do XML; apenas grava o XML recebido e, quando presente, extrai o protocolo de autorização (`protNFe`). ## Request body - NfeTransacaoCompleta: Schema de entrada do POST /v1/vendas/nfe (Cabeçalho + Cliente + Itens + Financeiro). Além dos campos abaixo, aceita campos livres do dicionário de dados do SankhyaOm: qualquer nome de coluna de TGFCAB enviado em UPPERCASE (ex.: `NUMCONTRATO`) é gravado diretamente. Para maior controle, é possível enviar os blocos `camposNativos` (colunas nativas de TGFCAB, chave:valor) e `camposAdicionais` (campos customizados prefixados com `AD_`). Quando o mesmo dado é enviado tanto em um atributo oficial (ex.: `baseICMS`) quanto em `camposNativos`/`camposAdicionais` (ex.: `BASEICMS`), o valor do atributo oficial prevalece. `baseICMS`, `valorICMS`, `valorIPI`, `valorPIS` e `valorCOFINS` são obrigatórios e espelham exatamente o valor enviado: a API não recalcula esses 5 totais a partir da soma dos itens, então a nota reflete fielmente o que o integrador informou (inclusive eventuais divergências de arredondamento). - `notaModelo` integer, required: Código da nota modelo (TGFCAB) usada como base para os valores padrão da negociação (empresa, natureza, etc.). - `dataNegociacao` string, required: Data da negociação, formato dd/MM/yyyy. - `numeroNota` integer - `serieNota` string - `codigoTipoOperacao` integer, required: Código da Tipo de Operação (TGFTOP). Define TIPMOV, se movimenta estoque (ATUALEST) e se a nota fica pendente. - `codigoTipoNegociacao` integer: Código do Tipo de Negociação (TGFTPV). Quando ausente, usa o valor da nota modelo. - `codigoNatureza` integer - `codigoCentroResultado` integer - `codigoProjeto` integer - `codigoContrato` integer - `codigoVendedor` integer - `codigoContato` integer: Código do Contato do Parceiro que contém o endereço de entrega da venda. - `codigoMoeda` integer - `valorMoeda` number, double - `cliente` ConsumidorCliente, required: Dados do cliente (parceiro) vinculado à NF-e. Campo obrigatório no cabeçalho. O parceiro é localizado por CPF/CNPJ (priorizando o ativo de menor CODPARC); se não for encontrado, é criado automaticamente com o tipo "cliente" habilitado. Além dos campos abaixo, é possível enviar diretamente atributos da entidade Parceiro (ex.: `CGCCPF` em vez de `cnpjCpf`). - `atualizar` boolean: Quando true, sobrescreve os dados cadastrais de um parceiro já existente. Quando false/ausente, os dados só são usados para localizar ou criar o parceiro. - `cnpjCpf` string: CPF (11 dígitos numéricos) ou CNPJ (14 caracteres) do parceiro. - `ieRg` string - `nome` string - `razao` string - `email` string - `telefoneDdd` string - `telefoneNumero` string - `endereco` Endereco - `entrega` boolean - `nomeContato` string - `email` string - `logradouro` string - `numero` string - `complemento` string - `bairro` string - `cidade` string - `codigoIbge` integer - `uf` string - `cep` string - `valorNota` number, double, required: Valor total da nota. O somatório de financeiros.valorParcela deve fechar com este valor (tolerância de 0,01). - `descontoTotal` number, double - `valorSeguro` number, double - `valorFrete` number, double - `valorDestaque` number, double - `codigoRemetente` integer - `codigoTransportadora` integer - `chaveNFe` string, required: Chave de acesso da NF-e (44 dígitos). Não pode existir em outra nota ativa nem em nota cancelada. - `statusNFe` 'A', required: Status da NF-e. Somente "A" (Aprovada) é aceito para importação por este endpoint. - `numeroProtocolo` string: Número do protocolo de autorização da SEFAZ. - `dataProtocoloNFe` string: Data/hora do protocolo de autorização. Aceita "dd/MM/yyyy HH:mm:ss" ou "dd/MM/yyyy". - `numeroAleatorioNFe` string - `loteNFe` string - `xmlNFe` string: XML autorizado da NF-e, em base64. É gravado exatamente como recebido (sem reformatar, reindentar ou reserializar) nos campos XML e XMLENVCLI. Quando o XML contém a tag protNFe, o trecho literal ... é extraído e gravado como protocolo de autorização; quando ausente (ou não puder ser extraído), a nota é incluída normalmente e o protocolo fica vazio. A API não valida a chave de acesso, o cStat nem qualquer outro conteúdo do XML — apenas grava e extrai o protocolo. - `itens` ItemNfe[], required: Itens da nota. Obrigatório informar ao menos um. - `sequencia` integer - `codigoProduto` integer - `descricaoProduto` string - `quantidade` number, double - `unidade` string - `valorUnitario` number, double - `valorTotal` number, double - `cfop` string - `ncm` string - `cst` string - `valorDesconto` number, double: Exige valorTotal maior que zero para cálculo do percentual de desconto do item. - `codigoLocalEstoque` integer: CODLOCALORIG. Local de estoque de origem do item, necessário quando existe controle de estoque por local. Essa informação deve ser obtida previamente pela entidade "Estoque" (CODLOCAL). Deve existir em TGFLOC; caso contrário, HTTP 404. Opcional: quando ausente, o local é resolvido pelo parâmetro com.local.padrao do usuário autenticado, desde que o produto use local (TGFPRO.USALOCAL) e o parâmetro com.utiliza.local esteja ativo; na sequência, pelo local padrão da empresa (TGFEMP.LOCALPAD) quando o parâmetro com.utiliza.local.padrao.fast estiver ativo. Sem nenhum deles, o item é gravado com local zero. - `valorICMS` number, double - `valorIPI` number, double - `impostos` Impostos[] - `tipo` 'icms' | 'icms-st' | 'ipi' | 'pis' | 'cofins' | 'ibs' | 'cbs' | 'is': icms, icms-st, ipi, pis e cofins gravam campos planos do item (TGFITE/TGFDIN); ibs, cbs e is gravam em TGFDIN como impostos de reforma tributária e alimentam a totalização automática do cabeçalho. Para tipo=icms, os atributos valorBaseReduzida, valorBaseFCP, percentualFCP, valorFCP, valorBaseDIFAL, valorBaseFCPInterno, percentualFCPInterno, valorFCPInterno, aliquotaInternaDestino, percentualPartilhaDIFAL, valorDIFALDestino e valorDIFALRemetente também são aceitos e gravados em TGFDIN (CODIMP=1), mas exigem que aliquota também seja informada: se qualquer um deles vier sem aliquota, a API rejeita com HTTP 400. - `cst` string - `tributacaoMunicipio` string - `classificacaoTributaria` integer - `aliquota` number, double - `aliquotaEfetivaRegular` number, double - `aliquotaUnidadeMedida` number, double - `aliquotaEfetivaBaseCalculo` number, double - `reducaoAliquota` number, double - `percentualFCP` number, double: Percentual do FCP. Para tipo=icms, grava TGFDIN.PERCFCP (CODIMP=1). - `valorBaseFCP` number, double: Base de cálculo do FCP do item. Para tipo=icms, grava TGFDIN.BASEFCP (CODIMP=1). - `valorBaseDIFAL` number, double: Base de cálculo do DIFAL do item. Para tipo=icms, grava TGFDIN.BASEDIFAL (CODIMP=1). - `valorBaseFCPInterno` number, double: Base de cálculo do FCP interno do item. Para tipo=icms, grava TGFDIN.BASEFCPINT (CODIMP=1). - `percentualFCPInterno` number, double: Percentual do FCP interno do item. Para tipo=icms, grava TGFDIN.PERCFCPINT (CODIMP=1). - `valorFCPInterno` number, double: Valor do FCP interno do item. Para tipo=icms, grava TGFDIN.VLRFCPINT (CODIMP=1). - `aliquotaInternaDestino` number, double: Alíquota interna do estado de destino. Para tipo=icms, grava TGFDIN.ALIQINTDEST (CODIMP=1). - `percentualPartilhaDIFAL` number, double: Percentual de partilha do DIFAL entre origem e destino. Para tipo=icms, grava TGFDIN.PERCPARTDIFAL (CODIMP=1). - `valorDIFALDestino` number, double: Valor do DIFAL devido ao estado de destino. Para tipo=icms, grava TGFDIN.VLRDIFALDEST (CODIMP=1). - `valorDIFALRemetente` number, double: Valor do DIFAL devido ao estado do remetente. Para tipo=icms, grava TGFDIN.VLRDIFALREM (CODIMP=1). - `percentualReducaoAliquotaGovernamental` number, double - `percentualDiferimento` number, double - `valorBase` number, double - `valorBaseReduzida` number, double: Base de cálculo reduzida do imposto. Para tipo=icms, grava TGFDIN.BASERED (CODIMP=1). O valor enviado é gravado como recebido, mesmo 0 (sem redução) — a API não assume BASERED = base cheia por conta própria. - `valorImposto` number, double - `valorFCP` number, double: Valor do FCP. Para tipo=icms, grava TGFDIN.VLRFCP (CODIMP=1). - `valorRegular` number, double - `valorDiferimento` number, double - `valorTributoDevolvido` number, double - `camposNativos` object: Colunas nativas adicionais de TGFITE, no formato { "NOMECOLUNA": valor }. - `camposAdicionais` object: Campos customizados (prefixo AD_) de TGFITE, no formato { "AD_CAMPO": valor }. - `financeiros` FinanceiroNfe[]: Parcelas financeiras da nota (títulos a vencer, sem baixa em caixa PDV). - `sequencia` integer - `tipoPagamento` integer - `cheque` Cheque - `codigoBarras` string - `banco` string - `agencia` string - `conta` string - `numero` integer - `nome` string - `cnpjCpf` string - `cartao` Cartao - `bandeira` '01' | '02' | '03' | '04' | '05' | '06' | '07' | '08' | '09' | '99' - `autorizacao` integer - `dataVencimento` string - `dataBaixa` string - `valorParcela` number, double - `idTransacao` string - `camposNativos` object: Colunas nativas adicionais de TGFFIN, no formato { "NOMECOLUNA": valor }. - `camposAdicionais` object: Campos customizados (prefixo AD_) de TGFFIN, no formato { "AD_CAMPO": valor }. - `observacao` string: Observação da nota (TGFCAB.OBSERVACAO). - `baseICMS` number, double, required: Base de cálculo do ICMS do cabeçalho (TGFCAB.BASEICMS). Obrigatório: o valor enviado é gravado como recebido, sem recálculo a partir da soma dos itens. - `baseICMSFrete` number, double: Base de cálculo do ICMS sobre o frete (TGFCAB.BASEICMSFRETE). - `valorICMS` number, double, required: Valor do ICMS do cabeçalho (TGFCAB.VLRICMS). Obrigatório: o valor enviado é gravado como recebido, sem recálculo a partir da soma dos itens. - `valorICMSFCP` number, double: Valor do FCP do ICMS do cabeçalho (TGFCAB.VLRICMSFCP). - `valorICMSFCPInterno` number, double: Valor do FCP interno do ICMS do cabeçalho (TGFCAB.VLRICMSFCPINT). - `valorSTFCPInterno` number, double: Valor do FCP interno da substituição tributária do cabeçalho (TGFCAB.VLRSTFCPINT). - `valorIPI` number, double, required: Valor do IPI do cabeçalho (TGFCAB.VLRIPI). Obrigatório: o valor enviado é gravado como recebido, sem recálculo a partir da soma dos itens. - `valorPIS` number, double, required: Valor do PIS do cabeçalho (TGFCAB.VLRPIS). Obrigatório: o valor enviado é gravado como recebido, sem recálculo a partir da soma dos itens. - `valorCOFINS` number, double, required: Valor do COFINS do cabeçalho (TGFCAB.VLRCOFINS). Obrigatório: o valor enviado é gravado como recebido, sem recálculo a partir da soma dos itens. - `valorICMSDIFALDestino` number, double: Valor do ICMS DIFAL devido ao estado de destino (TGFCAB.VLRICMSDIFALDEST). - `valorICMSDIFALRemetente` number, double: Valor do ICMS DIFAL devido ao estado do remetente (TGFCAB.VLRICMSDIFALREM). - `dataEntradaSaida` string: Data de entrada/saída da nota, formato dd/mm/aaaa (TGFCAB.DTENTSAI). - `pesoBruto` number, double: Peso bruto da nota (TGFCAB.PESOBRUTO). - `quantidadeVolumes` integer: Quantidade de volumes da nota (TGFCAB.QTDVOL). - `pesoLiquido` number, double: Peso líquido da nota (TGFCAB.PESO). - `indicadorIntermediador` 1 | 2: Indica se a venda ocorreu em plataforma de terceiros. Opções não iniciam em zero (convenção EasyAPI): 1 = operação sem intermediador (grava INTERMED=0); 2 = operação em site/plataforma de terceiros, marketplace (grava INTERMED=1). Qualquer valor diferente de 1 ou 2 é rejeitado com HTTP 400. - `codigoIntermediador` integer: Código do parceiro intermediador/canal de venda (TGFCAB.CODINTERM). Opcional mesmo com indicadorIntermediador=2. Deve corresponder a um parceiro existente; caso contrário, HTTP 400 com a mensagem "O parceiro Intermediador enviado nao foi encontrado". - `camposNativos` object: Colunas nativas adicionais de TGFCAB não cobertas pelos campos acima, no formato { "NOMECOLUNA": valor }. - `camposAdicionais` object: Campos customizados (prefixo AD_) de TGFCAB, no formato { "AD_CAMPO": valor }. ## Response `200` Nota fiscal importada com sucesso. - RetornoNfe - `codigoEmpresa` integer - `nomeEmpresa` string - `cliente` Cliente - `atualizar` boolean - `tipo` string - `cnpjCpf` string - `ieRg` string - `nome` string - `razao` string - `email` string - `telefoneDdd` string - `telefoneNumero` string - `endereco` Endereco - `entrega` boolean - `nomeContato` string - `email` string - `logradouro` string - `numero` string - `complemento` string - `bairro` string - `cidade` string - `codigoIbge` integer - `uf` string - `cep` string - `confirmada` boolean - `pendente` boolean - `statusWMS` integer - `situacaoWMS` integer - `statusConferencia` integer - `dataNegociacao` string - `dataHoraAlteracao` string - `numeroNota` integer - `codigoNota` integer - `serieNota` string - `codigoTipoNegociacao` integer - `nomeTipoNegociacao` string - `codigoTipoOperacao` integer - `nomeTipoOperacao` string - `codigoNatureza` integer - `nomeNatureza` string - `codigoCentroResultado` integer - `nomeCentroResultado` string - `codigoProjeto` integer - `nomeProjeto` string - `codigoContrato` integer - `codigoVendedor` integer - `nomeVendedor` string - `codigoContato` integer - `nomeContato` string - `codigoMoeda` integer - `nomeMoeda` string - `valorMoeda` number, double - `valorNota` number, double - `descontoTotal` number, double - `valorSeguro` number, double - `valorDestaque` number, double - `valorVendor` number, double - `valorJuro` number, double - `valorOutros` number, double - `valorEmbalagem` number, double - `valorFrete` number, double - `vencimentoFrete` string, date - `codigoOrdemCarga` integer - `codigoVeiculo` integer - `placaVeiculo` string - `codigoMotorista` integer - `nomeMotorista` string - `codigoTransportadora` integer - `nomeTransportadora` string - `codigoRemetente` integer - `nomeRemetente` string - `codigoDestinatario` integer - `nomeDestinatario` string - `quantidadeVolumes` integer - `numeracaoVolumes` string - `lacres` string - `pesoBruto` number, double - `cifFob` 1 | 2 | 3 | 4 | 5 | 6 - `tipoFrete` 1 | 2 - `baseICMSFrete` number, double - `icmsFrete` number, double - `chaveNFe` string - `statusNFe` string - `numeroProtocoloNFe` string - `dataProtocoloNFe` string, date-time - `numeroAleatorioNFe` string - `loteNFe` string - `numeroRegistroDPEC` string - `dataRegEPEC` string, date-time - `xmlNFe` string - `codigoPedidoOrigem` integer - `reformaTributaria` ReformaTributaria - `valorCreditoPresumido` number, double - `valorCreditoPresumidoSuspensivaCBS` number, double - `valorCreditoPresumidoSuspensivaIBS` number, double - `valorTotalImposto` number, double - `valorDevolucaoCBS` number, double - `valorDevolucaoTributosIBSUF` number, double - `valorDevolucaoTributosMunicipio` number, double - `valorDiferimento` number, double - `valorDiferimentoIBSUF` number, double - `valorDiferimentoMunicipioIBS` number, double - `valorIBSUF` number, double - `valorIBSMunicipio` number, double - `valorImpostoSeletivo` number, double - `valorBaseCalculo` number, double - `valorTotalDocumento` number, double - `itens` ItemNfe[] - `sequencia` integer - `codigoProduto` integer - `descricaoProduto` string - `quantidade` number, double - `unidade` string - `valorUnitario` number, double - `valorTotal` number, double - `cfop` string - `ncm` string - `cst` string - `valorDesconto` number, double: Exige valorTotal maior que zero para cálculo do percentual de desconto do item. - `codigoLocalEstoque` integer: CODLOCALORIG. Local de estoque de origem do item, necessário quando existe controle de estoque por local. Essa informação deve ser obtida previamente pela entidade "Estoque" (CODLOCAL). Deve existir em TGFLOC; caso contrário, HTTP 404. Opcional: quando ausente, o local é resolvido pelo parâmetro com.local.padrao do usuário autenticado, desde que o produto use local (TGFPRO.USALOCAL) e o parâmetro com.utiliza.local esteja ativo; na sequência, pelo local padrão da empresa (TGFEMP.LOCALPAD) quando o parâmetro com.utiliza.local.padrao.fast estiver ativo. Sem nenhum deles, o item é gravado com local zero. - `valorICMS` number, double - `valorIPI` number, double - `impostos` Impostos[] - `tipo` 'icms' | 'icms-st' | 'ipi' | 'pis' | 'cofins' | 'ibs' | 'cbs' | 'is': icms, icms-st, ipi, pis e cofins gravam campos planos do item (TGFITE/TGFDIN); ibs, cbs e is gravam em TGFDIN como impostos de reforma tributária e alimentam a totalização automática do cabeçalho. Para tipo=icms, os atributos valorBaseReduzida, valorBaseFCP, percentualFCP, valorFCP, valorBaseDIFAL, valorBaseFCPInterno, percentualFCPInterno, valorFCPInterno, aliquotaInternaDestino, percentualPartilhaDIFAL, valorDIFALDestino e valorDIFALRemetente também são aceitos e gravados em TGFDIN (CODIMP=1), mas exigem que aliquota também seja informada: se qualquer um deles vier sem aliquota, a API rejeita com HTTP 400. - `cst` string - `tributacaoMunicipio` string - `classificacaoTributaria` integer - `aliquota` number, double - `aliquotaEfetivaRegular` number, double - `aliquotaUnidadeMedida` number, double - `aliquotaEfetivaBaseCalculo` number, double - `reducaoAliquota` number, double - `percentualFCP` number, double: Percentual do FCP. Para tipo=icms, grava TGFDIN.PERCFCP (CODIMP=1). - `valorBaseFCP` number, double: Base de cálculo do FCP do item. Para tipo=icms, grava TGFDIN.BASEFCP (CODIMP=1). - `valorBaseDIFAL` number, double: Base de cálculo do DIFAL do item. Para tipo=icms, grava TGFDIN.BASEDIFAL (CODIMP=1). - `valorBaseFCPInterno` number, double: Base de cálculo do FCP interno do item. Para tipo=icms, grava TGFDIN.BASEFCPINT (CODIMP=1). - `percentualFCPInterno` number, double: Percentual do FCP interno do item. Para tipo=icms, grava TGFDIN.PERCFCPINT (CODIMP=1). - `valorFCPInterno` number, double: Valor do FCP interno do item. Para tipo=icms, grava TGFDIN.VLRFCPINT (CODIMP=1). - `aliquotaInternaDestino` number, double: Alíquota interna do estado de destino. Para tipo=icms, grava TGFDIN.ALIQINTDEST (CODIMP=1). - `percentualPartilhaDIFAL` number, double: Percentual de partilha do DIFAL entre origem e destino. Para tipo=icms, grava TGFDIN.PERCPARTDIFAL (CODIMP=1). - `valorDIFALDestino` number, double: Valor do DIFAL devido ao estado de destino. Para tipo=icms, grava TGFDIN.VLRDIFALDEST (CODIMP=1). - `valorDIFALRemetente` number, double: Valor do DIFAL devido ao estado do remetente. Para tipo=icms, grava TGFDIN.VLRDIFALREM (CODIMP=1). - `percentualReducaoAliquotaGovernamental` number, double - `percentualDiferimento` number, double - `valorBase` number, double - `valorBaseReduzida` number, double: Base de cálculo reduzida do imposto. Para tipo=icms, grava TGFDIN.BASERED (CODIMP=1). O valor enviado é gravado como recebido, mesmo 0 (sem redução) — a API não assume BASERED = base cheia por conta própria. - `valorImposto` number, double - `valorFCP` number, double: Valor do FCP. Para tipo=icms, grava TGFDIN.VLRFCP (CODIMP=1). - `valorRegular` number, double - `valorDiferimento` number, double - `valorTributoDevolvido` number, double - `camposNativos` object: Colunas nativas adicionais de TGFITE, no formato { "NOMECOLUNA": valor }. - `camposAdicionais` object: Campos customizados (prefixo AD_) de TGFITE, no formato { "AD_CAMPO": valor }. - `financeiros` FinanceiroNfe[] - `sequencia` integer - `tipoPagamento` integer - `cheque` Cheque - `codigoBarras` string - `banco` string - `agencia` string - `conta` string - `numero` integer - `nome` string - `cnpjCpf` string - `cartao` Cartao - `bandeira` '01' | '02' | '03' | '04' | '05' | '06' | '07' | '08' | '09' | '99' - `autorizacao` integer - `dataVencimento` string - `dataBaixa` string - `valorParcela` number, double - `idTransacao` string - `camposNativos` object: Colunas nativas adicionais de TGFFIN, no formato { "NOMECOLUNA": valor }. - `camposAdicionais` object: Campos customizados (prefixo AD_) de TGFFIN, no formato { "AD_CAMPO": valor }. ## Other responses - `400`: Erro de validação: campo obrigatório ausente, status diferente de aprovada, chave de NF-e duplicada, ou somatório do financeiro divergente do valor da nota. - `401`: Não autorizado. - `404`: Produto ou local de estoque informado em um item não foi localizado. - `500`: Erro interno. ## Changes - **2026-11-03** `b3c833e7aab1`: 1 info - endpoint added [Operation history](https://skmtc.dev/sankhya/apis/api-sankhya/changes/v1/vendas/nfe/post.md) --- [API](https://skmtc.dev/sankhya/apis/api-sankhya.md) - [All operations](https://skmtc.dev/sankhya/apis/api-sankhya/llms.txt) - [OpenAPI document](https://skmtc.dev/sankhya/apis/api-sankhya/revisions/b3c833e7aab1?raw)