HTTP API
Chaves de API, URL base e autenticação para a API REST do Tillor
Última atualização em
A API do Tillor é uma API REST. Autentique-se com uma chave de API e envie os cabeçalhos certos em cada pedido. As chaves de API são por conta - uma só chave funciona para todas as organizações a que tem acesso.
Referência da API e OpenAPI
- Referência da API - Cada endpoint com parâmetros e exemplos; experimente pedidos diretamente no navegador
- Especificação OpenAPI - Documentação completa da API em formato JSON para geração de código ou importação no Postman/Insomnia
Chaves de API
Criar
As chaves de API são criadas na aplicação Tillor, no menu do utilizador, em Conta > Chaves de API (marca 1 = menu, marca 2 = Chaves de API na captura de ecrã). Também pode criá-las através da API com uma sessão iniciada (sem chave de API). Veja a especificação OpenAPI, na etiqueta api-keys, para caminhos e esquemas de pedido e resposta.
A chave em bruto é devolvida uma única vez ao criar ou regenerar. Guarde-a em segurança; depois já não a pode voltar a obter.
Limitar permissões
Por predefinição, uma chave pode fazer tudo o que você próprio pode, em qualquer organização de que seja membro. Na janela da chave, ative Limitar às permissões selecionadas e escolha as permissões de que a ligação precisa, por exemplo apenas ler faturas. Uma chave limitada recebe, em cada organização, a interseção das suas permissões com a sua participação aí: uma chave nunca pode mais do que você. Uma chamada fora das permissões escolhidas recebe 403 Forbidden, tal como um utilizador sem essa permissão. Uma alteração das permissões entra em vigor em menos de um minuto. Através da API: scopes (lista de ids de permissões como invoices:read, ou null para tudo) ao criar e atualizar uma chave.
Utilização
Envie a chave de API no cabeçalho x-api-key:
x-api-key: tkn_xxxAs chaves usam o prefixo tkn_. Nos endpoints de organização, o ID da organização está no caminho (/orgs/org_abc123/...); não é necessário um cabeçalho à parte.
Limites de pedidos
- Predefinição: 5000 pedidos por 60 segundos por chave
- Em caso de excesso:
429 Too Many RequestscomRetry-After - Cada resposta com chave de API contém cabeçalhos IETF
RateLimit-*:
RateLimit-Limit: 5000
RateLimit-Remaining: 4999
RateLimit-Reset: 58
RateLimit-Policy: 5000;w=60RateLimit-Reset é o número de segundos até a janela atual recomeçar. Os clientes de navegador podem ler estes cabeçalhos através de CORS (Access-Control-Expose-Headers).
Segurança
Atenção
- Nunca exponha chaves de API em código do lado do cliente ou em repositórios públicos
- Regenere as chaves periodicamente através de Regenerar na aplicação (OpenAPI:
POST /api/api-keys/:id/renew) - Elimine chaves não utilizadas com
DELETE /api/api-keys/:id
URL base e contexto da organização
URL base: https://tillor.eu (ou o URL da sua instalação; o OpenAPI indica {APP_URL}/api)
Caminhos de organização: acrescente o ID da organização ao caminho:
/api/orgs/:orgId/...Exemplo:
GET https://tillor.eu/api/orgs/org_abc123/customersCabeçalho obrigatório para endpoints de organização: x-api-key: tkn_xxx. O ID da organização está no caminho.
Exemplo: cURL
curl -X GET "https://tillor.eu/api/orgs/org_abc123/customers" \
-H "x-api-key: tkn_xxx" \
-H "Content-Type: application/json"Integrações (marketplace)
As integrações da organização (antes "apps" na API) usam um recurso por tipo em /api/orgs/:orgId/integrations/{integrationType}. As permissões necessárias são organization:integrations:read e organization:integrations:write (substitui organization:apps:*).
| Método | Caminho | Descrição |
|---|---|---|
| GET | /integrations/{integrationType} | Estado (installed, available) e settings ocultadas |
| POST | /integrations/{integrationType} | Instalar (settings opcional no corpo; o OAuth pode devolver redirectUrl) |
| PUT | /integrations/{integrationType} | Atualizar definições (settings no corpo) |
| DELETE | /integrations/{integrationType} | Desinstalar |
Em GET e depois de PUT, settings contém apenas campos públicos mais, por campo secreto, { configured: true }. Palavras-passe, chaves de API e tokens OAuth não são devolvidos. Deixe os campos secretos vazios em PUT para manter o valor existente.
Veja a especificação OpenAPI (etiqueta integrations) para os esquemas exatos.
Relacionado
- Referência da API - Cada endpoint, para experimentar no navegador
- OpenAPI - Especificação da API (JSON)
- MCP - Ligar o Cursor, o Claude, o ChatGPT ou o Gemini através de OAuth
- Notificações externas - Registar e-mails que o seu próprio sistema enviou
- Webhooks - Receber eventos através de HTTP POST
- Webhook de entrada de uma automatização - Iniciar uma automatização com um POST, sem chave de API
- SSE - Transmitir eventos através de Server-Sent Events
- Exemplos - Exemplos de código e de payload