PT EN

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

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

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

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

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#