Área do desenvolvedorComunidadeMarketplaceUniversidade
Documentação API

Inclusão de Nota Fiscal Completa

post
https://api.sankhya.com.br/v1/vendas/nfe

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).
Recent Requests
Log in to see full request history
TimeStatusUser Agent
Retrieving recent requests…
LoadingLoading…
Body Params

Objeto completo da nota fiscal para inclusão.

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

integer
required

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

string
required

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

integer
string
integer
required

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

integer

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

integer
integer
integer
integer
integer
integer

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

integer
double
cliente
object
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).

double
required

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

double
double
double
double
integer
integer
string
required

Chave de acesso da NF-e (44 dígitos). Não pode existir em outra nota ativa nem em nota cancelada.

string
enum
required

Status da NF-e. Somente "A" (Aprovada) é aceito para importação por este endpoint.

Allowed:
string

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

string

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

string
string
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
array of objects
required
length ≥ 1

Itens da nota. Obrigatório informar ao menos um.

itens*
integer
integer
string
double
string
double
double
string
string
string
double

Exige valorTotal maior que zero para cálculo do percentual de desconto do item.

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.

double
double
impostos
array of objects
impostos
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
array of objects

Parcelas financeiras da nota (títulos a vencer, sem baixa em caixa PDV).

financeiros
string

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

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.

double

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

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.

double

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

double

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

double

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

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.

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.

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.

double

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

double

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

string

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

double

Peso bruto da nota (TGFCAB.PESOBRUTO).

integer

Quantidade de volumes da nota (TGFCAB.QTDVOL).

double

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

integer
enum

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.

Allowed:
int64

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

Responses

401

Não autorizado.

500

Erro interno.

Updated 2 days ago

Did this page help you?
Language
Credentials
Header
URL
LoadingLoading…
Response
Click Try It! to start a request and see the response here! Or choose an example:
application/json

Updated 2 days ago

Did this page help you?