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.

Body (JSON)

Campo	Tipo	Req?	Descrição
tomador.cnpj	string	sim	CNPJ do tomador (14 dígitos, sem formatação). Obrigatório pelo XSD — use CNPJ ou CPF.
tomador.cpf	string	não	CPF do tomador (11 dígitos). Alternativo ao CNPJ.
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 — resolvido para código IBGE automaticamente. Obrigatório se endereco for informado.
tomador.endereco.uf	string	não	Sigla do estado (ex: "SP"). Obrigatório se endereco for informado.
tomador.endereco.cep	string	não	CEP do tomador (apenas dígitos). Recomendado — XSD exige CEP no endereço nacional.
servico.descricao	string	sim	Descrição do serviço prestado
servico.codigo	string	não	cTribNac LC 116/2003 — 6 dígitos numéricos (ex: "010700"). Opcional: usa o Código de Tributação padrão do projeto se omitido. ❌ "1.07" → ✅ "010700". Não aplicável para São Paulo. Códigos do Item 99 (ex: "990101" — sem incidência de ISSQN/ICMS): informar aliquotaIss: 0.
servico.codigoServico	string	não	Código de serviço SP (4–5 dígitos, ex: "07498"). Opcional para projetos em SP — usa padrão do projeto se omitido.
servico.localPrestacao	string	não	Código IBGE 7 dígitos do local de prestação. Opcional — padrão: município do projeto.
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%). Para serviços sem incidência de ISSQN/ICMS (cTribNac do Item 99, ex: "990101"), informar 0.
valores.issRetido	boolean	não	ISS retido pelo tomador (padrão: false)
competencia	string	não	Competência no formato YYYY-MM (padrão: mês atual)
referencia	string	não	Identificador externo opcional (seu sistema)

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

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 para download do PDF da NFS-e (disponível quando status=issued)
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)

PDF da NFS-e

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

Retorna o PDF (DANFSE) da NFS-e emitida. Disponível apenas quando status=issued.

Comportamento por sistema

Campo	Tipo	Req?	Descrição
SNNFSE federal	200 PDF	não	Proxy mTLS → ADN Federal (adn.nfse.gov.br) → PDF inline. Requer certificado A1 ativo no projeto.
Pronim (Cidade360)	200 PDF	não	Consulta portal Cidade360 e retorna PDF inline.
São Paulo (SP)	302 redirect	não	Redireciona para o portal da Prefeitura SP com CCM, número e código de verificação.

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 ou dados Pronim incompletos
501	Not Implemented	não	Sistema municipal não suporta download de PDF via API neste momento
502	Bad Gateway	não	Portal externo (ADN ou portal municipal) 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", "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 ou status ativo/inativo de um endpoint.

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.