Devoluciones a proveedores

Mercadería enviada de vuelta al proveedor: líneas y compensación esperada y recibida, sea nota de crédito, reposición o dinero.

Cargando el índice de búsqueda…

Devoluciones a proveedores

Objetos

SupplierReturn

  • idintegerobligatorio

    ID del registro, único entre los registros de su tipo en la tienda.

  • numberstringobligatorio

    Número de la devolución.

  • statusstringobligatorio

    draft: borrador, el stock no se tocó y las líneas se pueden editar; shipped: enviada al proveedor, stock dado de baja, se espera la compensación; closed: cerrada, se recibió la compensación o se resolvió el rechazo; void: anulada, el stock se repuso.

    Valores:
    draftshippedclosedvoid
  • reasonstringobligatorio

    Motivo de la devolución: defect: defectuoso; wrong_item: artículo equivocado; surplus: sobrante; recall: retiro del lote; expiry: vencido; other: otro.

    Valores:
    defectwrong_itemsurplusrecallexpiryother
  • supplier_idintegerobligatorio

    ID del proveedor (/v1/suppliers).

  • legal_entity_idinteger o nullobligatorio

    Razón social de la tienda a cuyo nombre se espera la nota de crédito (/v1/legal-entities); null en devoluciones antiguas.

  • location_idintegerobligatorio

    Local desde donde salió la mercadería (/v1/locations).

  • goods_receipt_idinteger o nullobligatorio

    Recepción de origen (/v1/goods-receipts); null si la devolución no tiene recepción y se valoró al costo.

  • purchase_order_idinteger o nullobligatorio

    Orden de compra (/v1/purchase-orders); null sin orden.

  • issued_onstring (date) o nullobligatorio

    Fecha del documento: el día en la conciliación y en el papel, YYYY-MM-DD; null en un borrador.

  • currencystringobligatorio

    Moneda de la devolución, ISO 4217: en ella van los precios de las líneas, subtotal y settled_amount.

  • exchange_ratestring o nullobligatorio

    Tipo de cambio de la moneda de la devolución a la moneda de la tienda como texto decimal, tomado al enviar; null antes del envío.

  • subtotalintegerobligatorio

    Valor de las líneas de la devolución en su moneda.

  • base_subtotalintegerobligatorio

    Valor de las líneas en la moneda de la tienda al tipo de cambio tomado.

  • expected_settlementstring o nullobligatorio

    Qué se espera del proveedor, se fija al enviar: credit_note: nota de crédito; replacement: reposición de mercadería; refund: dinero; none: sin compensación; null: no se fijó.

    Valores:
    credit_notereplacementrefundrejectednonenull
  • settlementstring o nullobligatorio

    Qué se recibió al cerrar: credit_note: nota de crédito; replacement: reposición; refund: dinero; rejected: el proveedor la rechazó; none: sin compensación; null: no está cerrada.

    Valores:
    credit_notereplacementrefundrejectednonenull
  • settled_amountinteger o nullobligatorio

    Monto que reconoció el proveedor, en la moneda de la devolución; null si todavía no lo reconoció.

  • base_settled_amountinteger o nullobligatorio

    Monto reconocido en la moneda de la tienda al tipo de cambio tomado; null si todavía no se reconoció.

  • shipped_atstring (date-time) o nullobligatorio

    Cuándo se envió la mercadería al proveedor; null en un borrador.

  • closed_atstring (date-time) o nullobligatorio

    Cuándo se cerró la devolución; null si no está cerrada.

  • voided_atstring (date-time) o nullobligatorio

    Cuándo se anuló la devolución; null en una devolución vigente.

  • void_reasonstring o nullobligatorio

    Por qué se anuló la devolución; null en una vigente y en documentos antiguos.

  • notestring o nullobligatorio

    Nota del personal; null si no hay.

  • linesarray de objectobligatorio

    Líneas de la devolución.

    Campos · 15
    • idintegerobligatorio

      ID del registro, único entre los registros de su tipo en la tienda.

    • variant_idinteger o nullobligatorio

      ID de la variante del producto (/v1/variants).

    • lot_idinteger o nullobligatorio

      Lote de la línea (/v1/lots); null en un producto sin lotes.

    • goods_receipt_line_idinteger o nullobligatorio

      Línea de la recepción de origen (lines[].id de la recepción) de la que sale el precio; null en una línea sin recepción.

    • purchase_order_line_idinteger o nullobligatorio

      Línea de la orden de compra (lines[].id de la orden); null sin orden.

    • unitstring o nullobligatorio

      Unidad base de las cantidades de la línea: pcs, unidades; g, gramos; ml, mililitros.

    • quantitystring o nullobligatorio

      Cantidad enviada al proveedor, texto decimal en la unidad base.

    • settled_quantitystring o nullobligatorio

      Cuánto de eso reconoció el proveedor.

    • unit_costinteger o nullobligatorio

      Precio en la moneda de la devolución por cost_per_quantity; null si no hay precio.

    • cost_per_quantitystring o nullobligatorio

      Cantidad en la unidad base a la que corresponde el precio: "1000" en un producto por peso es por kilo.

    • store_unit_cost_microinteger o nullobligatorio

      El mismo precio en la moneda de la tienda, en millonésimas de la unidad menor; null si no hay precio.

    • amountintegerobligatorio

      Valor de lo enviado al precio de la línea; la suma de las líneas da subtotal.

    • settled_amountintegerobligatorio

      Valor de lo que reconoció el proveedor al precio de la línea.

    • reasonstring o nullobligatorio

      Motivo de la línea con los mismos códigos que el motivo del documento; null si rige el del documento.

      Valores:
      defectwrong_itemsurplusrecallexpiryothernull
    • notestring o nullobligatorio

      Nota de la línea; null si no hay.

  • correctionsarray de objectobligatorio

    Correcciones de la devolución enviada, en orden.

    Campos · 7
    • idintegerobligatorio

      ID del registro, único entre los registros de su tipo en la tienda.

    • numberstringobligatorio

      Número de la corrección.

    • reasonstringobligatorio

      Por qué se corrigió; se imprime en el documento y lo ve el proveedor.

    • subtotal_beforeintegerobligatorio

      subtotal antes de la corrección.

    • subtotal_afterintegerobligatorio

      subtotal después de la corrección.

    • linesarray de objectobligatorio

      Líneas corregidas, antes y después.

      Campos · 6
      • supplier_return_line_idinteger o nullobligatorio

        ID de la línea de la devolución (lines[].id); null si la corrección quitó la línea.

      • variant_idinteger o nullobligatorio

        Variante del producto de la línea (/v1/variants).

      • quantity_beforestring o nullobligatorio

        Cantidad antes de la corrección, en la unidad base.

      • quantity_afterstring o nullobligatorio

        Cantidad después de la corrección, en la unidad base.

      • reason_beforestring o nullobligatorio

        Motivo de la línea antes de la corrección; null si regía el del documento.

        Valores:
        defectwrong_itemsurplusrecallexpiryothernull
      • reason_afterstring o nullobligatorio

        Motivo de la línea después de la corrección; null si rige el del documento.

        Valores:
        defectwrong_itemsurplusrecallexpiryothernull
    • created_atstring (date-time)obligatorio

      Cuándo se registró la corrección.

  • created_atstring (date-time)obligatorio

    Cuándo se creó el registro.

  • updated_atstring (date-time)obligatorio

    Cuándo cambió el registro por última vez.

Endpoints

Devoluciones a proveedores: mercadería enviada de vuelta y su compensación

get/supplier-returns

Scope: procurement:read

Parámetros

Query

  • limitinteger

    Tamaño de página: hasta 250 registros; 50 por defecto.

    Mínimo:
    1
    Máximo:
    250
  • cursorstring

    Cursor opaco: next_cursor de la página anterior, o sync_cursor de la última página guardado por la sincronización anterior. El listado va en orden de confirmación, así que el cursor de sincronización devuelve luego solo lo que cambió después de él.

    Largo máximo:
    4096
  • updated_sincestring (date-time)

    Solo los registros cambiados después de este momento, ISO 8601 con zona horaria. Un filtro de la primera sincronización; después se sigue con el cursor.

    Patrón:
    ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{1,6})?(Z|[+-]\d{2}:\d{2})$
  • include_deletedboolean

    true — devolver también los registros eliminados: los archivados con deleted_at y los borrados de la base como marcas de eliminación {id, deleted_at} en la continuación por el cursor de sincronización. Activalo para sincronizar.

  • supplier_idinteger

    Solo documentos de este proveedor.

    Mínimo:
    1
  • goods_receipt_idinteger

    Solo devoluciones de esta recepción.

    Mínimo:
    1

Respuestas

200Éxito

application/json

  • dataarray de SupplierReturnobligatorio

    Registros de la página.

  • deletedarray de objectobligatorio

    Registros borrados de la base desde el cursor, como marcas de eliminación: solo con include_deleted=true en la continuación por el cursor de sincronización.

    Campos · 2
    • idintegerobligatorio

      ID del registro borrado.

    • deleted_atstring (date-time)obligatorio

      Cuándo se borró el registro.

  • next_cursorstring o nullobligatorio

    Cursor de la página siguiente; null en la última.

  • has_morebooleanobligatorio

    true si hay una página siguiente.

  • sync_cursorstring o nullobligatorio

    En la última página — el cursor desde el que continuar más tarde: con él llega solo lo que cambió después de esta página. null en las demás.

401Falta el token, es inválido, venció o fue revocado

Encabezados

  • WWW-Authenticatestringobligatorio

    Esquema de autenticación (RFC 6750).

    Ejemplo:
    Bearer

application/problem+json

Devuelve Problem

403El plan, la dirección IP o los scopes del token no permiten la solicitud

Encabezados

  • WWW-Authenticatestring

    Esquema de autenticación (RFC 6750).

    Ejemplo:
    Bearer error="insufficient_scope", scope="locations:read"

application/problem+json

Devuelve ForbiddenProblem

410El cursor de sincronización supera el plazo de conservación de eliminaciones o se emitió antes de restaurar la base de datos

application/problem+json

Devuelve Problem

422Un parámetro es inválido o desconocido

application/problem+json

Devuelve ValidationProblem

429Se agotó el límite de solicitudes

Encabezados

  • Retry-Afterintegerobligatorio

    Segundos de espera antes de reintentar.

    Mínimo:
    0

application/problem+json

Devuelve RateLimitProblem

503La tienda no está disponible por ahora

Encabezados

  • Retry-Afterinteger

    Segundos de espera antes de reintentar.

    Mínimo:
    0

application/problem+json

Devuelve Problem

Errores de este endpoint

Los errores comunes, como token, acceso, validación de la entrada y límite de solicitudes, pueden venir de cualquier endpoint; están en el catálogo: Errores

Ejemplo de solicitud
curl "https://api.saleya.app/v1/supplier-returns" \
  -H "Authorization: Bearer $SALEYA_API_TOKEN"
Ejemplo de respuesta · 200
{
  "data": [
    {
      "id": 0,
      "number": "string",
      "status": "draft",
      "reason": "defect",
      "supplier_id": 0,
      "legal_entity_id": 0,
      "location_id": 0,
      "goods_receipt_id": 0,
      "purchase_order_id": 0,
      "issued_on": "2026-01-15",
      "currency": "string",
      "exchange_rate": "string",
      "subtotal": 0,
      "base_subtotal": 0,
      "expected_settlement": "credit_note",
      "settlement": "credit_note",
      "settled_amount": 0,
      "base_settled_amount": 0,
      "shipped_at": "2026-01-15T12:00:00Z",
      "closed_at": "2026-01-15T12:00:00Z",
      "voided_at": "2026-01-15T12:00:00Z",
      "void_reason": "string",
      "note": "string",
      "lines": [
        {
          "id": 0,
          "variant_id": 0,
          "lot_id": 0,
          "goods_receipt_line_id": 0,
          "purchase_order_line_id": 0,
          "unit": "string",
          "quantity": "string",
          "settled_quantity": "string",
          "unit_cost": 0,
          "cost_per_quantity": "string",
          "store_unit_cost_micro": 0,
          "amount": 0,
          "settled_amount": 0,
          "reason": "defect",
          "note": "string"
        }
      ],
      "corrections": [
        {
          "id": 0,
          "number": "string",
          "reason": "string",
          "subtotal_before": 0,
          "subtotal_after": 0,
          "lines": [
            {
              "supplier_return_line_id": 0,
              "variant_id": 0,
              "quantity_before": "string",
              "quantity_after": "string",
              "reason_before": "defect",
              "reason_after": "defect"
            }
          ],
          "created_at": "2026-01-15T12:00:00Z"
        }
      ],
      "created_at": "2026-01-15T12:00:00Z",
      "updated_at": "2026-01-15T12:00:00Z"
    }
  ],
  "deleted": [
    {
      "id": 0,
      "deleted_at": "2026-01-15T12:00:00Z"
    }
  ],
  "next_cursor": "string",
  "has_more": true,
  "sync_cursor": "string"
}

Devolución a proveedor

get/supplier-returns/{supplier_return}

Scope: procurement:read

Parámetros

Ruta

  • supplier_returnintegerobligatorio

    ID de la devolución a proveedor.

Respuestas

200Éxito

application/json

Devuelve SupplierReturn

401Falta el token, es inválido, venció o fue revocado

Encabezados

  • WWW-Authenticatestringobligatorio

    Esquema de autenticación (RFC 6750).

    Ejemplo:
    Bearer

application/problem+json

Devuelve Problem

403El plan, la dirección IP o los scopes del token no permiten la solicitud

Encabezados

  • WWW-Authenticatestring

    Esquema de autenticación (RFC 6750).

    Ejemplo:
    Bearer error="insufficient_scope", scope="locations:read"

application/problem+json

Devuelve ForbiddenProblem

404El objeto no existe o no está disponible para la aplicación

application/problem+json

Devuelve Problem

422Un parámetro es inválido o desconocido

application/problem+json

Devuelve ValidationProblem

429Se agotó el límite de solicitudes

Encabezados

  • Retry-Afterintegerobligatorio

    Segundos de espera antes de reintentar.

    Mínimo:
    0

application/problem+json

Devuelve RateLimitProblem

503La tienda no está disponible por ahora

Encabezados

  • Retry-Afterinteger

    Segundos de espera antes de reintentar.

    Mínimo:
    0

application/problem+json

Devuelve Problem

Los errores comunes, como token, acceso, validación de la entrada y límite de solicitudes, pueden venir de cualquier endpoint; están en el catálogo: Errores

Ejemplo de solicitud
curl "https://api.saleya.app/v1/supplier-returns/{supplier_return}" \
  -H "Authorization: Bearer $SALEYA_API_TOKEN"
Ejemplo de respuesta · 200
{
  "id": 0,
  "number": "string",
  "status": "draft",
  "reason": "defect",
  "supplier_id": 0,
  "legal_entity_id": 0,
  "location_id": 0,
  "goods_receipt_id": 0,
  "purchase_order_id": 0,
  "issued_on": "2026-01-15",
  "currency": "string",
  "exchange_rate": "string",
  "subtotal": 0,
  "base_subtotal": 0,
  "expected_settlement": "credit_note",
  "settlement": "credit_note",
  "settled_amount": 0,
  "base_settled_amount": 0,
  "shipped_at": "2026-01-15T12:00:00Z",
  "closed_at": "2026-01-15T12:00:00Z",
  "voided_at": "2026-01-15T12:00:00Z",
  "void_reason": "string",
  "note": "string",
  "lines": [
    {
      "id": 0,
      "variant_id": 0,
      "lot_id": 0,
      "goods_receipt_line_id": 0,
      "purchase_order_line_id": 0,
      "unit": "string",
      "quantity": "string",
      "settled_quantity": "string",
      "unit_cost": 0,
      "cost_per_quantity": "string",
      "store_unit_cost_micro": 0,
      "amount": 0,
      "settled_amount": 0,
      "reason": "defect",
      "note": "string"
    }
  ],
  "corrections": [
    {
      "id": 0,
      "number": "string",
      "reason": "string",
      "subtotal_before": 0,
      "subtotal_after": 0,
      "lines": [
        {
          "supplier_return_line_id": 0,
          "variant_id": 0,
          "quantity_before": "string",
          "quantity_after": "string",
          "reason_before": "defect",
          "reason_after": "defect"
        }
      ],
      "created_at": "2026-01-15T12:00:00Z"
    }
  ],
  "created_at": "2026-01-15T12:00:00Z",
  "updated_at": "2026-01-15T12:00:00Z"
}