# Automatizar com a CLI

Escreva um processo nocturno que envia leituras de contadores a partir de um ficheiro CSV e exporta as facturas em aberto, com a chave pela entrada padrão, saída em JSON e decisões tomadas pelos códigos de saída da CLI.


## O que vai construir

Um script de shell para o cron ou para um agendamento de CI que faz duas coisas todas as noites: envia as leituras de contadores recolhidas durante o dia, um pedido por cada linha de um ficheiro CSV, e grava num ficheiro JSON as facturas em aberto da empresa, para outro sistema as recolher. O script nunca escreve a chave na linha de comandos, não repete à mão o que a CLI ou a API já tornam seguro e pára com uma mensagem útil quando algo corre mal.

## Pré-requisitos

- Uma sandbox e uma chave de teste restrita (prefixo `sk_rtest_`) com `business:readings:create`, `business:readings:read` e `invoices:read`, guardada nos segredos do processo como `API_KEY`.
- `gotactl` no `PATH` da máquina que corre o processo e `jq` para montar os corpos dos pedidos.
- Um ficheiro CSV com o cabeçalho `meter_id,value,measured_at`, em que `measured_at` é uma data e hora RFC 3339.

As opções globais usadas neste guia:

| Opção | Descrição |
| :--- | :--- |
| `--api-key-stdin` | Lê a chave de API da entrada padrão |
| `--json` | Saída em JSON, com uma lista opcional de campos separados por vírgulas |
| `--idempotency-key` | Valor do cabeçalho Idempotency-Key nos pedidos de escrita |

## 1. Passar a chave pela entrada padrão

```bash
printf '%s\n' "$API_KEY" | gotactl --api-key-stdin whoami --json mode
```

```json
{
  "mode": "sandbox"
}
```

✓ Checkpoint: `mode` vale `sandbox`. `--api-key-stdin` lê a primeira linha da entrada padrão e confirma o prefixo da chave antes de qualquer pedido sair da máquina, por isso um valor que não seja uma chave de API falha logo com o código de saída `2`. Como a chave ocupa a entrada padrão, os corpos dos pedidos deste script vão em ficheiros.

## 2. Enviar uma leitura por linha

O endpoint de leituras exige `meter_id`, `value` (um decimal escrito como texto), `unit`, `measured_at`, `client_reading_id` e `idempotency_key`. Se construir os dois identificadores a partir do contador e da hora, voltar a correr o mesmo ficheiro não tem efeitos.

```bash
jq -n --arg m "mtr_2pR5cK8wNd3XqL7vTb1MzH4yJf9" --arg v "1342.517" --arg t "2026-11-18T16:40:00Z" \
  '{meter_id:$m,value:$v,unit:"m3",measured_at:$t,client_reading_id:("nightly-"+$m+"-"+$t),idempotency_key:("nightly-"+$m+"-"+$t)}' > reading.json

printf '%s\n' "$API_KEY" | gotactl --api-key-stdin api POST business:/readings --input reading.json --json id,meter_id,status
```

```json
{
  "id": "rdg_2pR5dV1xQm6ZtB4nKc8WyL3hGa7",
  "meter_id": "mtr_2pR5cK8wNd3XqL7vTb1MzH4yJf9",
  "status": "submitted"
}
```

✓ Checkpoint: `status` vale `submitted`, ou `review_required` quando a verificação de plausibilidade pede que alguém confirme o valor. O mesmo `idempotency_key` com os mesmos dados devolve a leitura original; a mesma chave com dados diferentes é recusada com `409`. O contador tem de estar activo, `unit` tem de ser a unidade do próprio contador, e `measured_at` não pode ser anterior à instalação nem estar mais de 5 minutos no futuro.

## 3. Exportar as facturas em aberto

```bash
printf '%s\n' "$API_KEY" | gotactl --api-key-stdin invoices list --status open --all \
  --json id,invoice_number,account_id,amount_due_cents > open-invoices.json
```

✓ Checkpoint: `open-invoices.json` contém uma lista JSON com um objecto por factura e apenas os quatro campos pedidos. Em `invoices list`, `--all` (obter todas as páginas) segue `next_cursor` até `has_more` ser `false`, e `--status` (filtrar por estado) limita às facturas `open`; o ficheiro fica completo seja qual for o número de páginas.

## 4. Parar nos erros certos

```bash
set -u
tail -n +2 readings.csv | while IFS=, read -r meter value at; do
  jq -n --arg m "$meter" --arg v "$value" --arg t "$at" \
    '{meter_id:$m,value:$v,unit:"m3",measured_at:$t,client_reading_id:("nightly-"+$m+"-"+$t),idempotency_key:("nightly-"+$m+"-"+$t)}' > reading.json
  printf '%s\n' "$API_KEY" | gotactl --api-key-stdin api POST business:/readings --input reading.json --json id,status
  code=$?
  case $code in
    0) ;;
    3) echo "acesso recusado: chave revogada, scope em falta ou contador inactivo ($meter)" >&2; exit 3 ;;
    5|6) echo "API ocupada ou inacessível: volte a correr o processo, as chaves de idempotência tornam-no seguro" >&2; exit "$code" ;;
    *) echo "linha recusada: $meter em $at" >&2 ;;
  esac
done
```

✓ Checkpoint: uma linha recusada fica registada e o ciclo continua; uma resposta `401` ou `403` (código de saída `3`) ou uma API inacessível termina o processo. A API responde `403` tanto a uma chave sem o scope como a um contador que não está activo, por isso a mensagem indica o contador. Uma resposta `5xx` também sai com o código `6`. A CLI já espera nas respostas `429` segundo o `Retry-After` e desiste com o código `5` à terceira tentativa. Cada erro é escrito na saída de erro com o título, o detalhe e o `request_id` do problema.

## Testar

Corra o script contra a sandbox e confira o resultado com `gotactl readings list --meter-id mtr_2pR5cK8wNd3XqL7vTb1MzH4yJf9 --json id,value,status`, em que `--meter-id` filtra pelo identificador do contador. Cada pedido feito com a chave aparece no painel em **Programadores** > **Registos**. Nos comandos de escrita sem campo de idempotência no corpo, a opção global `--idempotency-key` envia o cabeçalho `Idempotency-Key`.

## Próximos passos

- [Todos os comandos da CLI e as respectivas opções](/docs/cli/reference)
- [Limitar a chave do processo aos scopes que usa](/docs/getting-started/restricted-keys)
- [O que o endpoint de leituras verifica antes de aceitar um valor](/docs/guides/record-readings)

