Como emitir NFS-e Nacional com Prestador Pessoa Física (CPF e CAEPF) via API REST

Se você desenvolve um software para clínicas médicas, plataformas de psicologia, escritórios de advocacia, engenharia ou gestão do agronegócio, provavelmente já bateu de frente com uma limitação clássica das APIs fiscais legadas: tentar cadastrar um cliente que presta serviço como Pessoa Física (CPF) ou possui inscrição no CAEPF (Cadastro de Atividade Econômica da Pessoa Física) e receber um erro 400 CNPJ inválido — esperado 14 dígitos.

Durante anos, a maioria dos integradores fiscais brasileiros tratou o emitente da nota exclusivamente como Pessoa Jurídica. Só que na vida real — especialmente com a expansão do Padrão Nacional de NFS-e (SNNFSE) — milhares de médicos, dentistas, terapeutas, consultores autônomos e produtores rurais emitem Nota Fiscal de Serviço Eletrônica utilizando certificado digital e-CPF (A1) e, em diversos casos, precisam vincular o número do CAEPF no XML da Declaração de Prestação de Serviços (DPS).

Emitir NFS-e Nacional com prestador CPF e CAEPF exige mudanças estruturais no XML da DPS v1.01: o identificador de 45 posições (TSIdDPS) muda o tipo de inscrição para 1 com zero-padding de 14 dígitos, o grupo <prest> substitui <CNPJ> por <CPF> seguido de <CAEPF>, e o pedido de cancelamento passa a exigir <CPFAutor> no lugar de <CNPJAutor>.

Aqui na Notaas, nós acabamos de liberar o suporte nativo completo a Prestador CPF e CAEPF em toda a nossa engine nacional, nos endpoints da Organization API (Multi-Cliente) e na renderização local do DANFSe v2.0 (NT-008). Neste artigo, vou mostrar exatamente o que muda no schema XSD da Receita Federal e como você pode automatizar essa emissão com um único JSON.

Quando o seu SaaS atende médicos, dentistas, autônomos ou produtores rurais, obrigar o profissional a abrir um CNPJ só porque a sua API fiscal não aceita e-CPF é perder cliente na porta de entrada.

O que muda no XSD da DPS Nacional quando o prestador é CPF com CAEPF

Quem já construiu um builder XML para o SNNFSE sabe que o validador da SEFIN Nacional (sefin.nfse.gov.br) não perdoa um único caractere fora de posição. Quando saímos do cenário padrão de PJ (14 dígitos) para um prestador Pessoa Física (11 dígitos) com ou sem CAEPF, existem quatro armadilhas técnicas no schema DPS_v1.01.xsd e no pedRegEvento_v1.01.xsd:

1. A formação do atributo Id da DPS (TSIdDPS de 45 caracteres)

No padrão nacional, toda tag <infDPS Id="DPS..."> carrega um identificador único de 45 caracteres composto por:

• DPS (3 caracteres fixos)
• cLocEmi (7 dígitos do código IBGE do município emissor)
• tpInscr (1 dígito: 1 para CPF ou 2 para CNPJ)
• nInscr (14 dígitos da inscrição federal)
• serie (5 dígitos numéricos com zeros à esquerda)
• nDPS (15 dígitos do número da DPS com zeros à esquerda)

Aqui mora o primeiro erro que derruba 90% das implementações caseiras: mesmo quando tpInscr é igual a 1 (CPF), o campo nInscr continua exigindo 14 posições numéricas. Ou seja, os 11 dígitos do CPF precisam ser preenchidos com três zeros à esquerda (000 + CPF). Se você concatenar apenas os 11 dígitos do CPF, a chave ficará com 42 caracteres e a SEFIN rejeitará o XML imediatamente por violação da regex DPS[0-9]{42}.

Veja como tratamos a construção determinística do TSIdDPS em TypeScript:

export function buildDpsId(params: {
  codigoIbge: string;
  documentoPrestador: string; // CPF (11) ou CNPJ (14)
  serie: string | number;
  numeroDps: string | number;
}): string {
  const docDigits = params.documentoPrestador.replace(/\D/g, '');
  const isCpf = docDigits.length === 11;

  // tpInscr: '1' = CPF (com left-pad para 14 dígitos), '2' = CNPJ
  const tpInscr = isCpf ? '1' : '2';
  const inscricao14 = docDigits.padStart(14, '0');
  const ibge7 = params.codigoIbge.replace(/\D/g, '').padStart(7, '0');
  const serie5 = String(params.serie).replace(/\D/g, '').padStart(5, '0');
  const nDps15 = String(params.numeroDps).replace(/\D/g, '').padStart(15, '0');

  return `DPS${ibge7}${tpInscr}${inscricao14}${serie5}${nDps15}`;
}

2. A ordem estrita de <CPF>, <CAEPF> e <IM> dentro de <prest>

No schema XSD da DPS (TCInfoPrestador), a escolha entre <CNPJ> e <CPF> é um xs:choice, mas o elemento <CAEPF> (tipo TSCAEPF, validado pela regex [0-9]{14}) é um elemento opcional posicionado estritamente após a identificação federal e antes da Inscrição Municipal (<IM>).

Se você enviar <CAEPF> depois de <IM> ou enviar <CAEPF> com máscara (123.456.789/001-23), o schema falha na validação XSD antes mesmo de avaliar as regras de negócio:

<prest>
  <CPF>12345678901</CPF>
  <CAEPF>12345678900123</CAEPF>
  <IM>987654</IM>
  <regTrib>
    <opSimpNac>1</opSimpNac>
    <regEspTrib>0</regEspTrib>
  </regTrib>
</prest>

Além disso, para um prestador Pessoa Física (autônomo ou profissional liberal), o campo <opSimpNac> deve ser preenchido como 1 (Não Optante pelo Simples Nacional), já que pessoa física não adere ao regime do Simples Nacional exclusivo de PJ.

3. O evento de cancelamento (e101101) exige <CPFAutor>

Outro ponto que costuma passar batido em homologação e só explode quando o cliente tenta cancelar uma nota emitida em produção é o schema de eventos (pedRegEvento_v1.01.xsd). No bloco <infPedReg>, o autor do evento também é um xs:choice:

• Para empresas (14 dígitos): <CNPJAutor>12345678000199</CNPJAutor>
• Para prestadores PF (11 dígitos): <CPFAutor>12345678901</CPFAutor>

Se o seu sistema emitir a nota com <CPF> na DPS, mas tentar assinar o pedido de cancelamento enviando <CNPJAutor>, a prefeitura ou o ambiente nacional bloqueará o cancelamento.

4. Exibição do CAEPF no DANFSe v2.0

Quando o prestador possui CAEPF — muito comum em serviços prestados por produtores rurais pessoa física ou contribuintes individuais com matrícula específica na Receita Federal — o contador do tomador exige que o número do CAEPF apareça impresso no quadro do Prestador do Serviço no PDF da nota. No gerador local de DANFSe v2.0 da Notaas, extraímos automaticamente a tag <CAEPF> do XML autorizado e a exibimos formatada (XXX.XXX.XXX/XXX-XX) no cabeçalho do prestador.

Como provisionar projetos CPF + CAEPF e emitir via API JSON na Notaas

Em vez de construir condicionais de XSD para CPF, CNPJ e CAEPF no seu código, você pode gerenciar tanto clientes PJ quanto clientes PF na mesma estrutura usando a Notaas.

⚡ Fluxo Multi-Cliente para Prestadores PF e PJ (Org API):

• 1. Provisionamento (POST /api/v1/org/projects): Seu SaaS cadastra o prestador enviando o CPF de 11 dígitos no campo cnpj e os 14 dígitos no campo caepf (opcional).
• 2. Upload do Certificado e-CPF A1: Envia o arquivo .pfx/.p12 do profissional liberal para o projeto criado.
• 3. Emissão Unificada (POST /api/v1/emitir): Envia o JSON da prestação de serviço; a Notaas monta o TSIdDPS com tpInscr=1, injeta <CPF> e <CAEPF> no XML, assina e transmite.
• 4. PDF e Webhook: Você recebe o XML assinado e o PDF do DANFSe v2.0 já com o CAEPF formatado.

Passo 1: Cadastrando o Prestador PF (com CAEPF) via Org API

Se você tem uma plataforma vertical (como um sistema para clínicas ou escritório contábil), pode provisionar o projeto do profissional liberal via POST /api/v1/org/projects:

curl -X POST "https://platform.notaas.com.br/api/v1/org/projects" \
  -H "Authorization: Bearer ntaas_org_seu_token_organizacao" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Dr. Marcos Silva - Clínica Odontológica",
    "cnpj": "12345678901",
    "caepf": "123.456.789/001-23",
    "razaoSocial": "Marcos Silva Odontologia",
    "inscricaoMunicipal": "445566",
    "codigoMunicipio": "3550308",
    "regimeTributario": 1,
    "ambiente": 2
  }'

Repare em três detalhes pensados para facilitar a vida do desenvolvedor:

1. O campo caepf aceita tanto os 14 dígitos puros ("12345678900123") quanto a máscara oficial ("123.456.789/001-23"), validando o formato TSCAEPF antes de salvar.
2. Se você tentar associar um caepf a um projeto CNPJ (14 dígitos), a API retorna um erro claro de validação (400 Bad Request), já que o CAEPF é exclusivo de Pessoa Física.
3. No Plano Free, você pode criar até 5 projetos simultâneos em Homologação (ambiente: 2) usando a Org API para testar toda a sua esteira multi-cliente sem custo, além de contar com 20 notas fiscais gratuitas por mês em Produção (ambiente: 1) para 1 projeto.

Passo 2: Emitindo a NFS-e Nacional com CPF e CAEPF

Com o caepf configurado no projeto, todas as emissões daquele prestador já incluirão <CAEPF> automaticamente no XML da DPS. Caso você queira informar ou sobrescrever o CAEPF em uma nota específica (ou suprimi-lo passando null), basta enviar no payload do POST /api/v1/emitir:

{
  "externalId": "consulta-odonto-2026-1084",
  "ambiente": 1,
  "tomador": {
    "cpfCnpj": "98765432100",
    "razaoSocial": " Juliana Ferreira Mendes",
    "email": "juliana.mendes@email.com.br",
    "endereco": {
      "cep": "01310100",
      "logradouro": "Avenida Paulista",
      "numero": "1000",
      "bairro": "Bela Vista",
      "codigoMunicipio": "3550308",
      "uf": "SP"
    }
  },
  "servico": {
    "codigoTributacaoNacional": "040101",
    "discriminacao": "Consulta e profilaxia odontológica especializada",
    "valorServicos": 350.00,
    "caepf": "12345678900123"
  }
}

Se a sua aplicação também precisa lidar com rateio de receitas entre profissionais — como acontece em clínicas de estética e salões de beleza —, recomendo ler nosso guia sobre emissão de NFS-e na Lei do Salão-Parceiro e deduções no SNNFSE e nosso artigo sobre como preparar sistemas contábeis para a Reforma Tributária (IBS e CBS).

Escale seu SaaS para profissionais liberais e PJ na mesma API

Não importa se o seu cliente final é um médico autônomo emitindo com e-CPF, um produtor rural com CAEPF ou uma rede de clínicas com dezenas de CNPJs: a sua camada de integração fiscal deve ser uma só.

• Plano Free (R$ 0/mês): 20 notas fiscais gratuitas por mês em Produção (1 projeto) + até 5 projetos simultâneos em Homologação na Org API para você homologar sua arquitetura multi-tenant sem cartão de crédito.
• Plano Dev (R$ 99/mês): 500 notas/mês + até 3 projetos em Produção (e 10 em Homologação).
• Plano SaaS Pro (R$ 249/mês): 2.000 notas/mês + projetos/CNPJs/CPFs ilimitados em Produção e Homologação + White-Label.

👉 Criar Conta Gratuita na Notaas · Consultar Documentação da Org API