Uma API para tudo o que vê no painel.
Chaves de API em qualquer contexto, webhooks assinados e um CLI.
API
Integre os seus sistemas com uma API clara. A API REST está descrita num documento OpenAPI e a referência no painel mostra os parâmetros e as respostas de cada operação. As chaves são criadas em Programadores, Chaves de API: uma chave secreta herda as permissões de quem a cria, uma chave restrita leva só os scopes que escolher, e o prefixo indica se é de teste ou de produção. O fluxo habitual é começar no sandbox com uma chave de teste, que é recusada num tenant live, e trocar para uma chave live sem mudar o código.
- Chaves com limitesDefina scopes, data de expiração e uma lista de IPs ou CIDR a partir dos quais a chave é aceite.
- Rotação sem corteAo rodar uma chave, a anterior continua válida durante um período de sobreposição que escolhe, até um máximo de sete dias.
- Idempotency-KeyUm POST repetido com a mesma chave nas 24 horas seguintes devolve a resposta guardada, e um corpo diferente com a mesma chave recebe 409.
- Request-Id e erros problem+jsonCada resposta traz um Request-Id, e os erros chegam em problem+json com um error_code documentado.
- Limite por chaveOs cabeçalhos RateLimit-Limit, RateLimit-Remaining e RateLimit-Reset mostram o orçamento restante, e um orçamento esgotado responde 429 com Retry-After.
- Registo de pedidosNo painel, filtre os pedidos por método, caminho, chave ou Request-Id, com campos sensíveis removidos antes de serem guardados.
Documentação: API
Webhooks
Reaja a cada evento em tempo real. Registe um URL HTTPS, escolha os tipos de evento (facturas, pagamentos, leituras, contadores, ligações, ordens de trabalho, cobranças e outros) ou subscreva todos, e guarde o segredo whsec_, que só é mostrado uma vez. Cada aviso segue o formato Standard Webhooks, com os cabeçalhos webhook-id, webhook-timestamp e webhook-signature calculados por HMAC-SHA256. Endereços privados ou internos são recusados quando o URL é guardado e outra vez no momento da ligação.
- Reenvios com espera crescenteUma resposta fora de 2xx ou uma falha de ligação agenda nova tentativa, com intervalos cada vez maiores, durante até 72 horas.
- Saúde do endpointUm endpoint que falha durante 72 horas, ou que responde 410 Gone, é pausado e as entregas ficam guardadas até o retomar.
- Segredo rodado com sobreposiçãoDurante a janela de rotação, cada aviso leva duas assinaturas, uma por segredo, para trocar o segredo sem perder entregas.
- Reenvio de um períodoVolte a pôr na fila as entregas falhadas de uma janela até sete dias, enviadas por ordem para cada registo, com contagem prévia.
- Histórico de cada entregaVeja a carga útil, o código HTTP, o corpo da resposta e a próxima tentativa, e reenvie uma entrega isolada.
- Evento de testeEnvie um evento webhook.test a partir do painel para confirmar que o seu receptor verifica a assinatura.
Documentação: Webhooks
CLI
Automatize operações e testes no terminal. A CLI entra por device grant, mostrando um código e um QR no terminal, o que funciona por SSH e em contentores sem navegador; também aceita login no navegador com PKCE ou uma chave de API lida do ambiente ou de stdin, nunca de um argumento. Lista e consulta clientes, contas, facturas, pagamentos e leituras, submete leituras, gere chaves de API e alterna entre contextos. Num sandbox, dispara eventos reais e encaminha-os para um servidor local.
- Saída JSON para scriptsCom --json obtém JSON em stdout, com os campos que indicar, e códigos de saída distintos para falta de sessão, recurso inexistente ou limite de pedidos.
- Webhooks em localhostO comando webhooks listen encaminha eventos do sandbox para um URL local, assinados com um segredo temporário, e recusa um contexto live sem confirmação explícita.
- Disparo de eventosO comando events trigger cria no sandbox um cliente, uma conta, uma factura emitida ou paga, um pagamento ou uma leitura, e o evento correspondente.
- Avançar o sandboxO comando sandbox advance confirma, falha ou expira pagamentos simulados pendentes e pode gerar um novo ciclo de leituras.
- Pedidos directos à APIO comando api envia um pedido a qualquer caminho descoberto pelo catálogo da API, com campos, cabeçalhos e paginação por cursor.
- Segredos protegidosCredenciais ficam no keychain do sistema, ou num ficheiro com permissões 0600, e um ficheiro de configuração legível por outros é recusado.
Documentação: CLI
O CLI
Inicie sessão com um código no painel, sem colar chaves no terminal, e use as mesmas APIs a partir da linha de comandos.
$ gotactl auth login Abra o painel e confirme o código ✓ Sessão iniciada
# O endereço da API vem do catálogo: # https://api.gota.umbeluzi.com/.well-known/api-catalog $ curl -H "Authorization: Bearer sk_test_••••1a2b" \ "https://api.gota.umbeluzi.com/…/customers"