API de bexio: La Guía Completa 2026 para Freelancers Suizos

¿Qué Es la API de bexio?

Una API (Interfaz de Programación de Aplicaciones) permite que diferentes sistemas de software intercambien datos automáticamente. La API de bexio es una interfaz RESTful que expone las funciones principales de bexio—contactos, facturas, contabilidad, inventario—a aplicaciones externas.

En términos prácticos: En lugar de crear manualmente una factura en bexio después de completar un proyecto, su herramienta de gestión de proyectos puede activar la creación automática de facturas. En lugar de copiar datos de clientes de su tienda web, los pedidos fluyen directamente a bexio.

La API utiliza HTTPS y formato JSON, haciéndola compatible con cualquier lenguaje de programación. bexio actualmente ofrece la versión 3.0.0 de la API.

Qué Puede Automatizar

Automatizaciones Populares de Zapier para Freelancers

1. Shopify → bexio: Nuevo pedido crea factura automáticamente
2. Toggl → bexio: Entradas de tiempo registradas se sincronizan al proyecto
3. HubSpot → bexio: Nuevo contacto de CRM crea contacto en bexio
4. Gmail → bexio: Adjunto de email crea entrada de gasto

Autenticación en Profundidad

bexio utiliza OAuth 2.0, el estándar de la industria para autorización de APIs. Entender el sistema de autorización dual es crucial.

Dos Niveles de Autorización

Nivel 1: Scopes de la Aplicación Cuando los usuarios conectan su app, otorgan permisos específicos (scopes). Solicite solo lo que necesita—los usuarios ven estos permisos en la pantalla de consentimiento.

Categorías de scopes disponibles:

• contact_show, contact_edit — Gestión de contactos
• kb_invoice_show, kb_invoice_edit — Acceso a facturas
• accounting_show — Leer datos de contabilidad
• article_show, article_edit — Gestión de productos

Nivel 2: Permisos de Usuario Las solicitudes a la API se ejecutan con los permisos del usuario que autorizó la conexión. Si ese usuario no puede eliminar facturas en bexio, su API tampoco puede eliminar facturas.

Flujo OAuth 2.0

1. Su app redirige al usuario a:
   https://auth.bexio.com/realms/bexio/protocol/openid-connect/auth
   ?client_id=YOUR_CLIENT_ID
   &redirect_uri=YOUR_REDIRECT_URL
   &response_type=code
   &scope=contact_show kb_invoice_edit

2. El usuario inicia sesión y aprueba los permisos

3. bexio redirige a su URL con el código de autorización

4. Intercambie el código por tokens en:
   https://auth.bexio.com/realms/bexio/protocol/openid-connect/token

5. Use el access token para las solicitudes a la API

Gestión de tokens:

• Los access tokens son de corta duración (típicamente 1 hora)
• Los refresh tokens obtienen nuevos access tokens sin interacción del usuario
• Almacene los refresh tokens de forma segura e implemente actualización automática de tokens

Soluciones para la Ausencia de Webhooks

• Polling: Verificar cambios periódicamente (cada 5-15 minutos)
• Zapier: Usa polling pero gestiona la infraestructura
• Servicios de webhook de terceros: Algunas plataformas de integración ofrecen funcionalidad pseudo-webhook

Gestionar Límites de Tasa

Basado en la experiencia de la comunidad:

• Implemente backoff exponencial en errores 429
• Cache respuestas donde sea posible
• Agrupe solicitudes cuando la API lo soporte
• Evite frecuencia de polling innecesaria

Bibliotecas de Cliente Limitadas

No existen SDKs oficiales. Las bibliotecas de la comunidad están incompletas. Para aplicaciones en producción, espere escribir código personalizado.

API de Facturas de Magic Heidi

La API de Facturas con Código QR Suizo de Magic Heidi es una API abierta de un solo endpoint para generar facturas suizas profesionales con recibos de pago QR. Sin OAuth, sin renovación de tokens, sin scopes—solo una clave API y una solicitud POST.

Cómo Funciona

1. Envíe una solicitud POST con los datos de su factura (remitente, cliente, partidas)
2. Reciba una URL de descarga del PDF válida por 24 horas
3. Eso es todo—sin flujo OAuth, sin registro en portal de desarrolladores

Ejemplo en Python

import requests

response = requests.post(
    "https://europe-west6-magic-heidi.cloudfunctions.net/create_invoice_abstract_v1d",
    headers={"key": "your_api_key"},
    json={
        "user_details": {
            "name": "Muster GmbH",
            "address": "Bahnhofstrasse 1",
            "zip": "8001",
            "city": "Zurich",
            "iban": "CH93 0076 2011 6238 5295 7"
        },
        "customer_details": {
            "name": "Acme AG",
            "address": "Bundesplatz 3",
            "zip": "3011",
            "city": "Bern"
        },
        "invoice_items": [
            {
                "description": "Web Development",
                "quantity": 10,
                "unit_price": 150
            },
            {
                "description": "Design Review",
                "quantity": 3,
                "unit_price": 120
            }
        ],
        "language": "en",
        "currency": "CHF",
        "vat_enabled": true,
        "vat_percentage": 8.1,
        "vat_number": "CHE-123.456.789 MWST"
    }
)

data = response.json()
print(f"Download your invoice: {data['url']}")

Ejemplo en JavaScript (Node.js)

const axios = require('axios');

const response = await axios.post(
  'https://europe-west6-magic-heidi.cloudfunctions.net/create_invoice_abstract_v1d',
  {
    user_details: {
      name: 'Muster GmbH',
      address: 'Bahnhofstrasse 1',
      zip: '8001',
      city: 'Zurich',
      iban: 'CH93 0076 2011 6238 5295 7'
    },
    customer_details: {
      name: 'Acme AG',
      address: 'Bundesplatz 3',
      zip: '3011',
      city: 'Bern'
    },
    invoice_items: [
      { description: 'Web Development', quantity: 10, unit_price: 150 },
      { description: 'Design Review', quantity: 3, unit_price: 120 }
    ],
    language: 'en',
    currency: 'CHF'
  },
  { headers: { key: 'your_api_key' } }
);

console.log(`Download your invoice: ${response.data.url}`);

Características Principales

• Facturas suizas con QR conformes con los estándares de pago suizos
• Multi-idioma: inglés, alemán, francés, italiano
• CHF y EUR como monedas soportadas
• Gestión del IVA con tasas configurables y número de IVA
• Logos personalizados mediante URL
• Modo solo QR para generar únicamente el recibo de pago
• Pruebas gratuitas sin clave API
• Documentación abierta en GitHub

Recursos

• API de Facturas de Magic Heidi — GitHub
• Generar Facturas Suizas con QR Programáticamente — Artículo del Blog
• Portal de Desarrolladores de bexio
• Documentación de la API de bexio
• Página de Estado de bexio
• Marketplace de bexio — más de 120 integraciones preconstruidas