API bexio: O Guia Completo 2026 para Freelancers Suíços

O Que É a API bexio?

Uma API (Interface de Programação de Aplicações) permite que diferentes sistemas de software troquem dados automaticamente. A API bexio é uma interface RESTful que expõe os recursos principais do bexio—contatos, faturas, contabilidade, estoque—para aplicações externas.

Na prática: Em vez de criar manualmente uma fatura no bexio após concluir um projeto, sua ferramenta de gestão de projetos pode acionar a criação automática de faturas. Em vez de copiar dados de clientes da sua loja virtual, os pedidos fluem diretamente para o bexio.

A API usa HTTPS e formato JSON, tornando-a compatível com qualquer linguagem de programação. O bexio oferece atualmente a versão 3.0.0 da API.

O Que Você Pode Automatizar

Automações Zapier Populares para Freelancers

1. Shopify → bexio: Novo pedido cria fatura automaticamente
2. Toggl → bexio: Entradas de tempo registradas sincronizam com projeto
3. HubSpot → bexio: Novo contato no CRM cria contato no bexio
4. Gmail → bexio: Anexo de email cria entrada de despesa

Autenticação em Detalhes

O bexio usa OAuth 2.0, o padrão da indústria para autorização de API. Entender o sistema de autorização dual é crucial.

Dois Níveis de Autorização

Nível 1: Escopos da Aplicação Quando usuários conectam seu app, eles concedem permissões específicas (escopos). Solicite apenas o que você precisa—os usuários veem essas permissões na tela de consentimento.

Categorias de escopo disponíveis:

• contact_show, contact_edit — Gestão de contatos
• kb_invoice_show, kb_invoice_edit — Acesso a faturas
• accounting_show — Leitura de dados contábeis
• article_show, article_edit — Gestão de produtos

Nível 2: Direitos do Usuário Requisições da API executam com as permissões do usuário que autorizou a conexão. Se esse usuário não tem permissão para excluir faturas no bexio, sua API também não pode excluir faturas.

Fluxo OAuth 2.0

1. Seu app redireciona o usuário para:
   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. Usuário faz login e aprova permissões

3. bexio redireciona para sua URL com código de autorização

4. Troque o código por tokens em:
   https://auth.bexio.com/realms/bexio/protocol/openid-connect/token

5. Use o access token para requisições da API

Gestão de tokens:

• Access tokens são de curta duração (tipicamente 1 hora)
• Refresh tokens obtêm novos access tokens sem interação do usuário
• Armazene refresh tokens com segurança e implemente refresh automático de tokens

Alternativas para Ausência de Webhooks

• Polling: Verifique mudanças periodicamente (a cada 5-15 minutos)
• Zapier: Usa polling mas cuida da infraestrutura
• Serviços de webhook terceiros: Algumas plataformas de integração oferecem funcionalidade pseudo-webhook

Lidando com Limites de Taxa

Baseado na experiência da comunidade:

• Implemente backoff exponencial em erros 429
• Faça cache de respostas quando possível
• Agrupe requisições quando a API suportar
• Evite frequência de polling desnecessária

Bibliotecas de Cliente Limitadas

SDKs oficiais não existem. Bibliotecas da comunidade são incompletas. Para aplicações em produção, espere escrever código customizado.

API de Faturas Magic Heidi

A API Magic Heidi Swiss Invoice QR Code é uma API aberta de endpoint único para gerar faturas suíças profissionais com boletos de pagamento QR. Sem OAuth, sem refresh de token, sem escopos—apenas uma chave de API e uma requisição POST.

Como Funciona

1. Envie uma requisição POST com os dados da fatura (remetente, cliente, itens)
2. Receba uma URL de download de PDF válida por 24 horas
3. É isso—sem fluxo OAuth, sem registro em portal de desenvolvedor

Exemplo em 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']}")

Exemplo em 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}`);

Recursos Principais

• Faturas QR suíças em conformidade com padrões de pagamento suíços
• Multi-idioma: Inglês, Alemão, Francês, Italiano
• CHF e EUR suporte a moedas
• Gestão de IVA com taxas configuráveis e número de IVA
• Logos personalizados via URL
• Modo somente QR para gerar apenas o boleto de pagamento
• Teste gratuito sem chave de API
• Documentação aberta no GitHub

Recursos

• API de Faturas Magic Heidi — GitHub
• Gerar Faturas QR Suíças Programaticamente — Artigo do Blog
• Portal do Desenvolvedor bexio
• Documentação da API bexio
• Página de Status bexio
• Marketplace bexio — mais de 120 integrações pré-construídas