--- title: "Registrar/atualizar nota fiscal do pedido" method: PATCH path: "/pedidos/{pedidoId}/nota" tags: ["Pedidos"] --- # Registrar/atualizar nota fiscal do pedido `PATCH /pedidos/{pedidoId}/nota` ## Request - Base URL: `https://app.vendizap.com/api` - URL: `https://app.vendizap.com/api/pedidos/{pedidoId}/nota` - Auth: API key in header `X-Auth-Id` and API key in header `X-Auth-Secret` 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. ## Request body - PedidoNotaInput: É obrigatório informar `chave` ou `numero` (identidade mínima da nota). A nota enviada é a mesma nota já registrada no pedido quando têm a mesma `chave`, **ou** o mesmo `tipo` + `serie` + `numero` (`serie` ausente equivale a vazia); nesse caso o registro existente é 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. Máximo de 20 notas ativas por pedido (excluídas não contam); teto de 40 no total (ativas + excluídas). - `tipo` 'nfe' | 'nfce' | 'nfse' | 'cte' | 'sat', required: Tipo do documento: NF-e, NFC-e, NFS-e, CT-e ou SAT. - `chave` string: Chave de acesso, só dígitos: 44 dígitos para nfe/nfce/cte/sat, 50 para nfse (padrão nacional). NFS-e municipal sem chave é aceita, identificada por `numero` + `codigoVerificacao`. - `numero` union: Sempre gravado como texto, com zero à esquerda preservado (ex.: `"000123"`). Número JSON inteiro também é aceito e convertido para string. `null` e `""` equivalem a não informado. - string - integer - `serie` union: Mesma regra de `numero` (texto, aceita número JSON convertido; `null`/`""` = não informado). - string - integer - `protocolo` union: Mesma regra de `numero` (texto, aceita número JSON convertido; `null`/`""` = não informado). - string - integer - `codigoVerificacao` union: Código de verificação (usado por NFS-e municipais sem chave). Mesma regra de `numero` (texto, aceita número JSON convertido; `null`/`""` = não informado). - string - integer - `situacao` 'autorizada' | 'cancelada' | 'denegada' | 'inutilizada': Quando a nota ainda não tem situação gravada, o padrão é `autorizada`. Reenviar a nota sem `situacao` preserva a situação já gravada. - `dataEmissao` string: ISO 8601: `AAAA-MM-DD` ou `AAAA-MM-DDTHH:MM:SS` (ou `AAAA-MM-DDTHH:MM`, sem segundos), com ou sem offset/`Z`. Também aceita espaço no lugar do `T`. Sem offset, assume o fuso America/Sao_Paulo. - `valor` number - `linkPdf` string, uri: URL http/https do PDF (DANFE/DACTE/espelho). - `linkXml` string, uri: URL http/https do XML autorizado. - `excluir` boolean: Exclusão lógica: `true` marca a nota (identificada pela mesma regra de identidade acima — `chave`, ou `tipo`+`serie`+`numero`) como excluída — ela continua gravada, mas some de todo retorno da API (`GET /pedidos`, `GET /pedidos/{pedidoId}` e da resposta deste PATCH). Segue a regra de merge dos demais campos: só muda quando enviado — reenviar a nota sem `excluir` não ressuscita uma nota excluída; para reativar, envie `excluir: false` explícito. `excluir: true` numa identidade que ainda não existe no pedido responde 400 (não cria uma nota já excluída). `null` equivale a não informado. Só aceita booleano JSON — outros valores (ex.: `"true"`, `1`) respondem 400. ## Response `200` Notas do pedido após a gravação. - object - `notas` NotaFiscalPedido[] - `tipo` 'nfe' | 'nfce' | 'nfse' | 'cte' | 'sat': Tipo do documento: NF-e, NFC-e, NFS-e, CT-e ou SAT. - `chave` string: Chave de acesso (só dígitos). - `numero` string - `serie` string - `protocolo` string - `codigoVerificacao` string: Código de verificação (usado por NFS-e municipais sem chave). - `situacao` 'autorizada' | 'cancelada' | 'denegada' | 'inutilizada' - `dataEmissao` string: Data e hora de emissão no formato `AAAA-MM-DD HH:MM:SS` (fuso America/Sao_Paulo), igual ao campo `data` do pedido. - `valor` number - `linkPdf` string, uri: URL do PDF (DANFE/DACTE/espelho). - `linkXml` string, uri: URL do XML autorizado. - `atualizadaEm` string: Data e hora da última gravação desta nota, mesmo formato de `dataEmissao`. ## Other responses - `400`: Erro na requisição que não foi possível ser completada. O erro é retornado em uma string (não JSON). - `401`: Credenciais informadas inválidas. - `409`: Conflito de concorrência que impede a requisição de ser completada agora. O erro é retornado em uma string (não JSON). --- [API](https://skmtc.dev/vendizap/apis/api-vendizap.md) · [All operations](https://skmtc.dev/vendizap/apis/api-vendizap/llms.txt) · [OpenAPI document](https://skmtc.dev/vendizap/apis/api-vendizap/revisions/2c0d0a254abb?raw)