Devoluciones

Endpoint para la generación de documentos del tipo devolución/anulaciones de ventas. (Ej. Nota de crédito electrónica, nota de débito electrónica).

Siempre se debe referenciar el id del documento venta que se desea devolver.

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"
  }
}