Guia de Integração API

API Bexio: O Guia Completo 2025 para Freelancers Suíços

Conecte o software de gestão mais popular da Suíça com praticamente qualquer ferramenta que você usa. Configuração OAuth 2.0, exemplos de código e a migração de autenticação crítica de 2025 explicada.

Ilustração de Integração API

Pare a Entrada Manual de Dados.
Automatize Tudo.

Você gasta horas digitando dados manualmente entre suas ferramentas. Seu app de faturamento não se comunica com seu CRM. Sua loja virtual exige copiar e colar pedidos no software de contabilidade. A API Bexio resolve isso—conectando mais de 40.000 empresas suíças com praticamente qualquer outra ferramenta.

⏰
5+ Horas SemanaisPerdidas com entrada manual de dados
🔗
Ferramentas DesconectadasApps que não se comunicam
📋
Caos de Copiar e ColarPedidos inseridos manualmente na contabilidade

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

FunçãoCapacidade da API
ContatosCriar, atualizar, listar clientes e fornecedores
FaturasGerar, enviar, rastrear status de pagamento
PedidosCriar a partir de sistemas externos, atualizar status
ProdutosSincronizar estoque, atualizar níveis de inventário
ContabilidadeBuscar contas, registrar transações
ProjetosCriar, atribuir, rastrear tempo
⚠️ Atualização Crítica

Migração de Autenticação 2025

Se você tem integrações existentes com a API Bexio, leia isto primeiro.

O Bexio está desativando idp.bexio.com em 31 de março de 2025. Todas as aplicações devem migrar para o novo provedor de identidade:

Antigo: https://idp.bexio.com
Novo: https://auth.bexio.com/realms/bexio

Para a maioria das aplicações, a migração requer apenas atualizar as URLs dos endpoints de autorização e token. No entanto, se você não migrar até o prazo, sua integração deixará de funcionar.

Checklist de migração:

  1. Atualize a URL de autorização na configuração do seu app
  2. Atualize a URL do endpoint de token
  3. Teste o fluxo OAuth completo antes de março de 2025
  4. Monitore a página de status do Bexio em bexio-status.com para anúncios

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
Configuração para Desenvolvedores

Começando com a API Bexio

Tudo que você precisa saber para sua primeira integração

Pré-requisitos

  1. Conta Bexio: Qualquer plano pago (Starter CHF 45/mês, Pro CHF 75/mês, Pro+ CHF 125/mês). Acesso à API está incluído.
  2. Acesso ao Portal do Desenvolvedor: Visite o Portal do Desenvolvedor Bexio e faça login com suas credenciais Bexio.

Criando Credenciais da API

  1. Navegue até "My Apps" no portal do desenvolvedor
  2. Clique em "Create New App"
  3. Defina uma Redirect URL (necessária para o fluxo OAuth)
  4. Salve seu Client ID e Client Secret imediatamente—você não verá o secret novamente

🔒 Nota de segurança: Nunca faça commit de credenciais no controle de versão. Use variáveis de ambiente ou um gerenciador de secrets.

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
Exemplos de Código

Implementação em Múltiplas Linguagens

Trechos de código prontos para usar em Python, JavaScript e PHP

Python

Python é popular entre freelancers suíços para scripts de automação. Embora não exista biblioteca oficial, o bexio-api-python-client mantido pela comunidade oferece um ponto de partida.

import requests

BASE_URL = "https://api.bexio.com/2.0"
ACCESS_TOKEN = "your_access_token"

headers = {
    "Authorization": f"Bearer {ACCESS_TOKEN}",
    "Accept": "application/json"
}

# Buscar todos os contatos
response = requests.get(f"{BASE_URL}/contact", headers=headers)
contacts = response.json()

for contact in contacts:
    print(f"{contact['id']}: {contact['name_1']}")

# Criar nova fatura
invoice_data = {
    "contact_id": 1,
    "title": "Trabalho de Projeto - Janeiro 2025",
    "positions": [
        {
            "type": "KbPositionCustom",
            "text": "Serviços de Consultoria",
            "unit_price": "150.00",
            "amount": "10"
        }
    ]
}

response = requests.post(
    f"{BASE_URL}/kb_invoice",
    headers=headers,
    json=invoice_data
)
print(response.json())

JavaScript (Node.js)

const axios = require('axios');

const BASE_URL = 'https://api.bexio.com/2.0';
const ACCESS_TOKEN = process.env.BEXIO_TOKEN;

const api = axios.create({
  baseURL: BASE_URL,
  headers: {
    'Authorization': `Bearer ${ACCESS_TOKEN}`,
    'Accept': 'application/json'
  }
});

// Buscar contatos
async function getContacts() {
  const response = await api.get('/contact');
  return response.data;
}

// Criar contato
async function createContact(contactData) {
  const response = await api.post('/contact', {
    contact_type_id: 1, // 1 = Empresa, 2 = Pessoa
    name_1: contactData.company,
    name_2: contactData.name,
    mail: contactData.email,
    country_id: 1 // Suíça
  });
  return response.data;
}

getContacts().then(contacts => console.log(contacts));

PHP

A biblioteca onlime/bexio-api-client no GitHub oferece integração PHP:

<?php
require 'vendor/autoload.php';

use Bexio\Client;

$client = new Client([
    'clientId' => 'your_client_id',
    'clientSecret' => 'your_client_secret',
]);

$client->setAccessToken('your_access_token');

// Obter todos os contatos
$contacts = $client->getContacts();

// Criar fatura
$invoice = $client->createInvoice([
    'contact_id' => 1,
    'title' => 'Serviços de Desenvolvimento Web',
    'positions' => [
        [
            'type' => 'KbPositionCustom',
            'text' => 'Desenvolvimento Frontend',
            'unit_price' => '120.00',
            'amount' => '20'
        ]
    ]
]);

Nota: Tanto as bibliotecas da comunidade em Python quanto PHP cobrem apenas um subconjunto dos métodos da API. Para funcionalidade completa, você pode precisar de chamadas HTTP diretas.

Exemplos de Integração Reais

E-Commerce: Shopify + Bexio

A integração Shopware-Bexio demonstra o que é possível:

  • Geração automática de faturas baseada no método de pagamento
  • Criação de contatos a partir de contas de clientes
  • Sincronização de status de pedidos
  • Atualizações de estoque entre plataformas

Para Shopify, use Zapier ou construa uma integração customizada que:

  1. Escuta novos pedidos do Shopify (webhook ou polling)
  2. Cria/atualiza contato no Bexio a partir dos dados do cliente
  3. Gera fatura com itens de linha
  4. Opcionalmente envia fatura automaticamente

Rastreamento de Tempo: Toggl + Bexio

Vincule seu rastreamento de tempo com faturamento:

  1. Crie projetos correspondentes em ambos os sistemas
  2. Quando tempo é registrado no Toggl, sincronize com projeto Bexio
  3. Gere fatura a partir das entradas de tempo acumuladas
  4. Inclua detalhamento de tempo na fatura

CRM: HubSpot + Bexio

Mantenha vendas e contabilidade alinhados:

  • Novo negócio fechado no HubSpot → Criar fatura no Bexio
  • Contato atualizado no HubSpot → Sincronizar com contato Bexio
  • Fatura Bexio paga → Atualizar status do negócio no HubSpot

Limitações da API
& Alternativas

Ser transparente sobre o que a API não pode fazer economiza horas de frustração. A API do Bexio tem limitações—mas conhecê-las antecipadamente ajuda você a planejar melhor.

🔔
Sem Webhooks NativosUse polling ou Zapier como alternativas
🚦
Limites de Taxa Não DocumentadosImplemente backoff e cache
🧪
Sem Ambiente SandboxTeste com dados reais cuidadosamente

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 algum código customizado.

Segurança

Melhores Práticas de Segurança

Proteja sua integração e os dados dos seus clientes

Preços

Planos Bexio & Acesso à API

Planos atuais em 2025—todos incluem acesso à API

RecursoStarterProPro+
PreçoCHF 45/mêsCHF 75/mêsCHF 125/mês
Usuários1 usuárioAté 3Até 25
Acesso à API✓ Incluído✓ Incluído✓ Incluído
App bexio Go✗ Não✓ Incluído✓ Incluído
Teste Grátis30 dias30 dias30 dias (recursos Pro+)
Alternativa Mais Simples

Quando a API Bexio É Demais

Nem todo freelancer suíço precisa de integração via API. Se você envia menos de 10 faturas por mês, não usa múltiplas ferramentas de negócios, ou acha OAuth 2.0 intimidador—considere alternativas mais simples. Magic Heidi oferece faturamento simplificado para freelancers suíços por CHF 30/mês. Sem complexidade de API.

Lista de Faturas Magic Heidi
FAQ

Perguntas Frequentes

A API Bexio é gratuita?

Sim, acesso à API está incluído em todos os planos pagos do Bexio (a partir de CHF 45/mês).

Quais linguagens de programação funcionam com a API?

Qualquer linguagem que possa fazer requisições HTTP—Python, JavaScript, PHP, C#, Ruby, Go, etc.

Posso usar a API sem programar?

Sim. Zapier e Make.com oferecem automação no-code com Bexio.

O Bexio suporta webhooks?

Não nativamente. Use polling ou Zapier como alternativas.

Quais são os limites de taxa da API?

Não documentados publicamente. Implemente backoff e cache como precauções.

Existe ambiente de teste/sandbox?

Não. Teste com dados reais cuidadosamente.

Quando devo migrar a autenticação?

Antes de 31 de março de 2025. O endpoint antigo idp.bexio.com deixará de funcionar.

Recursos

Precisa de Faturamento Suíço Mais Simples?

Magic Heidi cuida de faturas QR, despesas e IVA—disponível em todas as plataformas. Sem complexidade de API.

Começar Teste GrátisComparar com Bexio
App Store Google Play Microsoft Store Aplicação Web