Introducción


La API de Acelérala está construida bajo los estándares de REST. Es decir, nuestra API posee URLs orientada a recursos, y hace uso de los códigos de respuesta HTTP para indicar los posibles errores en el API. Es importante indicar que se encuentra implementada una autenticación HTTP (Bearer Token), solicitada en cada petición. Además, soportamos las solicitudes HTTP de origen cruzado (CORS), permitiendo que tu sitio y Acelérala puedan interactuar de manera segura mediante nuestra API desde una aplicación cliente. Por otro lado, un objeto JSON es retornado en cada una las peticiones hacia el API, incluyendo los errores. Adicionalmente nuestras bibliotecas convierten las respuestas en objetos específicos para cada lenguaje soportado.


Autenticación


Para poder acceder y utilizar la API de Acelérala necesitas previamente registrar un cliente y asignarle los permisos que tendrá. Una vez que esté registrado, obtendrás tus Llaves de Autenticación. Con las llaves podrás solicitar un Token que luego tendrás que incluir en cada petición que hagas al API.

El Token se solicita enviando un POST request al endpoint https://api.acelerala.com/v1/token. Este endpoint recibe autenticación tipo Basic Authenticate. Deberás enviar en el header dos parámetros: Content-Type con el valor application/x-www-form-urlencoded y Authorization con el valor Basic < credenciales > donde las credenciales son el identificador del cliente y la llave privada del cliente cifradas con Base64 de la forma client_id:client_secret. Adicionalmente, en el cuerpo de la petición se debe enviar el parámetro grant_type con el valor client_credentials.

Recuerda enviar los parámetros por HTTPS ya que Basic Authenticate puede ser descifrado para obtener tus credenciales.


Errores


Por medio de nuestra API, podrás ser notificado con toda la información en caso presentes un error al momento de hacer una petición a cualquier operación del API. La API de Acelérala utiliza el estándar de Códigos de Estado HTTP (HTTP Status Codes) en todas sus respuestas para indicar si las solicitudes se pudieron procesar con éxito o fallaron.


Paginación


Todos los recursos principales de Acelérala soportan operaciones de listado, entre ellos Órdenes, Productos y Clientes. Adicionalmente, todos los métodos de listado del API comparten una estructura similar tomando en cuenta estos tres parámetros: limit, after y before.

Acelérala utiliza una paginación en tiempo real basada en cursor a través de los parámetros after y before. Un cursor se refiere a un string de caracteres random que marca un ítem específico en una lista de datos. A menos que el ítem sea borrado, el cursor siempre estará punteando la misma parte de la lista, pero será invalidado si el ítem es removido.

En Acelérala, los parámetros after y before toman el valor ID y el valor por el que esté siendo ordenado (por defecto created) retornan los objetos en un orden cronológico reverso. El parámetro before devuelve los objetos creados antes del objeto en cuestión. El parámetro after devuelve los objetos creados después del objeto en cuestión. Si ambos parámetros son provistos sólo after es utilizado.

Adicionalmente, algunos recursos permiten retornar los objetos en otro órden si es que se solicita en la petición. Para esto se debe enviar el parámetro sort e indicar por qué campo se quiere ordenar y en qué dirección serparados por :, por ejemplo sort=created:desc. Los posibles valores para la dirección son asc (ascendientemente) y desc (descendientemente). Los posibles campos para ordenar dependerán de cada recurso y se detallarán en el recurso.

Al listar varios resultados de un recurso, se puede filtrar los resultados para obtener una lista de resultados específicos enviando los campos por los que desea filtrar como parámetros. Se puede filtrar utilizando equivalencias: gt (mayor), lt (menor), gte (mayor o igual), lte (menor o igual), o simplemente colocando el valor buscado (igual), o una serie de valores buscados separados por coma.

Por ejemplo, si quisieramos buscar todos las órdenes con un total entre 1 y 500, y que estén pagadas:

https://api.acelerala.com/v1/orders?total=gt:1,lt:500&payment_status=paid


Objeto Orden


Atributos

id integer

Identificador único del objeto.


object string, valor es "order"

Nombre del objeto.


currency_code currency

Código de la moneda en tres letras (Formato ISO 4217).


payment_status string

El estado de los pagos asociados a la orden. Solo puede colocarse cuando la orden es creada. Valores válidos:

pending: Pago pendiente. El pago aún puede fallar en este estado. Las ordenes se crean en este estado si es que no se define ningún estado.
authorized: El pago ha sido autorizado por el procesador.
partially_paid: La orden ha sido pagada parcialmente.
paid: La orden ha sido pagada en su totalidad.
partially_refunded: Los pagos de la orden han sido devueltos parcialmente.
refunded: Los pagos de la orden han sido devueltos completamente.
voided: El pago ha sido anulado antes de completarse.


billing_details string

La información de facturación de la Orden.

Ocultar atributos
billing_details.first_name string

Nombre del cliente


billing_details.last_name string

Apellido del cliente.


billing_details.company string

Nombre de la empresa


billing_details.email string

Correo electrónico al que se le enviará los datos del pedido.


billing_details.document_type string

Tipo de documento. Posibles valores:

dni: Documento nacional de identidad.
ce: Carné de extranjería.
passport: Pasaporte.
ruc:RUC.


billing_details.document_number string

Número de documento.


billing_details.phone string

Teléfono de contacto del cliente.


billing_details.address1 string

Dirección de Facturación.


billing_details.address2 string

Información adicional de la direción del cliente.


billing_details.city string

Ciudad de la dirección de facturación.


billing_details.province string

Provincia de la dirección de facturación.


billing_details.district string

Distrito de la dirección de facturación


billing_details.country string

País de la dirección de facturación


billing_details.country_code string

Código de país (Formato ISO 3166).


billing_details.zip_code integer

Código postal de 6 dígitos.


shipping_address string

La dirección de entrega de la Orden.

Ocultar atributos
shipping_address.first_name string

Nombre del que recibirá la ordeniente


shipping_address.last_name string

Apellido del que recibirá la orden.


shipping_address.phone string

Teléfono de contacto del encargado de la recepción del pedido.


shipping_address.address1 string

Dirección de entrega.


shipping_address.address2 string

Información adicional de la direción de entrega.


shipping_address.city string

Ciudad de la dirección de entrega.


shipping_address.province string

Provincia de la dirección de entrega.


shipping_address.district string

Distrito de la dirección de entrega


shipping_address.country string

País de la dirección de entrega


shipping_address.country_code string

Código de país (Formato ISO 3166).


shipping_address.longitude decimal

Longitud de la dirección de entrega


shipping_address.latitude decimal

Latitud de la dirección de entrega


shipping_address.zip_code integer

Código postal de 6 dígitos.


lines

Los ítems que componen la Orden. Contienen información del Producto como estaba definido al momento en que se creo la Orden. Mostrar atributos

Ocultar atributos
lines.id integer

Identificador único del objeto


lines.object string, valor es "line"

Nombre del objeto.


lines.product_id integer

Identificador único del producto de la orden.


lines.alternative_id integer

Identificador único de la alternativa de la orden.


lines.quantity integer

Cantidad de la alternativa que se agregó a la orden.


lines.grams decimal

Peso unitario del ítem.


lines.price decimal

Precio unitario del ítem.


lines.fulfillment_details.requires_shipping boolean

Si es que el ítem requiere de envío. Por ejemplo, un producto difital tendría valor false.


lines.fulfillment_details.fulfillable_quantity integer

El stock disponible cuando se agregó la el ítem al pedido.


lines.fulfillment_details.preferred_datetime timestamp

Fecha y hora preferida de entrega (Formato ISO 8601).


lines.name string

Nombre del producto y alternativa concatenados.


lines.sku string

SKU del ítem.


lines.fulfillment_details.requires_shipping boolean

Si es que el ítem requiere de envío. Por ejemplo, un producto difital tendría valor false.


lines.fulfillment_details.fulfillable_quantity integer

El stock disponible cuando se agregó la el ítem al pedido.


lines.fulfillment_details.preferred_datetime timestamp

Fecha y hora preferida de entrega (Formato ISO 8601).


discount_applications

Una lista de descuentos aplicados a la Orden.

Ocultar atributos
discount_applications.id integer

Identificador único del objeto


discount_applications.label string

Nombre del descuento.


discount_applications.value

Valor del descuento.


discount_applications.value_type

Cómo se calcula el valor final del descuento.

percentage: se descuenta un porcentaje.
fixed_amount: se descuenta un monto fijo


discount_applications.allocation_trigger string

Qué hizo que se asigne el descuento. Valores válidos:

manual: El descuento fue aplicado manualmente por el comercio.
automatic: El descuento fue aplicado porque el pedido cumplía los requerimientos para participar en una promoción.
discount_code: El descuento fue aplicado porque el cliente o el comercio aplicó un código promocional al pedido.


discount_applications.allocation_method

La forma en que el valor del descuento es aplicado al pedido. Valores válidos:

across: El valor es distribuido equitativamente entre todos los ítem de la orden.
each: El valor se aplica a cada ítem. Por ejemplo si es un descuento de 10 soles, se le descuenta 10 soles a cada ítem
one: El valor se aplica a un ítem.
subtotal: El valor se aplica diréctamente al subtotal de la orden.


taxes_included boolean

Si es que los precios de los ítems y los totales de la Orden incluyen impuestos o no.


lines_total decimal

La suma de los precios finales de los ítems antes de aplicar descuentos globales y costo de entrega. Se calcula multiplicando el precio unitario (lines.price) por la cantidad de ítems (lines.quantity) y luego restando el descuento total (lines.total_discount).


discounts_total decimal

La suma de los descuentos globales aplicados a la orden. No se consideran descuentos aplicados a las líneas.


subtotal decimal

El total antes de considerar el costo de envío. Se calcula restando discounts_total a lines_total.


shipping_total decimal

El costo de envío asociado al pedido. Se calcula en base a la configuración de la tienda.


total decimal

El total del pedido que pagará el cliente. Se calcula sumando el subtotal y el costo de delivery.


created timestamp

La fecha y hora en la que se creo la orden (Formato ISO 8601).


modified timestamp

La última fecha y hora en la que se modificó la orden (Formato ISO 8601).


placed timestamp

La fecha y hora en la que se realizó el pedido (Formato ISO 8601). Una vez que se realiza, se requieren permisos adicionales para modificar la orden.

	
{
	"id": 32203,
	"object": "order",
	"currency_code": "PEN",
	"payment_status": "paid",
	"billing_details": {
		"first_name": "Manuel",
		"last_name": "Cornejo",
		"company": "",
		"email": "manuelcornejo@testmail.com",
		"document_type": "dni",
		"document_number": "48765432",
		"phone": "991231231",
		"address1": "Av Aviación 2405, San Borja",
		"city": "Lima",
		"province": "Lima",
		"district": "San Borja",
		"country": "Perú",
		"country_code": "PE",
		"zip_code": 15035
	},
	"shipping_address": {
		"first_name": "Manuel",
		"last_name": "Cornejo",
		"phone": 991231231,
		"address1": "Calle Mi Casa 123, San Borja",
		"address2": "Al frente de la Rambla",
		"city": "Lima",
		"province": "Lima",
		"district": "San Borja",
		"country": "Perú",
		"country_code": "PE",
		"longitude": null,
		"latitude": null,	
		"zip_code": 15035
	},
	"lines": [
		{
			"id": 47691,
			"object": "line",
			"product_id": 2233,
			"alternative_id": 2254,
			"quantity": 3,
			"grams": null,			
			"name": "Grips - ",
			"sku": null,
			"price": "100.00",
			"discounts_total": "120.00",
			"discount_allocations": [{
				{
					"discount_id": 1337,
					"amount": "120.00"
				}
			}],
			"fulfillment_details": {
				"requires_shipping": true,
				"fulfillable_quantity": "4",
				"preferred_datetime": null
			}
		}
	],
	"discount_applications": [
		{
			"id": 1337,					
			"label": "CYBERWOW",
			"value":  120.00,
			"value_type": "fixed_amount",
			"allocation_trigger": "manual",
			"allocation_method": "across",
			"target_selection": "explicit",
			"target_type": "line_item"
		}
	
	],
	"taxes_included": true,
	"lines_total": 300,
	"discounts_total": 0,
	"subtotal": 30,
	"shipping_total": 0,
	"total": 30,
	"created": "2019-03-29T14:39:08.000Z",
	"modified": "2019-03-29T14:39:35.000Z",
	"placed": "2019-03-29T14:39:35.000Z"
}
				

Listar Ordenes

GET https://api.acelerala.com/v1/orders
Permisos:

Requiere el siguiente permiso:
read:orders para ver todos los pedidos de una tienda. Si se lista ordenes sin el permiso, sólo encontrará las ordenes que le pertenecen al usuario específico.

Ordenar:

Puedes elegir cualquiera de estos campos para ordenar los pedidos: id,total,created,modified,placed.

Ejemplos

Listar órdenes
GET https://api.acelerala.com/v1/orders

Listar las últimas 20 órdenes en las que el pedido se haya realizado despues de una fecha específica
GET https://api.acelerala.com/v1/orders?limit=20&sort=placed:desc&placed=gt:2019-01-10T16:58:14.000Z

Listar órdenes con solo ciertas propiedades GET https://api.acelerala.com/v1/orders?fields=id,payment_status,items

Listar órdenes con total entre 1000 y 5000, y mostrar solo 10 resultados GET https://api.acelerala.com/v1/orders?total=gt:1000,lt=5000&limit=10

Listar órdenes que hayan sido pagadas GET https://api.acelerala.com/v1/orders