Referência da API (beta)

A API do To Bill é a que a própria app utiliza: clientes, faturas, orçamentos, artigos, despesas, banco, contabilidade, IVA, salários e tempo. Uma chave API pessoal abre-a aos seus scripts e ferramentas, com os seus direitos. A referência interativa da API descreve cada rota que uma chave pode chamar, os seus parâmetros e respostas, dá exemplos em curl, JavaScript, Python e PHP e permite-lhe experimentar um pedido com a sua chave.

A referência está em inglês

Como a maioria das referências técnicas, está redigida em inglês, a língua dos programadores. Esta página resume o essencial.

Uma versão beta

A API está em versão beta (0.x). As suas rotas e respostas podem mudar sem aviso prévio: não há garantia de compatibilidade nem suporte para a sua utilização direta. Para ligar um assistente de IA, utilize o servidor MCP, que é a interface estável: consulte Ligar um assistente de IA.

Autenticar-se

Cada pedido leva uma chave API pessoal no cabeçalho HTTP Authorization:

curl https://app.tobill.ch/api/clients -H "Authorization: Bearer tb_pk_…"

A chave cria-se em Definições › Ligações IA e API: consulte A API e as chaves API. Age em seu nome, na empresa onde a criou, com os seus direitos nessa empresa. Uma chave Só leitura só envia pedidos de leitura (GET); uma chave Leitura e alteração também pode criar, alterar e eliminar.

Os erros

Um pedido recusado recebe uma resposta JSON desta forma: { "statusMessage": "error", "message": "…", "error_code": "…", "fallback": "…" }. message é um código estável, a testar no seu programa; fallback é uma frase legível, por exemplo com o campo em causa.

Código HTTP	Significado
400	Dados inválidos.
401	Chave ausente, inválida, expirada ou revogada.
403	Recusado: chave só de leitura, direito em falta, subscrição sem acesso à API, ou parte do To Bill fechada às chaves (not_available_with_api_token).
404	Não encontrado nesta empresa.
429	Demasiados pedidos: aguarde o número de segundos indicado pelo cabeçalho Retry-After.

Os limites

• 300 pedidos por minuto e por chave; uma alteração conta a dobrar.
• Uma chave não abre o início de sessão na sua conta, a subscrição, os pagamentos, a gestão da equipa e das chaves, outra empresa, o cockpit de um fiduciário nem as ações em massa. Estas rotas não constam da referência.

A especificação OpenAPI

A referência é gerada a partir do documento OpenAPI 3.1 da API. Pode importá-lo para uma ferramenta como o Postman ou gerar um cliente a partir dele:

O quê	Endereço
Referência interativa	https://docs.tobill.ch/api
Especificação OpenAPI 3.1	https://app.tobill.ch/api/openapi.json

Experimentar um pedido

Na referência, o botão Test Request envia o pedido a partir do seu navegador diretamente para https://app.tobill.ch, sem intermediários. A sua chave só vai para o To Bill e não é guardada: desaparece quando fecha a página. Um pedido de alteração altera mesmo os seus dados: para descobrir a API, experimente-a com uma chave Só leitura.