Substituição

POST /v1/notas/{notaId}/substituicao com o token de acesso, onde {notaId} é a nota original, a que será substituída (referência). A substituição corrige uma nota autorizada (descrição, códigos, retenção, dados do tomador) sem cancelar e emitir de novo: a API emite uma nota nova, a substituta, com o grupo de substituição da Sefin Nacional (chave da original, cMotivo e xMotivo). Autorizada a substituta, a Sefin Nacional cancela a original por substituição. O processamento é assíncrono, como a emissão.

Corpo do pedido

• nota (obrigatório): a nota corrigida completa, no mesmo formato de uma nota do lote e com as mesmas recusas (envio do lote). Não é uma alteração parcial: todos os campos são enviados de novo, inclusive os que não mudaram. A chave da original não vai no corpo: a API a lê da nota indicada no endereço.
• nota.idOperacao: novo, escolhido pelo seu sistema, com a mesma idempotência do lote. Repetir o pedido com o mesmo idOperacao para a mesma original devolve 202 com a substituta já gravada, sem criar outra. Um idOperacao já usado por outra nota do emitente recebe 409 ID_OPERACAO_EM_USO.
• cMotivo (obrigatório): texto, um de 01 (desenquadramento do Simples Nacional), 02 (enquadramento no Simples Nacional), 03 (inclusão retroativa de imunidade ou isenção), 04 (exclusão retroativa de imunidade ou isenção), 05 (rejeição pelo tomador ou intermediário) e 99 (outros). Número JSON (99 sem aspas) é recusado.
• xMotivo: obrigatório com cMotivo 99 e opcional com os demais; quando informado, de 15 a 255 caracteres depois de remover os espaços das pontas, só com caracteres de U+0020 a U+00FF, a mesma regra do motivo do cancelamento.
• Só nota autorizada pode ser substituída, e só uma substituição por vez para a mesma original.

Requisição

POST /v1/notas/3f8b2c1a-6d4e-4b7f-9a21-0c5e8d7f6a10/substituicao HTTP/1.1
Host: hml.nfse.lideraweb.com
Authorization: Bearer <seu-token>
Content-Type: application/json

{
  "nota": {
    "idOperacao": "FAT-1001-S1",
    "competencia": "2026-11-10",
    "tomador": {
      "documento": "11222333000181",
      "nome": "Cliente Exemplo Ltda",
      "email": "financeiro@cliente.example",
      "endereco": {
        "cep": "30130000",
        "logradouro": "Rua Exemplo",
        "numero": "100",
        "bairro": "Centro",
        "codigoMunicipio": "3106200"
      }
    },
    "servico": {
      "codigoTributacaoNacional": "010701",
      "descricao": "Desenvolvimento de sistema sob encomenda"
    },
    "valores": {
      "valorServico": 1450,
      "issRetido": false
    }
  },
  "cMotivo": "99",
  "xMotivo": "Correção do valor do serviço informado na nota"
}

curl -X POST "$BASE_URL/notas/3f8b2c1a-6d4e-4b7f-9a21-0c5e8d7f6a10/substituicao" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  --data '{
  "nota": {
    "idOperacao": "FAT-1001-S1",
    "competencia": "2026-11-10",
    "tomador": {
      "documento": "11222333000181",
      "nome": "Cliente Exemplo Ltda",
      "email": "financeiro@cliente.example",
      "endereco": {
        "cep": "30130000",
        "logradouro": "Rua Exemplo",
        "numero": "100",
        "bairro": "Centro",
        "codigoMunicipio": "3106200"
      }
    },
    "servico": {
      "codigoTributacaoNacional": "010701",
      "descricao": "Desenvolvimento de sistema sob encomenda"
    },
    "valores": {
      "valorServico": 1450,
      "issRetido": false
    }
  },
  "cMotivo": "99",
  "xMotivo": "Correção do valor do serviço informado na nota"
}'

Resposta 202, com a nota substituta:

{
  "id": "b2d4f6a8-1c3e-4a5b-8c7d-9e0f1a2b3c4d",
  "idOperacao": "FAT-1001-S1",
  "loteId": "9d8c7b6a-5f4e-4d3c-a2b1-0f9e8d7c6b5a",
  "status": "recebida",
  "ambiente": "homologacao",
  "substitui": {
    "notaId": "3f8b2c1a-6d4e-4b7f-9a21-0c5e8d7f6a10",
    "chaveAcesso": "31062002211222333000181000000000012326110000001234",
    "cMotivo": "99",
    "xMotivo": "Correção do valor do serviço informado na nota"
  }
}

Guarde o id da substituta: é por ele que o seu sistema acompanha a substituição.

O que não pode mudar

A API compara a substituta com a original conforme o perfil do emitente e recusa na hora, com 422 SUBSTITUICAO_NAO_PERMITIDA, sem gravar nada. campos traz um item por campo alterado, com codigo (E0061 ou E0060), campo e mensagem.

O exemplo acima altera o valor do serviço, o que só vale para emitente não optante.

Desfecho

• Substituta autorizada: chegam dois eventos no webhook: autorizada da substituta, com nota.substitui, e substituida da original, com nota.status substituida e nota.substituidaPor. A original mantém o XML, os links e o DANFSe, que passa a sair com a marca "SUBSTITUÍDA".
• Substituta rejeitada (pela Sefin Nacional ou pela validação antes do envio): chega só o evento rejeitada da substituta, com nota.erro e nota.substitui. A original continua autorizada, sem evento. Para tentar de novo, corrija e peça outra substituição com outro idOperacao. Rejeições comuns: E0050 (fora do prazo de substituição do município; não vale para os motivos 01 e 02), E0070 e E0072 (a nota já foi confirmada pelo tomador ou pelo intermediário).
• Em processamento: enquanto a substituta não tem desfecho, a original continua autorizada e recusa outro pedido de substituição e o pedido de cancelamento com 409 NOTA_EM_ESTADO_INCOMPATIVEL. Continue consultando a substituta.
• Nova correção: para corrigir de novo uma nota já substituída, substitua a substituta (substituidaPor.notaId).

Respostas de erro