Emissão de NF-e

Todas as UFs. A emissão funciona em qualquer estado: a Sudrel prepara a UF da sua empresa em minutos, a partir do cadastro, sem ação sua. Onde o texto cita a Bahia, é a UF dos exemplos e das regras já detalhadas.

Emita NF-e (modelo 55) com as mesmas convenções da NFS-e: Idempotency-Key, referencia única por empresa, Prefer: wait, erros em Problem Details, ajustes, regras_versao, cursor de eventos e webhooks assinados. Quem já integrou NFS-e não reaprende nada.

Três modos, escolhidos em modo:

• informado (padrão): os tributos vêm prontos do seu ERP. Você manda, em cada item, os grupos de ICMS, IPI, PIS, COFINS e IBS/CBS já calculados; a Sudrel confere os totais contra a soma dos itens, valida no esquema oficial da SEFAZ antes de assinar, assina com o certificado A1 da empresa, transmite e acompanha.
• calcular: cada item traz só produto (o código cadastrado em /v1/produtos), quantidade e valor; o motor fiscal da Sudrel resolve CFOP e tributos e explica cada valor em ajustes (regra, versão e fonte legal). Veja Produtos e motor fiscal.
• conferir: você manda os valores, como no informado, mais o produto de cada item; a Sudrel calcula ao lado e devolve as diferenças em ajustes.

Uma nota nunca vira duas. A chave de acesso é gravada antes do envio. Se a resposta da SEFAZ não chega (timeout, queda), a nota fica aguardando_confirmacao e a Sudrel consulta a chave na SEFAZ: só reenvia, e o MESMO XML, se a SEFAZ disser que a nota não existe. Duplicidade (204) não é erro para você: a consulta resolve.

O que é obrigatório

Campo	Modo informado	Modo calcular
empresa_id	Sim (dispensado com chave restrita a uma empresa)	Igual
referencia	Não, mas mande: é por ela que você consulta e evita nota dobrada	Igual
natureza_operacao	Sim	Não: vem do catálogo de operações
presenca	Sim	Sim
destinatario.documento	Sim	Sim
destinatario.nome	Com CPF. Com CNPJ, vem da Receita	Igual
destinatario.endereco	Com CPF, só cep e numero. Com CNPJ, vem da Receita	Igual
destinatario.inscricao_estadual	Só com contribuinte: "contribuinte". Sem contribuinte, a Sudrel consulta a SEFAZ	Igual
Item	codigo, descricao, ncm, cfop, origem, unidade, quantidade, valor_unitario, icms, pis e cofins	produto, quantidade e valor_unitario
pagamentos	Ao menos um, com forma e valor (descricao na forma outros)	Ao menos um; se for um só, o valor pode faltar (vira o valor da nota)
totais	Não: somados dos itens	Não

Conforme a operacao (modos calcular e conferir; no informado, o CFOP e a finalidade que você manda já dizem a operação):

operacao	Exige a mais	Tributos
venda (padrão), venda_consumidor_final, bonificacao	Nada	Calculados
remessa	subtipo: conserto, demonstracao, industrializacao ou outras	No modo informado: o catálogo resolve CFOP e natureza, o motor não calcula remessa
transferencia	Nada	No modo informado
devolucao	chave_referenciada (44 caracteres) e subtipo comercializacao (padrão) ou industrializacao	No modo informado: mande a mesma chave_referenciada e finalidade: "devolucao", com os tributos da nota de origem. No conferir, a nota segue com os seus valores, sem conferência

No modo informado, a finalidade decide se a nota de origem é obrigatória: devolucao e complementar exigem chave_referenciada (sem ela, 422 chave_referenciada_obrigatoria); normal e ajuste aceitam, sem exigir. A Sudrel confere o tamanho e o dígito verificador antes de enviar e põe a chave onde a SEFAZ pede: na devolução, em cada item (det/DFeReferenciado, com o item_referenciado quando você informa); nas outras finalidades, na nota (NFref/refNFe). As duas juntas a SEFAZ recusa (rejeição 1010).

O que falta ou está errado volta junto, num 422 validacao, cada erro com o campo (JSON Pointer), a mensagem e a correcao.

Sandbox e produção

• Chave sdr_test_: emite de verdade na homologação da SEFAZ (tpAmb 2), com o certificado real da empresa, sem valor fiscal e sem cobrança, em qualquer UF. O nome do destinatário sai como a SEFAZ exige em homologação.
• Chave sdr_live_: emite na produção da SEFAZ (tpAmb 1), com valor fiscal. O pedido, a resposta e os webhooks são os mesmos da homologação.

Status

Status	O que significa
transmitindo	Estamos cuidando: na fila ou enviando. Não reenvie.
aguardando_confirmacao	A nota foi enviada e a resposta da SEFAZ não chegou. A Sudrel está consultando a chave; nenhuma nota nova é criada e você não precisa fazer nada.
autorizada	NF-e autorizada. protocolo, chave_acesso, XML e DANFE disponíveis.
rejeitada	A SEFAZ recusou. rejeicao traz o cStat, a mensagem da SEFAZ e, quando conhecida, a explicação em português. O número continua seu: corrija por POST /v1/nfe/{id}/correcao.
denegada	Uso denegado pela SEFAZ (irregularidade fiscal). O número foi consumido e a nota não pode ser usada.
cancelada	Cancelada depois de autorizada. Protocolo em cancelamento.
descartada	Você desistiu da nota (ou a Sudrel descartou uma rejeitada esquecida). O número é inutilizado.
contingencia_epec	A SEFAZ da UF estava fora e a nota entrou em contingência por EPEC: o evento foi registrado no Ambiente Nacional e o DANFE já vale. A NF-e vai à UF quando ela voltar (veja Contingência da NF-e).

Equivalência com o status interno: PENDENTE e TRANSMITINDO são transmitindo; AGUARDANDO_CONFIRMACAO, AUTORIZADA, DENEGADA, REJEITADA, DESCARTADA e CANCELADA têm o mesmo nome em minúsculas; EPEC_REGISTRADO é contingencia_epec. Na NFS-e, aguardando_confirmacao pede a sua confirmação; na NF-e, é a Sudrel confirmando com a SEFAZ.

O que a Sudrel preenche (ajustes)

regra	O que foi feito
nfe_modo_informado	Sem modo: tributos informados por você.
nfe_serie_da_origem	Sem serie: a série da API desta empresa (cada canal tem a sua).
nfe_destino_operacao	Operação interna, interestadual ou com o exterior, pelas UFs.
nfe_totais_somados	Totais que você não mandou, somados dos itens.
nfe_valor_total_item	Valor do item: quantidade vezes valor unitário.
nfe_sem_gtin	Produto sem código de barras: "SEM GTIN".
nfe_transporte_sem_frete	Sem transporte: "sem frete".
nfe_tipo_operacao_saida	Sem tipo_operacao: saída.
nfe_finalidade_normal	Sem finalidade: NF-e normal.
nfe_ibs_soma_uf_municipio	IBS do item: soma da parcela da UF com a do município.
nfe_totais_ibs_cbs_somados	Totais de IBS e CBS que você não mandou, somados dos itens.
nfe_correcao_<cStat>	Correção automática feita depois de uma rejeição conhecida.
nfe_destinatario_homologacao	No sandbox, o nome do destinatário é a literal da SEFAZ.
nfe_autxml_escritorio	Na BA, o escritório de contabilidade da empresa no grupo autXML (exigência da UF).
nfe_autxml_sefaz_sem_escritorio	Na BA, sem escritório vinculado: o CNPJ da SEFAZ-BA.
nfe_autxml_sefaz_apos_487	A SEFAZ recusou o escritório (487); a nota foi refeita com o CNPJ da SEFAZ.
nfe_indintermed_padrao	Indicativo de intermediador "sem intermediador", quando a presença exige.
nfe_autxml_sefaz_escritorio_recusado	A SEFAZ já tinha recusado o escritório desta empresa (487): a nota saiu direto com o CNPJ da SEFAZ, sem uma ida rejeitada.
nfe_operacao_venda	Modos calcular e conferir, sem operacao: venda.
nfe_natureza_da_operacao	Natureza da operação do catálogo de operações.
nfe_pagamento_valor_da_nota	Modo calcular, um pagamento sem valor: o valor da nota calculada.
nfe_conferencia_divergencia	Modo conferir: o valor informado difere do calculado (acao: "divergente").
nfe_conferencia_fora_de_cobertura	Modo conferir: o item não foi conferido porque está fora da cobertura do motor.

No modo calcular, cada valor calculado entra em ajustes com acao: "calculado", a regra (por exemplo icms_ba_ai_geral_2024, ipi_aliquota_tipi, pis_cofins_base_sem_icms, ibs_cbs_calculadora_oficial), o valor, a versao da regra ou da tabela e a fonte legal.

Cancelamento e carta de correção

Cancelamento até 24 horas depois da autorização (regra nacional). Fora do prazo, a resposta é 422 cancelamento_fora_do_prazo: só resta o cancelamento extemporâneo, pedido pelo contribuinte na SEFAZ. Na Bahia não existe cancelamento extemporâneo (RICMS/BA, art. 92): se a mercadoria não circulou, o caminho é uma NF-e de entrada ou saída de regularização em até 60 dias, com a chave da nota incorreta referenciada; a resposta do 422 já diz isso. A carta de correção (até 20 por nota) não corrige valores, quantidade, base de cálculo, alíquota, dados que mudem o remetente ou o destinatário, nem a data de emissão ou de saída. A Sudrel não lê o texto: a resposta traz esse aviso, sem bloquear.

Numeração

Cada canal (API, planilha, painel) tem a sua série, e o número só é reservado quando a nota é criada (validação e prévia nunca reservam). Rejeitada esquecida vira descartada sozinha antes do prazo legal de inutilização, com o webhook NFE_DESCARTE_PROXIMO alguns dias antes. A Sudrel inutiliza sozinha os números que ela mesma perdeu; GET /v1/nfe/inutilizacoes mostra o que foi inutilizado e por quê.