Devoluciones

El recurso Devoluciones te permite consultar los reembolsos registrados en Zelta POS. Es de solo lectura.

Todas las rutas son relativas a la URL base de producción:

https://api-pos.zelta.dev/public/v1

INFO

Las devoluciones se generan desde el dashboard de Zelta POS. Por API solo se consultan; no se crean ni se modifican.

Listar devoluciones

GET /returns

Devuelve la lista de devoluciones en un envoltorio { "data": [ ... ] }. Soporta paginación y sincronización incremental (start, limit, updatedSince, from/to, metadata). Consulta la .

curl "https://api-pos.zelta.dev/public/v1/returns?limit=30&metadata=true" \
  -H "Authorization: Bearer zpk_live_xxx"

Ejemplo JS

const res = await fetch('https://api-pos.zelta.dev/public/v1/returns?limit=30&metadata=true', {
  headers: { 'Authorization': `Bearer ${process.env.ZELTA_POS_API_KEY}` }
});
const data = await res.json();

Ejemplo Py

import requests

res = requests.get(
    'https://api-pos.zelta.dev/public/v1/returns',
    headers={'Authorization': 'Bearer zpk_live_xxx'},
    params={'limit': 30, 'metadata': 'true'}
)
data = res.json()

Respuesta

{
  "data": [
    {
      "id": "ret_5e6f7g8h9i0j1k2l",
      "number": "DEV-0000045",
      "orderId": "sal_1a2b3c4d5e6f7g8h",
      "branchId": "br_0p9o8i7u6y5t4r3e",
      "status": "complete",
      "refundAmount": "10.70",
      "amountPaid": "10.70",
      "balanceRemaining": "0.00",
      "createdAt": "2026-06-30T15:00:00.000Z",
      "updatedAt": "2026-06-30T15:05:00.000Z"
    }
  ],
  "metadata": { "total": 1 }
}

Campo	Tipo	Descripción
id	string	ID de la devolución.
number	string	Número de la devolución.
orderId	string | null	Venta de origen.
branchId	string | null	Sucursal donde se registró.
status	string	open o complete.
refundAmount	string	Monto total a reembolsar.
amountPaid	string	Monto ya reembolsado.
balanceRemaining	string	Saldo pendiente de reembolso.
createdAt	string	Fecha de creación.
updatedAt	string	Fecha de última actualización.

Obtener una devolución

GET /returns/{id}

Devuelve una devolución como objeto directo. Responde 404 si no existe.

curl "https://api-pos.zelta.dev/public/v1/returns/ret_5e6f7g8h9i0j1k2l" \
  -H "Authorization: Bearer zpk_live_xxx"

Ejemplo JS

const res = await fetch('https://api-pos.zelta.dev/public/v1/returns/ret_5e6f7g8h9i0j1k2l', {
  headers: { 'Authorization': `Bearer ${process.env.ZELTA_POS_API_KEY}` }
});
const data = await res.json();

Ejemplo Py

import requests

res = requests.get(
    'https://api-pos.zelta.dev/public/v1/returns/ret_5e6f7g8h9i0j1k2l',
    headers={'Authorization': 'Bearer zpk_live_xxx'}
)
data = res.json()

Problemas comunes

Código	HTTP	Causa probable
unauthorized	401	API key ausente o inválida.
forbidden	403	La key no tiene acceso al recurso solicitado.
not_found	404	El id de la devolución no existe.
rate_limited	429	Se superó el límite de peticiones.
internal_error	500	Error interno del servidor.

Siguientes pasos

• — consulta las ventas de origen de cada devolución.
• — revisa los pagos asociados a una venta.
• — paginación y sincronización incremental.