Referência completa de campos de emissão de NFS-e
Lista de todos os campos aceitos no corpo (POST) de emissão de NFS-e. Apenas cityServiceCode, description, servicesAmount e borrower são obrigatórios — todo o restante é opcional e deve ser enviado apenas quando aplicável.
nota
Por padrão a plataforma faz o cálculo automático dos impostos — os campos de alíquota/valor (issRate, pisRate, etc.) são opcionais e usados apenas no cálculo manual. Veja Cálculo automático e Cálculo manual.
Obrigatórios
| Campo | Tipo | Descrição |
|---|---|---|
cityServiceCode | string | Código do serviço no município. |
description | string | Descrição dos serviços. |
servicesAmount | número | Valor dos serviços. |
borrower | objeto | Tomador dos serviços (ver Por regime e tomador). |
Identificação e datas
| Campo | Tipo | Descrição | Cenário |
|---|---|---|---|
externalId | string | Identificação externa (idempotência). | externalId e RPS |
issuedOn | data/hora | Data da emissão. | — |
accrualOn | data (AAAA-MM-DD) | Data da competência da prestação. | — |
rpsSerialNumber | string | Número de série da RPS. | externalId e RPS |
rpsNumber | inteiro | Número da RPS. | externalId e RPS |
Classificação do serviço
| Campo | Tipo | Descrição |
|---|---|---|
federalServiceCode | string | Código federal do serviço (item da lista LC 116). |
cnaeCode | string | Código CNAE (quando exigido pela cidade). |
nbsCode | string | Código NBS (quando exigido pela cidade). |
ncmCode | string | Código NCM (Nomenclatura Comum do Mercosul). |
dica
Sobre a validação de CNAE × item da LC116 (algumas prefeituras exigem compatibilidade), veja CNAE e item da LC116.
Valores e pagamento
| Campo | Tipo | Descrição |
|---|---|---|
paidAmount | número | Valor dos serviços pago. |
paymentMethod | enum | Forma de pagamento. |
deductionsAmount | número | Valor de deduções. |
discountUnconditionedAmount | número | Valor do desconto incondicionado. |
discountConditionedAmount | número | Valor do desconto condicionado. |
isEarlyInstallmentPayment | booleano | Indica pagamento antecipado de parcela. |
ISS e tributação
| Campo | Tipo | Descrição | Cenário |
|---|---|---|---|
taxationType | enum | Tipo da tributação (WithinCity, OutsideCity, Export, Free, Immune, SuspendedCourtDecision, FixedISSQN, …). Export classifica exportação de serviço. | ISS e local · Cliente no exterior |
issRate | número | Alíquota do ISS (cálculo manual; opcional). | ISS e local |
issTaxAmount | número | Valor do ISS. | — |
issAmountWithheld | número | Valor retido do ISS. | Retenções |
retentionType | enum | Tipo de retenção do ISSQN (withheldByBuyer, withheldByIntermediary, notWithheld). | Retenções |
immunityType | enum | Tipo de imunidade (apenas com taxationType=Immune). | ISS e local |
Retenções federais
| Campo | Tipo | Descrição | Cenário |
|---|---|---|---|
irAmountWithheld | número | Valor retido do IR. | Retenções |
cstPisCofins | enum | Código de Situação Tributária PIS/COFINS. | — |
pisCofinsBaseTax | número | Base de cálculo de PIS/COFINS. | — |
pisAmount / pisRate / pisAmountWithheld | número | Valor / alíquota / valor retido do PIS. | Retenções |
cofinsAmount / cofinsRate / cofinsAmountWithheld | número | Valor / alíquota / valor retido do COFINS. | Retenções |
csllAmount / csllRate / csllAmountWithheld | número | Valor / alíquota / valor retido do CSLL. | Retenções |
inssRate / inssAmountWithheld | número | Alíquota / valor retido do INSS. | Retenções |
ipiRate / ipiAmount | número | Alíquota / valor do IPI (SP). | — |
othersAmountWithheld | número | Valor de outras retenções. | — |
nota
Clientes às vezes enviam irRate (alíquota do IR), mas o contrato não tem esse campo — para o IR, use irAmountWithheld (valor retido).
Reforma Tributária (IBS/CBS)
| Campo | Tipo | Descrição | Cenário |
|---|---|---|---|
ibsCbs | objeto | Grupo de IBS/CBS (operationIndicator, classCode, situationCode, ibs, cbs, governmentPurchase, …). | Reforma Tributária |
Local e grupos de atividade
| Campo | Tipo | Descrição | Cenário |
|---|---|---|---|
location | objeto | Local da prestação do serviço. Para o exterior, informe location.country (ISO 3166-1 alfa-3). | ISS e local · Cliente no exterior |
activityEvent | objeto | Atividade de evento (nome, datas, endereço). | Tipos de atividade |
realEstate | objeto | Operações com bens imóveis (exceto obras). | — |
construction | objeto | Obras de construção civil. | Tipos de atividade |
lease | objeto | Locação/sublocação/arrendamento/direito de passagem. | Tipos de atividade |
foreignTrade | objeto | Transações com residentes/domiciliados no exterior. Exigido pelo Ambiente Nacional; ao enviar o grupo, 8 subcampos passam a ser obrigatórios. | Cliente no exterior · Tipos de atividade |
referenceSubstitution | objeto | NFS-e a ser substituída. | Tipos de atividade |
deduction | objeto | Deduções/reduções da base de cálculo do ISSQN. | — |
benefit | objeto | Benefício municipal aplicado à base do ISSQN. | — |
suspension | objeto | Suspensão da exigibilidade do ISSQN. | ISS e local |
Partes adicionais
| Campo | Tipo | Descrição |
|---|---|---|
intermediary | objeto | Intermediário do serviço. |
recipient | objeto | Destinatário (quando diferente do tomador). |
Tributos aproximados e informações adicionais
| Campo | Tipo | Descrição |
|---|---|---|
approximateTax | objeto | Tributos aproximados (fonte + alíquota). |
approximateTotals | objeto | Totais aproximados dos tributos (Lei 12.741/2012). |
additionalInformation | string | Informações adicionais (texto, máx. 500 caracteres). |
additionalInformationGroup | objeto | Grupo de informações adicionais. |
serviceAmountDetails | objeto | Informações adicionais de tributação do serviço. |