NFS-e em um padrão único de API, do envio aos arquivos fiscais.

Status atual

Superfície pública

A API pública de NFS-e permite rascunho, emissão, consulta, cancelamento e artefatos em homologação e produção. Recomendamos validar primeiro em homologação porque layouts e regras variam conforme o município.

Como a plataforma trata NFS-e

A plataforma apresenta a fragmentação municipal por meio de um contrato JSON único. O integrador envia tomador, serviço, valores e retenções em um formato estável. A identificação do prestador — CNPJ, inscrição municipal, regime, nome e endereço — vem do cadastro da empresa vinculada ao token, e não do payload da nota. O Fiscal Contora executa as validações, o processamento fiscal e a comunicação necessária com o ambiente autorizador aplicável.

Quem informa os dados fiscais

O Fiscal Contora é o emissor técnico: recebe os dados definidos pelo cliente, valida o contrato, monta e assina o documento e o transmite ao ambiente autorizador. A plataforma não escolhe por conta própria o enquadramento fiscal da operação nem inventa códigos ou alíquotas.

Exemplo completo de homologação — MEI

Este primeiro exemplo pressupõe uma empresa cadastrada como mei em um município que usa o padrão nacional. Por isso a alíquota de ISS é zero e não aparece o grupo de tributos do não optante.

{
  "environment": "homologacao",
  "payload": {
    "number": 501,
    "series": 1,
    "service": {
      "description": "Serviço de implantação de software",
      "service_code": "01.05.01",
      "national_tax_code": "010501",
      "cnae": "6203100",
      "iss_rate": 0,
      "iss_withheld": false
    },
    "taker": {
      "name": "Cliente de Servicos LTDA",
      "document": "12345678000199",
      "email": "[email protected]",
      "address": {
        "street": "Rua de Exemplo",
        "number": "100",
        "district": "Centro",
        "city_code": "3550308",
        "state_code": "SP",
        "postal_code": "01001000"
      }
    },
    "amounts": {
      "service_amount": 1500,
      "net_amount": 1500
    }
  }
}

Exemplo de não optante no padrão nacional

Para empresas de Lucro Presumido ou Lucro Real, o cliente precisa informar também os percentuais aproximados por esfera. No Rio de Janeiro, o municipal_tax_code de três dígitos é obrigatório para prestadores não-MEI. O exemplo abaixo mostra o formato que foi efetivamente autorizado em homologação; os códigos e percentuais são ilustrativos e precisam ser confirmados para cada operação.

{
  "environment": "homologacao",
  "payload": {
    "service": {
      "description": "Serviço de publicidade e criação",
      "service_code": "170601",
      "national_tax_code": "170601",
      "municipal_tax_code": "002",
      "cnae": "7311400",
      "iss_rate": 5,
      "iss_withheld": false,
      "approximate_tax_percentages": {
        "federal": 0,
        "state": 0,
        "municipal": 5
      }
    },
    "taker": {
      "name": "Cliente de Serviços LTDA",
      "document": "44295808000119",
      "email": "[email protected]"
    },
    "amounts": {
      "service_amount": 1500,
      "net_amount": 1500
    }
  }
}

Exemplo de município com layout próprio

Salvador BA — veja o guia sobre CTISS, a diferença entre os códigos nacional e municipal e a tabela oficial da prefeitura.

Onde o município mantém layout próprio, os códigos mudam de lugar: o national_tax_code não é usado, e entram o item da lista e o código de tributação do município. Municípios que já adotaram os campos da reforma tributária exigem também o nbs_code. O exemplo abaixo é de Salvador/BA.

Repare que tax_classification_code e operation_indicator não aparecem no payload: a plataforma deriva os dois da correlação oficial do Anexo VIII, a partir do item da lista somado ao NBS. Envie-os apenas quando quiser sobrepor a derivação — o valor informado sempre vence.

{
  "environment": "producao",
  "payload": {
    "service": {
      "description": "Serviço de manutenção e reparação de motores elétricos",
      "item_list_code": "1401",
      "municipal_tax_code": "1401001",
      "nbs_code": "120015000",
      "cnae": "3313901",
      "iss_rate": 5,
      "iss_withheld": false
    },
    "taker": {
      "name": "Cliente de Servicos LTDA",
      "document": "12345678000199",
      "address": {
        "street": "Rua de Exemplo",
        "number": "100",
        "district": "Centro",
        "city_code": "2927408",
        "state_code": "BA",
        "postal_code": "40000000"
      }
    },
    "amounts": {
      "service_amount": 1500,
      "net_amount": 1500
    }
  }
}

Descontos, deduções e informações complementares

O bloco amounts aceita mais do que o valor do serviço. Quando a nota tem desconto, o caminho correto é declarar o valor bruto em service_amount e o desconto em campo próprio, e não enviar apenas o valor já líquido: só assim o desconto aparece discriminado no DANFSe e no XML. O texto que não é descrição do serviço — número de ordem de serviço, pedido do cliente, referência de contrato — tem lugar próprio em service.additional_info, em vez de disputar espaço com a discriminação.

{
  "environment": "producao",
  "payload": {
    "service": {
      "description": "Manutenção elétrica embarcada",
      "national_tax_code": "140101",
      "cnae": "3317102",
      "iss_rate": 3,
      "iss_withheld": false,
      "additional_info": "OS 4821 - Pedido do cliente 99-B"
    },
    "taker": {
      "name": "Cliente de Servicos LTDA",
      "document": "12345678000199"
    },
    "amounts": {
      "service_amount": 538.33,
      "unconditional_discount": 169.78
    }
  }
}

Nesse exemplo a DPS sai com vServ = 538.33, vDescIncond = 169.78 e o Sistema Nacional devolve vLiq = 368.55. O net_amount pode ser omitido: sem ele, o líquido é calculado como service_amount menos descontos e deduções. Se você informar os dois, o valor enviado é respeitado — mas a resposta traz um aviso quando ele diverge do cálculo, porque o engano mais comum é subtrair o desconto do bruto e ainda assim declará-lo.

Padrão nacional ou layout municipal

A NFS-e tem dois caminhos, e o que decide não é o regime tributário da empresa: é o município. Onde o município aderiu ao Sistema Nacional da NFS-e, o documento vale pelo padrão nacional, seja o prestador MEI, Simples, Lucro Presumido ou Real. Só onde o município mantém layout próprio o caminho é o do provedor municipal.

O padrão nacional é o comportamento assumido por padrão. Alguns municípios são reconhecidos pelo código IBGE e encaminhados ao provedor municipal sem qualquer configuração — hoje Salvador/BA (2927408) e Currais Novos/RN (2403103). Para outros municípios que ainda usam layout próprio, configure settings.nfse_standard = "municipal" no cadastro da empresa.

Situação no Simples Nacional

No padrão nacional o documento declara a situação do prestador perante o Simples Nacional, e o Sistema Nacional confere esse valor contra o cadastro do Simples na competência. A plataforma deriva a situação do regime tributário da empresa — mei declara Optante MEI, simples declara Optante ME/EPP, e os demais declaram Não Optante.

Quando o regime cadastrado aqui não corresponde à situação real (o cadastro do Simples é que vale), informe settings.nfse_simples_nacional_option no cadastro da empresa com 1 (não optante), 2 (optante MEI) ou 3 (optante ME/EPP). Divergência resulta na rejeição E0160.

Inscrição municipal

No padrão nacional a inscrição municipal só entra no documento quando o município tem informações complementares registradas no CNC NFS-e. Quando a opção settings.nfse_municipal_registration_in_cnc estiver ativa, grave em settings.municipal_registration a IM exatamente como consta no CNC, inclusive zeros à esquerda. O Sistema Nacional cruza município emissor, CNPJ/CPF e IM; uma versão abreviada ou com formatação diferente pode voltar como E0116, mesmo que a tag da IM tenha sido enviada.

Onde o município não mantém a IM no CNC, o Sistema Nacional recusa o envio com E0120. Nesse caso configure settings.nfse_municipal_registration_in_cnc = false no cadastro da empresa e a inscrição deixa de ser enviada e de ser exigida. Para o MEI a inscrição nunca é enviada: o cadastro nacional responde pelos dados do prestador.

GET /companies/{company_id}/nfse/health mostra qual caminho está ativo para a empresa e o que ainda falta antes da primeira emissão.

São Paulo (SP) — Nota Fiscal Paulistana

São Paulo é o caso em que o município e o regime decidem juntos. A prefeitura aceita o padrão nacional apenas para o MEI; ME/EPP e demais prestadores emitem pelo sistema próprio dela. Um emitente não-MEI que tente o padrão nacional em São Paulo recebe E0120 e, corrigido isso, E0312 — sem ajuste de payload que resolva.

Por isso São Paulo não é encaminhada automaticamente ao provedor municipal como Salvador: isso quebraria os MEI que hoje emitem pelo nacional. Configure no cadastro da empresa:

PATCH /api/v1/companies/{company_id}
{
  "settings": {
    "nfse_standard": "municipal",
    "municipal_registration": "01234567"
  }
}

A inscrição municipal é o CCM. O schema da prefeitura exige exatamente 8 dígitos e a ficha do contribuinte costuma mostrar o número sem o zero à esquerda; a plataforma completa sozinha (1234567 vira 01234567), então grave como estiver na ficha.

Código de serviço

São Paulo mantém tabela própria de códigos, com 5 dígitos — não é o item da LC 116 e não é o código nacional. Envie em service.service_code ou service.item_list_code; as duas formas valem.

{
  "environment": "producao",
  "payload": {
    "service": {
      "description": "Licenciamento de uso da plataforma",
      "service_code": "02800",
      "cnae": "6201501",
      "iss_rate": 2.9
    },
    "taker": {
      "name": "Cliente Exemplo",
      "document": "12345678909"
    },
    "amounts": { "service_amount": 100.00, "net_amount": 100.00 }
  }
}

Não existe ambiente de homologação

A prefeitura publica apenas o endereço de produção. O que faz as vezes de ensaio é a operação de envio de teste dela, que roda todas as validações e não gera nota. A plataforma usa esse caminho automaticamente quando o documento é de homologação:

{
  "environment": "homologacao",
  "payload": { ... }
}

O documento termina em built_signed, sem número de NFS-e, e provider.message explica o desfecho. É o jeito de validar cadastro, certificado, CCM e código de serviço antes da primeira nota real. Note que a chave de API precisa ser de produção (com allows_homologation ligado na empresa): produção nunca é relaxada, e uma chave de homologação não opera numa empresa de produção.

Cancelamento

Cancelamento por API, com justificativa obrigatória:

POST /api/v1/companies/{company_id}/nfse/drafts/{id}/cancel
{
  "reason": "Servico nao prestado."
}

O resultado aparece no bloco cancellation do endpoint de status. Repetir a chamada é seguro: numa nota já cancelada a prefeitura devolve o código 1301 e a plataforma mantém o documento como cancelado.

O ISS sai zerado na nota do optante pelo Simples Nacional — é o comportamento correto, já que o imposto é recolhido no DAS. O DANFSE gerado traz essa observação impressa.

Fluxo de emissão

1. Cadastrar a empresa prestadora no console.
2. Configurar certificado e dados fiscais da empresa.
3. Enviar um payload padrão de NFS-e com tomador, serviço e valores.
4. Disparar a emissão por fila, sem travar o ERP integrador.
5. Acompanhar autorizacao, rejeicao ou cancelamento por status e webhook.
6. Baixar o XML autorizado e o DANFSe v2.0 gerado a partir desse XML.

Respostas e estados

Número do RPS e número da NFS-e

O campo legado number continua sendo o número do RPS. Use rps_number quando quiser essa referência de forma explícita e nfse_number para o número fiscal atribuído pelo município ou pelo Sistema Nacional depois da autorização. display_number devolve o número da NFS-e quando disponível e, antes disso, o RPS.

access_key traz a chave de acesso nacional de 50 dígitos assim que o Sistema Nacional autoriza, no status e no GET do documento — não é preciso baixar e abrir o xml_nfse para conciliar a nota ou montar o link da consulta pública. Provedor municipal que não emite chave nacional devolve null e continua identificando a nota por provider.verification_code.

{
  "ok": true,
  "data": {
    "id": "UUID_DO_DOCUMENTO",
    "series": 1,
    "number": 501,
    "rps_number": 501,
    "nfse_number": "1",
    "display_number": "1",
    "access_key": "42082032250057049000159000000000000126083779781389",
    "lifecycle": {
      "status": "authorized",
      "processing_status": "completed",
      "requested_action": "submit"
    },
    "last_error_code": null,
    "last_error_message": null,
    "provider": {
      "number": "1"
    }
  }
}

Cancelamento

O cancelamento é aceito somente para uma NFS-e autorizada e também é processado de forma assíncrona.

curl --request POST \
  --url https://fiscal.contora.com.br/api/v1/nfse/drafts/ID_DO_DOCUMENTO/cancel \
  --header 'Authorization: Bearer SEU_TOKEN' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: cancelamento-nfse-501' \
  --data '{"reason":"Serviço cancelado antes da execução."}'

A justificativa é obrigatória e deve conter entre 15 e 255 caracteres. Depois do 202 Accepted, acompanhe o bloco cancellation no status ou aguarde o webhook.

Substituição

A substituição não tem endpoint próprio, e isso não é uma limitação da API: no padrão nacional ela é declarada dentro da DPS da nota nova, no grupo subst. Você cria um rascunho normal acrescentando o bloco substitution ao payload e despacha como qualquer outra NFS-e.

curl --request POST \
  --url https://fiscal.contora.com.br/api/v1/nfse/drafts \
  --header 'Authorization: Bearer SEU_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "environment": "producao",
    "payload": {
      "substitution": {
        "replaced_access_key": "35503082267882130000176000000000005026082005262745",
        "reason_code": "05",
        "reason": "Nota rejeitada pelo tomador; reemissao com a descricao correta do servico."
      },
      "service": {
        "description": "Servico de suporte tecnico em informatica",
        "service_code": "1.07",
        "national_tax_code": "010701",
        "cnae": "6203100",
        "iss_rate": 0
      },
      "taker": { "name": "Tomador de Exemplo LTDA", "document": "12345678000190" },
      "amounts": { "service_amount": 1.00, "net_amount": 1.00 }
    }
  }'

Os três campos do bloco correspondem direto ao grupo subst da DPS:

• replaced_access_key → chSubstda: chave da NFS-e substituída, 50 dígitos. Obrigatório.
• reason_code → cMotivo: código de justificativa da substituição. Obrigatório.
• reason → xMotivo: descrição do motivo. Opcional; quando enviada, entre 15 e 255 caracteres.

Os códigos de justificativa da substituição são próprios:

• 01 — desenquadramento de NFS-e do Simples Nacional
• 02 — enquadramento de NFS-e no Simples Nacional
• 03 — inclusão retroativa de imunidade/isenção
• 04 — exclusão retroativa de imunidade/isenção
• 05 — rejeição da NFS-e pelo tomador ou pelo intermediário responsável pelo recolhimento
• 99 — outros

Você não precisa cancelar a nota antiga: assim que a substituta é autorizada, a NFS-e substituída passa a responder com cancellation_status = "cancelled" e cancellation_status_code = "105102". A substituição existe apenas no padrão nacional; empresa em município de layout próprio recebe recusa antes do envio.

Para um passo a passo detalhado com exemplos de payload, diagrama de estados e integração com ERP, veja o Guia Completo de Substituição de NFS-e no Padrão Nacional (Grupo Subst).

XML e DANFSe (Pós-autorização)

Assim que o documento atinge o status authorized, todos os artefatos fiscais ficam imediatamente disponíveis para consulta e download pelo seu ERP.

Consulte GET https://fiscal.contora.com.br/api/v1/nfse/drafts/{document}/artifacts para listar os artefatos gerados:

{
  "ok": true,
  "data": [
    {
      "type": "xml_nfse",
      "label": "XML da NFS-e",
      "available": true,
      "filename": "nfse-1.xml",
      "download_url": "https://fiscal.contora.com.br/api/v1/nfse/drafts/ID_DO_DOCUMENTO/artifacts/xml_nfse"
    },
    {
      "type": "pdf_nfse",
      "label": "PDF da NFS-e",
      "available": true,
      "filename": "nfse-1.pdf",
      "download_url": "https://fiscal.contora.com.br/api/v1/nfse/drafts/ID_DO_DOCUMENTO/artifacts/pdf_nfse"
    },
    {
      "type": "xml_rps",
      "label": "XML do RPS",
      "available": true,
      "filename": "nfse-1.rps.xml",
      "download_url": "https://fiscal.contora.com.br/api/v1/nfse/drafts/ID_DO_DOCUMENTO/artifacts/xml_rps"
    }
  ]
}

Download direto dos arquivos

Para baixar diretamente no seu backend ou repassar ao cliente final:

• XML da NFS-e: GET https://fiscal.contora.com.br/api/v1/nfse/drafts/{document}/artifacts/xml_nfse (Content-Type: application/xml)
• DANFSe (PDF): GET https://fiscal.contora.com.br/api/v1/nfse/drafts/{document}/artifacts/pdf_nfse (Content-Type: application/pdf)
• XML do RPS: GET https://fiscal.contora.com.br/api/v1/nfse/drafts/{document}/artifacts/xml_rps (Content-Type: application/xml)

# Baixar o XML autorizado
curl --request GET \
  --url https://fiscal.contora.com.br/api/v1/nfse/drafts/ID_DO_DOCUMENTO/artifacts/xml_nfse \
  --header 'Authorization: Bearer SEU_TOKEN' \
  --output nfse.xml

# Baixar o DANFSe (PDF)
curl --request GET \
  --url https://fiscal.contora.com.br/api/v1/nfse/drafts/ID_DO_DOCUMENTO/artifacts/pdf_nfse \
  --header 'Authorization: Bearer SEU_TOKEN' \
  --output danfse.pdf

Referência dos códigos de serviço

Preparação para produção

Para quem vai integrar NFS-e conosco, a melhor preparacao agora e organizar os cadastros de prestadores, serviços, tomadores, códigos municipais e cenários de retenção. Antes da primeira emissão em produção, valide o mesmo cenário em homologação e confirme as regras específicas do município emissor.