Para desarrolladores

Documentación API REST

Integra la emisión de facturas electrónicas de Orange Bill directamente desde tu sistema, ERP o e-commerce.

Base URL: https://orangebill.com.bo/misfacturas/api Formato: JSON
Antes de empezar

Requisitos y autenticación

Documentación v1 (básica). Cubre los métodos y ejemplos disponibles actualmente. El equipo de Orange Bill entregará una versión más completa más adelante — si algo no está claro o tu integración necesita un dato que no ves aquí, escríbenos por contacto.

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).
Solicitar credenciales de API

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).

En los ejemplos de esta v1, 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.
Guía rápida

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
      }
    ]
  }'
Referencia

Métodos disponibles

GET /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ámetros de Get_User
ParámetroEjemploNota
nit20974000000NIT de tu empresa
sector1Código de sector asignado por el SIN
modality2Modalidad de facturación
usernametu_usuario_apiUsuario de API
passwordtu_password_apiContraseñ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"
  }
}
GET /misfacturas/api/Get_Identity_Document

Devuelve los tipos de documento de identidad habilitados para facturar (CI, NIT, pasaporte, etc.).

Parámetros (query string)

Parámetros de Get_Identity_Document
ParámetroEjemploNota
nit20974000000NIT de tu empresa
sector1Código de sector
modality2Modalidad 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" }
  ]
}
GET /misfacturas/api/Get_Payment_Method

Devuelve los métodos de pago habilitados para facturar.

Parámetros (query string)

Parámetros de Get_Payment_Method
ParámetroEjemploNota
nit20974000000NIT de tu empresa
sector1Código de sector
modality2Modalidad 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.

GET /misfacturas/api/Get_All_Products

Devuelve los productos/servicios asociados a una actividad económica registrada en tu cuenta.

Parámetros (query string)

Parámetros de Get_All_Products
ParámetroEjemploNota
nit20974000000NIT de tu empresa
sector1Código de sector
modality2Modalidad de facturación
activities620901Có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" }
  ]
}
GET /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ámetros de Get_Product
ParámetroEjemploNota
nit20974000000NIT de tu empresa
sector1Código de sector
modality2Modalidad de facturación
code_product83151Có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"
    }
  ]
}
POST /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.

El ejemplo oficial de esta v1 incluye 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)

Campos del cuerpo de Set_Invoice
CampoTipoNota
nit, sector, modalitynumberIdentifican tu cuenta
username, passwordstringCredenciales de API
activities_idnumberActividad económica (CAEB)
invoice_namestringNombre o razón social del cliente
type_of_document_idnumberCódigo de Get_Identity_Document
invoice_nitstringDocumento del cliente
invoice_emailstringCorreo donde se envía la factura
code_pay_methodnumberCódigo de Get_Payment_Method
total_costnumberMonto total de la factura
productsarrayÍ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.

Da el paso

¿Listo para integrar tu sistema?

Escríbenos para obtener tus credenciales de API y activar la modalidad de integración.