Automação & JSON

A CLI foi feita para scripts e CI: saída JSON estável, erros no stderr e códigos de saída por categoria — para você ramificar no código de saída, nunca no texto da mensagem.

Saída JSON

Sem --json, a saída é uma tabela/legível para humanos. Com --json, o comando imprime o corpo cru da resposta no stdout — pronto para o jq:

# id da última transação aprovada
selectwin transactions list --limit 1 --json | jq -r '.data[0].id'

# criar um cliente e capturar o id
CUS=$(selectwin customers create -d '{"firstName":"Ana","lastName":"Lima","email":"[email protected]"}' --json | jq -r '.id')
echo "criado $CUS"

Códigos de saída

Erros vão para o stderr e o processo sai com um código mapeado pelo status HTTP. Ramifique por ele:

if selectwin get /v1/transactions/tra_123 --json > tx.json; then
  echo "ok"
else
  case $? in
    12) echo "transação não existe" ;;
    16) echo "rate limited — tente mais tarde" ;;
    *)  echo "falhou (código $?)" ; exit 1 ;;
  esac
fi

Chave por ambiente

Não há flag --live/--sandbox — o ambiente vem do prefixo da chave (sk_test_… = sandbox, sk_live_… = produção). Em CI, injete a chave por variável de ambiente ou flag:

export SELECTWIN_API_KEY=sk_live_…      # $SELECTWIN_API_KEY tem precedência sobre o perfil
selectwin whoami --json
# ou por chamada:
selectwin get /v1/customers --api-key sk_test_… --json

A precedência da chave é: --api-key › $SELECTWIN_API_KEY › perfil ativo.

Idempotência em retries

Para tornar um retry de mutação seguro (não duplicar), passe sua própria chave no escape hatch:

selectwin post /v1/transactions -d @payload.json --idempotency-key "$(uuidgen)"

Próximos passos

• Receitas — os comandos do dia a dia.
• Idempotência · Tratamento de erros.