Documentación API REST
Integra la emisión de facturas electrónicas de Orange Bill directamente desde tu sistema, ERP o e-commerce.
Requisitos y autenticación
Necesitas antes de integrar
- NIT, sector y modalidad — datos de tu empresa asignados por el SIN dentro de Orange Bill.
- Usuario y contraseña de API — credenciales propias de tu cuenta (distintas del login del panel web), solicítalas a tu contacto de Orange Bill.
-
Catálogo de productos — cada producto que facturas debe existir previamente en tu cuenta de Orange Bill (se consulta con
Get_All_Products/Get_Product).
Cómo se autentican las llamadas
En esta v1, cada llamada envía nit, sector y modality para identificar tu cuenta. Los métodos que consultan o generan información sensible (como Get_User y Set_Invoice) además exigen username y password de API. No hay token/Bearer independiente en esta versión.
Formato de las respuestas
Todas las respuestas son JSON con tres campos: error (booleano), message (texto descriptivo) y data (el resultado).
error aparece en true incluso en respuestas exitosas (revisa siempre el texto de message para confirmar el resultado). Valida este comportamiento con tu contacto técnico antes de usarlo como condición en producción — quedará precisado en la próxima versión de esta documentación.
Tu primera factura por API
Flujo típico: consulta el catálogo de productos de tu actividad económica y luego emite la factura con Set_Invoice.
# 1. Consultar productos de tu actividad económica
curl -G "https://orangebill.com.bo/misfacturas/api/Get_All_Products" \
--data-urlencode "nit=20974000000" \
--data-urlencode "sector=1" \
--data-urlencode "modality=2" \
--data-urlencode "activities=620901"
# 2. Emitir la factura
curl -X POST "https://orangebill.com.bo/misfacturas/api/Set_Invoice" \
-H "Content-Type: application/json" \
-d '{
"nit": 20974000000,
"sector": 1,
"modality": 2,
"username": "tu_usuario_api",
"password": "tu_password_api",
"activities_id": 620901,
"invoice_name": "Juan Pérez",
"type_of_document_id": 5,
"invoice_nit": "1234567",
"invoice_complement": "",
"invoice_email": "cliente@ejemplo.com",
"code_pay_method": 1,
"cardnumber": "0",
"cardcost": 0.00,
"total_cost": 50.00,
"giftcardnumber": 0,
"giftcard": 0.00,
"invoice_discount": 0.00,
"products": [
{
"activity": "620901",
"Code_Sin": 83151,
"Code": 1,
"Description": "SERVICIOS DE ALOJAMIENTO WEB (HOSTING)",
"quantity": 1,
"unity": 58,
"unit_cost": 50,
"discount": 0,
"subtototal": 50
}
]
}'
<?php
declare(strict_types=1);
$baseUrl = 'https://orangebill.com.bo/misfacturas/api';
// 1. Consultar productos de tu actividad económica
$query = http_build_query([
'nit' => 20974000000,
'sector' => 1,
'modality' => 2,
'activities' => 620901,
]);
$productos = json_decode(file_get_contents("{$baseUrl}/Get_All_Products?{$query}"), true);
// 2. Emitir la factura
$payload = [
'nit' => 20974000000,
'sector' => 1,
'modality' => 2,
'username' => 'tu_usuario_api',
'password' => 'tu_password_api',
'activities_id' => 620901,
'invoice_name' => 'Juan Pérez',
'type_of_document_id' => 5,
'invoice_nit' => '1234567',
'invoice_complement' => '',
'invoice_email' => 'cliente@ejemplo.com',
'code_pay_method' => 1,
'cardnumber' => '0',
'cardcost' => 0.00,
'total_cost' => 50.00,
'giftcardnumber' => 0,
'giftcard' => 0.00,
'invoice_discount' => 0.00,
'products' => [[
'activity' => '620901',
'Code_Sin' => 83151,
'Code' => 1,
'Description' => 'SERVICIOS DE ALOJAMIENTO WEB (HOSTING)',
'quantity' => 1,
'unity' => 58,
'unit_cost' => 50,
'discount' => 0,
'subtototal' => 50,
]],
];
$ch = curl_init("{$baseUrl}/Set_Invoice");
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
CURLOPT_POSTFIELDS => json_encode($payload),
]);
$response = json_decode(curl_exec($ch), true);
curl_close($ch);
if ($response['error'] === true) {
echo "Factura emitida: {$response['data']['pdf']}";
}
import { useState } from 'react';
async function emitirFactura(payload) {
const res = await fetch('https://orangebill.com.bo/misfacturas/api/Set_Invoice', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify(payload),
});
return res.json();
}
function BotonFacturar({ cliente, total }) {
const [estado, setEstado] = useState('idle');
const [pdfUrl, setPdfUrl] = useState(null);
async function handleClick() {
setEstado('cargando');
try {
const data = await emitirFactura({
nit: 20974000000,
sector: 1,
modality: 2,
username: 'tu_usuario_api',
password: 'tu_password_api',
activities_id: 620901,
invoice_name: cliente.nombre,
type_of_document_id: 5,
invoice_nit: cliente.nit,
invoice_complement: '',
invoice_email: cliente.email,
code_pay_method: 1,
cardnumber: '0',
cardcost: 0,
total_cost: total,
giftcardnumber: 0,
giftcard: 0,
invoice_discount: 0,
products: [
{
activity: '620901',
Code_Sin: 83151,
Code: 1,
Description: 'SERVICIOS DE ALOJAMIENTO WEB (HOSTING)',
quantity: 1,
unity: 58,
unit_cost: 50,
discount: 0,
subtototal: 50,
},
],
});
if (data.error === true) {
setPdfUrl(data.data.pdf);
setEstado('listo');
} else {
setEstado('error');
}
} catch {
setEstado('error');
}
}
return (
<button onClick={handleClick} disabled={estado === 'cargando'}>
{estado === 'cargando' ? 'Emitiendo...' : 'Emitir factura'}
</button>
);
}
import requests
BASE_URL = "https://orangebill.com.bo/misfacturas/api"
# 1. Consultar productos de tu actividad económica
productos = requests.get(f"{BASE_URL}/Get_All_Products", params={
"nit": 20974000000,
"sector": 1,
"modality": 2,
"activities": 620901,
}).json()
# 2. Emitir la factura
payload = {
"nit": 20974000000,
"sector": 1,
"modality": 2,
"username": "tu_usuario_api",
"password": "tu_password_api",
"activities_id": 620901,
"invoice_name": "Juan Pérez",
"type_of_document_id": 5,
"invoice_nit": "1234567",
"invoice_complement": "",
"invoice_email": "cliente@ejemplo.com",
"code_pay_method": 1,
"cardnumber": "0",
"cardcost": 0.00,
"total_cost": 50.00,
"giftcardnumber": 0,
"giftcard": 0.00,
"invoice_discount": 0.00,
"products": [{
"activity": "620901",
"Code_Sin": 83151,
"Code": 1,
"Description": "SERVICIOS DE ALOJAMIENTO WEB (HOSTING)",
"quantity": 1,
"unity": 58,
"unit_cost": 50,
"discount": 0,
"subtototal": 50,
}],
}
response = requests.post(f"{BASE_URL}/Set_Invoice", json=payload).json()
if response["error"] is True:
print("Factura emitida:", response["data"]["pdf"])
Métodos disponibles
/misfacturas/api/Get_User
Devuelve los datos de la sucursal, punto de venta y actividad económica asociados al usuario de API.
Parámetros (query string)
| Parámetro | Ejemplo | Nota |
|---|---|---|
nit | 20974000000 | NIT de tu empresa |
sector | 1 | Código de sector asignado por el SIN |
modality | 2 | Modalidad de facturación |
username | tu_usuario_api | Usuario de API |
password | tu_password_api | Contraseña de API |
Ejemplo
curl -G "https://orangebill.com.bo/misfacturas/api/Get_User" \
--data-urlencode "nit=20974000000" \
--data-urlencode "sector=1" \
--data-urlencode "modality=2" \
--data-urlencode "username=tu_usuario_api" \
--data-urlencode "password=tu_password_api"
Respuesta
{
"error": true,
"message": "Usuario Encontrado",
"data": {
"Id_Sucursal": "0",
"Name_Sucursal": "CASA MATRIZ",
"Id_PointOfSale": "0",
"Name_PointOfSale": "Punto de Venta 0",
"Activity": "620901",
"Name_Activity": "OTRAS ACTIVIDADES DE INFORMÁTICA"
}
}
/misfacturas/api/Get_Identity_Document
Devuelve los tipos de documento de identidad habilitados para facturar (CI, NIT, pasaporte, etc.).
Parámetros (query string)
| Parámetro | Ejemplo | Nota |
|---|---|---|
nit | 20974000000 | NIT de tu empresa |
sector | 1 | Código de sector |
modality | 2 | Modalidad de facturación |
Ejemplo
curl -G "https://orangebill.com.bo/misfacturas/api/Get_Identity_Document" \
--data-urlencode "nit=20974000000" \
--data-urlencode "sector=1" \
--data-urlencode "modality=2"
Respuesta
{
"error": true,
"message": "Tipos de Documentos de Identidad Encontrados",
"data": [
{ "Code": "1", "Description": "CI - CEDULA DE IDENTIDAD" },
{ "Code": "2", "Description": "CEX - CEDULA DE IDENTIDAD DE EXTRANJERO" },
{ "Code": "5", "Description": "NIT - NÚMERO DE IDENTIFICACIÓN TRIBUTARIA" },
{ "Code": "3", "Description": "PAS - PASAPORTE" },
{ "Code": "4", "Description": "OD - OTRO DOCUMENTO DE IDENTIDAD" }
]
}
/misfacturas/api/Get_Payment_Method
Devuelve los métodos de pago habilitados para facturar.
Parámetros (query string)
| Parámetro | Ejemplo | Nota |
|---|---|---|
nit | 20974000000 | NIT de tu empresa |
sector | 1 | Código de sector |
modality | 2 | Modalidad de facturación |
Ejemplo
curl -G "https://orangebill.com.bo/misfacturas/api/Get_Payment_Method" \
--data-urlencode "nit=20974000000" \
--data-urlencode "sector=1" \
--data-urlencode "modality=2"
Respuesta
{
"error": true,
"message": "Metodos de Pago Encontrados",
"data": [
{ "Code": "1", "Description": "EFECTIVO" },
{ "Code": "2", "Description": "TARJETA" },
{ "Code": "3", "Description": "CHEQUE" },
{ "Code": "4", "Description": "VALES" },
{ "Code": "5", "Description": "OTROS" },
{ "Code": "6", "Description": "PAGO POSTERIOR" }
]
}
El catálogo completo es más extenso (incluye variantes de "DÉBITO AUTOMÁTICO" con códigos adicionales). Consume este endpoint dinámicamente en vez de fijar la lista en tu código.
/misfacturas/api/Get_All_Products
Devuelve los productos/servicios asociados a una actividad económica registrada en tu cuenta.
Parámetros (query string)
| Parámetro | Ejemplo | Nota |
|---|---|---|
nit | 20974000000 | NIT de tu empresa |
sector | 1 | Código de sector |
modality | 2 | Modalidad de facturación |
activities | 620901 | Código CAEB de la actividad económica |
Ejemplo
curl -G "https://orangebill.com.bo/misfacturas/api/Get_All_Products" \
--data-urlencode "nit=20974000000" \
--data-urlencode "sector=1" \
--data-urlencode "modality=2" \
--data-urlencode "activities=620901"
Respuesta
{
"error": true,
"message": "Productos Encontrados",
"data": [
{ "Code": "83151", "Description": "SERVICIOS DE ALOJAMIENTO WEB (HOSTING)" },
{ "Code": "83152", "Description": "SERVICIOS DE APROVISIONAMIENTO DE APLICACIONES" },
{ "Code": "83159", "Description": "OTROS SERVICIOS DE ALOJAMIENTO Y SERVICIOS DE PROVISIÓN DE LA INFRAESTRUCTURA DE TI" },
{ "Code": "83161", "Description": "SERVICIOS DE GESTIÓN DE REDES" },
{ "Code": "83162", "Description": "SERVICIOS DE GESTIÓN DE SISTEMAS INFORMÁTICOS" }
]
}
/misfacturas/api/Get_Product
Devuelve los datos completos de un producto (código interno, código SIN, unidad de medida y costo) a partir de su código.
Parámetros (query string)
| Parámetro | Ejemplo | Nota |
|---|---|---|
nit | 20974000000 | NIT de tu empresa |
sector | 1 | Código de sector |
modality | 2 | Modalidad de facturación |
code_product | 83151 | Código devuelto por Get_All_Products |
Ejemplo
curl -G "https://orangebill.com.bo/misfacturas/api/Get_Product" \
--data-urlencode "nit=20974000000" \
--data-urlencode "sector=1" \
--data-urlencode "modality=2" \
--data-urlencode "code_product=83151"
Respuesta
{
"error": true,
"message": "Productos Encontrados",
"data": [
{
"Code": "2385",
"Code_Sin": "83151",
"Description": "SERVICIOS DE ALOJAMIENTO WEB (HOSTING)",
"Name_Unity": "UNIDAD (SERVICIOS)",
"Id_Unity": "58",
"Cost": "10.00"
}
]
}
/misfacturas/api/Set_Invoice
Genera la factura ante el SIN y devuelve el código de recepción, el XML del documento fiscal y la URL del PDF.
period y student_name, propios del esquema de Sector Educativo (facturaComputarizadaSectorEducativo). Si tu actividad no es educativa, probablemente no los necesites — confírmalo con tu contacto de Orange Bill según el sector asignado a tu cuenta.
Cuerpo de la petición (JSON)
| Campo | Tipo | Nota |
|---|---|---|
nit, sector, modality | number | Identifican tu cuenta |
username, password | string | Credenciales de API |
activities_id | number | Actividad económica (CAEB) |
invoice_name | string | Nombre o razón social del cliente |
type_of_document_id | number | Código de Get_Identity_Document |
invoice_nit | string | Documento del cliente |
invoice_email | string | Correo donde se envía la factura |
code_pay_method | number | Código de Get_Payment_Method |
total_cost | number | Monto total de la factura |
products | array | Ítems: código SIN, cantidad, costo unitario y subtotal |
Ejemplo
{
"nit": 20974000000,
"sector": 1,
"modality": 2,
"username": "tu_usuario_api",
"password": "tu_password_api",
"activities_id": 620901,
"invoice_name": "Juan Pérez",
"type_of_document_id": 5,
"invoice_nit": "1234567",
"invoice_complement": "",
"invoice_email": "cliente@ejemplo.com",
"code_pay_method": 1,
"cardnumber": "0",
"cardcost": 0.00,
"total_cost": 50.00,
"giftcardnumber": 0,
"giftcard": 0.00,
"invoice_discount": 0.00,
"products": [
{
"activity": "620901",
"Code_Sin": 83151,
"Code": 1,
"Description": "SERVICIOS DE ALOJAMIENTO WEB (HOSTING)",
"quantity": 1,
"unity": 58,
"unit_cost": 50,
"discount": 0,
"subtototal": 50
}
]
}
Respuesta
{
"error": true,
"message": "Factura Generada con Exito!",
"data": {
"Reception_code": "b2a785e3-a766-11ee-8680-81d64f92d1f0",
"xml": "<?xml version=\"1.0\"?><facturaComputarizadaSectorEducativo>...</facturaComputarizadaSectorEducativo>",
"pdf": "https://orangebill.com.bo/misfacturas/assets/facturas/Factura_XXXXXXXXXXXXXXXXXX.pdf"
}
}
xml contiene el documento fiscal completo (abreviado aquí por espacio) y pdf es la URL descargable de la factura ya emitida.
¿Listo para integrar tu sistema?
Escríbenos para obtener tus credenciales de API y activar la modalidad de integración.