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

No AGROs, abraConfiguraçõ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.
Em Tokens de API, clique em criar.
Dê um nome que identifique o uso (Power BI — financeiro é melhor que token1: é o que aparece na auditoria).
Escolha os escopos. Veja abaixo.

O token aparece uma única vez

Guarde na hora, num cofre de senhas. Não temos como mostrá-lo de novo — guardamos apenas um hash. Se perder, revogue e crie outro.

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.

Escopo	Dá acesso a
`agriculture.read`	Apontamentos, colheita, território, pragas, clima, pesagens
`finance.read`	Contas a pagar e receber, vendas, lançamentos, centros de custo
`livestock.read`	Pecuária e cadastro de animais

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 prefixoBearer. O token começa com oag_.

curl

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.

Ferramentas de BI que não têm campo de token são aceitas nos formatos que elas sabem mandar, com o mesmo token: autenticação Básica com o token na senha (é o caminho do Power BI) ou o valor cru em Authorization, sem esquema. Em código, use sempre Bearer.

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 240 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á recebe401.
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 responde409.

Erros comuns

Código	Significa
`401`	Token ausente, inválido, revogado ou expirado
`403`	O token não tem o escopo daquela coleção
`403 OpenAGROsNotLicensed`	A organização não tem o OpenAGROs contratado
`429`	Limite de requisições por minuto estourado

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