Guia

Versionamento

A versão está no caminho — /v1/ no REST, /odata/v1/ no OData. Enquanto ela for v1, o que já funciona continua funcionando.

O que pode mudar sem aviso

Estas mudanças são aditivas: nada que você já lê muda de lugar, de tipo ou de significado.

Coleções novas na lista do serviço.
Campos novos em coleções existentes.
Valores novos em campos de texto — uma cultura nova, um status novo.
Melhorias de desempenho e de mensagem de erro (o error muda; o code, não).

Escreva um leitor tolerante

Campo novo é a mudança mais frequente, e é a que mais quebra integração mal escrita. Leia os campos que você conhece pelo nome e ignore os demais — não itere sobre tudo o que vier assumindo um formato fixo.

Python

# Errado: quebra quando a coleção ganha um campo novo
for campo in linha:
    grava(campo)

# Certo: leia o que você conhece, ignore o resto
grava(linha["id"], linha["date"], linha["grossWeightKg"])

O que conta como quebra

Nada disto acontece dentro da v1:

Remover ou renomear uma coleção ou um campo.
Mudar o tipo de um campo — número que vira texto, data que vira carimbo.
Mudar o significado ou a granularidade de um campo existente. Uma medida que passa a somar outra coisa é quebra ainda que o tipo continue igual — e é a pior delas, porque não estoura erro nenhum: só muda o número do seu relatório.
Passar a exigir um filtro que antes era opcional, ou apertar um limite de paginação.
Remover um escopo ou mudar o que ele libera.

Quando precisar quebrar

Sai uma v2 num caminho novo, e a v1 continua servindo por 90 dias depois do anúncio. As duas rodam lado a lado nesse período: você migra quando der, não no dia do lançamento.

O anúncio sai em Configurações → Integrações, no AGROs — a mesma tela onde os tokens são criados, e por isso a que quem integra já acompanha.

O contrato executável

No OData, quem descreve as coleções, os campos e os tipos é o $metadata. Ele é gerado do mesmo contrato que gera esta documentação, então nunca discorda dela:

curl

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

Vale diferenciar: o $metadata descreve o estado de hoje — e traz só as coleções que os escopos do seu token alcançam. É o que o Power BI lê para montar o modelo sozinho. Esta página é sobre o que pode mudar amanhã; as duas coisas se complementam.