# notem — Documentação da API > API para sistemas parceiros emitirem, cancelarem, substituírem e consultarem NFS-e do padrão nacional. Endereço da API: https://app.notemfiscal.com.br/api/v1. Autenticação por chave de integração no cabeçalho Authorization. Todos os exemplos usam dados fictícios. ## Início - [Documentação da API da notem](https://docs.notemfiscal.com.br/): Integre seu sistema à notem para emitir, cancelar e consultar NFS-e do padrão nacional. ## Primeiros passos - [Primeiros passos](https://docs.notemfiscal.com.br/primeiros-passos/primeiros-passos): Da chave de homologação à primeira nota de teste, em sete passos. - [Autenticação](https://docs.notemfiscal.com.br/primeiros-passos/autenticacao): Chaves de integração por ambiente, cabeçalho Authorization e troca de chaves sem interrupção. - [Ambientes](https://docs.notemfiscal.com.br/primeiros-passos/ambientes): Homologação e produção, o que é separado por ambiente e o que é compartilhado. - [Requisições e formatos](https://docs.notemfiscal.com.br/primeiros-passos/requisicoes): Endereço, versão, formato JSON, padrões de dados, texto aceito pela NFS-e, listas e segurança. - [Limites de uso](https://docs.notemfiscal.com.br/primeiros-passos/limites): Quantas chamadas cada chave pode fazer por minuto, por tipo de operação, e o que fazer ao receber 429. - [Erros](https://docs.notemfiscal.com.br/primeiros-passos/erros): Formato único de erro, códigos estáveis e o que cada status significa. - [Idempotência](https://docs.notemfiscal.com.br/primeiros-passos/idempotencia): Reenvio seguro com Idempotency-Key: mesma chave, mesma resposta, nunca uma nota duplicada. - [Checklist de produção](https://docs.notemfiscal.com.br/primeiros-passos/checklist-producao): O que conferir antes de trocar a chave de homologação pela de produção. - [Glossário](https://docs.notemfiscal.com.br/primeiros-passos/glossario): Termos usados na API e na documentação da notem. ## Guias - [Conceitos](https://docs.notemfiscal.com.br/guias/conceitos): Organização, integração, empresa, serviço, tomador e nota: como as peças da notem se relacionam. - [Empresa e certificado](https://docs.notemfiscal.com.br/guias/empresa-e-certificado): Cadastro da empresa emitente, desativação, exclusão e certificado digital A1. - [Configuração fiscal](https://docs.notemfiscal.com.br/guias/configuracao-fiscal): Como informar a situação no Simples Nacional, os regimes e os tributos aproximados, e quais combinações o governo aceita. - [Serviços e códigos](https://docs.notemfiscal.com.br/guias/servicos-e-codigos): Modelos de serviço da empresa, código nacional, tributação do ISS, retenção e catálogos oficiais. - [Situação da empresa e municípios](https://docs.notemfiscal.com.br/guias/municipios-conveniados): Como saber se a empresa está pronta para emitir e se o município atende o ambiente. - [Emissão de notas](https://docs.notemfiscal.com.br/guias/emissao): Como emitir a NFS-e: pedido, tomador, resposta, numeração, reenvio seguro, consultas, XML e PDF. - [Ciclo de vida da nota](https://docs.notemfiscal.com.br/guias/ciclo-de-vida): Situações da nota, transições possíveis e o objeto nota completo. - [Cancelamento](https://docs.notemfiscal.com.br/guias/cancelamento): Cancelar uma NFS-e autorizada, pedir análise fiscal à prefeitura e acompanhar o pedido. - [Substituição](https://docs.notemfiscal.com.br/guias/substituicao): Corrigir uma nota autorizada emitindo outra no lugar dela: o que pode mudar e quando a original deixa de valer. - [IBS/CBS](https://docs.notemfiscal.com.br/guias/ibs-cbs): Classificação IBS/CBS dos serviços, quando o grupo vai na nota e as recusas do governo. - [Notas recebidas e sincronização](https://docs.notemfiscal.com.br/guias/notas-recebidas): Notas emitidas fora da notem, notas em que a empresa é tomadora e a sincronização com o Ambiente de Dados Nacional. - [CNPJ alfanumérico](https://docs.notemfiscal.com.br/guias/cnpj-alfanumerico): Como a notem trata o novo formato de CNPJ com letras, em homologação e produção. - [Leiaute da NFS-e (NT 009)](https://docs.notemfiscal.com.br/guias/leiaute-nt009): Como a notem acompanha as mudanças de leiaute do governo sem exigir mudanças no seu sistema. ## Webhooks - [Visão geral](https://docs.notemfiscal.com.br/webhooks/visao-geral): Avisos automáticos da notem para o seu sistema: cadastro, formato da mensagem e cabeçalhos. - [Eventos](https://docs.notemfiscal.com.br/webhooks/eventos): Lista de eventos, assinatura por grupo com curingas e o conteúdo de cada evento, com exemplos completos. - [Assinatura](https://docs.notemfiscal.com.br/webhooks/assinatura): Como validar a assinatura HMAC-SHA256 do cabeçalho Notem-Assinatura, com exemplo em JavaScript. - [Entregas e reenvios](https://docs.notemfiscal.com.br/webhooks/entregas): Resposta esperada, cronograma de novas tentativas, desativação automática e cuidados de segurança. - [Chave de autorização](https://docs.notemfiscal.com.br/webhooks/autorizacao): Chave opcional enviada em um cabeçalho escolhido por você, além da assinatura. ## Referência da API - [Introdução à referência](https://docs.notemfiscal.com.br/referencia/introducao): As 40 operações da API v1, agrupadas por assunto, com campos, respostas e exemplos. - [Rejeições do governo](https://docs.notemfiscal.com.br/referencia/rejeicoes-do-governo): Códigos de recusa do governo que a notem explica em português, com o campo e a orientação prática. - [Consultar status (GET /api/v1/status)](https://docs.notemfiscal.com.br/referencia/status/consultar-status): Confirma que a chave funciona e informa o ambiente, a organização e a integração. - [Listar empresas (GET /api/v1/empresas)](https://docs.notemfiscal.com.br/referencia/empresas/listar-empresas): Lista as empresas emitentes da organização, da mais recente para a mais antiga. - [Cadastrar empresa (POST /api/v1/empresas)](https://docs.notemfiscal.com.br/referencia/empresas/cadastrar-empresa): Cadastra uma empresa que vai emitir notas pela notem. - [Consultar empresa (GET /api/v1/empresas/{id})](https://docs.notemfiscal.com.br/referencia/empresas/consultar-empresa): Devolve os dados cadastrais de uma empresa. - [Alterar empresa (PATCH /api/v1/empresas/{id})](https://docs.notemfiscal.com.br/referencia/empresas/alterar-empresa): Altera os dados de uma empresa, ou a desativa e reativa. - [Excluir empresa (DELETE /api/v1/empresas/{id})](https://docs.notemfiscal.com.br/referencia/empresas/excluir-empresa): Exclui uma empresa que nunca emitiu nota. - [Consultar configuração fiscal (GET /api/v1/empresas/{id}/configuracao-fiscal)](https://docs.notemfiscal.com.br/referencia/configuracao-fiscal/consultar-configuracao-fiscal): Devolve como a empresa é tributada: Simples Nacional, regimes e tributos aproximados. - [Gravar configuração fiscal (PUT /api/v1/empresas/{id}/configuracao-fiscal)](https://docs.notemfiscal.com.br/referencia/configuracao-fiscal/gravar-configuracao-fiscal): Grava como a empresa é tributada e recusa combinações que o governo não aceita. - [Consultar certificado (GET /api/v1/empresas/{id}/certificado)](https://docs.notemfiscal.com.br/referencia/certificado/consultar-certificado): Mostra os dados do certificado digital ativo, como titular e validade. - [Enviar certificado (POST /api/v1/empresas/{id}/certificado)](https://docs.notemfiscal.com.br/referencia/certificado/enviar-certificado): Envia ou troca o certificado digital A1 que a empresa usa para assinar as notas. - [Listar serviços (GET /api/v1/empresas/{id}/servicos)](https://docs.notemfiscal.com.br/referencia/servicos/listar-servicos): Lista os serviços cadastrados na empresa, ativos e inativos. - [Cadastrar serviço (POST /api/v1/empresas/{id}/servicos)](https://docs.notemfiscal.com.br/referencia/servicos/cadastrar-servico): Cadastra um serviço que a empresa presta, com os códigos que vão na nota. - [Consultar serviço (GET /api/v1/empresas/{id}/servicos/{servico_id})](https://docs.notemfiscal.com.br/referencia/servicos/consultar-servico): Devolve um serviço cadastrado na empresa. - [Alterar serviço (PATCH /api/v1/empresas/{id}/servicos/{servico_id})](https://docs.notemfiscal.com.br/referencia/servicos/alterar-servico): Altera um serviço ou o desativa. - [Listar tomadores (GET /api/v1/empresas/{id}/tomadores)](https://docs.notemfiscal.com.br/referencia/tomadores/listar-tomadores): Lista os clientes (tomadores) cadastrados em uma empresa. - [Cadastrar tomador (POST /api/v1/empresas/{id}/tomadores)](https://docs.notemfiscal.com.br/referencia/tomadores/cadastrar-tomador): Guarda os dados de um cliente para usar nas próximas notas. - [Consultar tomador (GET /api/v1/empresas/{id}/tomadores/{tomador_id})](https://docs.notemfiscal.com.br/referencia/tomadores/consultar-tomador): Devolve os dados de um tomador cadastrado na empresa. - [Alterar tomador (PATCH /api/v1/empresas/{id}/tomadores/{tomador_id})](https://docs.notemfiscal.com.br/referencia/tomadores/alterar-tomador): Altera os dados de um tomador cadastrado. - [Consultar situação (GET /api/v1/empresas/{id}/situacao)](https://docs.notemfiscal.com.br/referencia/situacao-da-empresa/consultar-situacao): Diz se a empresa está pronta para emitir no ambiente da chave e o que falta. - [Verificar município (POST /api/v1/empresas/{id}/situacao/verificar-municipio)](https://docs.notemfiscal.com.br/referencia/situacao-da-empresa/verificar-municipio): Consulta no governo se o município da empresa aceita a NFS-e nacional e atualiza a situação. - [Consultar sincronização (GET /api/v1/empresas/{id}/sincronizacao)](https://docs.notemfiscal.com.br/referencia/sincronizacao/consultar-sincronizacao): Mostra quando a empresa foi sincronizada com o governo pela última vez e o resultado. - [Listar notas (GET /api/v1/notas)](https://docs.notemfiscal.com.br/referencia/notas/listar-notas): Lista as notas da organização no ambiente da chave, da mais recente para a mais antiga. - [Emitir nota (POST /api/v1/notas)](https://docs.notemfiscal.com.br/referencia/notas/emitir-nota): Envia a NFS-e ao governo e devolve a nota autorizada ou o motivo da recusa. - [Consultar nota (GET /api/v1/notas/{id})](https://docs.notemfiscal.com.br/referencia/notas/consultar-nota): Devolve a nota completa, com situação, valores, tomador e links do XML e do PDF. - [Baixar XML da nota (GET /api/v1/notas/{id}/xml)](https://docs.notemfiscal.com.br/referencia/notas/baixar-xml-nota): Baixa o XML oficial da nota, exatamente como o governo devolveu. - [Cancelar nota (POST /api/v1/notas/{id}/cancelar)](https://docs.notemfiscal.com.br/referencia/notas/cancelar-nota): Pede ao governo o cancelamento de uma nota autorizada e devolve a nota cancelada ou o motivo da recusa. - [Solicitar análise do cancelamento (POST /api/v1/notas/{id}/solicitar-analise-cancelamento)](https://docs.notemfiscal.com.br/referencia/notas/solicitar-analise-cancelamento): Pede à prefeitura que analise um cancelamento que o município não permite fazer diretamente. - [Substituir nota (POST /api/v1/notas/{id}/substituir)](https://docs.notemfiscal.com.br/referencia/notas/substituir-nota): Emite uma nova nota que corrige e substitui uma nota autorizada. - [Baixar XML do evento (GET /api/v1/notas/{id}/eventos/{codigo}/xml)](https://docs.notemfiscal.com.br/referencia/notas/baixar-xml-evento): Baixa o XML oficial de um cancelamento ou de um pedido de análise registrado no governo. - [Baixar PDF (DANFSe) (GET /api/v1/notas/{id}/pdf)](https://docs.notemfiscal.com.br/referencia/notas/baixar-pdf-nota): Gera o PDF da nota (DANFSe) a partir do XML oficial. - [Listar notas recebidas (GET /api/v1/empresas/{id}/notas-recebidas)](https://docs.notemfiscal.com.br/referencia/notas-recebidas/listar-notas-recebidas): Lista as notas em que a empresa aparece como cliente (tomadora) ou intermediária. - [Consultar nota recebida (GET /api/v1/empresas/{id}/notas-recebidas/{nota_id})](https://docs.notemfiscal.com.br/referencia/notas-recebidas/consultar-nota-recebida): Devolve uma nota recebida pela empresa. - [Baixar XML da nota recebida (GET /api/v1/empresas/{id}/notas-recebidas/{nota_id}/xml)](https://docs.notemfiscal.com.br/referencia/notas-recebidas/baixar-xml-nota-recebida): Baixa o XML oficial da nota recebida, sem alterações. - [Baixar PDF da nota recebida (GET /api/v1/empresas/{id}/notas-recebidas/{nota_id}/pdf)](https://docs.notemfiscal.com.br/referencia/notas-recebidas/baixar-pdf-nota-recebida): Gera o PDF (DANFSe) de uma nota recebida a partir do XML oficial. - [Municípios (GET /api/v1/catalogos/municipios)](https://docs.notemfiscal.com.br/referencia/catalogos/listar-municipios): Busca municípios pelo nome ou pelo código IBGE. - [Códigos de serviço (GET /api/v1/catalogos/servicos)](https://docs.notemfiscal.com.br/referencia/catalogos/listar-codigos-servico): Busca códigos da lista nacional de serviços pela descrição ou pelo código. - [Códigos NBS (GET /api/v1/catalogos/nbs)](https://docs.notemfiscal.com.br/referencia/catalogos/listar-nbs): Busca códigos NBS pela descrição ou pelo código. - [Classificações tributárias (GET /api/v1/catalogos/classificacoes-tributarias)](https://docs.notemfiscal.com.br/referencia/catalogos/listar-classificacoes-tributarias): Lista as classificações tributárias do IBS/CBS aceitas na NFS-e. - [Indicadores de operação (GET /api/v1/catalogos/indicadores-operacao)](https://docs.notemfiscal.com.br/referencia/catalogos/listar-indicadores-operacao): Lista os indicadores de operação do IBS/CBS, que dizem o tipo de operação e onde o imposto é devido. - [Sugestão de classificação (GET /api/v1/catalogos/sugestao-classificacao)](https://docs.notemfiscal.com.br/referencia/catalogos/sugerir-classificacao): Sugere NBS, classificação tributária e indicador de operação para um código de serviço. ## Optional - [Especificação OpenAPI 3.1](https://docs.notemfiscal.com.br/openapi.yaml): contrato técnico completo da API v1, com exemplos. - [Histórico de mudanças](https://docs.notemfiscal.com.br/historico): alterações que afetam respostas da API.