Documentação para desenvolvedores

A API do Segesio ERP permite ler e escrever os dados da sua conta — atividades, despesas, insumos, colheitas e os demais módulos operacionais — a partir dos seus próprios sistemas, sem passar pela interface web.

Não é uma API espelho nem uma simulação: uma chave de API com escopo de escrita chama exatamente os mesmos endpoints que o aplicativo web usa, autenticada com a identidade de um usuário real da sua conta. É um recurso do plano Enterprise.

Cada requisição leva a chave de API no cabeçalho X-API-Key. Não há login nem token que expire em minutos — a chave é válida até a data de expiração atribuída a ela.

A chave completa é exibida apenas uma vez, no momento em que é criada. Guarde-a em um lugar seguro (um gerenciador de segredos, não um repositório de código) — se você a perder, será preciso gerar uma nova.

Um usuário com papel de administrador pode criar chaves em Configurações → Chaves de API, dentro do aplicativo.

1. Escolha um nome descritivo (por exemplo, o sistema que vai usá-la).
2. Selecione os escopos necessários — nunca marque mais do que essa integração realmente vai usar.
3. Se algum escopo for de escrita, escolha qual pessoa da sua equipe essa chave representa: as escritas rodam com a identidade e as permissões reais dessa pessoa.
4. Defina um vencimento (há um valor padrão caso você não escolha um) e confirme.

A chave completa aparece uma única vez na tela, logo após a criação. Copie-a antes de fechar essa tela.

Cada escopo segue o mesmo formato usado no resto do sistema: módulo:ação. Uma chave nunca pode fazer mais do que o usuário ao qual está vinculada poderia fazer manualmente na interface.

A ação excluir nunca está disponível para nenhuma chave, em nenhum módulo — para excluir algo, use a interface normal.

O acesso de leitura já está incluído no plano Enterprise. O acesso de escrita é uma habilitação separada, ativada pela nossa equipe sob pedido — fale conosco (veja Suporte, abaixo) para ativá-la na sua conta.

Todos os endpoints usam o mesmo prefixo da API real do Segesio ERP. Um exemplo, criando uma atividade:

Quando a chave tem um escopo de escrita, a atividade criada fica atribuída ao usuário real ao qual a chave está vinculada — o mesmo valor que ficaria se essa pessoa a tivesse cadastrado pela web.

Respostas bem-sucedidas retornam o recurso criado ou solicitado em JSON. Um erro — permissão ausente, dado inválido, chave vencida — retorna um código HTTP correspondente e um corpo neste formato:

Este é o formato que o framework usa por padrão na maioria dos endpoints. Ainda não está 100% padronizado em todos os casos — avisamos isso para que sua integração não dependa de uma estrutura exata além de statusCode/message.

• Rate limiting por chave (não por endereço IP): uma chave compartilha os mesmos limites do tráfego normal do aplicativo, agrupados pela própria chave em vez de por IP.
• Toda chave tem vencimento obrigatório — 90 dias por padrão se tiver algum escopo de escrita, 180 dias se for somente leitura. É possível escolher um valor diferente ao criá-la.
• Até 30 escopos por chave.

Se você só precisa ler alguns poucos dados — fazendas, talhões, NDVI, colheitas, clima — sem escrever nada, existe uma API mais simples e estável pensada para isso, com estes escopos:

• fincas:read
• lotes:read
• ndvi:read
• harvest:read
• weather:read

É um contrato menor e mais estável, útil para integrações simples. Não substitui o catálogo completo acima, que permite escrever de fato.

• A maioria dos endpoints de listagem retorna o resultado completo, sem paginação — para volumes grandes, filtre usando os parâmetros que cada endpoint aceita.
• Ainda não há webhooks de saída: sua integração precisa consultar (polling), não há como o Segesio avisar você sobre uma mudança.
• O formato de erro não está 100% padronizado em todos os endpoints — veja a nota em Formato de resposta e erros.
• Não há rotação de chaves sem recriá-las: para rotacionar uma chave, crie uma nova e revogue a anterior.

Precisa que a gente habilite escrita na sua conta, ou tem uma dúvida pontual sobre algum endpoint? Fale com a gente.