Endpoints

Todos os endpoints são prefixados com https://platform.notaas.com.br/api/v1 e requerem o header x-api-key.

Emissão NFS-e

POST/emitir🔑 x-api-key

Enfileira uma NFS-e para emissão assíncrona. Retorna 202 com invoiceId para polling.

Estrutura Geral (Body JSON)

Campo	Tipo	Req?	Descrição
tomador.cnpj	string	sim	CNPJ do tomador (14 dígitos, sem formatação). Obrigatório pelo XSD (nacional) — use CNPJ ou CPF. Para estrangeiros, pode ser omitido caso o nif seja informado.
tomador.cpf	string	não	CPF do tomador (11 dígitos). Alternativo ao CNPJ.
tomador.nif	string	não	NIF (Número de Identificação Fiscal) do tomador estrangeiro. Obrigatório caso seja do exterior e não possua CNPJ/CPF.
tomador.nome	string	sim	Nome ou razão social do tomador. Obrigatório pelo XSD (TCInfoPessoa.xNome).
tomador.email	string	não	E-mail do tomador para envio da nota.
tomador.telefone	string	não	Telefone do tomador (apenas dígitos).
tomador.endereco.logradouro	string	não	Logradouro do tomador.
tomador.endereco.numero	string	não	Número do endereço.
tomador.endereco.complemento	string	não	Complemento do endereço.
tomador.endereco.bairro	string	não	Bairro do tomador.
tomador.endereco.cidade	string	não	Nome da cidade do tomador (ex: "Londrina"). Resolvido para código IBGE automaticamente.
tomador.endereco.uf	string	não	Sigla do estado (ex: "PR"). Use "EX" para o exterior.
tomador.endereco.cep	string	não	CEP do tomador (apenas dígitos).
tomador.endereco.pais	string	não	Sigla ISO2 do país do tomador (ex: "US"). Padrão: "BR". Se diferente de "BR", ativa o fluxo de tomador estrangeiro.
servico.descricao	string	sim	Descrição detalhada do serviço prestado.
servico.codigo	string	não	cTribNac LC 116/2003 — 6 dígitos numéricos (ex: "010700"). Opcional: usa o padrão do projeto se omitido.
servico.codigoServico	string	não	Código de serviço municipal (SP: 4-5 dígitos, ex: "07498"). Opcional se omitido.
servico.localPrestacao	string	não	Código IBGE 7 dígitos do local onde o serviço foi prestado (ex: "3205200"). Em prestação transfronteiriça (modo 1), informe o município onde foi executado e defina o país de destino em valores.exportacao.paisResultado. A Notaas resolve o município de incidência legal (cLocIncid) automaticamente conforme a LC 116/2003.
servico.nbs	string	não	Código NBS — Nomenclatura Brasileira de Serviços (9 dígitos numéricos). Obrigatório em municípios com engine TBW/SIL. Nas engines DBSeller, GINFES e GISSOnline, define o enquadramento IBS/CBS junto com valores.ibscbs.
servico.codigoTributacaoMunicipal	string	não	Código de tributação municipal (desdobro) — 3 dígitos numéricos (ex: "001"). Opcional.
valores.total	number	sim	Valor bruto do serviço em reais (ex: 1500.00).
valores.aliquotaIss	number	sim	Alíquota ISS em % (ex: 2.0 para 2%). Informar 0 para imunidade ou exportação.
valores.issRetido	boolean	não	ISSQN retido pelo tomador de serviço (true = tpRetISSQN 2 / retido pelo tomador; false = tpRetISSQN 1 / não retido). Padrão: false.
valores.tribISSQN	number	não	Forma de tributação do ISSQN: 1-Tributável, 2-Imunidade, 3-Exportação, 4-Não Incidência. Opcional: para exportação de serviços, é derivado automaticamente como 3 quando o grupo valores.exportacao for informado.
competencia	string	não	Competência no formato YYYY-MM (padrão: mês atual).
referencia	string	não	Identificador externo opcional (seu sistema).

Dados Complementares (opcional)

Campo	Tipo	Req?	Descrição
servico.informacoesComplementares	string	não	Informações adicionais/complementares impressas no corpo do DANFSe (limite de 2000 caracteres).
servico.pedidoCompra	string	não	Número do pedido de compra (PO) associado ao serviço.
servico.documentoReferencia	string	não	Contrato ou nota fiscal de referência.

Exportação de Serviços (opcional)

Campo	Tipo	Req?	Descrição
valores.exportacao	object	não	Grupo de dados adicionais de comércio exterior. Obrigatório quando servico.localPrestacao for uma sigla de país.
valores.exportacao.modoPrestacao	number	não	Modo de prestação: 1-Transfronteiriço, 2-Consumo no Brasil, 3-Presença Comercial no Exterior, 4-Movimento Temporário.
valores.exportacao.vinculoPartes	number	não	Vínculo entre partes: 0-Sem vínculo, 1-Controlada, 2-Controladora, 3-Coligada, 4-Matriz, 5-Filial, 6-Outro.
valores.exportacao.codigoMoeda	string	não	Código de 3 dígitos da moeda na tabela BACEN (ex: "220" para USD, "978" para EUR).
valores.exportacao.valorServicoMoeda	number	não	Valor do serviço expresso na moeda estrangeira.
valores.exportacao.fomentoPrestador	string	não	Código de fomento do prestador (padrão: "01" para nenhum).
valores.exportacao.fomentoTomador	string	não	Código de fomento do tomador (padrão: "01" para nenhum).
valores.exportacao.movimentacaoTemporariaBens	number	não	Movimentação temporária de bens: 1-Não, 2-Declaração Importação, 3-Declaração Exportação.
valores.exportacao.compartilharMdic	boolean	não	Enviar dados da NFS-e para a SECEX/MDIC.
valores.exportacao.paisResultado	string	sim	Sigla ISO2 do país onde se produz o resultado do serviço. Obrigatório em notas de exportação.

Dados de Obra (opcional)

Campo	Tipo	Req?	Descrição
servico.obra	object	não	Informações sobre a obra de construção civil associada ao serviço.
servico.obra.inscricaoImobiliaria	string	não	Inscrição imobiliária municipal da obra (IPTU/Inscrição Cadastral).
servico.obra.codigoObra	string	não	Número do cadastro CNO (Cadastro Nacional de Obras) ou CEI.
servico.obra.codigoCib	string	não	Código do Cadastro Imobiliário Brasileiro (CIB) da obra.
servico.obra.art	string	não	Anotação de Responsabilidade Técnica (ART) da obra (obrigatório para motores ABRASF).
servico.obra.endereco	object	não	Endereço específico da execução da obra (estrutura igual ao endereço do tomador).

Tributação Federal e Retenções (opcional)

Campo	Tipo	Req?	Descrição
valores.totaisTributosAproximados	object	não	Totais aproximados de tributos por esfera — Lei 12.741/2012 (Transparência Fiscal). Envie percentuais OU valores em R$, nunca ambos. Exclusivo para SNNFSE.
↳ percentualTributacaoFederal	number	não	Opção A (percentual): tributos federais aproximados em %.
↳ percentualTributacaoEstadual	number	não	Opção A (percentual): tributos estaduais aproximados em %.
↳ percentualTributacaoMunicipal	number	não	Opção A (percentual): tributos municipais (ISS) aproximados em %.
↳ valorTributacaoFederal	number	não	Opção B (valor R$): tributos federais em reais.
↳ valorTributacaoEstadual	number	não	Opção B (valor R$): tributos estaduais em reais.
↳ valorTributacaoMunicipal	number	não	Opção B (valor R$): tributos municipais (ISS) em reais.
valores.pisCofins	object	não	Override de tributação federal PIS/COFINS por nota. Exclusivo para SNNFSE (ignorado para MEI e Simples Nacional).
↳ cst	string	não	CST PIS/COFINS (2 dígitos). Ex: "01", "07".
↳ baseCalculo	number	não	Base de cálculo em R$. Padrão: total do serviço.
↳ aliquotaPis	number	não	Alíquota PIS em % (ex: 0.65).
↳ aliquotaCofins	number	não	Alíquota COFINS em % (ex: 3.00).
↳ valorPis	number	não	Override do valor do PIS em R$.
↳ valorCofins	number	não	Override do valor do COFINS em R$.
↳ tipoRetencao	number	não	Tipo de retenção: 0=Não Retidos, 1=PIS/COFINS Retidos, 3=Todos Retidos.
valores.retencaoIrrf	number	não	Valor retenção IRRF em R$.
valores.retencaoCp	number	não	Valor retenção Contribuição Previdenciária (INSS) em R$.
valores.retencaoCsll	number	não	Valor retenção CSLL em R$.

Atividades de Eventos (opcional)

Campo	Tipo	Req?	Descrição
servico.evento	object	não	Informações do evento associado à prestação de serviços (item 12 da LC 116).
servico.evento.nome	string	sim	Nome ou descrição do evento (ex: "Show de Música Ao Vivo").
servico.evento.dataInicio	string	sim	Data de início do evento no formato YYYY-MM-DD.
servico.evento.dataFim	string	sim	Data de término do evento no formato YYYY-MM-DD.
servico.evento.id	string	não	Identificador único do evento (opcional).

Reforma Tributária — IBS / CBS (opcional)

Campo	Tipo	Req?	Descrição
valores.ibscbs	object	não	Grupo IBS/CBS (LC 214/2025). Também aceito como servico.ibscbs. Precedência campo a campo: valores.ibscbs > servico.ibscbs > Configurações do Projeto no Dashboard (seção "Reforma Tributária (IBS / CBS)") > resolução automática pela tabela oficial do Anexo VIII da Receita Federal.
↳ classificacaoTributaria	string	não	Classificação tributária (cClassTrib) — 6 dígitos. Ex: "000001" (tributação integral), "200046" (operações com bens imóveis). Alias técnico: cClassTrib.
↳ indicadorOperacao	string	não	Indicador da operação (cIndOp) — 6 dígitos. Ex: "100301" (domicílio do adquirente), "020301" (local do imóvel). Aliases técnicos: cIndOp, indOp.
↳ cst	string	não	CST IBS/CBS — 3 dígitos. Ex: "000" (tributação integral), "200" (redução), "410" (imunidade). Alias: cstIbscbs.
↳ nbs	string	não	Código NBS — 9 dígitos (ex: "114012100"). Também aceito em servico.nbs. Alias: codigoNbs.
↳ consumidorFinal	boolean	não	Indica consumidor final (uso/consumo pessoal). Aceita true/false ou "0"/"1". Alias técnico: indFinal. Padrão: false.
↳ destinatarioPrincipal	string	não	Tomador é o destinatário principal (indDest): "0" (padrão) ou "1".
↳ tipoOperacao	string \| number	não	Tipo de operação (tpOper) para entes governamentais ou bens imóveis: 1 – Fornecimento com pagamento posterior; 2 – Recebimento do pagamento com fornecimento já realizado; 3 – Fornecimento com pagamento já realizado; 4 – Recebimento do pagamento com fornecimento posterior; 5 – Fornecimento e recebimento concomitantes. Alias técnico: tpOper.
↳ tipoEnteGovernamental	string \| number	não	Esfera governamental (tpEnteGov) para compras públicas: 1 – Federal; 2 – Estadual; 3 – Distrital; 4 – Municipal; 9 – Outros. Aliases: enteGovernamental, tpEnteGov.

Coerência IBS/CBS: a combinação NBS + indicadorOperacao + classificacaoTributaria deve formar uma tupla válida do Anexo VIII da Receita Federal. Se o item da LC 116 tiver mais de um enquadramento possível (ex: 17.12 — administração de imóveis × gestão de negócios) e nem o payload nem o projeto definirem o enquadramento, a API responde HTTP 400 com a lista das combinações válidas — a plataforma nunca "chuta" uma classificação fiscal. Para emitir sem alterar o payload, configure os valores padrão em Dashboard → Configurações → Reforma Tributária (IBS / CBS).

{
  "tomador": {
    "nome": "Empresa Tomadora Ltda",
    "cnpj": "12345678000195",
    "email": "[email protected]",
    "endereco": {
      "logradouro": "Rua das Flores",
      "numero": "100",
      "bairro": "Centro",
      "cidade": "Londrina",
      "uf": "PR",
      "cep": "86010010"
    }
  },
  "servico": {
    "descricao": "Desenvolvimento de software personalizado",
    "codigo": "010302"
  },
  "valores": {
    "total": 5000.00,
    "aliquotaIss": 2.0,
    "issRetido": false
  },
  "competencia": "2026-06",
  "referencia": "OS-2026-001"
}

{
  "queued": true,
  "invoiceId": "inv_abc123",
  "status": "queued",
  "pollUrl": "/api/v1/invoices/inv_abc123/status"
}

💰 Tributação Federal (PIS/COFINS/IRRF) — SNNFSE

MEI / Simples Nacional: campos federais são ignorados silenciosamente — PIS/COFINS já são recolhidos no DAS.
Prioridade de valores: API request (override) → Configuração do projeto (Settings) → Derivado do regime.
Se o projeto tem cstPisCofins e alíquotas configurados em Settings, o bloco <tribFed> é gerado automaticamente — sem precisar enviar na API.
Campos retencaoIrrf, retencaoCp e retencaoCsll são inseridos no XML apenas quando informados (valores em R$).

🏛️ Regras Fiscais de Incidência do ISSQN & Retenção (LC 116/2003)

Resolução Automática do Município de Incidência: Você não precisa calcular ou informar a cidade de incidência do imposto. A plataforma Notaas determina a incidência legal automaticamente pelo código de tributação nacional (cTribNac) e Anexo I da NFS-e — cobrindo a regra geral do prestador (277 subitens) e as exceções no local da prestação (58 subitens).
Local da Prestação (servico.localPrestacao): Informe o código IBGE apenas quando o serviço for executado fisicamente em outro município. O motor Notaas faz a correta separação entre a localização física e o município credor do tributo.
Retenção pelo Tomador (valores.issRetido): Informe issRetido: true quando o imposto for recolhido pelo tomador de serviço (tpRetISSQN = 2). A retenção é mantida de forma independente do município credor. Operações imunes, isentas ou de exportação não admitem retenção.

📋 Consultar lista completa de códigos de serviço (cTribNac) →🗺️ BH exige cTribMun? Ver cobertura municipal →

POST/cancelar🔑 x-api-key

Solicita o cancelamento assíncrono de uma NFS-e já emitida (status issued).

Body (JSON)

Campo	Tipo	Req?	Descrição
invoiceId	string	sim	ID da nota a cancelar
motivo	string	não	Motivo do cancelamento (texto livre, max 255 chars)

Status & Polling

GET/invoices/{id}/status🔑 x-api-key

Retorna o status atual de uma NFS-e individual.

Resposta

Campo	Tipo	Req?	Descrição
status	string	não	queued \| processing \| issued \| error \| cancelled
chNFSe	string	não	Chave/código de verificação da NFS-e (disponível quando status=issued)
numeroNfe	string	não	Número da NFS-e (disponível quando status=issued)
emittedAt	string (ISO 8601)	não	Timestamp de emissão (disponível quando status=issued)
ambiente	string	não	"producao" ou "homologacao" (disponível quando status=issued)
pdfUrl	string (URL)	não	URL pública CDN do PDF (disponível quando documentsCached=true). Acesso direto, sem autenticação.
xmlUrl	string (URL)	não	URL pública CDN do XML (disponível quando documentsCached=true). Acesso direto, sem autenticação.
documentsCached	boolean	não	true quando XML e PDF foram armazenados no CDN. URLs disponíveis em pdfUrl e xmlUrl.
errorCode	string	não	Código do erro (disponível quando status=error)
errorMessage	string	não	Mensagem de erro legível (disponível quando status=error)
errors	array	não	Array detalhado de erros da SEFAZ [{Codigo, Descricao, Complemento}] (disponível quando status=error)
cancelledAt	string (ISO 8601)	não	Timestamp do cancelamento (disponível quando status=cancelled)
cancelXmlUrl	string (URL)	não	URL pública CDN do XML de cancelamento (disponível quando status=cancelled e documentsCached=true)

Documentos da NFS-e

GET/invoices/{id}/xml🔑 x-api-key

Retorna o XML da NFS-e. Sem parâmetros, retorna o XML de emissão. Com ?type=cancel, retorna o XML de cancelamento.

Query Parameters

Campo	Tipo	Req?	Descrição
type	string	não	Tipo de XML: "emission" (default) ou "cancel". O tipo "cancel" retorna o XML de cancelamento — disponível apenas para notas com status cancelled.

Comportamento

Campo	Tipo	Req?	Descrição
Cache R2 (302)	redirect	não	Quando cacheado no CDN, redireciona para URL pública (cache immutable).
Fallback (200)	application/xml	não	Quando não cacheado, retorna o XML do banco com Content-Type application/xml.

Erros

Campo	Tipo	Req?	Descrição
409	Conflict	não	Invoice ainda não emitida (status ≠ issued ou cancelled)
409	Conflict	não	?type=cancel: nota não está cancelada
404	Not Found	não	XML não disponível para esta nota

GET/invoices/{id}/pdf🔑 x-api-key

Retorna o PDF (DANFSE) da NFS-e. Se cacheado no R2, redireciona (302) para a URL pública CDN. Caso contrário, busca ao vivo no portal municipal.

Comportamento

Campo	Tipo	Req?	Descrição
Cache R2 (302)	redirect	não	Quando documentsCached=true, redireciona para URL pública CDN (cache immutable).
SNNFSE federal	200 PDF	não	Geração local do DANFSe v2.0 a partir do XML da nota (substitui o ADN Federal descontinuado).
Pronim (Cidade360)	200 PDF	não	Fallback: consulta portal Cidade360 e retorna PDF inline.
São Paulo (SP)	302 redirect	não	Fallback: redireciona para o portal da Prefeitura SP.
WebISS	200 PDF / 302	não	Fallback: GET no portal WebISS (público ou mTLS).

Erros

Campo	Tipo	Req?	Descrição
409	Conflict	não	Invoice ainda não emitida (status ≠ issued)
422	Unprocessable	não	Dados insuficientes: certificado A1 ausente, chave de acesso inválida
501	Not Implemented	não	Sistema municipal não suporta download de PDF (DSF, Centi)
502	Bad Gateway	não	Portal externo retornou erro

Lote (Batch)

POST/emitir/batch🔑 x-api-key

Emite múltiplas NFS-e de forma assíncrona. Retorna batchId para acompanhamento.

Body (JSON)

Campo	Tipo	Req?	Descrição
items	array	sim	Array de objetos com o mesmo formato do POST /emitir

GET/invoices/batch/{batchId}/status🔑 x-api-key

Retorna o progresso de um lote: total, processados, emitidos, erros.

Resposta

Campo	Tipo	Req?	Descrição
batchId	string	não	ID do lote
status	string	não	processing \| completed \| partial \| failed
total	number	não	Total de itens no lote
processed	number	não	Itens já processados
issued	number	não	Itens emitidos com sucesso
errors	number	não	Itens com erro
items[].invoiceId	string	não	ID da invoice
items[].status	string	não	Status individual do item
items[].pdfUrl	string (URL)	não	URL para download do PDF (disponível quando status=issued)
items[].chNFSe	string	não	Chave/código de verificação (disponível quando status=issued)
items[].errorCode	string	não	Código do erro (disponível quando status=error)

Endpoints de Webhook

POST/webhooks/endpoints🔑 x-api-key

Cadastra um novo endpoint de webhook para a organização/projeto.

Body (JSON)

Campo	Tipo	Req?	Descrição
url	string	sim	URL HTTPS que receberá o POST
events	string[]	sim	Ex: ["nfse.issued", "nfse.error", "nfse.cancelled", "nfse.documents_ready", "batch.completed"]
secret	string	não	Secret para assinatura HMAC-SHA256 via X-Notaas-Signature (opcional)

GET/webhooks/endpoints🔑 x-api-key

Lista todos os endpoints de webhook configurados.

PATCH/webhooks/endpoints/{id}🔑 x-api-key

Atualiza URL, eventos, status ativo/inativo ou secret de um endpoint. Envie secret: null ou secret: '' para remover a assinatura.

DELETE/webhooks/endpoints/{id}🔑 x-api-key

Remove um endpoint de webhook.

POST/webhooks/endpoints/{id}/test🔑 x-api-key

Envia um payload de teste para validar a configuração do endpoint.

GET/webhooks/deliveries🔑 x-api-key

Lista o histórico de entregas de webhook com status e tentativas.

Eventos Suportados

Eventos

Campo	Tipo	Req?	Descrição
nfse.issued	event	não	NFS-e emitida com sucesso. Payload inclui número da nota e código de verificação.
nfse.error	event	não	Falha na emissão. Payload inclui código e mensagem de erro.
nfse.cancelled	event	não	NFS-e cancelada com sucesso. Payload inclui invoiceId, numeroNfse e cancelledAt.
nfse.documents_ready	event	não	Documentos cacheados no CDN. Payload inclui xmlUrl, pdfUrl, cancelXmlUrl (para notas canceladas) e documentStatus.
batch.completed	event	não	Todos os itens de um lote foram processados.

⚠️ nfse.documents_ready — comportamento de entrega

Este evento pode ser disparado até 2 vezes para a mesma invoice:

1ª chamada: documentStatus: "partial" — XML pronto, PDF pode estar indisponível (pdfUrl: null)
2ª chamada (até 10 min depois): documentStatus: "complete" — XML e PDF prontos. Se o retry esgotar sem sucesso, nenhum webhook adicional é enviado.

Use o campo documentStatus para determinar se todos os documentos estão disponíveis.

Para notas canceladas, o payload inclui o campo adicional cancelXmlUrl com a URL do XML de cancelamento. cancelXmlUrl é null para notas emitidas.

Em engines que não emitem PDF (ex.: dsf, centi), o evento chega uma única vez com pdfUrl: null e documentStatus: "complete".

ℹ️ Compatibilidade de Webhook

Campos adicionais podem ser incluídos nos payloads de webhook sem aviso prévio. Seu código deve ignorar campos desconhecidos para manter compatibilidade futura (Postel's Law).