# Visão geral da API

As áreas em que a API se divide, quem chama cada uma, e como obter os URLs base e a especificação OpenAPI a partir do catálogo do servidor.


A API cobre o trabalho de uma empresa de água ou de outro serviço público: clientes, propriedades e contas, contadores e leituras, facturação, pagamentos, crédito pré-pago, operações de campo e mensagens. Está dividida em áreas, cada uma com o seu caminho base, a sua forma de autenticação e o seu público. Esta página mostra como descobrir essas áreas e escolher a certa.

## O que vai construir

Um cliente que não tem URLs escritos no código: lê o catálogo do servidor, guarda o URL base de cada área e encontra a especificação OpenAPI a partir dele.

## Pré-requisitos

- Um ambiente sandbox ou o endereço de uma instalação.
- `curl` e `jq`, ou a CLI `gotactl` instalada.
- Para o passo 3, uma chave de API secreta de teste com a permissão `business:customers:read`.

## 1. Ler o catálogo da API

O catálogo segue o RFC 9727 e está sempre em `/.well-known/api-catalog`. Não precisa de autenticação.

```bash
curl -sS "https://api.gota.umbeluzi.com/.well-known/api-catalog"
```

A resposta tem o tipo `application/linkset+json` e pode ficar em cache durante 300 segundos (`Cache-Control: public, max-age=300`):

```json
{
  "linkset": [
    {"anchor": "$AUTH_API", "title": "auth", "service-desc": [{"href": "https://api.gota.umbeluzi.com/api/openapi.json", "type": "application/openapi+json"}]},
    {"anchor": "$PUBLIC_API", "title": "public", "service-desc": [{"href": "https://api.gota.umbeluzi.com/api/openapi.json", "type": "application/openapi+json"}]},
    {"anchor": "$BUSINESS_API", "title": "business", "service-desc": [{"href": "https://api.gota.umbeluzi.com/api/openapi.json", "type": "application/openapi+json"}]},
    {"anchor": "$CONSUMER_API", "title": "consumer", "service-desc": [{"href": "https://api.gota.umbeluzi.com/api/openapi.json", "type": "application/openapi+json"}]},
    {"anchor": "$PLATFORM_API", "title": "platform", "service-desc": [{"href": "https://api.gota.umbeluzi.com/api/openapi.json", "type": "application/openapi+json"}]},
    {"anchor": "$PRIVATE_API", "title": "private", "service-desc": [{"href": "https://api.gota.umbeluzi.com/api/openapi.json", "type": "application/openapi+json"}]},
    {"anchor": "$CONNECTOR_API", "title": "connector", "service-desc": [{"href": "https://api.gota.umbeluzi.com/api/openapi.json", "type": "application/openapi+json"}]},
    {"anchor": "https://api.gota.umbeluzi.com/api/openapi.json", "title": "openapi"}
  ]
}
```

✓ Checkpoint: `linkset` tem uma entrada por área, com o nome em `title` e o URL base em `anchor`.

Os caminhos acima são os que o servidor usa por omissão. O operador pode montar cada área noutro caminho ou retirá-la, e o catálogo reflecte sempre o que está montado. Por isso, resolva os URLs pelo `title` e não os escreva no código.

## 2. Escolher a área

| Área (`title`) | Caminho por omissão | Quem chama |
| :--- | :--- | :--- |
| `business` | `$BUSINESS_API` | Sistemas da empresa: ERP, contabilidade, automações e o painel da equipa. |
| `consumer` | `$CONSUMER_API` | Aplicações e portais dos moradores, em nome do titular da conta. |
| `public` | `$PUBLIC_API` | Páginas sem sessão: marca, definições do cliente, estimativas e pedidos de serviço. |
| `connector` | `$CONNECTOR_API` | Conectores de pagamento e de mensagens. |
| `auth` | `$AUTH_API` | Registo, entrada e gestão da identidade. |
| `private` | `$PRIVATE_API` | Integrações externas: eventos e lotes de leituras de contadores, estado das integrações. |
| `platform` | `$PLATFORM_API` | Administração da instalação pelo operador. |

Para começar a integrar os sistemas da empresa, use `business` com uma chave de API (veja [Autenticação](/docs/getting-started/authentication)). Obtenha o URL base dessa área no catálogo, pelo `title`:

```bash
curl -sS "https://api.gota.umbeluzi.com/.well-known/api-catalog" | jq -r '.linkset[] | select(.title == "business") | .anchor'
```

✓ Checkpoint: o comando mostra um único URL, a base da área que o seu sistema vai chamar.

## 3. Fazer um pedido à área escolhida

```bash
curl -sS "$BUSINESS_API/customers?limit=1" \
  -H "Authorization: Bearer $API_KEY"
```

✓ Checkpoint: a resposta traz `data` com no máximo um cliente e o campo `has_more`.

## Testar

Siga o `href` de `service-desc` para obter a especificação OpenAPI em JSON, ou peça-a pela CLI, que também a encontra através do catálogo:

```bash
gotactl openapi
```

## Próximos passos

- [Do registo ao primeiro pedido no início rápido](/docs/getting-started/quickstart)
- [Escolher o método de autenticação certo](/docs/getting-started/authentication)
- [Criar e gerir chaves de API](/docs/getting-started/api-keys)
- [Consultar a referência da Business API](/docs/api/business)

