Una API REST
sobre la que construir.
Endpoints autenticados con clave Bearer y limitados por scope: devoluciones, seguimiento, etiquetas y un agente de devoluciones al que preguntas en lenguaje natural. Cada clave lleva su propio límite de peticiones. La plataforma programable completa está en la hoja de ruta.
Lanza una petición.
Elige un endpoint. La petición y la respuesta se actualizan al lado.
Consultar una devolución
Devuelve una única devolución en JSON. {id} acepta el número de devolución (RET-####) o el id interno. Requiere returns:read.
curl https://app.returner.me/api/v1/returns/RET-9284 \
-H "Authorization: Bearer $RETURNER_API_KEY"{
"return_id": "RET-9284",
"order": "#1042",
"status": "in_transit",
"type": "refund",
"created_at": "2026-03-14T09:12:00Z",
"customer": { "name": "Maria Holm", "email": "[email protected]" },
"refund": { "amount": 49.00, "currency": "EUR" },
"carrier": "postnord",
"tracking_number": "SE392847561",
"items": [
{ "sku": "TEE-BLK-L", "name": "Cotton Tee",
"quantity": 1, "reason": "too_small", "condition": null }
]
}Todos los endpoints.
/api/v1/returns/{id} Consultar una devolución (JSON) · returns:read disponible/api/v1/returns/{id}/tracking Estado de seguimiento actual · returns:read disponible/api/v1/returns/{id}/label Etiqueta de devolución en PDF (redirección 302) · labels:read disponible/api/v1/agent Agente de devoluciones en lenguaje natural · returns:read disponible/api/v1/openapi.json Especificación OpenAPI 3.1 · public disponiblereturn.* Webhooks firmados: created · approved · received · refunded · exchanged · cancelled disponibleAsí se autorizan las peticiones.
Claves Bearer
Envía Authorization: Bearer ret_live_<key> en cada petición a /api/v1/*. La clave se muestra una sola vez, al crearla, y de ella guardamos solo un hash. Crea y revoca claves en Settings → API Keys.
Errores
- 401 clave desconocida o revocada
- 403 la clave no tiene el scope necesario
- 404 esa devolución no existe en tu tienda
- 429 límite de peticiones superado (mira
Retry-After)
Todo error responde con JSON { error, message, code }: error y message son la misma cadena legible; code es un slug estable para máquinas
(unauthorized, forbidden, not_found, rate_limited, …) sobre el que puedes ramificar sin riesgo.
Límite de peticiones
120 peticiones por minuto y clave. Cada respuesta lleva X-RateLimit-Limit, X-RateLimit-Remaining, y X-RateLimit-Reset; en un 429 se añade además Retry-After.
Esto es lo que te da la API.
Hoja de ruta de integraciones.
Shopify ya está disponible. Dinos cuál es la siguiente para tu stack y la priorizamos.
Empieza a construir con Returner.
Crea una clave en Settings → API Keys y luego lee la especificación o genera un cliente.