Registra os dados do documento fiscal (NF-e, NFC-e, NFS-e, CT-e ou SAT) emitido para o pedido — uso típico de parceiros/ERPs que emitem a nota e devolvem os dados para a Vendizap. Um pedido pode ter várias notas (ex.: venda + devolução, envio parcial, produto + frete).

Cada chamada envia uma nota. A nota é a mesma nota já gravada no pedido quando têm a mesma chave, ou o mesmo tipo + serie + numero (serie ausente equivale a vazia); nesse caso o registro é atualizado (mesclando — campos não enviados mantêm o valor anterior) em vez de duplicado. Uma chave diferente com tipo + serie + numero iguais também atualiza a nota existente — a chave nova substitui a anterior.

É obrigatório informar chave ou numero. A situacao tem padrão autorizada quando a nota ainda não tem situação gravada; reenviar sem situacao preserva a que já está gravada. numero, serie, protocolo e codigoVerificacao são sempre gravados como texto (zero à esquerda preservado); um número JSON inteiro também é aceito e convertido para string.

excluir: true marca a nota como excluída (identificada pela mesma regra de chave, ou tipo + serie + numero): ela continua gravada no banco, mas some de qualquer retorno da API — não aparece no GET /pedidos, no GET /pedidos/{pedidoId} nem na resposta deste PATCH. excluir segue a mesma regra de merge dos demais campos: só muda quando informado no body — reenviar a nota sem excluir não ressuscita uma nota excluída; para reativar, envie excluir: false explícito. Excluir a mesma nota duas vezes responde 200 nas duas (retry de ERP); excluir: true numa identidade que não existe no pedido responde 400 (não cria uma nota já excluída). Um pedido com todas as notas excluídas some do campo notas no GET (campo ausente, como pedido sem nota), mas a resposta deste PATCH devolve {"notas": []}.

Máximo de 20 notas ativas por pedido (excluídas não contam); teto de 40 no total (ativas + excluídas) — é o que permite abrir espaço excluindo uma nota gravada por engano.

Registrar uma nota atualiza a data de última alteração do pedido — ele volta a aparecer no polling GET /pedidos por data de atualização (tipoData=atualizacao).

Retorna o array completo de notas do pedido após a gravação.

Respostas 400 (texto): id do pedido inválido; pedido não encontrado (inclui pedido de outra loja ou de vendedor vinculado); tipo da nota inválido; chave com quantidade de dígitos errada para o tipo; nem chave nem numero informados; situação inválida; campo de texto (numero, serie, protocolo, codigoVerificacao) que não é texto nem número, ou com mais de 60 caracteres; data de emissão fora do formato ISO 8601; valor não numérico ou negativo; linkPdf/linkXml que não é uma URL http/https válida ou tem mais de 2048 caracteres; excluir que não é um booleano; excluir: true numa identidade que não existe no pedido; limite de 20 notas ativas por pedido atingido; limite de 40 notas por pedido (contando as excluídas) atingido.

Resposta 409 (texto): após 3 tentativas, outra gravação de nota concorrente no mesmo pedido impediu a escrita — repita a chamada.

{
  "tipo": "nfe",
  "dataEmissao": "2026-09-03T10:06:15-03:00"
}

{
  "notas": [
    {
      "tipo": "nfe",
      "numero": "000980",
      "serie": "001",
      "protocolo": "135260000012345",
      "chave": "35260912345678901234550010000019801234567890",
      "situacao": "autorizada",
      "dataEmissao": "2026-09-03 10:06:15",
      "valor": 199.9,
      "linkPdf": "https://exemplo.com/danfe.pdf",
      "linkXml": "https://exemplo.com/nfe.xml",
      "atualizadaEm": "2026-09-03 16:51:43"
    }
  ]
}