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_) combusiness:readings:create,business:readings:readeinvoices:read, guardada nos segredos do processo comoAPI_KEY. gotactlnoPATHda máquina que corre o processo ejqpara montar os corpos dos pedidos.- Um ficheiro CSV com o cabeçalho
meter_id,value,measured_at, em quemeasured_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#
printf '%s\n' "$API_KEY" | gotactl --api-key-stdin whoami --json mode
{
"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.
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
{
"id": "rdg_2pR5dV1xQm6ZtB4nKc8WyL3hGa7",
"meter_id": "mtr_2pR5cK8wNd3XqL7vTb1MzH4yJf9",
"status": "submitted"
}
3. Exportar as facturas em aberto#
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#
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.