--- title: "Servicios Web (API)" description: "" type: "docs" category: "doc" tags: [] authors: [Anonymous] date: "2026-08-25" last_update: "2026-08-25" time_minutes: 1 draft: false unlisted: false url: "https://www.billmysales.com/docs/api" --- ## BillMySales API BillMySales provee en [billmysales.com](https://app.billmysales.com) una API para interactuar con diferentes características del software BillMySales. En general, permite probar los servicios asociados al proceso de facturación y la obtención del estado del mismo, junto a su historial de eventos. Si requiere soporte con el uso de la API, por favor [abrir un ticket de soporte](https://app.billmysales.com/help). **Revisa la documentación dinámica de la API en** [API BillMySales Interactiva](https://app.billmysales.com/docs/devtools) --- ## Autenticación mediante Token La API soporta sólo el método de autenticación mediante Token. Se debe generar un *Token* a través de la [plataforma web de BillMySales](https://app.billmysales.com/users/profile#token) y hacer las solicitudes enviando el token en la cabecera: ```text Authorization: Token TOKEN ``` ### Error `Token inválido` El mensaje: ```json { "detail": "Token inválido." } ``` Puede ser a causa de los siguientes motivos: - No se envió el *token*. - Se envió un *access token* incorrecto. --- # Realizando peticiones Los parámetros que se puedan pasar a la API tienen 3 posibles ubicaciones: - **Variable en el PAT del recurso consumido**: parámetros que identifican un elemento en el recurso que se está consumiendo. Pueden existir casos donde cierto parámetro sea opcional, en cuyo caso se indicará en cada recurso. - **Variable agregada a la URL**: parámetros que permiten modificar el comportamiento de la consulta. Por ejemplo para cambiar el formato de la respuesta o el delimitador usado en los CSV. Estos parámetros siempre serán opcionales. - **Variable en el cuerpo de la solicitud POST**: agregada como un diccionario de datos en JSON. Este tipo de variables se usará principalmente para envío de datos para creación o modificación de datos en los recursos. A menos que se especifique lo contrario, todos los cuerpos de las llamadas a la API deben ser JSON con la cabecera: ```text Content-Type: application/json ``` Y de forma similar, la aplicación, a menos que se indique o soliciten los datos en un formato diferente, debe aceptar los datos en formato JSON con la cabecera: ```text Accept: application/json ``` ## Formato respuesta En general, la respuesta siempre será primero en JSON, a menos que el recurso especifique lo contrario. --- # Errores Todos los mensajes de error entregan un código HTTP y un mensaje legible con detalles del error. | Código | Descripción HTTP | Descripción BillMySales | |--------|--------------------------|------------------------------------------------------------------| | 400 | Bad Request | Petición inválida | | 401 | Unauthorized | *Token* incorrecto | | 403 | Forbidden | No tiene autorización para acceder al recurso solicitado | | 404 | Not Found | Recurso solicitado no pudo ser encontrado | | 405 | Method Not Allowed | El método o acción no está permitida | | 406 | Not Acceptable | Solicitó la respuesta en un formato de datos incorrecto | | 410 | Gone | El recurso solicitado ya no existe en la API | | 423 | Locked | Cuenta bloqueada por incumplir términos y condiciones | | 429 | Too Many Requests | Está solicitando muchos recursos en muy poco tiempo | | 500 | Internal Server Error | Error inesperado en el servidor (nuestro o del SII) | | 503 | Service Unavailable | Servicio temporalmente no disponible por mantención | > Con el paso del tiempo podríamos ir agregando o eliminando tipos de errores. Se recomienda que la aplicación maneje un caso por defecto cuando hay un error desconocido. En caso de error, se entregará un mensaje con el formato: ```json { ​​"status": "Código error", ​​"code": "error", ​​"detail": "Detalle del error." } ``` Index: - Applications - Send notification to an application webhook - Billing Gateways - Generate biller invoice from datasource - Generate normalized invoice from datasource - Generate normalized request (data) from datasource - Send notification to a billing gateway router - Send notification to a billing gateway webhook - Send test notification to a billing gateway webhook - Ordenes - Get data of an order - Run billing process - Send email of the invoice of an order - Download PDF of the invoice of an order - Test selector ### Applications #### POST /api/v1/applications/webhook/{application_type}/{application_code}/{application_dev_version} Send notification to an application webhook Este recurso recibe una notificación enviada por una aplicación integrada (por ejemplo Shopify), e identifica automáticamente el procesador correspondiente para manejar el contenido de la notificación. La ruta está compuesta por el tipo, nombre y versión del conector. **Este recurso también se utiliza en producción como webhook real de integración.** Parameters: - `action` (query, string) — Acción específica que define el comportamiento del webhook - `application_code` (path, string, required) — Código interno de la aplicación (ej: shopify) - `application_dev_version` (path, string, required) — Versión del procesador a utilizar (ej: 21.11.0) - `application_type` (path, string, required) — Tipo de aplicación (ej: datasource, marketplace) - `format` (query, string) Request body example: ``` { "shop_id": 954889, "shop_domain": "store-example.myshopify.com", "orders_requested": [ 299938, 280263, 220458 ], "customer": { "id": 191167, "email": "john@example.com", "phone": "555-625-1199" }, "billing_address": { "name": "John Doe", "address1": "123 Main St", "city": "Anytown", "country": "USA", "zip": "12345" }, "details": [ { "id": 1, "name": "Producto 1", "quantity": 1, "price": 100 } ], "data_request": { "id": 9999 } } ``` Responses: - `200` — Resultado del procesamiento del webhook ### Billing Gateways #### POST /api/v1/billing_gateways/datasource2biller/{billing_gateway_id}/{billing_gateway_hash} Generate biller invoice from datasource Recurso que genera, a partir de los datos del origen, los datos que se enviarán al facturador. Estos datos están en el formato exacto que cada facturador espera recibir para procesar correctamente la factura. **Este recurso es solo para pruebas y nunca debe ser usado en producción.** Parameters: - `billing_gateway_hash` (path, string, required) — Hash MD5 del billing gateway - `billing_gateway_id` (path, integer, required) — ID del billing gateway - `check_data` (query, integer) — Indica si se debe validar el contenido de los datos (0 - No validar, 1 - Validar) - `format` (query, string) Request body example: ``` { "shop_id": 954889, "shop_domain": "store-example.myshopify.com", "orders_requested": [ 299938, 280263, 220458 ], "customer": { "id": 191167, "email": "john@example.com", "phone": "555-625-1199" }, "billing_address": { "name": "John Doe", "address1": "123 Main St", "city": "Anytown", "country": "USA", "zip": "12345" }, "details": [ { "id": 1, "name": "Producto 1", "quantity": 1, "price": 100 } ], "data_request": { "id": 9999 } } ``` Responses: - `200` — Datos convertidos al formato del facturador #### POST /api/v1/billing_gateways/datasource2invoice/{billing_gateway_id}/{billing_gateway_hash} Generate normalized invoice from datasource Recurso que genera el JSON normalizado (interno) de BillMySales a partir de los datos recibidos desde un datasource. Todos los datos de los orígenes son convertidos a este formato normalizado, que luego es entregado al facturador. **Este recurso es solo para pruebas y nunca debe ser usado en producción.** Parameters: - `as_support_team` (query, integer) — Indica si la solicitud se realiza en contexto de soporte (0 - No, 1 - Sí) - `billing_gateway_hash` (path, string, required) — Hash MD5 del billing gateway - `billing_gateway_id` (path, integer, required) — ID del billing gateway - `check_data` (query, integer) — Indica si se debe validar el contenido de los datos (0 - No validar, 1 - Validar) - `format` (query, string) Request body example: ``` { "shop_id": 954889, "shop_domain": "store-example.myshopify.com", "orders_requested": [ 299938, 280263, 220458 ], "customer": { "id": 191167, "email": "john@example.com", "phone": "555-625-1199" }, "billing_address": { "name": "John Doe", "address1": "123 Main St", "city": "Anytown", "country": "USA", "zip": "12345" }, "details": [ { "id": 1, "name": "Producto 1", "quantity": 1, "price": 100 } ], "data_request": { "id": 9999 } } ``` Responses: - `200` — JSON normalizado de la factura #### POST /api/v1/billing_gateways/request/{billing_gateway_id}/{billing_gateway_hash} Generate normalized request (data) from datasource Recurso que permite obtener todos los datos enviados a la solicitud. Los datos ya están validados y convertidos a JSON si venían en otro formato. **Este recurso es solo para pruebas y nunca debe ser usado en producción.** Parameters: - `billing_gateway_hash` (path, string, required) — Hash MD5 del billing gateway - `billing_gateway_id` (path, integer, required) — ID del billing gateway - `check_data` (query, integer) — Indica si se debe validar el contenido de los datos (0 - No validar, 1 - Validar) - `format` (query, string) Request body example: ``` { "shop_id": 954889, "shop_domain": "store-example.myshopify.com", "orders_requested": [ 299938, 280263, 220458 ], "customer": { "id": 191167, "email": "john@example.com", "phone": "555-625-1199" }, "billing_address": { "name": "John Doe", "address1": "123 Main St", "city": "Anytown", "country": "USA", "zip": "12345" }, "details": [ { "id": 1, "name": "Producto 1", "quantity": 1, "price": 100 } ], "data_request": { "id": 9999 } } ``` Responses: - `200` — Datos normalizados desde el datasource #### POST /api/v1/billing_gateways/router/{datasource_code} Send notification to a billing gateway router Recurso que permite enrutar una notificación entrante desde un origen de datos a la pasarela de facturación correcta según su configuración. Se utiliza principalmente cuando el billing gateway no es conocido previamente, por ejemplo en integraciones como **Multivende**, donde solo se conoce el origen. Este servicio **crea la orden y la procesa de forma asíncrona**, tal como el webhook principal. La respuesta del facturador debe ser consultada luego accediendo a los datos de la orden. Parameters: - `datasource` (path, string, required) — Código del datasource (por ejemplo: multivende) - `datasource_code` (path, string, required) - `format` (query, string) - `user` (query, string) — Usuario asociado a la solicitud (útil para pruebas internas) - `version` (query, string) — Versión del parser a utilizar (por ejemplo: 22.01.0) Request body example: ``` { "shop_id": 954889, "shop_domain": "store-example.myshopify.com", "orders_requested": [ 299938, 280263, 220458 ], "customer": { "id": 191167, "email": "john@example.com", "phone": "555-625-1199" }, "billing_address": { "name": "John Doe", "address1": "123 Main St", "city": "Anytown", "country": "USA", "zip": "12345" }, "details": [ { "id": 1, "name": "Producto 1", "quantity": 1, "price": 100 } ], "data_request": { "id": 9999 } } ``` Responses: - `200` — Orden creada tras enrutamiento automático #### POST /api/v1/billing_gateways/webhook/{billing_gateway_id}/{billing_gateway_hash} Send notification to a billing gateway webhook Este recurso representa el webhook real que se configura en cada origen de datos. Recibe una notificación desde el origen y ejecuta el proceso de facturación de forma asíncrona. Cuando llamas a este endpoint, se crea una orden en BillMySales, pero **la respuesta del facturador no está disponible de inmediato**. Debes consultar la orden después de unos segundos para obtener el folio, PDF, etc. **Este recurso se debe usar solo en producción, como webhook oficial del origen.** Parameters: - `async` (query, integer) — Indica si la ejecución debe ser asíncrona (0 - Síncrona, 1 - Asíncrona). Por defecto es asíncrona - `billing_gateway_hash` (path, string, required) — Hash MD5 del billing gateway - `billing_gateway_id` (path, integer, required) — ID del billing gateway - `check_data` (query, integer) — Indica si se debe validar el contenido de los datos (0 - No validar, 1 - Validar) - `format` (query, string) Request body example: ``` { "shop_id": 954889, "shop_domain": "store-example.myshopify.com", "orders_requested": [ 299938, 280263, 220458 ], "customer": { "id": 191167, "email": "john@example.com", "phone": "555-625-1199" }, "billing_address": { "name": "John Doe", "address1": "123 Main St", "city": "Anytown", "country": "USA", "zip": "12345" }, "details": [ { "id": 1, "name": "Producto 1", "quantity": 1, "price": 100 } ], "data_request": { "id": 9999 } } ``` Responses: - `200` — Orden creada en BillMySales (sin respuesta del facturador) #### POST /api/v1/billing_gateways/webhook_test/{billing_gateway_id}/{billing_gateway_hash} Send test notification to a billing gateway webhook Recurso que simula una llamada al webhook del billing gateway. No se crea ninguna orden ni se persisten datos en la base de datos. Sin embargo, **sí se generan documentos reales en el facturador**, si este lo permite. Este recurso permite probar que los datos procesados llegan correctamente al facturador y verificar su respuesta. **Este recurso es solo para pruebas y nunca debe ser usado en producción.** ⚠️ Recuerda eliminar o anular los documentos generados en el facturador. Parameters: - `billing_gateway_hash` (path, string, required) — Hash MD5 del billing gateway - `billing_gateway_id` (path, integer, required) — ID del billing gateway - `check_data` (query, integer) — Indica si se debe validar el contenido de los datos (0 - No validar, 1 - Validar) - `format` (query, string) Request body example: ``` { "shop_id": 954889, "shop_domain": "store-example.myshopify.com", "orders_requested": [ 299938, 280263, 220458 ], "customer": { "id": 191167, "email": "john@example.com", "phone": "555-625-1199" }, "billing_address": { "name": "John Doe", "address1": "123 Main St", "city": "Anytown", "country": "USA", "zip": "12345" }, "details": [ { "id": 1, "name": "Producto 1", "quantity": 1, "price": 100 } ], "data_request": { "id": 9999 } } ``` Responses: - `200` — Respuesta del facturador al recibir datos simulados ### Ordenes #### GET /api/v1/order/{id} Get data of an order Recurso que permite obtener los datos detallados de una orden específica. Es especialmente útil para **consultar el estado de la orden** después de ejecutar el webhook, ya que este puede tardar unos segundos en completarse por el proceso de facturación. Los datos incluyen información general, estado, facturador utilizado, logs, y más. Parameters: - `billing_gateway` (query, integer) — Filtrar por ID del billing gateway (opcional) - `date_from` (query, string) — Filtrar desde esta fecha (formato YYYY-MM-DD) - `date_to` (query, string) — Filtrar hasta esta fecha (formato YYYY-MM-DD) - `format` (query, string) - `id` (path, integer, required) — ID único de la orden - `order_number` (query, string) — Filtrar por número de orden (opcional) - `period` (query, string) — Filtrar por período (AAAAMM) (opcional) - `status` (query, string) — Filtrar por estado de la orden (opcional) Responses: - `200` — Datos de la orden #### POST /api/v1/order/bill/{order_id} Run billing process Recurso que permite ejecutar manualmente el proceso de facturación para una orden existente. Este endpoint es útil cuando el webhook no logró completar el proceso, o si se requiere reintentar la facturación. **Solo se puede ejecutar si el estado actual de la orden lo permite.** Parameters: - `format` (query, string) - `order_id` (path, integer, required) — ID de la orden que se desea facturar Responses: - `200` — Proceso de facturación ejecutado exitosamente #### POST /api/v1/order/email/{order_id} Send email of the invoice of an order Este recurso permite enviar por correo electrónico la factura asociada a una orden. Puedes dejar que se envíe a los correos registrados en la orden, o bien pasar una lista de destinatarios separados por coma a través del campo `emails`. **La orden debe estar en estado facturada para poder enviar el correo.** Parameters: - `format` (query, string) - `order_id` (path, integer, required) — ID de la orden cuya factura se desea enviar Request body example: ``` { "emails": "cliente@empresa.cl, soporte@empresa.cl" } ``` Responses: - `200` — Correo enviado exitosamente #### GET /api/v1/order/pdf/{order_id} Download PDF of the invoice of an order Permite descargar el PDF de la factura generada para una orden específica. El PDF puede ser devuelto directamente o en un archivo `.zip` si se especifica `?compress=1` como parámetro en la URL. **Este recurso requiere que la orden ya haya sido facturada correctamente.** Parameters: - `compress` (query, integer) — Indica si el PDF debe entregarse comprimido (1 para sí) - `format` (query, string) - `order_id` (path, integer, required) — ID de la orden cuya factura se desea descargar Responses: - `200` — PDF en base64 entregado exitosamente (formato application/pdf o .zip). #### POST /api/v1/order/selector/{order_id} Test selector Permite probar una consulta (selector) sobre los datos de una orden ya existente. Este recurso es útil para depurar o verificar reglas de extracción de información. `origin` define qué datos usar como fuente. `root` permite fijar el punto base para la consulta (opcional). `selector` contiene la lógica de búsqueda dentro de los datos. **Este endpoint está pensado para pruebas internas y depuración.** Parameters: - `format` (query, string) - `order_id` (path, integer, required) — ID de la orden sobre la cual aplicar el selector Request body example: ``` { "origin": "datasource_data", "root": "line_items[0]", "selector": "taxes[id=1:total]" } ``` Responses: - `200` — Resultado del selector aplicado a los datos --- Last updated on 25/08/2026