NFS-e

Criar NFS-e

Cria uma NFS-e (nota de serviço) e a enfileira para emissão junto à prefeitura/provedor municipal. 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 NFS-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 NFS-e rejeitada, reenvie o POST com os dados corrigidos e o mesmo integrationId — sem necessidade de deletar a nota anterior

post/v1/service-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/service-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 competência.

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

numberinteger nullable

Número da NFS-e.

Só é enviado à prefeitura quando o provedor da cidade não usa RPS/DPS (provider.options.rps falso em «Cidades integradas»). Na maioria dos municípios, inclusive no Ambiente Nacional, o número é gerado pela prefeitura a partir do RPS/DPS.

additionalInformationstring nullable

Informações adicionais

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

descriptionstring required

Discriminação dos serviços

batchNumberinteger nullable

Número do lote.

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

rpsNumberinteger nullable

Número do RPS ou da DPS no Ambiente Nacional.

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

rpsSeriesstring nullable

Série do RPS ou da DPS no Ambiente Nacional.

Opcional: se omitida, é usada a série configurada na empresa.

cnaeCodestring nullable

Código CNAE

nbsCodestring nullable

Código NBS

federalServiceCodestring nullable

Código do Item da Lista de Serviço (LC 116/03)

nationalTaxationCodestring nullable

Código de Tributação Nacional

cityServiceCodestring nullable

Código do serviço no munícipio

Valores possíveis: <ul> <li>taxationInMunicipality: Tributado no Município / Exigível / Operação tributável</li> <li>taxationOutsideMunicipality: Tributado em outro município / Não incidência</li> <li>exemption: Isento</li> <li>immune: Imune</li> <li>suspendedByCourt: Suspenso por Decisão Judicial</li> <li>suspendedByAdministrativeProcedure: Suspenso por Decisão Administrativa</li> <li>exportation: Exportação</li> <li>nonIncidence: Não incidência</li> </ul>

cstPisCofinsstring nullable

Código de Situação Tributária (CST) de PIS/COFINS.

Informe quando a nota destaca PIS e COFINS. Usado apenas em provedores que utilizam o Layout Nacional.

Opcional: se omitido, é usado o CST do grupo de tributação, quando configurado.

Informe o código de dois dígitos (ex.: 01):

00: Nenhum
01: Operação Tributável com Alíquota Básica
02: Operação Tributável com Alíquota Diferenciada
03: Operação Tributável com Alíquota por Unidade de Medida de Produto
04: Operação Tributável monofásica - Revenda a Alíquota Zero
05: Operação Tributável por Substituição Tributária
06: Operação Tributável a Alíquota Zero
07: Operação Isenta da Contribuição
08: Operação sem Incidência da Contribuição
09: Operação com Suspensão da Contribuição

Tabela completa em Regimes e códigos fiscais.

simplesNacionalAnnexstring nullable

Anexo do Simples Nacional.

Obrigatório somente para os provedores Conam e Webfisco. Valores aceitos: I, II, III, IV, V.

taxLocation'companyMunicipality' | 'customerMunicipality' | 'serviceProvisionMunicipality'

Valores possíveis: <ul> <li>companyMunicipality: No município da empresa</li> <li>customerMunicipality: No município do cliente</li> <li>serviceProvisionMunicipality: No município de prestação do serviço</li> </ul>

Response

idstring uuid

ID da NF

integrationIdstring nullable

ID de integração

Valores possíveis: <ul> <li>created: Criada — aguarda emissão explícita via issue ou gatilho automático (ex: afterPayment)</li> <li>enqueued: Enfileirada para processamento junto à SEFAZ ou Prefeitura</li> <li>received: Recebido</li> <li>authorized: Autorizado</li> <li>inContingent: Em contingência</li> <li>rejected: Rejeitado</li> <li>canceled: Cancelado</li> <li>denied: Denegado</li> <li>removed: Removido</li> <li>disabled: Inutilizado</li> </ul>

model'productInvoice' | 'consumerInvoice' | 'serviceInvoice'

Valores possíveis: <ul> <li>productInvoice: NF-e</li> <li>consumerInvoice: NFC-e</li> <li>serviceInvoice: NFS-e</li> </ul>

environmentType'production' | 'development' | 'simulation'

Valores possíveis: <ul> <li>production: Produção</li> <li>development: Homologação</li> <li>simulation: </li> </ul>

issuedOnstring date-time nullable

Data e hora em que a emissão foi solicitada

effectiveDatestring date-time nullable

Data de competência

amountnumber double

Valor total da NF

numberinteger nullable

Número

isFromApiboolean

Emitida via API pública

descriptionstring nullable

nbsCodestring nullable

nationalTaxationCodestring nullable

batchNumberinteger nullable

Changes

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