NF-e

Criar NF-e

Cria uma NF-e (nota de produto, modelo 55) e a enfileira para emissão junto à SEFAZ. A emissão é assíncrona: a resposta 2xx confirma que a solicitação foi aceita, não que a nota foi autorizada — acompanhe o resultado por webhook ou consulta.

integrationId — Identificador da nota no seu sistema (máx. 36 caracteres). Recomendado em todas as integrações:

  • Associação: vincula a NF-e gerada pela Spedy a um ID do seu sistema (ex: ID do pedido)
  • Idempotência: um segundo POST com o mesmo integrationId atualiza a nota existente em vez de criar uma nova — protege contra duplicidade em retries e timeouts
  • Correção de rejeitada: para corrigir uma NF-e rejeitada, reenvie o POST com os dados corrigidos e o mesmo integrationId — sem necessidade de deletar a nota anterior
post/v1/product-invoices

Request

  • Base URL: https://api.spedy.com.br (the document declares no server; this is the origin it was published from)
  • URL: https://api.spedy.com.br/v1/product-invoices
  • Auth: API key in header X-Api-Key

Request body

integrationIdstring nullable

Identificador único da nota fiscal no sistema do cliente (máx. 36 caracteres).

effectiveDatestring date-time

Data de emissão [dhEmi].

Opcional: se omitida, é usada a data e hora em que a emissão é solicitada.

numberinteger nullable

Número da nota [nNF].

Opcional: se omitido, é usado o próximo número configurado na empresa.

additionalInformationstring nullable

Informações adicionais [infCpl]

sendEmailToCustomerboolean

Enviar e-mail para o cliente / tomador

issueboolean

Define se a nota é emitida ao ser criada. Padrão true.

  • true: a nota é criada e enfileirada para emissão (status enqueued).
  • false: a nota fica como rascunho (status created), sem consumir numeração nem transmitir — permite gerar a pré-visualização do PDF. Para emitir depois, use «Reemitir nota fiscal».
seriesstring nullable

Série [serie]

printingType'none' | 'portrait' | 'landscape' | 'simplified' | 'consumerInvoice' | 'electronicMessage'

Formato de impressão do DANFE<p>Valores possíveis:</p>

<ul> <li><b>none</b>: Sem geração de DANFE</li> <li><b>portrait</b>: Retrato (orientação vertical)</li> <li><b>landscape</b>: Paisagem (orientação horizontal)</li> <li><b>simplified</b>: Simplificado</li> <li><b>consumerInvoice</b>: DANFE NFC-e (cupom fiscal eletrônico)</li> <li><b>electronicMessage</b>: Mensagem eletrônica</li> </ul>
operationType'incoming' | 'outgoing'

Tipo de operação da nota fiscal<p>Valores possíveis:</p>

<ul> <li><b>incoming</b>: Entrada</li> <li><b>outgoing</b>: Saída</li> </ul>
purposeType'normal' | 'complement' | 'adjustment' | 'devolution' | 'credit' | 'debit'
<p>Valores possíveis:</p> <ul> <li><b>normal</b>: Normal</li> <li><b>complement</b>: Complemento</li> <li><b>adjustment</b>: Ajustamento</li> <li><b>devolution</b>: Devolução</li> <li><b>credit</b>: Crédito</li> <li><b>debit</b>: Débito</li> </ul>
operationNaturestring nullable

Natureza de Operação [natOp]

operationDatestring date-time nullable

Data da Operação [dhSaiEnt]

destination'internal' | 'interstate' | 'international'
<p>Valores possíveis:</p> <ul> <li><b>internal</b>: Interna</li> <li><b>interstate</b>: Interestadual</li> <li><b>international</b>: Exterior</li> </ul>
presenceType'none' | 'presence' | 'internet' | 'telephone' | 'delivery' | 'othersNonPresenceOperation'

Indicador de presença do comprador no estabelecimento comercial<p>Valores possíveis:</p>

<ul> <li><b>none</b>: Não se aplica (ex: NF-e complementar ou de ajuste)</li> <li><b>presence</b>: Operação presencial</li> <li><b>internet</b>: Operação não presencial via Internet</li> <li><b>telephone</b>: Operação não presencial via teleatendimento</li> <li><b>delivery</b>: Entrega em domicílio (NFC-e)</li> <li><b>othersNonPresenceOperation</b>: Operação não presencial — outros</li> </ul>
authorizedPersonsstring[] nullable

Pessoas autorizadas a acessar o XML da nota na SEFAZ [autXML] (máx. 10).

accessKeystring nullable

Chave de acesso [Id]

codestring nullable

Código Numérico [cNF]

isFinalCustomerboolean required

Consumidor Final [indFinal]

debitType'creditTransferToCooperatives' | 'creditReversalForExemptOrImmuneOutputs' | 'unprocessedInvoiceDebitInAssessment' | 'penaltyAndInterest' | 'creditTransferBySuccession' | 'advancePayment' | 'inventoryLoss' | 'simplesNacionalExclusion'

Tipo de Nota de Débito — NT 2025.002 Reforma Tributária<p>Valores possíveis:</p>

<ul> <li><b>creditTransferToCooperatives</b>: Transferência de créditos para Cooperativas</li> <li><b>creditReversalForExemptOrImmuneOutputs</b>: Anulação de crédito por saídas imunes/isentas</li> <li><b>unprocessedInvoiceDebitInAssessment</b>: Débitos de notas fiscais não processadas na apuração</li> <li><b>penaltyAndInterest</b>: Multa e juros</li> <li><b>creditTransferBySuccession</b>: Transferência de crédito de sucessão</li> <li><b>advancePayment</b>: Pagamento antecipado</li> <li><b>inventoryLoss</b>: Perda em estoque</li> <li><b>simplesNacionalExclusion</b>: Desenquadramento do Simples Nacional</li> </ul>
creditType'finesAndInterest' | 'appropriation' | 'returnByFullRefusal' | 'amountReduction' | 'creditTransferBySuccession' | 'returnByPartialRefusal'

Tipo de Nota de Crédito — NT 2025.002 Reforma Tributária<p>Valores possíveis:</p>

<ul> <li><b>finesAndInterest</b>: Multa e juros</li> <li><b>appropriation</b>: Apropriação de crédito presumido de IBS sobre o saldo devedor na ZFM (art. 450, § 1º, LC 214/25)</li> <li><b>returnByFullRefusal</b>: Retorno por recusa total na entrega ou por não localização do destinatário na tentativa de entrega</li> <li><b>amountReduction</b>: Redução de valores</li> <li><b>creditTransferBySuccession</b>: Transferência de crédito na sucessão</li> <li><b>returnByPartialRefusal</b>: Retorno por recusa parcial na entrega</li> </ul>
govOperationType'supply' | 'receipt'

Tipo de operação com o ente governamental — NT 2025.002 Reforma Tributária<p>Valores possíveis:</p>

<ul> <li><b>supply</b>: Fornecimento</li> <li><b>receipt</b>: Recebimento do pagamento, conforme fato gerador do IBS/CBS (Art. 10 § 2º)</li> </ul>
issueType'normal' | 'svcan' | 'svcrs'

Forma de emissão da NF-e [tpEmis]. Definida pela Spedy conforme o estado de contingência da UF no momento da emissão — o padrão é normal. Use principalmente para ler, na consulta da nota, se ela saiu em contingência.<p>Valores possíveis:</p>

<ul> <li><b>normal</b>: Emissão normal, direto na SEFAZ da UF</li> <li><b>svcan</b>: Contingência SVC-AN — SEFAZ Virtual de Contingência do Ambiente Nacional</li> <li><b>svcrs</b>: Contingência SVC-RS — SEFAZ Virtual de Contingência do Rio Grande do Sul</li> </ul>

Response

OK

idstring uuid

ID da NF

integrationIdstring nullable

ID de integração

status'created' | 'enqueued' | 'received' | 'authorized' | 'inContingent' | 'rejected' | 'canceled' | 'denied' | 'removed' | 'disabled'
<p>Valores possíveis:</p> <ul> <li><b>created</b>: Criada — aguarda emissão explícita via issue ou gatilho automático (ex: afterPayment)</li> <li><b>enqueued</b>: Enfileirada para processamento junto à SEFAZ ou Prefeitura</li> <li><b>received</b>: Recebido</li> <li><b>authorized</b>: Autorizado</li> <li><b>inContingent</b>: Em contingência</li> <li><b>rejected</b>: Rejeitado</li> <li><b>canceled</b>: Cancelado</li> <li><b>denied</b>: Denegado</li> <li><b>removed</b>: Removido</li> <li><b>disabled</b>: Inutilizado</li> </ul>
model'productInvoice' | 'consumerInvoice' | 'serviceInvoice'
<p>Valores possíveis:</p> <ul> <li><b>productInvoice</b>: NF-e</li> <li><b>consumerInvoice</b>: NFC-e</li> <li><b>serviceInvoice</b>: NFS-e</li> </ul>
environmentType'production' | 'development' | 'simulation'
<p>Valores possíveis:</p> <ul> <li><b>production</b>: Produção</li> <li><b>development</b>: Homologação</li> <li><b>simulation</b>: </li> </ul>
issuedOnstring date-time nullable

Data de emissão [dhEmi]

effectiveDatestring date-time nullable

Data usada como emissão da nota. Após a emissão, tem o mesmo valor de issuedOn.

amountnumber double

Valor total da NF

numberinteger nullable

Número

isFromApiboolean

Emitida via API pública

accessKeystring nullable
seriesstring nullable
operationType'incoming' | 'outgoing'

Tipo de operação da nota fiscal<p>Valores possíveis:</p>

<ul> <li><b>incoming</b>: Entrada</li> <li><b>outgoing</b>: Saída</li> </ul>
printingType'none' | 'portrait' | 'landscape' | 'simplified' | 'consumerInvoice' | 'electronicMessage'

Formato de impressão do DANFE<p>Valores possíveis:</p>

<ul> <li><b>none</b>: Sem geração de DANFE</li> <li><b>portrait</b>: Retrato (orientação vertical)</li> <li><b>landscape</b>: Paisagem (orientação horizontal)</li> <li><b>simplified</b>: Simplificado</li> <li><b>consumerInvoice</b>: DANFE NFC-e (cupom fiscal eletrônico)</li> <li><b>electronicMessage</b>: Mensagem eletrônica</li> </ul>
purposeType'normal' | 'complement' | 'adjustment' | 'devolution' | 'credit' | 'debit'
<p>Valores possíveis:</p> <ul> <li><b>normal</b>: Normal</li> <li><b>complement</b>: Complemento</li> <li><b>adjustment</b>: Ajustamento</li> <li><b>devolution</b>: Devolução</li> <li><b>credit</b>: Crédito</li> <li><b>debit</b>: Débito</li> </ul>
debitType'creditTransferToCooperatives' | 'creditReversalForExemptOrImmuneOutputs' | 'unprocessedInvoiceDebitInAssessment' | 'penaltyAndInterest' | 'creditTransferBySuccession' | 'advancePayment' | 'inventoryLoss' | 'simplesNacionalExclusion'

Tipo de Nota de Débito — NT 2025.002 Reforma Tributária<p>Valores possíveis:</p>

<ul> <li><b>creditTransferToCooperatives</b>: Transferência de créditos para Cooperativas</li> <li><b>creditReversalForExemptOrImmuneOutputs</b>: Anulação de crédito por saídas imunes/isentas</li> <li><b>unprocessedInvoiceDebitInAssessment</b>: Débitos de notas fiscais não processadas na apuração</li> <li><b>penaltyAndInterest</b>: Multa e juros</li> <li><b>creditTransferBySuccession</b>: Transferência de crédito de sucessão</li> <li><b>advancePayment</b>: Pagamento antecipado</li> <li><b>inventoryLoss</b>: Perda em estoque</li> <li><b>simplesNacionalExclusion</b>: Desenquadramento do Simples Nacional</li> </ul>
creditType'finesAndInterest' | 'appropriation' | 'returnByFullRefusal' | 'amountReduction' | 'creditTransferBySuccession' | 'returnByPartialRefusal'

Tipo de Nota de Crédito — NT 2025.002 Reforma Tributária<p>Valores possíveis:</p>

<ul> <li><b>finesAndInterest</b>: Multa e juros</li> <li><b>appropriation</b>: Apropriação de crédito presumido de IBS sobre o saldo devedor na ZFM (art. 450, § 1º, LC 214/25)</li> <li><b>returnByFullRefusal</b>: Retorno por recusa total na entrega ou por não localização do destinatário na tentativa de entrega</li> <li><b>amountReduction</b>: Redução de valores</li> <li><b>creditTransferBySuccession</b>: Transferência de crédito na sucessão</li> <li><b>returnByPartialRefusal</b>: Retorno por recusa parcial na entrega</li> </ul>
govOperationType'supply' | 'receipt'

Tipo de operação com o ente governamental — NT 2025.002 Reforma Tributária<p>Valores possíveis:</p>

<ul> <li><b>supply</b>: Fornecimento</li> <li><b>receipt</b>: Recebimento do pagamento, conforme fato gerador do IBS/CBS (Art. 10 § 2º)</li> </ul>
authorizedPersonsstring[] nullable
issueType'normal' | 'svcan' | 'svcrs'

Forma de emissão da NF-e [tpEmis]. Definida pela Spedy conforme o estado de contingência da UF no momento da emissão — o padrão é normal. Use principalmente para ler, na consulta da nota, se ela saiu em contingência.<p>Valores possíveis:</p>

<ul> <li><b>normal</b>: Emissão normal, direto na SEFAZ da UF</li> <li><b>svcan</b>: Contingência SVC-AN — SEFAZ Virtual de Contingência do Ambiente Nacional</li> <li><b>svcrs</b>: Contingência SVC-RS — SEFAZ Virtual de Contingência do Rio Grande do Sul</li> </ul>

Changes

No recorded changes to this operation across all 1 revision of this API.