Developer APIVisão geral
Developer API
Integre com a AGGU sem transformar cada conexão em um projeto improvisado.
A Developer API foi especificada para expor capacidades da plataforma com autenticação, escopos, idempotência, webhooks, limites e rastreabilidade. A disponibilidade de endpoints depende do ambiente e das capacidades liberadas.
Autenticação
Toda chamada identifica quem está chamando. O tipo de credencial depende de quem age na integração.
- OAuth, quando aplicável. Uma aplicação age em nome de uma pessoa, com o consentimento dela e as permissões dela.
- Service principals. Uma integração de servidor age em nome da organização, sem uma pessoa na ponta.
- Chaves e credenciais. Ficam no seu servidor. Nunca no navegador, em aplicativos distribuídos ou em repositórios.
- Escopos. Cada credencial recebe só os escopos de que precisa.
OAuthUma pessoaAplicações que acessam dados em nome do usuárioService principalA organizaçãoIntegrações entre servidoresNenhuma credencial nesta página é real. Valores como <token> são marcadores. Nunca publique tokens ou chaves.
Escopos
Escopos seguem o formato recurso:ação. Uma chamada fora do escopo da credencial é recusada, mesmo que o endpoint exista.
Exemplo ilustrativo — endpoint final conforme documentação da API. Escopos também são ilustrativos.
Ative escopos na credencial
- GET
/v1/clients - GET
/v1/documents - GET
/v1/requests - POST
/v1/requests
Requisições
Uma requisição carrega o que a plataforma precisa para decidir e registrar:
- 1Método e caminho versionado.
- 2Credencial no cabeçalho
Authorization. - 3Chave de idempotência em operações de criação.
- 4Corpo em JSON.
1POST /v1/example HTTP/1.1
Host: <host-da-api>
2Authorization: Bearer <token>
3Idempotency-Key: <uuid-gerado-pelo-cliente>
Content-Type: application/json
4{
"client_id": "cli_exemplo",
"title": "Extrato bancário de setembro"
}exemplo ilustrativo — endpoint final conforme documentação da API
Idempotência
Redes falham. Às vezes a requisição chega, mas a resposta se perde, e o seu sistema não sabe se deve tentar de novo.
Com uma Idempotency-Key, repetir o mesmo POST devolve o mesmo resultado em vez de criar outro registro. É o que torna seguro repetir operações críticas.
Compare as duas tentativas
- Seu sistema
POST /v1/exampleIdempotency-Key: <a1> - API201 · registro criadoreq_exemplo_1
- RedeA resposta se perdeO seu sistema não sabe se funcionou
- Seu sistema
POST /v1/exampleIdempotency-Key: <a1> · mesma chave - API201 · mesma respostareq_exemplo_1 · nada foi duplicado
Exemplo ilustrativo — endpoint final conforme documentação da API.
Webhooks
Quando um evento acontece, a AGGU envia um POST para a URL cadastrada. Cada entrega é assinada, tem status e é repetida com espera crescente quando falha.
- Verifique a assinatura antes de processar o evento.
- Responda rápido com 2xx e processe depois.
- Trate repetições: o mesmo evento pode chegar mais de uma vez; use o
id.
POST <sua-url-de-destino>
Content-Type: application/json
<cabeçalho-de-assinatura>: <assinatura>
{
"id": "evt_exemplo_001",
"type": "request.completed",
"created_at": "2026-10-06T10:42:03Z",
"data": { "request_id": "req_exemplo_184" }
}exemplo ilustrativo — endpoint final conforme documentação da API
Limites de uso
Cada credencial tem limites de volume para proteger a plataforma e as outras integrações. Os valores dependem do ambiente.
Ao passar do limite, a API responde 429 e indica quanto esperar. Respeite essa indicação e use espera crescente entre novas tentativas, em vez de repetir imediatamente.
Espera crescente
Tentativas · cada espera maior que a anterior
HTTP/1.1 429 Too Many Requests
Retry-After: <segundos>exemplo ilustrativo — endpoint final conforme documentação da API
Erros
Todo erro segue a mesma estrutura, para que o seu sistema trate falhas de um jeito só.
code- Identificador estável, para o seu código decidir o que fazer.
message- Explicação legível, para pessoas.
correlation_id- Liga a falha ao registro do lado da AGGU. Guarde nos seus logs.
{
"error": {
"code": "insufficient_scope",
"message": "A credencial não tem o escopo requests:write.",
"correlation_id": "corr_exemplo_7f3a"
}
}exemplo ilustrativo — endpoint final conforme documentação da API
Auditoria
Cada chamada fica registrada com quem fez, com qual escopo, quando e qual foi o resultado.
req_exemplo_9a1Integração ERP · service principalclients:read06/10 10:41:58200req_exemplo_9a2Integração ERP · service principalrequests:write06/10 10:42:03201req_exemplo_9a3Ana · via OAuthdocuments:read06/10 10:44:17200req_exemplo_9a4Painel BI · service principalrequests:write06/10 10:45:30403Dados ilustrativos
Segurança
Uma integração é tão segura quanto o lugar onde a credencial fica guardada.
- Segredos só no servidor. Nunca no navegador, em apps distribuídos ou em repositórios.
- Menor escopo possível. Uma credencial por integração, com só o que ela usa.
- Troque credenciais quando alguém sai do projeto ou houver suspeita de vazamento.
- Verifique a assinatura de todo webhook antes de confiar no conteúdo.
- Guarde o correlation id para rastrear qualquer falha com a AGGU.
Exemplos
A mesma chamada em três linguagens. São trechos conceituais para mostrar o formato, não um SDK nem um contrato final.
Credenciais vêm de variáveis de ambiente, nunca do código.
Escolha a linguagem
exemplo ilustrativo — endpoint final conforme documentação da API
OpenAPI
A documentação de referência e o contrato OpenAPI serão disponibilizados conforme ambiente.
Até lá, endpoints, escopos e trechos desta página são exemplos para mostrar o formato da API.