API Zarc NM (SiNM)

O SiNM foi desenvolvido com o propósito de receber dados relacionados à glebas (ou talhões) produtivas e a partir dos dados recebidos, classificar a gleba de acordo com o seu nível de manejo, seguindo a metodologia de classificação publicada em 2022 pela Embrapa com o título "Níveis de manejo do solo para avaliação de riscos climáticos na cultura da soja." (DEBIASI, H.; MONTEIRO, J. E. B. de A.; FRANCHINI, J. C.; FARIAS, J. R. B.; CONTE, O.; CUNHA, G. R. da; MORAES, M. T. de; BALBINOT JUNIOR, A. A.; SILVA, F. A. M. da; EVANGELISTA, B. A.; MARAFON, A. C.).

Requisitos

Os principais requisitos que guiaram a construção da API são listados abaixo:

1. Aplicar todas as regras de cálculo da classificação de nível de manejo (níveis de 1 a 4) de forma flexível para que as regras possam ser alteradas de maneira simples, assim como novas regras possam ser incorporadas e/ou removidas.
2. As regras de cálculo precisam ser versionadas para que haja rastreabilidade entre classificações já realizadas e regras/parâmetros aplicados.
3. Os dados das glebas precisam ser geolocalizados, para que se possa criar mecanismos de verificação via monitoramento por imagens de satélite/drone.
4. Tanto os dados das glebas enviados para a API, quanto os dados de classif icação gerados pela aplicação das regras precisam ser armazenados em banco de dados para posterior consulta e auditoria.
5. Permitir que parceiros possam enviar dados automaticamente via sistemas/máquinas.
6. Os dados da gleba relacionados às características da gleba (propriedade, localização) ao histórico de cultivo (diversidade de culturas ao longo do tempo) e de operações de manejo realizadas serão enviados em um endpoint específico com permissão a um perfil de usuário (Operador de Contratos).
7. Os dados da gleba relacionados à análise de amostras de solo (variáveis químico, físico e orgânicas do solo) serão enviadas em um endpoint específico com permissão a um perfil de usuário (Operador de Análise de Solo).
8. Os dados da gleba relacionados ao sensoriamento remoto, tais como índices vegetativos, interpretação de culturas e datas de operações serão enviadas em um endpoint específico com permissão a um perfil de usuário (Operador de Sensoriamento Remoto).
9. O score final relacionado à classificação de nível de manejo de uma gleba será dado por um conjunto de regras definidas.
10. As consultas ao resultado de uma classificação de nível de manejo para uma gleba retornarão apenas o score final de classificação da gleba.

Principais atores interessados:

Arquitetura

Visão geral do SiNM:

Visão Arquitetural do SiNM:

Autorização e Níveis de Acesso

Autorização no SiNM — Guia para Clientes e Integradores.

Homologação de integradores

Parceiro novo? Veja o Guia de Homologação — do formulário de credenciamento ao fluxo de teste ponta a ponta no ambiente de homologação (hml).

Acesso ao ambiente de produção

Produção é para dados reais e só para operadores credenciados. O credenciamento exige dois documentos: o Formulário de Credenciamento e os Termos de Uso e de Responsabilidades assinados digitalmente via gov.br. Se este é seu primeiro contato com o SiNM, prefira a homologação antes.

Requisitos, documentos e resumo dos Termos: Acesso ao Ambiente de Produção.

Funcionamento

Para a utilização do SiNM, primeiramente é necessário autenticar-se com usuário com credencias válidas e assim obter um token de acesso. Em posse do token de acesso e dentro de seu período de validade, as APIs podem ser acessadas. Abaixo, vamos ilustrar como se dá a autenticação e posteriormente o uso das APIs. Depois, na seção "Como usar?", temos um passo a passo de autenticação e uso de cada endpoint, com exemplos de requisição e remissões à Documentação Swagger e ao Dicionário de Dados.

1. Autenticação

Envio das credenciais de acesso

Obtendo o token de acesso após validação das credencias

Enviando uma requisição ao SiNM

Verificando a autenticidade e valdidade do token de acesso

Resposta da requisição enviada pela aplicação cliente

2. Envio de dados de identificação da gleba, histórico de cultivos e operaçõe de manejo

3. Envio de dados de amostras de solo

4. Envio de dados de sensoriamento remoto (visão geral)

5. Consulta à classificação final de nível de manejo

Versões da API: v1 e v2

Análise de solo e sensoriamento remoto existem em duas versões, com exatamente a mesma semântica, as mesmas regras de negócio e a mesma autorização. O que muda é só a forma do payload: o v2 abandonou nomes de campo que ficaram confusos ao longo do tempo.

ℹ️ A /api/v2 está disponível em Homologação desde 04/08/2026 e vai para produção na entrega seguinte — Cf. Informativo v6.2026. O /api/v1 continua no ar sem alteração.

Você não precisa executar nada agora. O /api/v1 está congelado, não tem data de desligamento, e a remoção dos nomes legados que havia sido anunciada para a virada de safra foi cancelada (Cf. Mudanças Obrigatórias). O quando migrar é escolha sua.

📌 Mas planeje-se. Congelado significa que o v1 não recebe mais evolução de contrato — só o v2 recebe — e que ele será depreciado num futuro próximo. A migração para o /api/v2 vai ser necessária em algum momento; trate a troca de rota e dos nomes de campo como item de backlog de um próximo release, não como algo indefinido. O desligamento não é automático: ele só acontece quando o uso residual for praticamente nulo e é comunicado à parte, com antecedência, em Mudanças Obrigatórias.

⚠️ Se decidir migrar. Enviar um nome antigo para o v2 não devolve erro — a chave é ignorada e o valor descartado em silêncio, como qualquer campo desconhecido. Não conte com um 400 para descobrir que esqueceu de trocar um campo: migre a rota e os nomes de campo juntos, ou permaneça no v1. No Swagger, as seções terminadas em (v1) e (v2) separam as duas versões.

¹ O nó laboratorio continua aceito no v1, sem prazo — a descontinuação anunciada para 29/08/2026 foi cancelada no v1. No v2 ele não existe e o cnpjLaboratorio é obrigatório (a falta dele devolve 400) — Cf. Mudanças Obrigatórias.

Os demais recursos (gleba/talhão, classificação, culturas, satélites) existem só no v1: eles não sofreram nenhuma alteração de contrato, e por isso não precisaram de uma versão nova.

Como usar?

📌 Coleção Postman descontinuada (jul/2026). A coleção Postman que era distribuída nesta wiki foi descontinuada e os arquivos foram removidos. Para explorar e testar os endpoints, use a Documentação Swagger de cada ambiente (botão Authorize para autenticar) e o Dicionário de Dados para o significado de cada campo. O passo a passo abaixo mostra como autenticar e usar a API com qualquer cliente HTTP.

1. Autenticação de usuário

Para ter acesso ao SiNM o usuário precisa estar autenticado. A autenticação é realizada via protocolo OpenId Connect (OIDC) usando o fluxo Password Credentials da especificação OAuth2: a aplicação cliente troca as credenciais da empresa e do usuário por um token de acesso no Keycloak e envia esse token em cada requisição ao SiNM.

O endpoint de obtenção de token de cada ambiente é:

Exemplo de requisição de token (ambiente de homologação), com qualquer cliente HTTP — aqui, curl:

curl -X POST 'https://www.keycloak.cnptia.embrapa.br/realms/zarcnm-h/protocol/openid-connect/token' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'grant_type=password' \
  -d 'client_id=<CNPJ da empresa, somente dígitos>' \
  -d 'client_secret=<Client Secret da empresa>' \
  -d 'username=<e-mail do usuário>' \
  -d 'password=<senha do usuário no Keycloak>'

A resposta traz o campo access_token (um JWT) e o campo expires_in (validade em segundos). Enquanto o token estiver válido, envie-o em toda requisição ao SiNM no cabeçalho HTTP Authorization: Bearer <access_token>. Quando expirar, basta repetir a requisição de token.

Para testar os endpoints diretamente pelo navegador, abra a Documentação Swagger do ambiente desejado, clique no botão Authorize e informe as mesmas credenciais (Client ID, Client Secret, Username e Password) — a partir daí, o botão Try it out de cada endpoint já envia as requisições autenticadas.

Em caso de problemas com senha, Client Secret ou cadastro, consulte Ajuda — Problemas de Autenticação. Os perfis de acesso (papéis) exigidos por cada endpoint estão descritos em Autorização no SiNM.

2. Envio de dados da gleba/talhão

Dados da gleba/talhão (propriedade, glebas, culturas e manejos). Essas informações são necessárias para dar início ao processo de classificação da gleba/talhão, para a qual se deseja obter o nível de manejo. Após realizar o processo de autenticação descrito na Subseção Autenticação de usuário, o envio é feito com o perfil Operador de Contratos por:

POST /api/v1/glebas

A estrutura completa do corpo da requisição (e exemplos prontos) está na Documentação Swagger; o significado de cada campo está no Dicionário de Dados. Neste payload, o CNPJ da propriedade é informado no campo propriedade.cnpj.

Se todas as informações enviadas no cabeçalho e no corpo da requisição estiverem corretas, o SiNM retorna o código 201 Created - HTTP Status informando que o recurso foi criado com sucesso. No corpo da resposta são retornados os dados que foram enviados na requisição e uma chave nomeada de chave da classificação de nível de manejo - chaveClassificacaoNM — que deverá ser guardada. Esta chave será a identificação usada para envio posterior dos dados de análise de solo, de sensoriamento remoto e de consulta ao nível de manejo calculado.

3. Envio de dados de análise de solo

Dados de análise de solo (do conjunto de amostras de solo). Essas informações são necessárias para dar continuidade no processo de classificação após cadastro da(s) gleba(s). Para enviar estes dados, o usuário deve estar autenticado (Cf. Subseção Autenticação de usuário) com o perfil Operador de Análise de Solo e precisa ter a chave chaveClassificacaoNM gerada com o cadastro da gleba na etapa anterior.

Desde a entrega v4.2026, a análise de solo é tratada como duas análises independentes — uma química e uma física (em produção a partir de 18/07, Cf. Informativo v5.2026). Os endpoints recomendados para novas integrações são os endpoints por tipo:

POST /api/v1/analises-solo/quimica/{chaveClassificacaoNM}
POST /api/v1/analises-solo/fisica/{chaveClassificacaoNM}

Cada tipo também oferece GET (consulta por uuid e listagem) e PUT (atualização por uuid). O envio combinado POST /api/v1/analises-solo/{chaveClassificacaoNM} (com amostrasQuimicas e amostrasFisicas no mesmo corpo) segue aceito por compatibilidade e cria as duas metades automaticamente, mas está descontinuado (deprecated) junto com a listagem combinada GET /api/v1/analises-solo — prefira os endpoints por tipo.

Campos importantes do payload:

• cnpjPropriedade — nome canônico do CNPJ da propriedade. O nome legado cnpj segue aceito no /api/v1, sem data de remoção — a remoção que havia sido anunciada foi cancelada (Cf. Mudanças Obrigatórias). Quem quiser o payload já limpo pode usar o /api/v2.
• cnpjLaboratorio — vínculo recomendado com o laboratório responsável, no nível da análise (o nó estruturado laboratorio está em descontinuação — Cf. Informativo v4.2026).
• amostrasQuimicas[].camada / amostrasFisicas[].camada — códigos de profundidade (Cf. Códigos de camada).

A estrutura completa dos corpos de requisição está na Documentação Swagger e o significado de cada campo no Dicionário de Dados. Se todas as informações estiverem corretas, o SiNM retorna o código 201 Created - HTTP Status com os dados enviados no corpo da resposta.

Novidade v5.2026 (em homologação a partir de 18/07, em produção a partir de 04/08): antes de solicitar uma nova análise, é possível descobrir se o produtor já tem análises válidas — sem expor o conteúdo delas — com GET /api/v1/analises-solo/disponiveis?cpf={cpf}&dataReferencia={yyyy-MM-dd} (Cf. Informativo v5.2026).

Cada item traz também o uuidAnaliseSolo — campo acrescentado depois da entrada em homologação, que vai para produção junto com o endpoint em 04/08. Com ele, dá para consultar a análise em GET /api/v1/analises-solo/quimica/{uuid} ou /fisica/{uuid}, conforme a lista de onde o item veio. O uuid identifica, não autoriza: a consulta segue exigindo as mesmas permissões de sempre (Cf. Informativo v6.2026 e Dicionário de Dados).

4. Envio de dados de sensoriamento remoto

Dados de sensoriamento remoto relacionados à gleba/talhão para a qual foi solicitada uma classificação de nível de manejo. Os dados de geoprocessamento serão necessários para validar as informações fornecidas pelo agente do contrato no processo de classificação das glebas/talhões. Para realizar o envio desses dados, o usuário deve estar autenticado (Cf. Subseção Autenticação de usuário) com o perfil Operador de Sensoriamento Remoto e precisa ter a chave chaveClassificacaoNM gerada com o cadastro da gleba na etapa anterior.

O envio é feito passando a chave na URL:

POST /api/v1/sensoriamentos-remotos/{chaveClassificacaoNM}

Também estão disponíveis GET /api/v1/sensoriamentos-remotos (listagem), GET /api/v1/sensoriamentos-remotos/{uuid} (consulta individual) e PUT /api/v1/sensoriamentos-remotos/{uuid} (atualização).

Campos importantes do payload (MonitoramentoSateliteInput):

• cnpjPropriedade — nome canônico do CNPJ da propriedade. O nome legado cnpj segue aceito no /api/v1, sem data de remoção — a remoção que havia sido anunciada foi cancelada (Cf. Mudanças Obrigatórias). Quem quiser o payload já limpo pode usar o /api/v2.
• cnpjEmpresaSensoriamento — CNPJ da empresa de sensoriamento responsável pelos dados (opcional).
• indices[].codigoSatelite e demais campos codigoSatelite* — códigos do satélite de origem (Cf. Códigos de satélite).

A estrutura completa do corpo da requisição está na Documentação Swagger e o significado de cada campo no Dicionário de Dados. Se todas as informações estiverem corretas, o SiNM retorna o código 201 Created - HTTP Status com os dados enviados no corpo da resposta. Além disso, logo após o envio desses dados, é realizado o cálculo da classificação de nível de manejo para a gleba/talhão referente à chave informada. E o usuário pode consultar o resultado da classificação no SiNM (Cf. Subseção Consulta da classificação de nível de manejo).

5. Consulta da classificação de nível de manejo

Uma vez que o registro dos dados obrigatórios tenha sido finalizado e o cálculo da classificação tenha ocorrido, é possível consultar a classificação do nível de manejo de uma determinada gleba/talhão no SiNM. Para a consulta, o usuário deve estar autenticado (Cf. Subseção Autenticação de usuário) e precisa ter a chave chaveClassificacaoNM gerada com o cadastro de uma determinada gleba/talhão.

A consulta é feita passando a chave na URL:

GET /api/v1/classificacoes/{chaveClassificacaoNM}

Também é possível listar todas as classificações às quais o usuário tem acesso com GET /api/v1/classificacoes.

Se todas as informações enviadas no cabeçalho da requisição estiverem corretas, o SiNM retorna o código 200 OK - HTTP Status informando que o recurso foi encontrado. No corpo da resposta é retornada a chave da classificação (chaveClassificacaoNM), o score final (nível de manejo), a data e hora em que foi realizado o cálculo da classificação e uma lista de inconsistências (tipo, descrição e a data e hora do registro das inconsistências), se houver dados inconsistentes. Se o usuário tentar consultar o resultado de uma classificação que ainda não foi finalizada, o SiNM retorna o código 404 Not Found - HTTP Status e uma mensagem informando qual ou quais dado(s) estão faltando para finalizar o cálculo de classificação de nível de manejo.

6. Racional da classificação (por que esse nível de manejo?)

Além do score final, o SiNM expõe o racional do cálculo — uma explicação de por que a gleba/talhão recebeu aquele nível de manejo. É útil para o integrador justificar o resultado ao produtor e identificar pontos de melhoria no manejo.

🆕 Leitura causal a partir da v6.2026 — em Homologação desde 04/08/2026, em Produção na entrega seguinte (ver Ciclo de promoção). Além de dizer o que aconteceu, o racional responde o que melhorar primeiro: regraDeterminante e limitantesPrincipais[] na classificação, papelNaNota e contribuicao em cada indicador. Todos são acréscimos — os campos anteriores continuam iguais. O efeitoNaNota segue presente, porém depreciado (ver a ressalva no fim desta seção). Detalhes e exemplo completo no Informativo v6.2026 — Racional do cálculo.

A consulta é feita pelo método GET, informando a chave da classificação:

GET /api/v1/classificacoes/{chaveClassificacaoNM}/racional

Pontos de atenção:

• Apenas para a classificação completa. O racional só existe para a classificação completa (com dados de análise de solo e de sensoriamento remoto). Para uma classificação preliminar ou ainda em processamento, o SiNM retorna 404 Not Found — não há racional de preliminar.
• Quem tem a chave consulta. A autorização é a mesma da consulta da classificação.
• A resposta tem duas formas, conforme o perfil do token:
  • Com o perfil Operador de Análise de Solo, cada indicador vem com valor medido, unidade, faixa, score parcial e contribuicao (projeção completa).
  • Sem esse perfil (ex.: Operador de Contratos), cada indicador vem apenas com nome, origem, papelNaNota e efeitoNaNota (projeção compacta) — sem expor valores da análise de solo.
  • A explicação da nota — regraDeterminante, limitantesPrincipais[], fatoresRestritivos[] e papelNaNota — é sempre visível, nas duas projeções: diz o motivo da nota sem revelar valores medidos.

O corpo da resposta traz, em ambas as formas:

Em cada indicador, dois campos respondem perguntas diferentes:

Os detalhes de cada campo e exemplos das duas projeções estão na Documentação Swagger da API.

⚠️ efeitoNaNota está depreciado — não use para decidir o que melhorar. Ele compara cada indicador com a nota final, então engana quando a nota foi fixada por uma regra de teto em vez da média: com a nota travada em NM1, nenhum indicador pode ficar abaixo dela — os indicadores que causaram o NM1 aparecem como NEUTRO e os fortes como ELEVOU, como se tivessem ajudado. O campo continua na resposta, com o mesmo comportamento (nada quebra), mas a leitura correta agora é regraDeterminante + limitantesPrincipais[] + papelNaNota para a causa, e contribuicao para a posição. Uma eventual remoção do efeitoNaNota será comunicada com antecedência em Mudanças Obrigatórias.

7. Lista de culturas

Para enviar os dados de uma determinada gleba/talhão (Cf. Subseção Envio de dados da gleba/talhão), é preciso informar as culturas cultivadas na gleba/talhão durante o período de três anos. Essa informação é adicionada no campo codigo, do objeto cultura presente na lista de producoes que compõe os dados da gleba/talhão (Cf. Dicionário de Dados).

Para auxiliar o usuário na hora de adicionar essa informação, o SiNM disponibiliza uma lista com os nomes e códigos das culturas que ele aceita:

GET /api/v1/culturas

Se todas as informações enviadas no cabeçalho da requisição estiverem corretas, o SiNM retorna o código 200 OK - HTTP Status e, no corpo da resposta, a lista contendo todos os nomes e códigos das culturas.

8. Códigos de satélite

No envio de dados de sensoriamento remoto (Cf. Subseção Envio de dados de sensoriamento remoto), os campos que identificam o satélite de origem (indices[].codigoSatelite, codigoSateliteDeclividadeMedia e, quando aplicável, codigoSatelitePlantioContorno e codigoSateliteTerraceamento) usam um código de 3 caracteres. A relação dos códigos aceitos e o comportamento em caso de código desconhecido estão documentados em Códigos de satélite. A lista vigente também pode ser consultada pela API em GET /api/v1/satelites.

9. Códigos de camada

No envio de dados de análise de solo (Cf. Subseção Envio de dados de análise de solo), o campo camada de cada amostra (amostrasQuimicas[].camada e amostrasFisicas[].camada) usa um código de 6 caracteres que identifica a profundidade (ex.: 00_020 para 0–20 cm). A relação dos códigos aceitos e o comportamento quando o código não é reconhecido (a amostra é preservada e uma inconsistência é registrada na classificação) estão documentados em Códigos de camada.

Links úteis

• Documentação Swagger da API (Ambiente Homologação e Testes)

• Documentação Swagger da API (Ambiente Produção)

• Dicionário de Dados dos Payloads (significado de cada entidade e campo dos envios — complementa o Swagger)

• Formulário de Credenciamento ao SiNM (versão vigente, publicada junto ao Swagger)

• Acesso ao Ambiente de Produção (credenciamento em produção: formulário e Termos de Uso assinados via gov.br)

• Termos de Uso e de Responsabilidades do SiNM (assinatura obrigatória para acesso à produção)

• Ajuda — Problemas de Autenticação (esqueci a senha, recuperar Client Secret, sem cadastro)

• E-mails para contato:

  credenciamentoNM@embrapa.br (documentação e credenciamento)

  suporteNM@embrapa.br (específico para questões técnicas do sistema e TI)

  zarcNM@embrapa.br (assuntos diversos, dúvidas, metodologia)

• Plano de desenvolvimento e evolução do SINM

As novas funcionalidades implementadas e os planos de novas evoluções podem ser consultadas aqui. Precisa se adaptar a alguma mudança obrigatória? Veja o Registro de Mudanças Obrigatórias.