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
}
]
}
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]:https://github.com/gmontero/API-Bsale-PE/wiki/Documentos#get-un-detalle-de-un-documento
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"
}
}