SAsankhya
Vendas NF-e

Inclusão de Nota Fiscal Completa

Changed on

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).
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

Request body

notaModelointeger required

Código da nota modelo (TGFCAB) usada como base para os valores padrão da negociação (empresa, natureza, etc.).

dataNegociacaostring required

Data da negociação, formato dd/MM/yyyy.

numeroNotainteger
serieNotastring
codigoTipoOperacaointeger required

Código da Tipo de Operação (TGFTOP). Define TIPMOV, se movimenta estoque (ATUALEST) e se a nota fica pendente.

codigoTipoNegociacaointeger

Código do Tipo de Negociação (TGFTPV). Quando ausente, usa o valor da nota modelo.

codigoNaturezainteger
codigoCentroResultadointeger
codigoProjetointeger
codigoContratointeger
codigoVendedorinteger
codigoContatointeger

Código do Contato do Parceiro que contém o endereço de entrega da venda.

codigoMoedainteger
valorMoedanumber double
valorNotanumber double required

Valor total da nota. O somatório de financeiros.valorParcela deve fechar com este valor (tolerância de 0,01).

descontoTotalnumber double
valorSeguronumber double
valorFretenumber double
valorDestaquenumber double
codigoRemetenteinteger
codigoTransportadorainteger
chaveNFestring 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.

numeroProtocolostring

Número do protocolo de autorização da SEFAZ.

dataProtocoloNFestring

Data/hora do protocolo de autorização. Aceita "dd/MM/yyyy HH:mm:ss" ou "dd/MM/yyyy".

numeroAleatorioNFestring
loteNFestring
xmlNFestring

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 <protNFe>...</protNFe> é 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.

observacaostring

Observação da nota (TGFCAB.OBSERVACAO).

baseICMSnumber 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.

baseICMSFretenumber double

Base de cálculo do ICMS sobre o frete (TGFCAB.BASEICMSFRETE).

valorICMSnumber 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.

valorICMSFCPnumber double

Valor do FCP do ICMS do cabeçalho (TGFCAB.VLRICMSFCP).

valorICMSFCPInternonumber double

Valor do FCP interno do ICMS do cabeçalho (TGFCAB.VLRICMSFCPINT).

valorSTFCPInternonumber double

Valor do FCP interno da substituição tributária do cabeçalho (TGFCAB.VLRSTFCPINT).

valorIPInumber 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.

valorPISnumber 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.

valorCOFINSnumber 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.

valorICMSDIFALDestinonumber double

Valor do ICMS DIFAL devido ao estado de destino (TGFCAB.VLRICMSDIFALDEST).

valorICMSDIFALRemetentenumber double

Valor do ICMS DIFAL devido ao estado do remetente (TGFCAB.VLRICMSDIFALREM).

dataEntradaSaidastring

Data de entrada/saída da nota, formato dd/mm/aaaa (TGFCAB.DTENTSAI).

pesoBrutonumber double

Peso bruto da nota (TGFCAB.PESOBRUTO).

quantidadeVolumesinteger

Quantidade de volumes da nota (TGFCAB.QTDVOL).

pesoLiquidonumber double

Peso líquido da nota (TGFCAB.PESO).

indicadorIntermediador1 | 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.

codigoIntermediadorinteger

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".

camposNativosobject

Colunas nativas adicionais de TGFCAB não cobertas pelos campos acima, no formato { "NOMECOLUNA": valor }.

camposAdicionaisobject

Campos customizados (prefixo AD_) de TGFCAB, no formato { "AD_CAMPO": valor }.

Example request

{
  "notaModelo": 45941,
  "dataNegociacao": "15/06/2024",
  "numeroNota": 254100,
  "serieNota": "1",
  "codigoTipoOperacao": 1200,
  "codigoTipoNegociacao": 110,
  "codigoNatureza": 30100,
  "codigoCentroResultado": 10100,
  "codigoProjeto": 202401,
  "codigoContrato": 4502,
  "codigoVendedor": 55,
  "codigoContato": 5,
  "cliente": {
    "cnpjCpf": "12315914799",
    "ieRg": "12315914799",
    "nome": "José da Silva",
    "razao": "José da Silva ME",
    "email": "contato@provedor.com.br",
    "telefoneDdd": "34",
    "telefoneNumero": "912349966",
    "endereco": {
      "entrega": true,
      "nomeContato": "Maria Roberta",
      "email": "maria.roberta@provedor.com.br",
      "logradouro": "Rua Maria Roberta",
      "numero": "10",
      "complemento": "Apto 104",
      "bairro": "Centro",
      "cidade": "Uberlândia",
      "codigoIbge": 11155566,
      "uf": "MG",
      "cep": "38400000"
    }
  },
  "valorNota": 5450,
  "descontoTotal": 250,
  "valorSeguro": 45,
  "valorFrete": 180,
  "codigoRemetente": 1,
  "codigoTransportadora": 800,
  "chaveNFe": "35240612345678000199550010000125401002541002",
  "statusNFe": "A",
  "numeroProtocolo": "135240008899774",
  "dataProtocoloNFe": "15/06/2024 10:30:00",
  "numeroAleatorioNFe": "98765432",
  "loteNFe": "20240055",
  "xmlNFe": "PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz48bmZlUHJvYyB2ZXJzaW9uPSI0LjAwIiB4bWxucz0iaHR0cDovL3d3dy5wb3J0YWxmaXNjYWwuaW5mLmJyL25mZSI+Li4uPC9uZmVQcm9jPg==",
  "itens": [
    {
      "sequencia": 1,
      "codigoProduto": 1050,
      "descricaoProduto": "Notebook Gamer i7 16GB",
      "quantidade": 2,
      "unidade": "UN",
      "valorUnitario": 2500,
      "valorTotal": 5000,
      "cfop": "5101",
      "ncm": "84714100",
      "cst": "000",
      "valorDesconto": 100,
      "codigoLocalEstoque": 2,
      "valorICMS": 900,
      "valorIPI": 250,
      "impostos": [
        {
          "tipo": "ibs",
          "cst": "00",
          "tributacaoMunicipio": "140801",
          "classificacaoTributaria": 200,
          "aliquota": 26.5,
          "aliquotaEfetivaRegular": 26.5,
          "aliquotaEfetivaBaseCalculo": 26.5,
          "valorBaseDIFAL": 43.64,
          "aliquotaInternaDestino": 19.5,
          "percentualPartilhaDIFAL": 100,
          "valorDIFALDestino": 6.76,
          "percentualReducaoAliquotaGovernamental": 60,
          "percentualDiferimento": 10,
          "valorBase": 1000,
          "valorImposto": 106,
          "valorRegular": 106,
          "valorDiferimento": 10.6
        }
      ]
    }
  ],
  "financeiros": [
    {
      "sequencia": 1,
      "tipoPagamento": 19,
      "cheque": {
        "codigoBarras": "341067330330018805201725766099",
        "banco": "341",
        "agencia": "0673",
        "conta": "576609",
        "numero": 1880,
        "nome": "José da Silva Souza",
        "cnpjCpf": "14532515955"
      },
      "cartao": {
        "bandeira": "02",
        "autorizacao": 4581596
      },
      "dataVencimento": "30/05/2024",
      "dataBaixa": "30/05/2024",
      "valorParcela": 3.38,
      "idTransacao": "dadotiuiwnlkeuhcnhlahdiwlaoaokd48ge55x"
    }
  ],
  "observacao": "Exemplo de envio",
  "baseICMS": 43.64,
  "valorICMS": 1.75,
  "valorPIS": 0.72,
  "valorCOFINS": 3.32,
  "valorICMSDIFALDestino": 6.76,
  "dataEntradaSaida": "07/09/2026",
  "pesoBruto": 0.25,
  "quantidadeVolumes": 1,
  "pesoLiquido": 0.25,
  "indicadorIntermediador": 1,
  "codigoIntermediador": 19002
}

Response

Nota fiscal importada com sucesso.

codigoEmpresainteger
nomeEmpresastring
confirmadaboolean
pendenteboolean
statusWMSinteger
situacaoWMSinteger
statusConferenciainteger
dataNegociacaostring
dataHoraAlteracaostring
numeroNotainteger
codigoNotainteger
serieNotastring
codigoTipoNegociacaointeger
nomeTipoNegociacaostring
codigoTipoOperacaointeger
nomeTipoOperacaostring
codigoNaturezainteger
nomeNaturezastring
codigoCentroResultadointeger
nomeCentroResultadostring
codigoProjetointeger
nomeProjetostring
codigoContratointeger
codigoVendedorinteger
nomeVendedorstring
codigoContatointeger
nomeContatostring
codigoMoedainteger
nomeMoedastring
valorMoedanumber double
valorNotanumber double
descontoTotalnumber double
valorSeguronumber double
valorDestaquenumber double
valorVendornumber double
valorJuronumber double
valorOutrosnumber double
valorEmbalagemnumber double
valorFretenumber double
vencimentoFretestring date
codigoOrdemCargainteger
codigoVeiculointeger
placaVeiculostring
codigoMotoristainteger
nomeMotoristastring
codigoTransportadorainteger
nomeTransportadorastring
codigoRemetenteinteger
nomeRemetentestring
codigoDestinatariointeger
nomeDestinatariostring
quantidadeVolumesinteger
numeracaoVolumesstring
lacresstring
pesoBrutonumber double
cifFob1 | 2 | 3 | 4 | 5 | 6
tipoFrete1 | 2
baseICMSFretenumber double
icmsFretenumber double
chaveNFestring
statusNFestring
numeroProtocoloNFestring
dataProtocoloNFestring date-time
numeroAleatorioNFestring
loteNFestring
numeroRegistroDPECstring
dataRegEPECstring date-time
xmlNFestring
codigoPedidoOrigeminteger

Example response

{
  "codigoEmpresa": 1,
  "nomeEmpresa": "Sankhya Gestão de Negócios Matriz",
  "cliente": {
    "tipo": "PF",
    "cnpjCpf": "12315914799",
    "ieRg": "12315914799",
    "nome": "José da Silva",
    "razao": "José da Silva ME",
    "email": "contato@provedor.com.br",
    "telefoneDdd": "34",
    "telefoneNumero": "912349966",
    "endereco": {
      "entrega": true,
      "nomeContato": "Maria Roberta",
      "email": "maria.roberta@provedor.com.br",
      "logradouro": "Rua Maria Roberta",
      "numero": "10",
      "complemento": "Apto 104",
      "bairro": "Centro",
      "cidade": "Uberlândia",
      "codigoIbge": 11155566,
      "uf": "MG",
      "cep": "38400000"
    }
  },
  "confirmada": true,
  "statusWMS": 2,
  "situacaoWMS": 17,
  "statusConferencia": 6,
  "dataNegociacao": "15/06/2024",
  "dataHoraAlteracao": "15/06/2024 14:45:30",
  "numeroNota": 254100,
  "codigoNota": 12540,
  "serieNota": "1",
  "codigoTipoNegociacao": 110,
  "nomeTipoNegociacao": "Venda de Mercadoria Nacional",
  "codigoTipoOperacao": 1200,
  "nomeTipoOperacao": "Venda Estadual de Produção Própria",
  "codigoNatureza": 30100,
  "nomeNatureza": "Venda de Produção do Estabelecimento",
  "codigoCentroResultado": 10100,
  "nomeCentroResultado": "Departamento Comercial SP",
  "codigoProjeto": 202401,
  "nomeProjeto": "Expansão Sudeste 2024",
  "codigoContrato": 4502,
  "codigoVendedor": 55,
  "nomeVendedor": "Carlos Eduardo Silva",
  "codigoContato": 302,
  "nomeContato": "Maria Paula",
  "nomeMoeda": "Real",
  "valorNota": 5450,
  "descontoTotal": 250,
  "valorSeguro": 45,
  "valorOutros": 85,
  "valorEmbalagem": 20,
  "valorFrete": 180,
  "vencimentoFrete": "2024-07-15",
  "codigoOrdemCarga": 995512,
  "codigoVeiculo": 45,
  "placaVeiculo": "ABC-1234",
  "codigoMotorista": 102,
  "nomeMotorista": "Roberto Mendes",
  "codigoTransportadora": 800,
  "nomeTransportadora": "Expresso Logística Rápida",
  "codigoRemetente": 1,
  "nomeRemetente": "Sankhya Gestão de Negócios Matriz",
  "codigoDestinatario": 20500,
  "nomeDestinatario": "Tech Solutions Comercio e Servicos LTDA",
  "quantidadeVolumes": 12,
  "numeracaoVolumes": "1/12 a 12/12",
  "lacres": "LACRE-001254",
  "pesoBruto": 245.5,
  "cifFob": 1,
  "tipoFrete": 2,
  "baseICMSFrete": 180,
  "icmsFrete": 21.6,
  "chaveNFe": "35240612345678000199550010000125401002541002",
  "statusNFe": "5",
  "numeroProtocoloNFe": "135240008899774",
  "dataProtocoloNFe": "2024-06-15T10:30:00",
  "numeroAleatorioNFe": "98765432",
  "loteNFe": "20240055",
  "numeroRegistroDPEC": "998877",
  "dataRegEPEC": "2024-06-15T09:00:00",
  "xmlNFe": "PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz48bmZlUHJvYyB2ZXJzaW9uPSI0LjAwIiB4bWxucz0iaHR0cDovL3d3dy5wb3J0YWxmaXNjYWwuaW5mLmJyL25mZSI+Li4uPC9uZmVQcm9jPg==",
  "codigoPedidoOrigem": 15420,
  "reformaTributaria": {
    "valorTotalImposto": 1325,
    "valorIBSUF": 662.5,
    "valorIBSMunicipio": 150,
    "valorBaseCalculo": 5000,
    "valorTotalDocumento": 6325
  },
  "itens": [
    {
      "sequencia": 1,
      "codigoProduto": 1050,
      "descricaoProduto": "Notebook Gamer i7 16GB",
      "quantidade": 2,
      "unidade": "UN",
      "valorUnitario": 2500,
      "valorTotal": 5000,
      "cfop": "5101",
      "ncm": "84714100",
      "cst": "000",
      "valorDesconto": 100,
      "codigoLocalEstoque": 2,
      "valorICMS": 900,
      "valorIPI": 250,
      "impostos": [
        {
          "tipo": "ibs",
          "cst": "00",
          "tributacaoMunicipio": "140801",
          "classificacaoTributaria": 200,
          "aliquota": 26.5,
          "aliquotaEfetivaRegular": 26.5,
          "aliquotaEfetivaBaseCalculo": 26.5,
          "valorBaseDIFAL": 43.64,
          "aliquotaInternaDestino": 19.5,
          "percentualPartilhaDIFAL": 100,
          "valorDIFALDestino": 6.76,
          "percentualReducaoAliquotaGovernamental": 60,
          "percentualDiferimento": 10,
          "valorBase": 1000,
          "valorImposto": 106,
          "valorRegular": 106,
          "valorDiferimento": 10.6
        }
      ]
    }
  ],
  "financeiros": [
    {
      "sequencia": 1,
      "tipoPagamento": 19,
      "cheque": {
        "codigoBarras": "341067330330018805201725766099",
        "banco": "341",
        "agencia": "0673",
        "conta": "576609",
        "numero": 1880,
        "nome": "José da Silva Souza",
        "cnpjCpf": "14532515955"
      },
      "cartao": {
        "bandeira": "02",
        "autorizacao": 4581596
      },
      "dataVencimento": "30/05/2024",
      "dataBaixa": "30/05/2024",
      "valorParcela": 3.38,
      "idTransacao": "dadotiuiwnlkeuhcnhlahdiwlaoaokd48ge55x"
    }
  ]
}

Changes