Sua primeira nota
Da empresa à nota autorizada. Para testar sem certificado, cadastre a empresa com simulado: true e use uma chave sk_test_.
- 1
Cadastre a empresa
POST /empresas com cnpj e razao_social (e simulado: true para testar).
- 2
Configure a parte fiscal
PUT /empresas/{id}/configuracao_fiscal: município, regime (op_simp_nac) e inscrição municipal.
- 3
Envie o certificado A1
POST /empresas/{id}/certificado, multipart com arquivo (.pfx) e senha. Não precisa no simulado.
- 4
Confira a prontidão
GET /empresas/{id}/prontidao deve voltar pronto: true.
- 5
Emita a nota
POST /nfse: volta 202 com status processando; o resultado chega em segundos.
O pedido
tipo (PF ou PJ), documento, nome, email e endereco com codigo_ibge. Ou mande tomador_id do catálogo. Estrangeiro: tipo: "EX", documento com o NIF (ou motivo_sem_nif) e endereco_exterior (país ISO de 2 letras, código postal, cidade, estado/província, logradouro, número e bairro).servico_id (opcional, do catálogo), discriminacao, valor e iss_retido. Sem catálogo, mande também c_trib_nac (LC 116, 6 dígitos). Para tomador EX, servico.exportacao (moeda BACEN, valor na moeda, modo de prestação, vínculo); com ela, não mande aliquota_iss nem iss_retido. servico.ibs_cbs (cst, c_class_trib) é opcional em 2026; os valores calculados voltam em valores.ibs_cbs depois de autorizada.servico.desconto_incondicionado (reduz a base do ISS), servico.desconto_condicionado (não muda o ISS; reduz o líquido) e servico.deducao com percentual ou valor (materiais, subempreitada). servico.informacoes_complementares vai na nota e no DANFSe. A nota volta com valores.base_calculo, valores.descontos e valores.deducao. Só no Emissor Nacional (na prefeitura, 422 campo_indisponivel_municipal).ir, pis, cofins, csll, inss.email_tomador_padrao). emails_adicionais (até 10) recebem a nota além dos e-mails do tomador.Acompanhe por GET /nfse/{id} ou pelo webhook. O status vai de processando para autorizada, rejeitada ou falhou (erro_comunicacao enquanto a SEFIN ou a prefeitura não responde; o motor tenta de novo sozinho).
Quer conferir antes de emitir? Mande o mesmo corpo para POST /nfse/simular: o motor monta a DPS, valida no esquema oficial, confere CPF/CNPJ e CEP e assina, mas não envia, não grava e não gasta número. Volta valida, as pendencias (com codigo, descricao e dica) e o xml_dps assinado.
rejeitada com erros: [{codigo, original, mensagem, sugestao}]. Corrija os dados e emita outra, com outro id_externo.Depois da nota
motivo e o mesmo corpo da emissão emite a substituta; quando ela é autorizada, a original fica cancelada com substituicao e chega o webhook nfse.substituida. Só no Emissor Nacional (na prefeitura volta 422 substituicao_indisponivel).autenticidade da nota (depois de autorizada) traz o url_consulta pública, a chave de acesso, o código de verificação e o texto como_verificar; o e-mail ao tomador leva o link de verificação.valor_min e valor_max (valor do serviço), junto com os outros filtros.de, ate, situacao e formato devolve 202; GET /exportacoes/{id} traz o url do ZIP quando concluida (vale 15 min).Empresa e catálogo
inscricao_estadual, email (responde aos e-mails ao tomador), telefone, endereco e as preferências email_tomador_padrao, texto_email_tomador e informacoes_complementares_padrao (usada quando a nota não manda). O logotipo vai em POST /empresas/{id}/logo (PNG ou JPG até 500 KB) e aparece no e-mail ao tomador.ok, mensagem e tentar_novamente.pendente_configuracao até receber outro.documento e nome, até 5.000 linhas). Cada linha é validada sozinha: as com erro voltam em erros e não impedem as outras; com atualizar, os já cadastrados são atualizados.Para produção: a conta liberada para produção, a empresa com certificado e a produção liberada em POST /empresas/{id}/liberar_producao, e uma chave sk_live_.
{ "empresa_id": "8b0d6f0e-2c1a-4f4e-9a57-3f1e2d9c4a10", "id_externo": "pedido-98765", "data_competencia": "2026-11-01", "tomador": { "tipo": "PJ", "documento": "11222333000181", "nome": "Cliente Exemplo LTDA", "email": "financeiro@cliente.com.br", "endereco": { "logradouro": "Rua das Trincheiras", "numero": "100", "bairro": "Centro", "codigo_ibge": "2507507", "uf": "PB", "cep": "58000000" } }, "servico": { "c_trib_nac": "010501", "discriminacao": "Mensalidade do sistema - novembro/2026", "valor": 1500, "iss_retido": false }, "retencoes": { "ir": 0, "pis": 0, "cofins": 0, "csll": 0, "inss": 0 }, "enviar_email_tomador": true }