# HTTP API (/pt-PT/ontwikkelaars/http)
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 [#api-referentie-en-openapi]
- **[Referência da API](/api-referentie)** - Cada endpoint com parâmetros e exemplos; experimente pedidos diretamente no navegador
- **[Especificação OpenAPI](https://tillor.eu/api/openapi.json)** - Documentação completa da API em formato JSON para geração de código ou importação no Postman/Insomnia
---
## Chaves de API [#api-sleutels]
### Criar [#aanmaken]
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](https://tillor.eu/api/openapi.json), 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 [#rechten-beperken]
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 [#gebruik]
Envie a chave de API no cabeçalho `x-api-key`:
```http
x-api-key: tkn_xxx
```
As 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 [#rate-limits]
- **Predefinição:** 5000 pedidos por 60 segundos por chave
- Em caso de excesso: `429 Too Many Requests` com `Retry-After`
- Cada resposta com chave de API contém cabeçalhos IETF `RateLimit-*`:
```http
RateLimit-Limit: 5000
RateLimit-Remaining: 4999
RateLimit-Reset: 58
RateLimit-Policy: 5000;w=60
```
`RateLimit-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 [#beveiliging]
- **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 [#base-url-en-organisatie-context]
**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/customers
```
**Cabeçalho obrigatório para endpoints de organização:** `x-api-key: tkn_xxx`. O ID da organização está no caminho.
---
## Exemplo: cURL [#voorbeeld-curl]
```bash
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) [#integraties-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](https://tillor.eu/api/openapi.json) (etiqueta `integrations`) para os esquemas exatos.
---
## Relacionado [#gerelateerd]
- [Referência da API](/api-referentie) - Cada endpoint, para experimentar no navegador
- [OpenAPI](https://tillor.eu/api/openapi.json) - Especificação da API (JSON)
- [MCP](/ontwikkelaars/mcp) - Ligar o Cursor, o Claude, o ChatGPT ou o Gemini através de OAuth
- [Notificações externas](/ontwikkelaars/externe-notificaties) - Registar e-mails que o seu próprio sistema enviou
- [Webhooks](/ontwikkelaars/webhooks) - Receber eventos através de HTTP POST
- [Webhook de entrada de uma automatização](/ontwikkelaars/automatiseringen#een-automatisering-starten-met-een-webhook) - Iniciar uma automatização com um POST, sem chave de API
- [SSE](/ontwikkelaars/sse) - Transmitir eventos através de Server-Sent Events
- [Exemplos](/ontwikkelaars/voorbeelden) - Exemplos de código e de payload