Guia

Autenticação

O acesso é por token de integração — uma credencial que pertence ao sistema que consome, não a uma pessoa. Você o cria no AGROs e o envia em cada requisição; não existe tela de login na API.

Criar o token

1. No AGROs, abra Configurações → Integrações. É uma área administrativa: quem não administra a organização não vê a tela, e é isso que impede um token de nascer sem dono.
2. Em Tokens de API, clique em criar.
3. Dê um nome que identifique o uso (Power BI — financeiro é melhor que token1: é o que aparece na auditoria).
4. Escolha os escopos. Veja abaixo.

Escopos

Cada coleção exige um escopo. Dê ao token só o que ele precisa — um token de painel de safra não deveria abrir o contas a pagar.

A organização só pode liberar o que licencia: pedir um escopo de um módulo não contratado devolve 403 ScopeExceedsEntitlement já na criação do token.

Usar o token

Envie no cabeçalho Authorization, com o prefixo Bearer. O token começa com oag_.

curl -H "Authorization: Bearer oag_SEU_TOKEN" \
  "https://service.agrosti.com.br/odata/v1/"

Essa é a raiz do serviço OData: devolve a lista de coleções disponíveis para os escopos do seu token. Se ela responder, está tudo certo.

Limites e segurança

• Expiração. Opcional na criação. Recomendada para tokens de terceiros.
• Lista de IPs. Opcional. Restringe de onde o token funciona — útil quando o consumidor tem IP fixo (um gateway de BI, por exemplo).
• Limite de requisições. Por token, por minuto, no valor que você escolher na criação — até o teto de 60 da superfície aberta. Ao estourar, a API responde 429; espere a virada do minuto e repita. Detalhes em Erros.
• Auditoria. Todo acesso fica registrado com o token que o fez. Por isso o nome importa.
• Revogação. Imediata: a próxima requisição já recebe 401.
• Quantos tokens. Até 50 ativos por organização. Se atingir o teto, revogue um que não usa antes de criar outro — a criação responde 409.

Erros comuns

Com o token na mão, siga para conectar o Power BI.