Devolução de Venda - NF-e

Para realizar o cancelamento de uma venda acobertada por NF-e após o tempo de cancelamento da nota, é necessário emitir uma nota de devolução. Para a emissão da nota de devolução deve ser utilizada a rota aqui documentada.  

Esta rota está preparada para devoluções parciais ou totais. 

Autenticação

Para utilizar a rota de devolução de venda NF-e é necessário realizar autenticação, conforme detalhado na documentação de Autenticação do Emissor

---

API Devolução de Venda

• Endpoint: /nfemiddleware/Sale/Return
• Método: POST
• Header:
  • Authorization: Token de autorização
  • Content-Type: application/json 

Dados dos parâmetros de envio:

Campo	Descrição	Obrigatório Simples e MEI	Obrigatório Regime Normal	Grupo e Tag do XML que irá alimentar
Id	Id único da venda. Não poderá se repetir. Recomendado utilizar um GUID	Sim	Sim	-
SaleId	ID gerado no momento da venda	Sim	Sim	-
Cnpj	CNPJ do emissor	Sim	Sim	-
NumeroSerie	Número de série do documento fiscal. Recomendado um por PDV	Sim	Sim	serie
dhSaiEnt	Data/Hota da Saída. Se não informado será utilizada a  data da emissão	Não	Não	dhSaiEnt
tpDANFE	Tipo de Danfe a ser retornado 1 - Retrato 5 - Simplificado  6 - Simplificado SC 7 - Etiqueta 8 - Paisagem	Sim	Sim
infCpl	Informações Complementares de interesse do Contribuinte	Não	Não	infCpl
Items	Array de itens a serem desenvolvidos	Sim	Sim	-
Items.cProd	Código do produto informado na venda	Sim	Sim	cProd
Items.qCom	Quantidade a ser devolvida	Sim	Sim	qCom
Items.qTrib	Quantidade tributada a ser devolvida	Não	Não	qTrib
Items.infAdProd	Informação adicional do produto	Não	Não	infAdProd
Items.CSTPisDevolucao	Informar o CST que será vinculado ao PIS	Não	Sim	PIS - CST
Items.CSTCofinsDevolucao	Informar o CST que será vinculado ao COFINS	Não	Sim	PIS - COFINS

---

Exemplo Payload de Envio

{
"Id": "{{$guid}}",
"SaleId": "9058d650-5838-4f8e-b05f-de6a69fd4e67 ",
"NumeroSerie": "2",
"Cnpj": "99999999999999",
"dhSaiEnt": "2025-06-24T15:50:50TZD",
"tpDANFE": 1,
"infCpl": "Observações",
"Items": [
{
"cProd": "1",
"qCom": 1,
"qTrib": 1,
"infAdProd": ""
}
]
}

---

O retorno da API poderá ser o documento autorizado ou a rejeição do documento. Segue o detalhamento dos parâmetros retornados:

Tag	Descrição
chNFe	Chave da nota fiscal
cStat	Status vinculado ao documento. Os possíveis status serão detalhados em tópico específico.
xMotivo	Descrição do status do documento
danfe	DANFE em PNG. Deverá decodificar de Base64
nNF	Número do documento fiscal
xUrlDanfe	URL de consulta do documento fiscal na Sefaz

---

Exemplo Payload de Retorno

{
"chNFe": "35250649792429000158550020004001961370973520",
"cStat": "100",
"danfe": "Base64",
"nNF": 400196,
"xMotivo": "Autorizado o uso da NF-e",
"xUrlDanfe": null
}

---

Detalhamento campo cStat

Neste campo poderão haver retornos de status da SEFAZ e da Solução Fiscal, conforme segue

Retornos da SEFAZ

• Autorização:
  • 100 – Autorizado
• Rejeições:
  • Consultar todos os códigos de rejeição vinculados a emissão de documento no manual de orientação ao contribuinte (MOC – Anexo I) disponível no item “4.4.2. Tabela de Códigos de Rejeição”

Retornos da Solução Fiscal

• Rejeições

Retorno	Como Resolver
M0001 - O CNPJ não está cadastro para emissão.	Necessário cadastrar o CNPJ emissor na Solução Fiscal (Cadastro Emissor/Empresa). Após cadastrar o Emissor e gerar chave para ele autenticar, basta realizar a devolução novamente.
M0002 - O CNPJ está inativo para emissão.	Necessário vincular produto de emissão de NF-e no cadastro do CNPJ emissor na Solução Fiscal. Campos Produto e Produtos ID. (Cadastro Emissor/Empresa). Após realizar este ajuste, basta realizar a venda novamente.
M0003 - Não existe um certificado cadastrado para o CNPJ.	Necessário realizar upload de Certificado Digital para o CNPJ Emissor, conforme descrito na documentação Gestão Certificado Digital. Após enviar o Certificado basta realizar a devolução novamente.
M0004 - O certificado está inativo para este CNPJ.	Isso significa que o certificado vinculado ao CNPJ emissor foi revogado ou venceu. Para resolver é necessário que o Certificado Digital seja substituído e enviado para Solução Fiscal. Após substituir o Certificado basta realizar a venda novamente.
M0013 - Nota já autorizada com data de emissão.	A nota referente a esta venda já foi emitida. Para obter o documento emitido basta acionar a API de Consulta (Consulta Venda - NF-e)

---

Possíveis retornos HTTP

• 200 - Sucesso
• 400 – BadRequest
  • Caso tenha algum problema nas informações enviadas, causando falha na Solução Fiscal ou rejeição pela Sefaz
• 401 - Unauthorized
• 404 – NotFound
• 429 - TooManyRequests
• 500 - InternalServerError
• 503 - Service Unavailable