API de NFS-e Nacional (DPS) — emitir nota de serviço

NFS-e · Emissor Nacional chave ace_

POST /nfse/emitir

Nota Fiscal de Serviço eletrônica no padrão nacional (DPS → SEFIN Nacional), com DANFSe em PDF e XML autorizado. Cobra 1 un. por nota emitida.

O certificado é o da sua empresa. Diferente da NF-e/NFC-e/MDF-e/CT-e/DCe, a NFS-e Nacional é assinada pelo próprio prestador — não existe emissão em nome de terceiro. Cada empresa sobe o seu A1 em POST /nfse/certificado.

Antes de assinar: só dá para emitir se o município do prestador aderiu ao Emissor Nacional. Consulte de graça, sem chave: GET /nfse/municipios/{codigo_ibge}.

1 · Configurar o prestador

PUT /nfse/configuracao — os campos viram o padrão de toda nota.

Campo		Descrição
`cnpj` / `cpf`	obrig.	documento do prestador; tem de ser o mesmo titular do certificado
`cod_municipio`	obrig.	IBGE do município do prestador (7 díg) — precisa ser aderente
`cod_tributacao_nacional`	obrig.	código do serviço na LC 116/03 — confirme com seu contador
`inscricao_municipal`	opc.	IM do prestador na prefeitura
`simples_nacional`	opc.	1=não optante, 2=MEI, 3=ME/EPP no Simples (padrão 1)
`regime_apuracao`	opc.	exigido quando `simples_nacional` ≥ 2
`regime_especial`	opc.	0=nenhum (padrão)
`trib_issqn`	opc.	1=operação tributável (padrão)
`tipo_retencao_issqn`	opc.	1=não retido (padrão)
`serie_dps` · `ambiente`	opc.	série da numeração · 1=produção, 2=homologação (padrão 2)
`ultimo_numero_dps`	opc.	último DPS já emitido fora daqui — a numeração é global por CNPJ+série na SEFIN; ao migrar de outro sistema, informe-o ou toda emissão volta com `E0014`

GET /nfse/configuracao devolve pronto_para_emitir e a lista pendencias[] — consulte-a sempre que a emissão for recusada por configuração.

2 · Enviar o certificado A1

POST /nfse/certificado com certificado_base64 (o .pfx inteiro em base64) e senha. A senha é validada na hora: se estiver errada, nada é gravado. Guardamos o arquivo fora do alcance da web e a senha cifrada. DELETE /nfse/certificado remove.

3 · Emitir

Campo		Descrição
`tomador_nome`	obrig.	razão social ou nome de quem contratou
`tomador_documento`	obrig.	CPF (11) ou CNPJ (14)
`descricao_servico`	obrig.	discriminação do serviço prestado
`valor_servico`	obrig.	valor total, maior que zero
`data_competencia`	opc.	AAAA-MM-DD (padrão: hoje)
`cod_tributacao_nacional`	opc.	sobrescreve o da configuração, nota a nota
`cod_municipio_prestacao`	opc.	onde o serviço foi prestado (padrão: município do prestador)
`tomador_email` · `tomador_fone`	opc.	—
endereço do tomador	opc.	`tomador_logradouro`, `_numero`, `_complemento`, `_bairro`, `_cod_municipio`, `_cep`, `_uf`
`cod_interno`	opc.	seu identificador da nota — só letras e números, até 20 caracteres (padrão: nº do DPS)
`info_complementar`	opc.	informações complementares na nota

Rejeição não fura a numeração: se a SEFIN recusar o DPS, o número não é consumido e nenhuma nota fica pendurada — corrija o payload e reenvie.

Cancelar

POST /nfse/{id}/cancelar com motivo (mínimo 15 caracteres) e codigo_motivo: 1=erro na emissão, 2=serviço não prestado, 3=duplicidade, 4=outros.

Endpoints

GET  /nfse/municipios/{ibge} # público: cidade emite?
GET  /nfse/configuracao      # pendências
PUT  /nfse/configuracao
POST /nfse/certificado       # A1 da sua empresa
POST /nfse/emitir
GET  /nfse/{id}/danfse       # PDF
GET  /nfse/{id}/xml
POST /nfse/{id}/cancelar
GET  /nfse · /nfse/{id}

Configurar & certificado

curl -X PUT .../api/v1/nfse/configuracao \
  -H "Authorization: Bearer ace_SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "cnpj": "53953015000130",
    "inscricao_municipal": "12345",
    "cod_municipio": "3300159",
    "cod_tributacao_nacional": "010701",
    "simples_nacional": 3,
    "regime_apuracao": 1,
    "ambiente": 2
  }'

curl -X POST .../api/v1/nfse/certificado \
  -H "Authorization: Bearer ace_SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"certificado_base64\":\"$(base64 -w0 cert.pfx)\",
       \"senha\":\"SUA_SENHA\"}"

$cli->nfse()->configurar([
  'cnpj' => '53953015000130',
  'cod_municipio' => '3300159',
  'cod_tributacao_nacional' => '010701',
]);
$cli->nfse()->certificado('cert.pfx', 'SUA_SENHA');

Api.ConfigurarNFSe(JSONFromStr(Json));
Api.EnviarCertificado('nfse', Base64DoPfx, 'SUA_SENHA');

Emitir · requisição

curl -X POST .../api/v1/nfse/emitir \
  -H "Authorization: Bearer ace_SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "tomador_nome": "CLIENTE EXEMPLO LTDA",
    "tomador_documento": "11222333000181",
    "tomador_email": "[email protected]",
    "descricao_servico": "Desenvolvimento de software sob encomenda",
    "valor_servico": 1500.00,
    "data_competencia": "2026-07-01"
  }'

$nf = $cli->nfse()->emitir($payload);
$cli->nfse()->danfse($nf['id'], 'danfse.pdf');
$cli->nfse()->cancelar($nf['id'], 'Servico nao foi prestado', 2);

R := Api.EmitirNFSe(JSONFromStr(Json));
Api.BaixarPDF('nfse', R.Int('id'), 'danfse.pdf');
Api.Cancelar('nfse', R.Int('id'), 'Servico nao foi prestado');

200 · data

{ "id": 42, "status": "emitida",
  "ambiente": "homologacao",
  "numero_dps": 7, "serie": 1,
  "chave_acesso": "33001590...(50)",
  "valor_servico": 1500.00,
  "danfse_url": ".../api/v1/nfse/42/danfse",
  "xml_url": ".../api/v1/nfse/42/xml" }

Erros

422 emissao_rejeitada          # traz as pendências ou o erro da SEFIN
422 certificado_invalido       # .pfx corrompido ou senha errada
422 certificado_de_outro_titular
422 certificado_vencido
422 motivo_curto               # cancelamento < 15 caracteres
404 nfse_nao_encontrada
403 produto_nao_vinculado

Não achou o que procurava? Índice da documentação · tabela de erros · servidor MCP · contexto para IA · suporte · [email protected]