Devoluções de venda

Trocas/devoluções de clientes e NF-e de devolução.

Base: https://api.nivesistemas.com.br · 13 endpoints

GET /sale-returns

Listar devoluções de venda

curl -X GET "https://api.nivesistemas.com.br/sale-returns" \
  -H "Authorization: Bearer sl_live_exemplo_abc123xyz789" \
  -H "X-Store-Slug: loja-demo"

const res = await fetch("https://api.nivesistemas.com.br/sale-returns", {
  method: "GET",
  headers: {
    Authorization: "Bearer sl_live_exemplo_abc123xyz789",
    "X-Store-Slug": "loja-demo",
  },
});
const data = await res.json();

import requests

res = requests.request(
    "GET",
    "https://api.nivesistemas.com.br/sale-returns",
    headers={
        "Authorization": "Bearer sl_live_exemplo_abc123xyz789",
        "X-Store-Slug": "loja-demo",
    },
)
print(res.json())

GET /sale-returns/:id

Detalhe

Parâmetros de rota: id

curl -X GET "https://api.nivesistemas.com.br/sale-returns/{id}" \
  -H "Authorization: Bearer sl_live_exemplo_abc123xyz789" \
  -H "X-Store-Slug: loja-demo"

const res = await fetch("https://api.nivesistemas.com.br/sale-returns/{id}", {
  method: "GET",
  headers: {
    Authorization: "Bearer sl_live_exemplo_abc123xyz789",
    "X-Store-Slug": "loja-demo",
  },
});
const data = await res.json();

import requests

res = requests.request(
    "GET",
    "https://api.nivesistemas.com.br/sale-returns/{id}",
    headers={
        "Authorization": "Bearer sl_live_exemplo_abc123xyz789",
        "X-Store-Slug": "loja-demo",
    },
)
print(res.json())

POST /sale-returns/:id/cancel

Cancelar

Parâmetros de rota: id

Corpo (JSON)

Campo	Tipo	Obrigatório	Descrição
`storeCreditAction`	“cancel” \| “keep”	não	Vale-troca da devolução: cancelar junto (padrão) ou manter valendo

curl -X POST "https://api.nivesistemas.com.br/sale-returns/{id}/cancel" \
  -H "Authorization: Bearer sl_live_exemplo_abc123xyz789" \
  -H "X-Store-Slug: loja-demo" \
  -H "Content-Type: application/json" \
  -d '{"storeCreditAction":null}'

const res = await fetch("https://api.nivesistemas.com.br/sale-returns/{id}/cancel", {
  method: "POST",
  headers: {
    Authorization: "Bearer sl_live_exemplo_abc123xyz789",
    "X-Store-Slug": "loja-demo",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "storeCreditAction": null
  }),
});
const data = await res.json();

import requests

res = requests.request(
    "POST",
    "https://api.nivesistemas.com.br/sale-returns/{id}/cancel",
    headers={
        "Authorization": "Bearer sl_live_exemplo_abc123xyz789",
        "X-Store-Slug": "loja-demo",
    },
    json={
      "storeCreditAction": None
    },
)
print(res.json())

PATCH /sale-returns/:id

Atualizar

Parâmetros de rota: id

curl -X PATCH "https://api.nivesistemas.com.br/sale-returns/{id}" \
  -H "Authorization: Bearer sl_live_exemplo_abc123xyz789" \
  -H "X-Store-Slug: loja-demo"

const res = await fetch("https://api.nivesistemas.com.br/sale-returns/{id}", {
  method: "PATCH",
  headers: {
    Authorization: "Bearer sl_live_exemplo_abc123xyz789",
    "X-Store-Slug": "loja-demo",
  },
});
const data = await res.json();

import requests

res = requests.request(
    "PATCH",
    "https://api.nivesistemas.com.br/sale-returns/{id}",
    headers={
        "Authorization": "Bearer sl_live_exemplo_abc123xyz789",
        "X-Store-Slug": "loja-demo",
    },
)
print(res.json())

DELETE /sale-returns/:id

Excluir

Parâmetros de rota: id

Corpo (JSON)

Campo	Tipo	Obrigatório	Descrição
`username`	string	não	Usuário administrador
`password`	string	não	Senha do administrador
`storeCreditAction`	“cancel” \| “keep”	não	Vale-troca da devolução: excluir junto (padrão) ou manter valendo

curl -X DELETE "https://api.nivesistemas.com.br/sale-returns/{id}" \
  -H "Authorization: Bearer sl_live_exemplo_abc123xyz789" \
  -H "X-Store-Slug: loja-demo"

const res = await fetch("https://api.nivesistemas.com.br/sale-returns/{id}", {
  method: "DELETE",
  headers: {
    Authorization: "Bearer sl_live_exemplo_abc123xyz789",
    "X-Store-Slug": "loja-demo",
  },
});
const data = await res.json();

import requests

res = requests.request(
    "DELETE",
    "https://api.nivesistemas.com.br/sale-returns/{id}",
    headers={
        "Authorization": "Bearer sl_live_exemplo_abc123xyz789",
        "X-Store-Slug": "loja-demo",
    },
)
print(res.json())

POST /sale-returns/:id/emit-nfe

Emitir NF-e de devolução

Parâmetros de rota: id

Corpo (JSON)

Campo	Tipo	Obrigatório	Descrição
`taxId`	string	não	CPF/CNPJ do cliente, quando ainda falta no cadastro

curl -X POST "https://api.nivesistemas.com.br/sale-returns/{id}/emit-nfe" \
  -H "Authorization: Bearer sl_live_exemplo_abc123xyz789" \
  -H "X-Store-Slug: loja-demo" \
  -H "Content-Type: application/json" \
  -d '{"taxId":""}'

const res = await fetch("https://api.nivesistemas.com.br/sale-returns/{id}/emit-nfe", {
  method: "POST",
  headers: {
    Authorization: "Bearer sl_live_exemplo_abc123xyz789",
    "X-Store-Slug": "loja-demo",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "taxId": ""
  }),
});
const data = await res.json();

import requests

res = requests.request(
    "POST",
    "https://api.nivesistemas.com.br/sale-returns/{id}/emit-nfe",
    headers={
        "Authorization": "Bearer sl_live_exemplo_abc123xyz789",
        "X-Store-Slug": "loja-demo",
    },
    json={
      "taxId": ""
    },
)
print(res.json())

POST /sale-returns/:id/return-nfe/cancel

Cancelar NF-e de devolução na SEFAZ (até 24h após a autorização)

Parâmetros de rota: id

Corpo (JSON)

Campo	Tipo	Obrigatório	Descrição
`justification`	string	não	Justificativa com 15 a 255 caracteres

curl -X POST "https://api.nivesistemas.com.br/sale-returns/{id}/return-nfe/cancel" \
  -H "Authorization: Bearer sl_live_exemplo_abc123xyz789" \
  -H "X-Store-Slug: loja-demo" \
  -H "Content-Type: application/json" \
  -d '{"justification":""}'

const res = await fetch("https://api.nivesistemas.com.br/sale-returns/{id}/return-nfe/cancel", {
  method: "POST",
  headers: {
    Authorization: "Bearer sl_live_exemplo_abc123xyz789",
    "X-Store-Slug": "loja-demo",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "justification": ""
  }),
});
const data = await res.json();

import requests

res = requests.request(
    "POST",
    "https://api.nivesistemas.com.br/sale-returns/{id}/return-nfe/cancel",
    headers={
        "Authorization": "Bearer sl_live_exemplo_abc123xyz789",
        "X-Store-Slug": "loja-demo",
    },
    json={
      "justification": ""
    },
)
print(res.json())

GET /sale-returns/:id/return-nfe/xml

Baixar XML

Parâmetros de rota: id

curl -X GET "https://api.nivesistemas.com.br/sale-returns/{id}/return-nfe/xml" \
  -H "Authorization: Bearer sl_live_exemplo_abc123xyz789" \
  -H "X-Store-Slug: loja-demo"

const res = await fetch("https://api.nivesistemas.com.br/sale-returns/{id}/return-nfe/xml", {
  method: "GET",
  headers: {
    Authorization: "Bearer sl_live_exemplo_abc123xyz789",
    "X-Store-Slug": "loja-demo",
  },
});
const data = await res.json();

import requests

res = requests.request(
    "GET",
    "https://api.nivesistemas.com.br/sale-returns/{id}/return-nfe/xml",
    headers={
        "Authorization": "Bearer sl_live_exemplo_abc123xyz789",
        "X-Store-Slug": "loja-demo",
    },
)
print(res.json())

GET /sale-returns/:id/return-nfe/pdf

Baixar PDF

Parâmetros de rota: id

curl -X GET "https://api.nivesistemas.com.br/sale-returns/{id}/return-nfe/pdf" \
  -H "Authorization: Bearer sl_live_exemplo_abc123xyz789" \
  -H "X-Store-Slug: loja-demo"

const res = await fetch("https://api.nivesistemas.com.br/sale-returns/{id}/return-nfe/pdf", {
  method: "GET",
  headers: {
    Authorization: "Bearer sl_live_exemplo_abc123xyz789",
    "X-Store-Slug": "loja-demo",
  },
});
const data = await res.json();

import requests

res = requests.request(
    "GET",
    "https://api.nivesistemas.com.br/sale-returns/{id}/return-nfe/pdf",
    headers={
        "Authorization": "Bearer sl_live_exemplo_abc123xyz789",
        "X-Store-Slug": "loja-demo",
    },
)
print(res.json())

GET /sale-returns/:id/return-nfe/danfe-html

DANFE em HTML (autorizada ou cancelada)

Parâmetros de rota: id

curl -X GET "https://api.nivesistemas.com.br/sale-returns/{id}/return-nfe/danfe-html" \
  -H "Authorization: Bearer sl_live_exemplo_abc123xyz789" \
  -H "X-Store-Slug: loja-demo"

const res = await fetch("https://api.nivesistemas.com.br/sale-returns/{id}/return-nfe/danfe-html", {
  method: "GET",
  headers: {
    Authorization: "Bearer sl_live_exemplo_abc123xyz789",
    "X-Store-Slug": "loja-demo",
  },
});
const data = await res.json();

import requests

res = requests.request(
    "GET",
    "https://api.nivesistemas.com.br/sale-returns/{id}/return-nfe/danfe-html",
    headers={
        "Authorization": "Bearer sl_live_exemplo_abc123xyz789",
        "X-Store-Slug": "loja-demo",
    },
)
print(res.json())

POST /sale-returns

Criar devolução de venda

curl -X POST "https://api.nivesistemas.com.br/sale-returns" \
  -H "Authorization: Bearer sl_live_exemplo_abc123xyz789" \
  -H "X-Store-Slug: loja-demo"

const res = await fetch("https://api.nivesistemas.com.br/sale-returns", {
  method: "POST",
  headers: {
    Authorization: "Bearer sl_live_exemplo_abc123xyz789",
    "X-Store-Slug": "loja-demo",
  },
});
const data = await res.json();

import requests

res = requests.request(
    "POST",
    "https://api.nivesistemas.com.br/sale-returns",
    headers={
        "Authorization": "Bearer sl_live_exemplo_abc123xyz789",
        "X-Store-Slug": "loja-demo",
    },
)
print(res.json())

GET /sale-returns/ref-lookup

Devolução avulsa: verifica se a chave da nota de venda é de uma venda deste sistema

Query params

Campo	Tipo	Obrigatório	Descrição
`accessKey`	string	sim	Chave de acesso da NF-e/NFC-e de venda (44 dígitos; pontuação é ignorada)

Resposta: { accessKey, found, sale, previousReturns }. sale traz id, orderNumber, status, completedAt, customerName, documentModel e documentStatus quando found é true. previousReturns lista as devoluções avulsas já lançadas para a mesma chave (id, returnNumber, totalAmount, processedAt) para evitar devolver duas vezes.

curl -X GET "https://api.nivesistemas.com.br/sale-returns/ref-lookup" \
  -H "Authorization: Bearer sl_live_exemplo_abc123xyz789" \
  -H "X-Store-Slug: loja-demo"

const res = await fetch("https://api.nivesistemas.com.br/sale-returns/ref-lookup", {
  method: "GET",
  headers: {
    Authorization: "Bearer sl_live_exemplo_abc123xyz789",
    "X-Store-Slug": "loja-demo",
  },
});
const data = await res.json();

import requests

res = requests.request(
    "GET",
    "https://api.nivesistemas.com.br/sale-returns/ref-lookup",
    headers={
        "Authorization": "Bearer sl_live_exemplo_abc123xyz789",
        "X-Store-Slug": "loja-demo",
    },
)
print(res.json())

POST /sale-returns/standalone

Devolução avulsa de venda feita em outro sistema, informando só a chave da nota de venda

Corpo (JSON)

Campo	Tipo	Obrigatório	Descrição
`refAccessKey`	string	sim	Chave de acesso (44 dígitos válidos) da NF-e (55) ou NFC-e (65) de venda original
`confirmSaleNotFound`	boolean	sim	Deve ser true: confirma que a venda não está neste sistema
`items`	array	sim	[{ variantId, quantity, unitPrice }] — de 1 a 200 itens; unitPrice maior que zero
`customerId`	uuid	não	Cliente (opcional; vira o destinatário da NF-e de devolução e o titular do vale-troca)
`locationId`	uuid	não	Filial da devolução (padrão: filial de operação do usuário)
`reason`	string	não	Motivo (até 500)
`restockItems`	boolean	não	Devolver os itens ao estoque (padrão true)
`issueStoreCredit`	boolean	não	Gerar vale-troca para o cliente (padrão false)
`emitReturnNfe`	boolean	não	Emitir NF-e de devolução referenciando a nota original (padrão true)

Resposta: 201 Created — a devolução registrada (id, returnNumber, totalAmount…).

curl -X POST "https://api.nivesistemas.com.br/sale-returns/standalone" \
  -H "Authorization: Bearer sl_live_exemplo_abc123xyz789" \
  -H "X-Store-Slug: loja-demo" \
  -H "Content-Type: application/json" \
  -d '{"refAccessKey":"","confirmSaleNotFound":true,"items":[],"customerId":"00000000-0000-0000-0000-000000000000","locationId":"00000000-0000-0000-0000-000000000000","reason":"","restockItems":true,"issueStoreCredit":true,"emitReturnNfe":true}'

const res = await fetch("https://api.nivesistemas.com.br/sale-returns/standalone", {
  method: "POST",
  headers: {
    Authorization: "Bearer sl_live_exemplo_abc123xyz789",
    "X-Store-Slug": "loja-demo",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "refAccessKey": "",
    "confirmSaleNotFound": true,
    "items": [],
    "customerId": "00000000-0000-0000-0000-000000000000",
    "locationId": "00000000-0000-0000-0000-000000000000",
    "reason": "",
    "restockItems": true,
    "issueStoreCredit": true,
    "emitReturnNfe": true
  }),
});
const data = await res.json();

import requests

res = requests.request(
    "POST",
    "https://api.nivesistemas.com.br/sale-returns/standalone",
    headers={
        "Authorization": "Bearer sl_live_exemplo_abc123xyz789",
        "X-Store-Slug": "loja-demo",
    },
    json={
      "refAccessKey": "",
      "confirmSaleNotFound": True,
      "items": [],
      "customerId": "00000000-0000-0000-0000-000000000000",
      "locationId": "00000000-0000-0000-0000-000000000000",
      "reason": "",
      "restockItems": True,
      "issueStoreCredit": True,
      "emitReturnNfe": True
    },
)
print(res.json())