Base URL

https://heaven-commerce-gateway.heaven.com.ar/api

Autenticacion

Todos los endpoints requieren autenticacion mediante Bearer Token en el header Authorization.

Ejemplo de Header
Authorization: Bearer tu_token_aqui
Respuesta sin autenticacion
{ "success": false, "message": "Authorization header is required" }

Rate Limiting

La API implementa rate limiting por usuario. El limite de requests por hora depende del plan del usuario.

Headers de respuesta
  • X-RateLimit-Limit - Limite maximo de requests por hora
  • X-RateLimit-Remaining - Requests restantes en la ventana actual
Respuesta cuando se excede el limite
{ "success": false, "message": "Rate limit exceeded. Try again later." }

Endpoints

GET /health Health check del servicio

Verifica que el servicio este funcionando correctamente. No requiere autenticacion.

Respuesta exitosa
{ "status": "ok", "service": "Heaven Commerce Gateway", "timestamp": "2025-01-30T12:00:00-03:00" }
GET /api/items/{idc} Obtener informacion de un item
Requiere autenticacion Rate limited
Parametros de ruta
Parametro Tipo Descripcion
idc * string Identificador unico del item
Ejemplo de request
curl -X GET "https://heaven-commerce-gateway.heaven.com.ar/api/items/1906051701179088" \ -H "Authorization: Bearer tu_token"
Respuesta exitosa
{ "success": true, "data": { "id": 837, "idc": "1906051701179088", "marca": "LENOVO", "modelo": "320 80XS0024 US", "nombreRubro": "Notebooks", "precioPublico": 10040.14, "precioOferta": 10040.14, "stock": 21, "porcentajeIVA": 21, "destacado": true, "mostrarPrecio": true, "discount": { "exists": false, "percentage": 0, "amount": 0 }, "fotos": [ "https://www.heavenimagenes.com/.../1906051701179088_01_small.jpg" ], // ... mas campos disponibles } }
GET /api/products/{idc}/price_and_stock Obtener precio y stock de un producto
Requiere autenticacion Rate limited
Parametros de ruta
Parametro Tipo Descripcion
idc * string Identificador unico del producto
Ejemplo de request
curl -X GET "https://heaven-commerce-gateway.heaven.com.ar/api/products/1906051701179088/price_and_stock" \ -H "Authorization: Bearer tu_token"
Respuesta exitosa
{ "success": true, "data": { "idc": "1906051701179088", "list_price": 6146.4, "sale_price": 745778.6, "final_price": 6146.4, "stock": 21, "pack_full_sale_price": 0, "pack_full_list_price": 0, "showing_currency_id": 32, "discount": { "exists": false, "percentage": 0, "amount": 0 } } }
GET /api/images/{idc} Obtener imagen de un producto
Requiere autenticacion Rate limited
Parametros de ruta
Parametro Tipo Descripcion
idc * string Identificador unico del producto
Ejemplo de request
curl -X GET "https://heaven-commerce-gateway.heaven.com.ar/api/images/1906051701179088" \ -H "Authorization: Bearer tu_token"
Respuesta

Retorna los datos de la imagen del producto segun la API de HeavenCommerce.

Nota: Este endpoint depende de la configuracion del catalogo en HeavenCommerce.

GET /api/settings Obtener configuracion del token
Requiere autenticacion Rate limited

Obtiene la configuracion actual asociada al token. Devuelve los IDs de las listas de precios y las sucursales configuradas para el calculo de stock.

Ejemplo de request
curl -X GET "https://heaven-commerce-gateway.heaven.com.ar/api/settings" \ -H "Authorization: Bearer tu_token"
Respuesta exitosa
{ "success": true, "data": { "id_precio_lista": 5, "id_precio_oferta": 3, "sucursales": [1, 2] } }
Campos de la respuesta
Campo Tipo Descripcion
id_precio_lista integer ID de la lista de precios principal
id_precio_oferta integer ID de la lista de precios de oferta
sucursales array IDs de sucursales para calcular stock
POST /api/settings Actualizar configuracion del token
Requiere autenticacion Rate limited

Actualiza la configuracion del token. Solo es necesario enviar los campos que se desean modificar. El resto de la configuracion se completa automaticamente con los valores actuales antes de enviar a HeavenCore.

Campos modificables
Campo Tipo Descripcion
sucursales array IDs de sucursales para calcular stock
id_precio_lista integer ID de la lista de precios principal
id_precio_oferta integer ID de la lista de precios de oferta
Ejemplo: Cambiar solo las sucursales
curl -X POST "https://heaven-commerce-gateway.heaven.com.ar/api/settings" \ -H "Authorization: Bearer tu_token" \ -H "Content-Type: application/json" \ -d '{ "sucursales": [1, 3, 5] }'
Ejemplo: Cambiar lista de precios y sucursales
curl -X POST "https://heaven-commerce-gateway.heaven.com.ar/api/settings" \ -H "Authorization: Bearer tu_token" \ -H "Content-Type: application/json" \ -d '{ "id_precio_lista": 2, "sucursales": [1, 2, 3] }'
Respuesta exitosa
{ "success": true, "data": { // Configuracion actualizada completa } }

Nota: Al enviar la actualizacion, el sistema obtiene automaticamente la configuracion actual y completa los campos faltantes (site_id, items_view, precio_lista, precio_oferta, etc.) antes de enviar a HeavenCore. El campo sucursales_s se actualiza automaticamente cuando se modifican las sucursales.

POST /api/invoice Crear un presupuesto
Requiere autenticacion Rate limited

Crea un comprobante del tipo Presupuesto en Heaven, registrado bajo el canal Pagina Web. El presupuesto queda visible en el modulo HC > Ordenes. El stock no se reserva en este paso; para reservarlo se debe llamar a /api/invoice/{id}/confirm.

Campos del body (JSON)
Campo Tipo Requerido Descripcion
sucursal string Si ID de la sucursal que emite el presupuesto (ej: "1")
client object Si Datos del cliente. Ver estructura mas abajo.
items array Si Lista de productos. Al menos un elemento. Ver estructura mas abajo.
payment_method object Si Medio de pago. Ver estructura mas abajo.
order_id integer No ID del pedido externo (referencia del comercio)
invoice_type_A boolean No Si true, solicita comprobante Tipo A. Default: false
discount number No Descuento general sobre el total. Default: 0
charges number No Recargo / coeficiente de financiacion (ej: 1.09 = 9% de recargo)
user_id string No ID del usuario vendedor en Heaven
pedido_comercio boolean No Indica si es pedido mayorista. Default: false
coupon object No Cupon de descuento. Campos: discount (number), comments (string)
comments string No Observaciones generales del pedido
metadata object No Datos de envio. Campos: shipping_id (integer), shipping_name (string)
extra_items array No Items adicionales sin IDC (ej: costo de envio). Ver estructura mas abajo.
Objeto client
Campo Tipo Requerido Descripcion
Nombre string Si Nombre del cliente
Apellido string Si Apellido del cliente
Email string Si Email del cliente. Formato valido requerido.
DNI string Si Numero de documento (DNI)
Domicilio string Si Calle y numero
Localidad string Si Ciudad / localidad
Provincia string Si Provincia (ej: "Capital Federal")
Pais string Si Pais (ej: "Argentina")
CP integer Si Codigo postal
Telefono string No Numero de telefono
CUIT string|null No CUIT. Obligatorio cuando facturacion.categoria_impositiva es "I" o "M". null para Consumidor Final.
facturacion object Si Datos de facturacion. Ver subcampos abajo.
facturacion.domicilio string Si Domicilio fiscal
facturacion.localidad string Si Localidad fiscal
facturacion.categoria_impositiva string Si Condicion fiscal: "C" Consumidor Final • "M" Monotributista • "I" Responsable Inscripto • "E" Exento
Array items (productos con IDC)
Campo Tipo Requerido Descripcion
IDC string Si Identificador del producto en Heaven
quantity integer Si Cantidad solicitada. Debe ser mayor a 0.
price_list_id string Si ID de la lista de precios a aplicar para este item
Array extra_items (items sin IDC)

Se usa para cargos adicionales que no son productos del catalogo, como el costo de envio.

Campo Tipo Requerido Descripcion
concept string Si Descripcion del cargo (ej: "Costo de Envio")
unit_price number Si Precio unitario sin impuestos
quantity integer Si Cantidad. Generalmente 1.
IVA integer Si Alicuota de IVA en porcentaje (ej: 21)
Objeto payment_method
Campo Tipo Requerido Descripcion
method integer Si ID del medio de pago:
  • 0 — Pago Efectivo
  • 2 — Billetera Virtual (usar para MercadoPago y medios de pago online)
  • 4 — Deposito Bancario (usar para pagos por transferencia bancaria)
bank_id integer Condicional ID del banco a usar para registrar la transferencia / deposito. Requerido cuando method = 4. Obtener los IDs disponibles desde GET /api/banks.
Ejemplo de request completo
curl -X POST "https://heaven-commerce-gateway.heaven.com.ar/api/invoice" \ -H "Authorization: Bearer tu_token" \ -H "Content-Type: application/json" \ -d '{ "sucursal": "1", "order_id": 1904, "invoice_type_A": false, "discount": 0, "charges": 1.09, "user_id": "3", "pedido_comercio": false, "client": { "Nombre": "Emilio", "Apellido": "Zottarel", "Domicilio": "Mexico 737, San Telmo", "Localidad": "San Telmo", "CP": 1097, "Provincia": "Capital Federal", "Pais": "Argentina", "Telefono": "3404535431", "DNI": "33218653", "CUIT": null, "Email": "zotta@msn.com", "facturacion": { "domicilio": "Mexico 737, San Telmo", "localidad": "San Telmo", "categoria_impositiva": "C" } }, "items": [ { "IDC": "1705301717585057", "quantity": 1, "price_list_id": "3" }, { "IDC": "1509281504274264", "quantity": 1, "price_list_id": "3" } ], "payment_method": { "method": 2 }, "coupon": { "discount": 0, "comments": "" }, "comments": "", "metadata": { "shipping_id": 1, "shipping_name": "Retiro en el Local" }, "extra_items": [ { "unit_price": 9177, "quantity": 1, "IVA": 21, "concept": "Costo de Envio" } ] }'
Respuesta exitosa
{ "is_valid": true, "invoice_id": 1234, "error": null }
Respuesta con error de validacion
{ "is_valid": false, "invoice_id": null, "data": "Items subtotal cannot be zero" }

Nota: El presupuesto generado no reserva stock. Para reservar el stock del presupuesto, llamar a POST /api/invoice/{invoice_id}/confirm.

POST /api/invoice/{id}/confirm Reservar stock de un presupuesto
Requiere autenticacion Rate limited

Convierte el presupuesto en una reserva de stock. Una vez confirmado, el stock de los items queda bloqueado en Heaven y no esta disponible para ventas en ningun otro canal (mostrador, web, MercadoLibre, etc.).

El id a usar es el valor de invoice_id retornado por POST /api/invoice.

Estados del comprobante
Paso Estado en Heaven Stock reservado
Despues de POST /api/invoice Presupuesto (canal: Pagina Web) No
Despues de POST /api/invoice/{id}/confirm Presupuesto reservado Si — bloqueado en todos los canales
Parametros de ruta
Parametro Tipo Descripcion
id * integer El invoice_id devuelto por POST /api/invoice
Ejemplo de request
curl -X POST "https://heaven-commerce-gateway.heaven.com.ar/api/invoice/1234/confirm" \ -H "Authorization: Bearer tu_token"
Respuesta exitosa
{ "success": true, "data": { // Datos del presupuesto reservado } }
GET /api/banks Listado de bancos disponibles
Requiere autenticacion

Devuelve el listado de bancos con su respectivo ID. Los IDs se utilizan en el campo bank_id del objeto payment_method cuando se usa method = 4 (Deposito Bancario).

Ejemplo de request
curl -X GET "https://heaven-commerce-gateway.heaven.com.ar/api/banks" \ -H "Authorization: Bearer tu_token"
Respuesta exitosa
[ { "id": 1, "name": "Banco Galicia" }, { "id": 2, "name": "Banco Supervielle" } ]
Campos de la respuesta
Campo Tipo Descripcion
id integer ID del banco. Usar como bank_id en payment_method.
name string Nombre del banco
GET /api/grupos Listado de grupos
Requiere autenticacion Rate limited

Devuelve el listado de grupos definidos en HeavenCommerce. Los grupos permiten organizar y clasificar productos en el catalogo.

Ejemplo de request
curl -X GET "https://heaven-commerce-gateway.heaven.com.ar/api/grupos" \ -H "Authorization: Bearer tu_token"
Respuesta exitosa
[ { "id": 1, "name": "Computacion" }, { "id": 2, "name": "Electronica" } ]
GET /api/rubros Listado de rubros
Requiere autenticacion Rate limited

Devuelve el listado de rubros (subcategorias) definidos en HeavenCommerce. Los rubros son subdivisiones dentro de los grupos para una clasificacion mas especifica de los productos.

Ejemplo de request
curl -X GET "https://heaven-commerce-gateway.heaven.com.ar/api/rubros" \ -H "Authorization: Bearer tu_token"
Respuesta exitosa
[ { "id": 1, "name": "Notebooks" }, { "id": 2, "name": "Monitores" } ]
GET /api/tags Listado de tags
Requiere autenticacion Rate limited

Devuelve el listado de tags disponibles en HeavenCommerce. Los tags se utilizan para etiquetar y filtrar productos en el catalogo.

Ejemplo de request
curl -X GET "https://heaven-commerce-gateway.heaven.com.ar/api/tags" \ -H "Authorization: Bearer tu_token"
Respuesta exitosa
[ { "id": 1, "name": "Destacado" }, { "id": 2, "name": "Oferta" } ]
GET /api/marcas Listado de marcas
Requiere autenticacion Rate limited

Devuelve el listado de marcas registradas en HeavenCommerce. Util para construir filtros de busqueda en el catalogo.

Ejemplo de request
curl -X GET "https://heaven-commerce-gateway.heaven.com.ar/api/marcas" \ -H "Authorization: Bearer tu_token"
Respuesta exitosa
[ { "id": 1, "name": "LENOVO" }, { "id": 2, "name": "HP" } ]
GET /api/sucursal Listado de sucursales
Requiere autenticacion Rate limited

Devuelve el listado de sucursales disponibles en HeavenCommerce. Los IDs de sucursal se utilizan en la configuracion del token (GET /api/settings) para determinar el calculo de stock.

Ejemplo de request
curl -X GET "https://heaven-commerce-gateway.heaven.com.ar/api/sucursal" \ -H "Authorization: Bearer tu_token"
Respuesta exitosa
[ { "id": 1, "name": "Casa Central" }, { "id": 2, "name": "Sucursal Norte" } ]

Nota: Los IDs devueltos por este endpoint son los mismos que se configuran en sucursales via POST /api/settings.

GET /api/hc/users Listado de usuarios de Heaven
Requiere autenticacion Rate limited

Devuelve el listado de usuarios registrados en HeavenCommerce. Los IDs de usuario se utilizan en el campo user_id al crear un presupuesto (POST /api/invoice) para asignar un vendedor.

Ejemplo de request
curl -X GET "https://heaven-commerce-gateway.heaven.com.ar/api/hc/users" \ -H "Authorization: Bearer tu_token"
Respuesta exitosa
[ { "id": 1, "name": "Admin" }, { "id": 3, "name": "Vendedor Web" } ]

Nota: El id devuelto corresponde al campo user_id del body en POST /api/invoice.

Codigos de Estado HTTP

200 Exito
400 Bad Request
401 No autorizado
403 Prohibido
404 No encontrado
429 Rate limit excedido
500 Error interno

Formato de Errores

Todos los errores siguen el mismo formato de respuesta:

{ "success": false, "message": "Descripcion del error" }
Modo Debug

En modo debug (APP_DEBUG=true), los errores incluyen informacion adicional:

{ "success": false, "message": "Descripcion del error", "file": "/path/to/file.php", "line": 42, "trace": "..." }