Skip to content

PropriedadeController

  1. Cadastro das Propriedades

Endpoint: /cadastroPlanejamento/propriedade

method: POST

path: /cadastroPlanejamento/propriedade

description: Endpoint para cadastrar uma propriedade

parameters:
  - name: body
    type: DadosCadastroPropriedade
    description: Payload de cadastro da propriedade
    required: true
    in: body

Estrutura real esperada pela API

O corpo do POST é enviado diretamente como DadosCadastroPropriedade. Não existe envelope com safraId, safraCodigo ou dados neste endpoint.

Campos do payload:

  • oesa obrigatório, com exatamente 11 caracteres.
  • nirf opcional, com exatamente 8 caracteres quando informado.
  • incra opcional.
  • ccir opcional.
  • codigoABS opcional.
  • nome obrigatório.
  • areaTotal opcional.
  • usosDaTerra opcional, como lista de objetos com ano e tipo.
  • cars opcional.
  • ativo opcional.
  • endereco opcional.
  • produtores opcional.
  • proprietarios opcional.
  • poligono obrigatório, com no mínimo 3 pontos.

Regras para associação no cadastro:

  • Em produtores, a API aceita produtores existentes com id ou novos produtores sem id.
  • Quando um produtor é enviado sem id, o backend exige identificadorReceita.
  • Em proprietarios, a API aceita proprietários existentes com id ou novos proprietários sem id.
  • Quando um proprietário é enviado sem id, o backend exige identificadorReceita.

Como cadastrar o polígono corretamente

Na criação da propriedade, a API considera o campo raiz poligono como a geometria oficial da propriedade. Esse é o campo efetivamente validado pelo backend no cadastro.

Cada ponto deve ser enviado assim:

{
  "latitude": -11.8597,
  "longitude": -55.5036
}

Regras importantes:

  • O campo obrigatório para a lógica atual é poligono na raiz do payload.
  • O backend exige no mínimo 3 coordenadas em poligono.
  • Enviar apenas endereco.latitude e endereco.longitude não atende a estrutura real da API.
  • endereco.centroide é opcional e pode ser usado para representar o ponto central da propriedade.
  • endereco.poligono também pode ser enviado, mas a validação principal da propriedade usa o campo raiz poligono.
  • Se a aplicação preencher endereco.poligono, o ideal é manter os mesmos vértices sincronizados com poligono.
  • Os vértices devem seguir a ordem do contorno da área da propriedade.

Como o usuário deve preencher

  1. Marque os vértices do limite da propriedade no mapa.
  2. Monte a lista poligono com pelo menos 3 coordenadas, na ordem do contorno.
  3. Preencha endereco.centroide se o sistema também trabalhar com ponto central.
  4. Não use apenas latitude/longitude soltas dentro de endereco.
  5. Cadastre depois os polígonos de plano de cultivo, plantio e talhão sempre dentro desse polígono principal da propriedade.

Exemplo de payload correto

{
  "oesa": "12345678901",
  "nirf": "12345678",
  "incra": "INCRA-001",
  "ccir": "CCIR123456",
  "codigoABS": "ABS-001",
  "nome": "Fazenda Grãos de Ouro",
  "areaTotal": 1500.5,
  "usosDaTerra": [
    {
      "ano": "2025",
      "tipo": "SOJA"
    },
    {
      "ano": "2025",
      "tipo": "PASTAGEM"
    }
  ],
  "cars": [
    "BR-MT-1234567-89012345678901234567890"
  ],
  "ativo": true,
  "endereco": {
    "logradouro": "Rodovia Soja, Km 10",
    "numero": "S/N",
    "complemento": "Gleba A",
    "bairro": "Zona Rural",
    "cidade": "Sinop",
    "estado": "MT",
    "cep": "78550-000",
    "centroide": {
      "latitude": -11.8601,
      "longitude": -55.5041
    },
    "poligono": [
      {
        "latitude": -11.8597,
        "longitude": -55.5036
      },
      {
        "latitude": -11.8600,
        "longitude": -55.5040
      },
      {
        "latitude": -11.8610,
        "longitude": -55.5050
      }
    ]
  },
  "poligono": [
    {
      "latitude": -11.8597,
      "longitude": -55.5036
    },
    {
      "latitude": -11.8600,
      "longitude": -55.5040
    },
    {
      "latitude": -11.8610,
      "longitude": -55.5050
    }
  ],
  "produtores": [],
  "proprietarios": []
}

Exemplo que não deve ser usado

O formato abaixo está incompleto para a lógica atual, porque não envia o campo raiz poligono:

{
  "endereco": {
    "latitude": -11.8597,
    "longitude": -55.5036
  }
}

Exemplo de requisição:

curl --request POST \
  --url https://<url>/cadastroPlanejamento/propriedade \
  --header 'X-API-ACCESS-KEY: <chave_de_acesso>' \
  --header 'X-API-SECRET-KEY: <chave_de_seguranca>' \
  --header 'Content-Type: application/json' \
  --data '{
    "oesa": "12345678901",
    "nirf": "12345678",
    "incra": "INCRA-001",
    "ccir": "CCIR123456",
    "codigoABS": "ABS-001",
    "nome": "Fazenda Grãos de Ouro",
    "areaTotal": 1500.5,
    "usosDaTerra": [
      {
        "ano": "2025",
        "tipo": "SOJA"
      }
    ],
    "cars": [
      "BR-MT-1234567-89012345678901234567890"
    ],
    "ativo": true,
    "endereco": {
      "logradouro": "Rodovia Soja, Km 10",
      "numero": "S/N",
      "bairro": "Zona Rural",
      "cidade": "Sinop",
      "estado": "MT",
      "cep": "78550-000",
      "centroide": {
        "latitude": -11.8601,
        "longitude": -55.5041
      }
    },
    "poligono": [
      {
        "latitude": -11.8597,
        "longitude": -55.5036
      },
      {
        "latitude": -11.8600,
        "longitude": -55.5040
      },
      {
        "latitude": -11.8610,
        "longitude": -55.5050
      }
    ],
    "produtores": [],
    "proprietarios": []
  }'

Exemplo de resposta:

{
  "id": "68221f4b2f8c9a0012345678"
}

Mensagens de erro verificadas no service:

  • OESA é obrigatória.
  • Polígono da propriedade é obrigatório com no mínimo 3 pontos.
  • Já existe propriedade com esta OESA (...) cadastrado para a Chave utilizada.
  • Produtor sem Identificador Receita não pode ser cadastrado.
  • Proprietário sem Identificador Receita não pode ser cadastrado.
  • Produtor com ID ... não encontrado para associação.
  • Proprietário com ID ... não encontrado para associação.

Endpoint: /cadastroPlanejamento/propriedade

method: GET

path: /cadastroPlanejamento/propriedade

description: Endpoint para listar propriedades da chave de API autenticada

parameters:
  - name: page
    type: integer
    description: Número da página
    required: false
    in: query
  - name: size
    type: integer
    description: Quantidade de itens por página
    required: false
    in: query
  - name: sort
    type: string
    description: Campo de ordenação
    required: false
    in: query

Observações:

  • A paginação padrão do controller é size=10.
  • A ordenação padrão do controller é por nome.

Exemplo de requisição:

curl --request GET \
  --url 'https://<url>/cadastroPlanejamento/propriedade?page=0&size=10&sort=nome' \
  --header 'X-API-ACCESS-KEY: <chave_de_acesso>' \
  --header 'X-API-SECRET-KEY: <chave_de_seguranca>'

Exemplo de resposta:

{
  "content": [
    {
      "id": "68221f4b2f8c9a0012345678",
      "oesa": "12345678901",
      "nirf": "12345678",
      "incra": "INCRA-001",
      "ccir": "CCIR123456",
      "codigoABS": "ABS-001",
      "nome": "Fazenda Grãos de Ouro",
      "areaTotal": 1500.5,
      "usosDaTerra": [
        {
          "ano": "2025",
          "tipo": "SOJA"
        }
      ],
      "cars": [
        "BR-MT-1234567-89012345678901234567890"
      ],
      "ativo": true,
      "poligono": [
        {
          "latitude": -11.8597,
          "longitude": -55.5036
        },
        {
          "latitude": -11.8600,
          "longitude": -55.5040
        },
        {
          "latitude": -11.8610,
          "longitude": -55.5050
        }
      ]
    }
  ],
  "pageable": {
    "pageNumber": 0,
    "pageSize": 10
  },
  "totalElements": 1,
  "totalPages": 1,
  "last": true,
  "first": true,
  "size": 10,
  "number": 0,
  "numberOfElements": 1,
  "empty": false
}

Endpoint: /cadastroPlanejamento/propriedade/{id}

method: GET

path: /cadastroPlanejamento/propriedade/{id}

description: Endpoint para obter uma propriedade pelo identificador

parameters:
  - name: id
    type: String
    description: Identificador da propriedade
    required: true
    in: path

Exemplo de requisição:

curl --request GET \
  --url https://<url>/cadastroPlanejamento/propriedade/{id} \
  --header 'X-API-ACCESS-KEY: <chave_de_acesso>' \
  --header 'X-API-SECRET-KEY: <chave_de_seguranca>'

Exemplo de resposta:

{
  "id": "68221f4b2f8c9a0012345678",
  "apiKeyId": 123,
  "oesa": "12345678901",
  "nirf": "12345678",
  "incra": "INCRA-001",
  "ccir": "CCIR123456",
  "codigoABS": "ABS-001",
  "nome": "Fazenda Grãos de Ouro",
  "areaTotal": 1500.5,
  "usosDaTerra": [
    {
      "ano": "2025",
      "tipo": "SOJA"
    }
  ],
  "cars": [
    "BR-MT-1234567-89012345678901234567890"
  ],
  "ativo": true,
  "endereco": {
    "id": "68221f4b2f8c9a0099999999",
    "logradouro": "Rodovia Soja, Km 10",
    "numero": "S/N",
    "complemento": "Gleba A",
    "bairro": "Zona Rural",
    "cidade": "Sinop",
    "estado": "MT",
    "cep": "78550-000",
    "centroide": {
      "latitude": -11.8601,
      "longitude": -55.5041
    },
    "poligono": [
      {
        "latitude": -11.8597,
        "longitude": -55.5036
      },
      {
        "latitude": -11.8600,
        "longitude": -55.5040
      },
      {
        "latitude": -11.8610,
        "longitude": -55.5050
      }
    ]
  },
  "poligono": [
    {
      "latitude": -11.8597,
      "longitude": -55.5036
    },
    {
      "latitude": -11.8600,
      "longitude": -55.5040
    },
    {
      "latitude": -11.8610,
      "longitude": -55.5050
    }
  ]
}

Endpoint: /cadastroPlanejamento/propriedade

method: PUT

path: /cadastroPlanejamento/propriedade

description: Endpoint para atualizar uma propriedade

parameters:
  - name: body
    type: DadosAtualizacaoPropriedade
    description: Payload de atualização
    required: true
    in: body

Observações:

  • O campo id é obrigatório.
  • Os demais campos são opcionais e atualizados apenas quando enviados.

Exemplo de requisição:

curl --request PUT \
  --url https://<url>/cadastroPlanejamento/propriedade \
  --header 'X-API-ACCESS-KEY: <chave_de_acesso>' \
  --header 'X-API-SECRET-KEY: <chave_de_seguranca>' \
  --header 'Content-Type: application/json' \
  --data '{
    "id": "68221f4b2f8c9a0012345678",
    "nome": "Fazenda Grãos de Ouro - Atualizada",
    "ativo": true,
    "poligono": [
      {
        "latitude": -11.8597,
        "longitude": -55.5036
      },
      {
        "latitude": -11.8600,
        "longitude": -55.5040
      },
      {
        "latitude": -11.8610,
        "longitude": -55.5050
      }
    ]
  }'

Exemplo de resposta:

HTTP 200 sem corpo.

Endpoint: /cadastroPlanejamento/propriedade/{id}

method: DELETE

path: /cadastroPlanejamento/propriedade/{id}

description: Endpoint para excluir uma propriedade

parameters:
  - name: id
    type: String
    description: Identificador da propriedade
    required: true
    in: path

Exemplo de requisição:

curl --request DELETE \
  --url https://<url>/cadastroPlanejamento/propriedade/{id} \
  --header 'X-API-ACCESS-KEY: <chave_de_acesso>' \
  --header 'X-API-SECRET-KEY: <chave_de_seguranca>'

Exemplo de resposta:

HTTP 200 sem corpo.

FSTec Logo

© 2025 FSTec — Todos os direitos reservados.