Skip to content

Devoluciones

Jump to bottom
Carlos Rojas Latorre edited this page Aug 28, 2018 · 5 revisions

Estructura JSON

Al realizar una petición HTTP, el servicio retornara un JSON con la siguiente estructura:

{
  "href": "https://api.bsale.com.pe/v1/returns/1.json",
  "id": 1,
  "code": "137615600351",
  "returnDate": 1376107200,
  "motive": "Cambio a Factura",
  "type": 1,
  "priceAdjustment": 0,
  "editTexts": 0,
  "amount": 27541.0,
  "office": {
    "href": "https://api.bsale.com.pe/v1/offices/1.json",
    "id": "1"
  },
  "reference_document": {
    "href": "https://api.bsale.com.pe/v1/documents/472.json",
    "id": "472"
  },
  "credit_note": {
    "href": "https://api.bsale.com.pe/v1/documents/477.json",
    "id": "477"
  },
  "details": {
    "href": "https://api.bsale.com.pe/v1/returns/1/details.json"
  }
}
  • href, url de la devolución (String).
  • id, identificador único de la devolución (Integer).
  • code, código interno único de la la devolución (String).
  • returnDate, fecha de la devolución (Integer).
  • motive, razón de por que fue efectuada la devolución (String).
  • type, identifica si la forma de pago de la devolución (Integer).
  • priceAdjustment, indica si la nota de crédito relacionada fue por ajuste de precio No(0) o Si(1) (Boolean).
  • editTexts, indica si la nota de crédito relacionada fue por corrección de texto (forma) No(0) o Si(1) (Boolean).
  • amount, monto total de la devolución (float).
  • office, nodo que indica la relación con la sucursal en la que fue emitida la devolución.
  • reference_document, nodo que indica la relación con el documento de referencia que se devuelve.
  • credit_note, nodo que indica el documento nota de crédito.
  • details, nodo que indica los detalles de la devolución.

GET lista de devoluciones

  • GET /v1/returns.json retornara todos las devoluciones.

####Parametros

  • limit, limita la cantidad de items de una respuesta JSON, por defecto el limit es 25, el máximo permitido es 50.
  • offset, permite paginar los items de una respuesta JSON, por defecto el offset es 0.
  • fields, solo devolver atributos específicos de un recurso
  • expand, permite expandir instancias y colecciones.
  • returndate, Permite filtrar por fecha de devolución.
  • code, filtra por código de la devolución.
  • type, filtra por tipo de devolución.
  • officeid, Permite filtrar por sucursal.
  • referencedocumentid, filtra por documento de referencia.

####Ejemplos

  • GET /v1/returns.json?limit=10&offset=0
  • GET /v1/returns.json?fields=[returndate,motive]
  • GET /v1/returns.json?expand=[reference_document,credit_note,details]

####Respuesta

{
  "href": "https://api.bsale.com.pe/v1/returns.json",
  "count": 49,
  "limit": 2,
  "offset": 0,
  "items": [
    {
      "href": "https://api.bsale.com.pe/v1/returns/1.json",
      "id": 1,
      "code": "137615600351",
      "returnDate": 1376107200,
      "motive": "Cambio a Factura",
      "type": 1,
      "priceAdjustment": 0,
      "editTexts": 0,
      "amount": 27541.0,
      "office": {
        "href": "https://api.bsale.com.pe/v1/offices/1.json",
        "id": "1"
      },
      "reference_document": {
        "href": "https://api.bsale.com.pe/v1/documents/472.json",
        "id": "472"
      },
      "credit_note": {
        "href": "https://api.bsale.com.pe/v1/documents/477.json",
        "id": "477"
      },
      "details": {
        "href": "https://api.bsale.com.pe/v1/returns/1/details.json"
      }
    },
    {
      "href": "https://api.bsale.com.pe/v1/returns/2.json",
      "id": 2,
      "code": "137668322351",
      "returnDate": 1376625600,
      "motive": "error de ventas",
      "type": 0,
      "priceAdjustment": 0,
      "editTexts": 0,
      "amount": 21488.0,
      "office": {
        "href": "https://api.bsale.com.pe/v1/offices/1.json",
        "id": "1"
      },
      "reference_document": {
        "href": "https://api.bsale.com.pe/v1/documents/527.json",
        "id": "527"
      },
      "credit_note": {
        "href": "https://api.bsale.com.pe/v1/documents/529.json",
        "id": "529"
      },
      "details": {
        "href": "https://api.bsale.com.pe/v1/returns/2/details.json"
      }
    }
  ]
}

GET única devolución

  • GET /v1/returns/1.json retornara una devolución específica.

####Parametros

  • expand, permite expandir instancias y colecciones.

####Ejemplos

  • GET /v1/returns/1.json?expand=[credit_note]

####Respuesta

{
  "href": "https://api.bsale.com.pe/v1/returns/1.json",
  "id": 1,
  "code": "137615600351",
  "returnDate": 1376107200,
  "motive": "Cambio a Factura",
  "type": 1,
  "priceAdjustment": 0,
  "editTexts": 0,
  "amount": 27541.0,
  "office": {
    "href": "https://api.bsale.com.pe/v1/offices/1.json",
    "id": "1"
  },
  "reference_document": {
    "href": "https://api.bsale.com.pe/v1/documents/472.json",
    "id": "472"
  },
  "credit_note": {
    "href": "https://api.bsale.com.pe/v1/documents/477.json",
    "id": "477"
  },
  "details": {
    "href": "https://api.bsale.com.pe/v1/returns/1/details.json"
  }
}

GET detalles de una devolución

  • GET /v1/returns/1/details.json
{
  "href": "https://api.bsale.com.pe/v1/returns/1/details.json",
  "count": 2,
  "limit": 25,
  "offset": 0,
  "items": [
    {
      "href": "https://api.bsale.com.pe/v1/returns/1/details/1.json",
      "id": 1,
      "quantity": 2.8,
      "quantityDevStock": 2.8,
      "variantStock": 59.37,
      "variantCost": 3200.0
    },
    {
      "href": "https://api.bsale.com.pe/v1/returns/1/details/2.json",
      "id": 2,
      "quantity": 1.64,
      "quantityDevStock": 1.64,
      "variantStock": 45.44,
      "variantCost": 3200.0
    }
  ]
}

GET un detalle de una devolución

  • GET /v1/returns/1/details/1.json
{
  "href": "https://api.bsale.com.pe/v1/returns/1/details/1.json",
  "id": 1,
  "quantity": 2.8,
  "quantityDevStock": 2.8,
  "variantStock": 59.37,
  "variantCost": 3200.0
}

POST una devolución

  • POST /v1/returns.json

Para crear una devolución y su respectiva nota da crédito se debe enviar un JSON con la siguiente estructura:

Referencias y Fechas

{
  "documentTypeId": 9,
  "officeId": 1,
  "referenceDocumentId": 11528,
  "expirationDate": 1407384000,
  "emissionDate": 1407384000,
  "motive": "prueba api",
  "declare": 1,
  "priceAdjustment": 0,
  "editTexts": 0,
  "type": 1
}
  • documentTypeId, Id del tipo de documento, en este caso, uno que sea nota de crédito (Integer).
  • officeId, Id de la sucursal donde se emite el documento (Integer).
  • referenceDocumentId, Id del documento original al cual se le va hacer la devolución (Integer).
  • emissionDate, Fecha de emisión de la devolución, se envía en formato GMT (Integer).
  • expirationDate, Fecha vencimiento de la devolución, se envía en formato GMT (Integer).
  • motive, Indica el motivo de la devolución (String).
  • declare, Si se desea declarar el documento al Servicio de impuestos internos se envía 1, en caso contrario un 0 (Boolean).
  • priceAdjustment, Si la devolución corresponde a un ajuste de precio de los productos se envía 1, en caso contrario 0 (Boolean).
  • editTexts, Si la devolución corresponde a una corrección de texto (por forma) se envía 1, en caso contrario 0 (Boolean).
  • type, Indica como se va a devolver el dinero del documento, 0 para devolución dinero, 1 para forma pago nueva venta, 2 para abono linea de crédito (Integer).

Cliente de la devolución

Para las notas de crédito es obligatorio especificar el cliente.

{
  "client": {
    "code": "1-9",
    "city": "Puerto Varas",
    "district": "distrito",
    "activity": "giro",
    "address": "direccion"
  },
}
  • code, ruc del cliente (String).
  • city, Ciudad del cliente (String).
  • company, Razón social del cliente (String).
  • district, Distrito del cliente (String).
  • activity, Giro del cliente (String).
  • address, Dirección del cliente (String).

Detalles de la devolución

{
  "details": [
    {
      "documentDetailId": 21493,
      "quantity": 1,
      "unitValue": 0
    }
  ]
}

Tres clases de la devolución

  • Si se desea crear una devolución para corregir información, se debe enviar el editTexts en 1 y el priceAdjustment en 0, ademas de enviar en el nodo details todos los detalles originales del documento (quantity = 0, unitValue = 0).

  • Si se desea crear una devolución para ajustar el precio de los productos, se debe enviar el editTexts en 0 y el priceAdjustment en 1, ademas de enviar en el nodo details solo los detalles que van a cambiar de precio del documento original (quantity = 0, unitValue = nuevo precio)

  • Si se desea crear una devolución solo para retornar productos, se debe enviar el editTexts en 0 y el priceAdjustment en 0, ademas de enviar en el nodo details solo los detalles que van a cambiar de cantidad del documento original (quantity = nueva cantidad, unitValue = 0).

Ejemplo de estructura JSON

{
  "documentTypeId": 9,
  "officeId": 1,
  "expirationDate": 1407384000,
  "emissionDate": 1407384000,
  "referenceDocumentId": 11528,
  "motive": "prueba api",
  "declare": 1,
  "priceAdjustment": 0,
  "editTexts": 0,
  "type": 1,
  "client": {
    "code": "1-9",
    "city": "Puerto Varas",
    "district": "distrito",
    "activity": "giro",
    "address": "direccion"
  },
  "details": [
    {
      "documentDetailId": 21493,
      "quantity": 1,
      "unitValue": 0
    }
  ]
}

####Respuesta

{
  "credit_note": {
    "href": "https://api.bsale.com.pe/v1/documents/11539.json",
    "id": "11539"
  },
  "reference_document": {
    "href": "https://api.bsale.com.pe/v1/documents/11528.json",
    "id": "11528"
  },
  "amount": 6490.0,
  "code": "140745397411",
  "type": 1,
  "editTexts": 0,
  "href": "https://api.bsale.com.pe/v1/returns/71.json",
  "returnDate": 1407384000,
  "details": {
    "href": "https://api.bsale.com.pe/v1/returns/71/details.json"
  },
  "office": {
    "href": "https://api.bsale.com.pe/v1/offices/1.json",
    "id": "1"
  },
  "motive": "prueba api",
  "priceAdjustment": 0,
  "id": 71
}

POST anular devolución

  • POST /v1/returns/146/annulments.json

En la url de la petición se debe especificar el id de la devolución, en este caso es 146. Para anular una devolución y generar la nota de débito correspondiente se debe enviar un JSON con la siguiente estructura:

{
  "documentTypeId": 37,
  "referenceDocumentId": 3733,
  "emissionDate": 1414501200,
  "expirationDate": 1417179600,
  "declare": 1,
  "number": 1,
}
  • documentTypeId, Id del tipo de documento, en este caso, uno que sea nota de débito (Integer).
  • referenceDocumentId, Id de la nota de crédito original al cual se le va hacer la anulación (Integer).
  • emissionDate, Fecha de emisión de la anulación, se envía en formato GMT (Integer).
  • expirationDate, Fecha vencimiento de la anulación, se envía en formato GMT (Integer).
  • declare, Si se desea declarar la nota de débito al servicio de impuestos internos se envía 1, en caso contrario un 0 (Boolean).
  • number, Es el folio de la nota de débito, si no se envía tomara el siguiente numero disponible (Integer)

####Respuesta

{
  "href": "https://api.bsale.com.pe/v1/returns/146/annulments/16.json",
  "id": 16,
  "annulmentDate": 1414551600,
  "amount": 65465465.0,
  "office": {
    "href": "https://api.bsale.com.pe/v1/offices/2.json",
    "id": "2"
  },
  "debit_note": {
    "href": "https://api.bsale.com.pe/v1/documents/3734.json",
    "id": "3734"
  }
}
Clone this wiki locally