PT EN

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"}
  ]
}

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). 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'

3. Fazer um pedido à área escolhida#

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

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#