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.

  • Cómo funciona el Front-end de Bsale, mira éstos videos:(ver)

Estructura JSON

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

{
  "href": "https://api.bsale.cl/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.cl/v1/offices/1.json",
    "id": "1"
  },
  "reference_document": {
    "href": "https://api.bsale.cl/v1/documents/472.json",
    "id": "472"
  },
  "credit_note": {
    "href": "https://api.bsale.cl/v1/documents/477.json",
    "id": "477"
  },
  "details": {
    "href": "https://api.bsale.cl/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.

Parámetros

  • 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.
  • creditnoteid, filtra por el id de la nota de crédito.

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.cl/v1/returns.json",
  "count": 49,
  "limit": 2,
  "offset": 0,
  "items": [
    {
      "href": "https://api.bsale.cl/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.cl/v1/offices/1.json",
        "id": "1"
      },
      "reference_document": {
        "href": "https://api.bsale.cl/v1/documents/472.json",
        "id": "472"
      },
      "credit_note": {
        "href": "https://api.bsale.cl/v1/documents/477.json",
        "id": "477"
      },
      "details": {
        "href": "https://api.bsale.cl/v1/returns/1/details.json"
      }
    },
    {
      "href": "https://api.bsale.cl/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.cl/v1/offices/1.json",
        "id": "1"
      },
      "reference_document": {
        "href": "https://api.bsale.cl/v1/documents/527.json",
        "id": "527"
      },
      "credit_note": {
        "href": "https://api.bsale.cl/v1/documents/529.json",
        "id": "529"
      },
      "details": {
        "href": "https://api.bsale.cl/v1/returns/2/details.json"
      }
    }
  ]
}

GET única devolución

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

Parámetros

  • expand, permite expandir instancias y colecciones.

Ejemplos

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

Respuesta

{
  "href": "https://api.bsale.cl/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.cl/v1/offices/1.json",
    "id": "1"
  },
  "reference_document": {
    "href": "https://api.bsale.cl/v1/documents/472.json",
    "id": "472"
  },
  "credit_note": {
    "href": "https://api.bsale.cl/v1/documents/477.json",
    "id": "477"
  },
  "details": {
    "href": "https://api.bsale.cl/v1/returns/1/details.json"
  }
}

GET detalles de una devolución

  • GET /v1/returns/1/details.json
{
  "href": "https://api.bsale.cl/v1/returns/1/details.json",
  "count": 2,
  "limit": 25,
  "offset": 0,
  "items": [
    {
      "href": "https://api.bsale.cl/v1/returns/1/details/1.json",
      "id": 1,
      "quantity": 2.8,
      "quantityDevStock": 2.8,
      "variantStock": 59.37,
      "variantCost": 3200.0
    },
    {
      "href": "https://api.bsale.cl/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.cl/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",
  "declareSii": 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).
  • declareSii, 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",
    "municipality": "comuna",
    "activity": "giro",
    "address": "direccion"
  },
}
  • code, Rut del cliente (String).
  • city, Ciudad del cliente (String).
  • company, Razón social del cliente (String).
  • municipality, Comuna 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
    }
  ]
}
  • documentDetailId, Id del [detalle del documento] original que se va a devolver (Integer).
  • quantity, Cantidad a devolver (Float).
  • unitValue, Valor unitario neto del detalle (String). [detalle del documento]

Opcionalmente si generas una nota de crédito que ajusta el precio del documento original, puedes cambiar la descripcion del del item con el atributo comment:

{
  "details": [
    {
      "documentDetailId": 21493,
      "comment": "Nueva descripción del item",
      "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",
  "declareSii": 1,
  "priceAdjustment": 0,
  "editTexts": 0,
  "type": 1,
  "client": {
    "code": "1-9",
    "city": "Puerto Varas",
    "municipality": "comuna",
    "activity": "giro",
    "address": "direccion"
  },
  "details": [
    {
      "documentDetailId": 21493,
      "quantity": 1,
      "unitValue": 0
    }
  ]
}

Respuesta

{
  "credit_note": {
    "href": "https://api.bsale.cl/v1/documents/11539.json",
    "id": "11539"
  },
  "reference_document": {
    "href": "https://api.bsale.cl/v1/documents/11528.json",
    "id": "11528"
  },
  "amount": 6490.0,
  "code": "140745397411",
  "type": 1,
  "editTexts": 0,
  "href": "https://api.bsale.cl/v1/returns/71.json",
  "returnDate": 1407384000,
  "details": {
    "href": "https://api.bsale.cl/v1/returns/71/details.json"
  },
  "office": {
    "href": "https://api.bsale.cl/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,
  "declareSii": 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).
  • declareSii, 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.cl/v1/returns/146/annulments/16.json",
  "id": 16,
  "annulmentDate": 1414551600,
  "amount": 65465465.0,
  "office": {
    "href": "https://api.bsale.cl/v1/offices/2.json",
    "id": "2"
  },
  "debit_note": {
    "href": "https://api.bsale.cl/v1/documents/3734.json",
    "id": "3734"
  }
}

POST Devolución

Caso 1: Nota de crédito anula documento (devolución total)

POST Devolución

Caso 2: Nota de crédito devolución parcial productos

POST Devolución

Caso 3: Nota de crédito ajuste de precios

POST Devolución

Caso 4: Anular devolución (Nota de débito a Nota de crédito)