DOCUMENTAÇÃO DOS DADOS

OPERADOS PELO SIMFAZ

Rest API SIMFaz

RENEILSON SANTOS | reneilson.santos@agrosatelite.com.br

SUPORTE SIMFAZ | simfaz.suporte@agrosatelite.com.br

08 DE DEZEMBRO DE 2022
Introdução 2

Primeiros Passos 2

Operação do SIMFaz 4
Entrada de Dados no SIMFaz 4

Entrada de dados via API 7

Cadastro de Pessoas 7

Cadastro de Áreas de Interesse 8

Criação Direta Da Geometria 8

Criação De Código (Car ou Incra) 9

Recuperando Geometria a partir de Código 10

Criação da Área de Interesse 11

Criação do Cadastro 12

Geração de Relatórios Socioambientais 13

Conjunto de Análises 13

Relatórios 16

Consultas 26

Requisição 27

Resposta 28

Auditabilidade 32

Listagem de todas requisições realizadas 32

Retorno de uma requisição específica 34

Relatório de Uso da Terra 37

Método 1 - Criação de Consultas 37

Método 2 - Relatório de Uso da Terra 38

Área de Análise 38

Dossiê de Área 39

Relatório de Uso da Terra 40

Metódo 1 vs Método 2 43

Campos Customizados 44

1
Introdução
O objetivo deste documento é descrever como a operação típica do SIMFaz (com foco
em verificações socioambientais) pode ser recriada através do consumo dos serviços e
funcionalidades do SIMFaz em outro sistema de informação, através da integração por
meio de APIs.

Primeiros Passos
Antes de qualquer coisa, faz-se necessário a aquisição de um token de acesso ao
sistema. Esse token pode ser obtido por meio de um contrato com a Agrosatélite. Ao
obter um contrato junto à Agrosatélite, pode-se então solicitar o Client ID e o Client
Secret, a partir dos quais será possível obter um token de acesso por meio do endpoint
api/v1/auth/token conforme segue:

Figura 1: Endpoint de recuperação de Token

curl --location --request POST 'https://simfaz.agrosatelite.com.br/api/v1/auth/token/' \

--form 'client_id="{my_client_id}"' \
--form 'grant_type="client_credentials"' \
--form 'client_secret="{my_client_secret}"'

Caso haja um usuário já disponível no contrato, o token pode ser adquirido por meio do
seguinte endpoint:

curl --location --request POST 'https://simfaz.agrosatelite.com.br/api/v1/auth/token/' \

--form 'client_id="{my_client_id}"' \
--form 'username="{my_user}"' \
--form 'password="{my_password}"' \
--form 'grant_type="password"'

2
Ambos os endpoints possuem o mesmo retorno, um JSON como se segue:

{
"access_token": "W0hbZkS6PlGKhD5bKqPlTlrQyFMcSo",
"expires_in": 1800,
"token_type": "Bearer",
"scope": "read write",
"refresh_token": "R9VTvEf07lCsAb5u08AVpl8CN66l8f"
}

Com o access_token retornado, portanto, pode-se realizar as requisições em todo o

sistema, inclusive, utilizá-lo para testar diretamente no Swagger da API
(https://simfaz.agrosatelite.com.br/api/v1/). Para isso, basta ir em Authorize e digitar
“Bearer {access_token}”, conforme imagem abaixo.

Figura 2: Autorização no Swagger

3
Operação do SIMFaz
A interface gráfica do SIMFaz será utilizada para ilustrar os conceitos, porém não faz
parte da solução entregue para integração de sistemas.

Para todos os endpoints apresentados a seguir, supõe-se que o token de acesso é

passado no cabeçalho (Oauth 2.0). Caso contrário, a resposta sempre será que o usuário
não está autenticado.

Entrada de Dados no SIMFaz

A integração com o SIMFaz passa por fornecer, por parte dos sistemas de informação, os
dados necessários para a operação da mesma.

E na operação da empresa existe recorrência da utilização de certas informações, dentre

elas, as fazendas dos fornecedores, na forma das pessoas físicas (CPF) e pessoas
jurídicas (CNPJ) e da identificação e delimitação dos imóveis rurais (direta através de
dados espaciais fornecidos diretamente, ou indiretamente a partir
códigos/matrículos/registros oficiais junto ao Serviço Florestal (CAR) e INCRA
(SIGEF/SNCR, SNCI)).

No SIMFaz essas informações são inseridas no sistema por meio dos cadastros e seus
dados componentes. Um cadastro pode representar a criação e informação do mesmo
como entidade (Figura 1).

4
 Figura 3: Tela de cadastros: a. Criação de ‘Cadastros’ e b. Entidades (pessoas físicas ou jurídicas)

Segue o exemplo de JSON para criação de pessoa (endpoint /api/v1/entities)

{
"name": "João Pessoa",
"document_type": "CPF",
"document": "11111111111"
}

O vínculo da pessoa será entre ela e o cadastro, portanto, somente ao final do cadastro,
com o id disponível, cria-se o vínculo (ARRENDATÁRIO ou PROPRIETÁRIO).

O vínculo não altera análises.

Um cadastro no SIMFaz pode conter nenhuma ou até 10 pessoas, independentemente

de seus vínculos e de seus tipos de documento (se pessoa física ou jurídica).

Além de inserir pessoas em um cadastro, é possível também inserir Áreas de Interesse,

que são as geometrias e códigos utilizados pelo imóvel/fazenda que pretende-se
analisar. Assim como há limitações na quantidade de pessoas por cadastro, há também
uma limitação na área de interesse. Uma área de interesse pode ter de 0 a 5 geometrias
(endpoint /api/v1/boundaries) e de 0 a 5 códigos relacionados ao CAR ou ao INCRA

5
(endpoint /api/v1/matriculations). O conjunto de nomes, geometrias e código compõem
uma área de interesse. E, por sua vez, o cadastro possui uma única área de interesse.

Através da interface gráfica é possível inserir os dados de área de interesse de diferentes

formas (como visto na figura abaixo), no entanto, pela API a única forma possível de criar
uma área de interesse será criando-se primeiramente as geometrias utilizando um
GeoJSON/WKT e os códigos com o seu valor e o seu tipo e depois chamando o
endpoint de criação da área, passando os ids gerados para as geometrias e os códigos,
além de um nome que é obrigatório, como será visto com mais detalhes na próxima
seção.

Figura 4: Opções para inserir na área de interesse

6
Entrada de dados via API
A interface Web do SIMFaz já agrupa algumas sequências de chamadas para a API em
cada etapa realizada pelo navegador. Ao realizar a entrada de dados pela API é
necessário sequenciar algumas chamadas. Esse processo pode parecer complicado à
primeira vista, porém fica simples após se entender os conceitos e como eles se
relacionam.

Cadastro de Pessoas

Figura 5: Endpoints de entidades (para cadastro/recuperação de pessoas)

● se a pessoa não existir ainda na base de dados:

○ criar a pessoa com tipo de documento, número de documento e nome
● se a pessoa já existir
○ buscar pelo ‘id’ da entidade com o mesmo tipo de documento e número
de documento
● Por fim, associam-se as pessoas ao cadastro, passando como parâmetro o id da
pessoa (entity), o id do cadastro (unit) e o tipo de vínculo (relation_type) (OWNER ->
Proprietário ou TENANT -> Arrendatário):

{
"unit": 1,
"entity": 1,
"relation_type": "OWNER"
}

7
É preciso repetir essa ação para todas as pessoas que houverem no cadastro, criando-se
o relacionamento para cada uma delas, lembrando que há uma limitação de até 10
pessoas por cadastro.

Vale ressaltar que os dados das pessoas só serão analisados no relatório socioambiental
no caso em que houver vínculo entre a pessoa e o cadastro. Não é possível passar
pessoas para criar relatórios, apenas cadastros geram relatórios socioambientais.

Cadastro de Áreas de Interesse

Criação Direta Da Geometria

Figura 6: Endpoints de boundaries (para cadastro/recuperação/atualização/remoção de geometrias)

[api/v1/boundaries]

Se já se estiver disponível as coordenadas de uma geometria (seu GeoJSON), pode-se

criar a geometria através do endpoint api/v1/boundaries passando como parâmetro o
seguinte JSON:

{
"label": "Minha fazenda",
"geometry": {
"type": "Polygon",
"coordinates": [ [ [ -55.016301808054038, -11.386921655736476 ],
[ -55.020683480420082, -11.403525887860452 ],
[ -55.00246494795072, -11.418977048309152 ],
[ -54.99231791720829, -11.411366775252329 ],
[ -54.987936244842246, -11.397760529484071 ],
[ -54.993470988883566, -11.387152270071532 ],
[ -55.012842593028203, -11.382770597705482 ],

8
 [ -55.016301808054038, -11.386921655736476 ] ] ]
}
}

Onde o label é o nome da geometria que poderá ser identificado posteriormente no

relatório (na aplicação web) e o campo geometry refere-se à geometria da fazenda que
deseja-se cadastrar, é possível passar a geometria nos formatos GeoJSON ou WKT. O
SIMFaz vai retornar um id para esta geometria.

Criação De Código (Car ou Incra)

Figura 7: Endpoints de matriculations (para cadastro/recuperação/atualização/remoção de códigos

CAR/Incra) [/api/v1/matriculations]

No caso do código do CAR ou do INCRA, é preciso realizar o seu cadastro dentro do

sistema também para que possa ser feita as devidas consultas com esses dados ou
utilizá-los para filtragem de cadastro. Para criar um código é necessário passar os
seguintes campos no endpoint api/v1/matriculations:

{
"code": "MT-5107065-B771EB9156A1426D9A692B9DDF981D99",
"code_type": "CAR"
}

No qual o code, é o código do CAR ou do INCRA (SIGEF/SNCR ou SNCI) e o code_type

identifica se está cadastrando um código do CAR ou do INCRA (SIGEF/SNCR ou SNCI).

9
Recuperando Geometria a partir de Código
O SIMFaz disponibiliza endpoints para a recuperação da geometria do CAR ou do INCRA
através de suas respectivas consultas, que serão tratadas posteriormente neste
documento (ir para endpoints de consultas).

Exemplo consulta CAR ou INCRA por ponto (/api/v1/queries/car_sicar/requests ou

/api/v1/queries/imoveis_incra/requests):

{
"query_parameters":{
"geometry":{
"type":"Point",
"coordinates":[
-50.86216222920524,
-10.223389933294143
]
}
}
}

Para o CAR ainda pode-se fazer:

{
"query_parameters":{
"car":"MT-5108600-D57E.3A04.9CBE.40AD.A032.986D.21D5.73F7"
}
}

E para o INCRA:

{
"query_parameters":{
"incra":"2078b1c5-c0f0-4ce4-bfbe-006b7d3760ef"
}
}

A partir do retorno das consultas, seja pelo CAR, INCRA ou pelo ponto, é preciso ainda
fazer uma busca pela resposta detalhada, que então trará a geometria no campo details

10
(será visto em maiores detalhes na seção de consultas do presente documento como
fazer a recuperação dos dados de uma consulta específica).

Criação da Área de Interesse

Figura 8: Endpoints de interest_areas (para cadastro/recuperação/atualização/remoção de áreas de

interesse) [/api/v1/interest_areas]

Ao finalizar os dados de geometrias e códigos, faz-se necessário concluir a área de

interesse, para isso passa-se como parâmetro uma lista de ids das geometrias
(boundaries) e uma lista de ids dos códigos (matriculations) que foram criados e um
nome para identificação da área. O JSON recebido pelo endpoint segue o seguinte
padrão:

{
"name": "Minha Fazenda",
"matriculations": [1],
"boundaries": [1]
}

O id é devolvido pelo SIMFaz após criar qualquer recurso.

11
Criação do Cadastro

Figura 9: Endpoints de units (para cadastro/recuperação/atualização/remoção de cadastros) [/api/v1/units]

Após a criação da(s) pessoa(s) e da área de interesse, pode-se então concluir o cadastro
dando um nome e associando-o à área de interesse, para isso, passa-se como
parâmetro o id da área de interesse criada e um nome, por exemplo:

{
"name": "Minha Fazenda",
"interest_area": 1
}

Para o caso do vínculo das pessoas ao cadastro, como mencionado anteriormente, seria
necessário endpoints diferentes associando o id do cadastro criado com o id das
pessoas criadas ou recuperadas.

12
Geração de Relatórios Socioambientais

Conjunto de Análises
Uma vez com o cadastro criado, independente da quantidade de atributos que possa
conter, a criação de um conjunto de análises para aquele cadastro pode ser feita com
uma única chamada à API passando simplesmente o identificador do cadastro (valor
associado com campo ‘unit’) através do endpoint api/v1/analyses_set:

Figura 10: Endpoint de criação de conjunto de Análises

Parâmetros:

{
"unit":1
}

Nesse caso, todas as análises contidas no contrato serão realizadas para todos os
atributos contidos dentro do cadastro. Cabe mencionar que as análises espaciais
utilizarão os atributos espaciais do cadastro, as análises com CPF/CNPJ utilizarão os
atributos com tais campos e as análises com código do CAR utilizarão os códigos do
CAR dentro do cadastro.

Há ainda a possibilidade de realizar um conjunto de consultas específico para um

determinado cadastro passando como parâmetro também uma lista com os códigos das
queries a serem analisadas.

{
"unit": 1,
"queries": ["embargos-ibama-espacial", "assentamentos-rurais"]
}

13
Independente da forma como os parâmetros são passados (se com uma lista de queries
ou não), o resultado é retornado no mesmo formato, uma lista de respostas para cada
query com os campos id, query, user, sources e response.

● Id é o id da requisição, que poderá ser utilizado para capturar mais informações

sobre a resposta daquela consulta.
● Query é um tipo de pergunta, um tipo de análise que pode ser respondida pelo
SIMFaz (e.g., embargo do ibama espacial, ldi Pará etc.). Ela é identificada pelo seu
código.
● User é o id do usuário que realizou a consulta (baseado no token de
autenticação). Para integrações entre sistemas, será fornecido um usuário do
SIMFaz representando o sistema que faz a integração.
● Sources é um JSON que apresenta o id da fonte de dado utilizada e a sua class,
por exemplo, se dentro do nosso cadastro houver três pessoas, ela retornará uma
resposta da query que usa CPF/CNPJ para cada uma das pessoas, seremos
capaz de identificar cada uma delas a partir do id. A classe (class) serve para :
○ determinar se foi usado a pessoa (entity) ou,
○ se foi usado para uma geometria (boundary) ou,
○ se foi usada para um código (matriculation) CAR, SIGEF, ou outros que
venham a ser suportados no futuro.
● Response é um JSON que retorna a resposta para a requisição àquela consulta
(query) com aquela fonte (source). Esse JSON é simplificado e retorna apenas
○ success:, se a consulta foi realizada com sucesso ou não;
○ value: cujo valores possíveis variam para cada query (tipo de consulta) e é
o campo que definirá se houve ou não problema (entende-se aqui
problema como sendo qualquer situação diferente do cenário ideal) com
aquele cadastro, naquela consulta específica e com aquela fonte;
○ source_date: indica a data do dado utilizado;
○ media: retorna uma lista com o id das mídias (imagens, documentos pdf,
etc) retornadas pela consulta (caso seja uma consulta que retorne algum
documento, como o LDI do Pará);
○ creation_date: indica a data da criação da requisição da consulta É
considerado o instante do recebimento da requisição no backend
(servidor) do SIMFaz.
○

14
A seguir se apresenta um exemplo do JSON da resposta do analyses_set:

[
{
"id": 1,
"query": "terras_indigenas",
"user": 1,
"sources": [
{
"id": 1,
"class": "boundary"
}
],
"response": {
"success": true,
"value": "0",
"source_date": "2021-02-09T11:50:50-03:00",
"media": [],
"creation_date": "2021-06-30T15:44:55.442426-03:00"
}
},
{
"id": 2,
"query": "embargos_ibama_espacial",
"user": 1,
"sources": [
{
"id": 1,
"class": "boundary"
}
],
"response": {
"success": true,
"value": "0",
"source_date": "2021-04-19T09:10:00.516505-03:00",
"media": [],
"creation_date": "2021-06-30T15:44:56.954958-03:00"
}
}
]

15
Relatórios
Uma vez que tenha em mãos os ids das requisições, para salvar essas informações
como um relatório (no SIMFaz) é preciso passá-la para um endpoint específico
(/api/v1/reports/) para criação do relatório.

Figura 11: Endpoint de criação/recuperação de relatórios

Caso apenas a análise seja feita sem salvar o relatório, as consultas realizadas não ficam
salvas na base de dados do cliente acessível pelos usuários. Na aplicação Web, isso é
identificado a partir do ícone salvar. Porém, todas as consultas que foram executadas,
salvas ou não como relatório, ficam registradas no backend (servidor) do SIMFaz e
podem ser consultadas pela API.

16
 Figura 12: Tela análise feita e opção de salvar

No caso da utilização da API, para criar um relatório, basta passar como parâmetro o id
da unidade que gerará o relatório e uma lista com os ids das requisições retornadas pela
análise. Exemplo para a análise anterior:

{
"unit": 1,
"requests": [1, 2]
}

Dessa forma, será retornado a estrutura de um relatório, um JSON com o id, unit,
contract, created_by, queries, requests, type e creation_date.
● O id, unit, contract e created_by indicam respectivamente o id do relatório
recém-criado, o id do cadastro usado para gerar o relatório, o id do contrato que
o usuário está autenticado, e o id do usuário autenticado;
● queries é uma lista com todas as consultas disponíveis dentro do contrato do

17
 usuário que está autenticado;
● requests é basicamente a lista com os ids das requisições salvas naquele
relatório;
● type indica o tipo de relatório, para análises socioambientais o valor é
“socioambiental”.
Estrutura do JSON retornado de um relatório:

{
"id": 1,
"unit": 1,
"contract": 1,
"created_by": 1,
"queries": [
"embargos_ibama_certidao",
"embargos_ibama_historico",
"embargos_ibama_espacial",
"trabalho_escravo",
"ldi_para_car",
"terras_indigenas",
"desmatamento_prodes",
"unidades_de_conservacao",
],
"requests": [
1,
2
],
"type": "socioambiental",
"creation_date": "2021-06-30T15:58:38.361332-03:00"
}

A diferença do JSON retornado na criação (POST) para o JSON retornado na requisição

(GET) de um relatório específico é que o GET irá trazer a lista de requests não como uma
lista de ids, mas uma lista com os detalhes, igual é retornado ao criar a análise.

{
"id": 1,
"unit": 1,
"contract": 1,
"created_by": 1,
"queries": [
"embargos_ibama_certidao",
"embargos_ibama_historico",
"embargos_ibama_espacial",
"trabalho_escravo",

18
 "ldi_para_car",
"terras_indigenas",
"desmatamento_prodes",
"unidades_de_conservacao",
],
"requests": [
{
"id": 1,
"query": "terras_indigenas",
"user": 1,
"sources": [
{
"id": 1,
"class": "boundary"
}
],
"response": {
"success": true,
"value": "0",
"source_date": "2021-02-09T11:50:50-03:00",
"media": [],
"creation_date": "2021-06-30T15:44:55.442426-03:00"
}
},
{
"id": 2,
"query": "embargos_ibama_espacial",
"user": 1,
"sources": [
{
"id": 1,
"class": "boundary"
}
],
"response": {
"success": true,
"value": "0",
"source_date": "2021-04-19T09:10:00.516505-03:00",
"media": [],
"creation_date": "2021-06-30T15:44:56.954958-03:00"
}
],
"type": "socioambiental",
"creation_date": "2021-06-30T15:58:38.361332-03:00"
}

19
Caso se deseje obter mais informações a respeito da resposta de uma consulta
específica, por exemplo, para verificar em quais anos do PRODES houve problema em
determinada consulta, pode-se utilizar o id de um request num endpoint para recuperar
a resposta detalhada. Caso se deseje saber os detalhes de cada resposta, é necessário
fazer uma requisição para cada response (recurso que armazena as respostas). O retorno
será o seguinte:

{
"id":3,
"query":"desmatamento_prodes",
"user":1,
"sources":[
{
"id":1,
"class":"boundary"
}
],
"query_parameters":{
"year":2008,
"geometry":{
"coordinates":[
[
[
[
-47.85361917,
-11.23792639
],
[
-47.84523583,
-11.24344889
],
...
[
-47.85361917,
-11.23792639
]
]
]
],
"type":"MultiPolygon"
}
},
"response":{
"success":true,

20
"value":"0.0363894796964155",
"details":{
"features":[
{
"properties":{
"id":882164.0,
"class_name":"d2015",
"satellite":null,
"julday":0.0,
"pathrow":"222/68",
"dsfnv":0.0,
"source":"inpe cerrado",
"scene_id":0.0,
"ano":"2015",
"ano_fim":2015.0,
"classname":"D_2015",
"intersection":{
"properties":{
"area_m2":1270,
"area_percentage":0.03640056639467809
},
"coordinates":[
[
[
[
-47.848531609256426,
-11.263975291786256
],
[
-47.84841600929133,
-11.263595463160073
],
[
-47.84837038669102,
-11.263595463160073
],
[
-47.84851639,
-11.26398417
],
[
-47.848531609256426,
-11.263975291786256
]
]

21
 ],
[
[
[
-47.84833229445356,
-11.26349404961437
],
[
-47.84844589016564,
-11.262926072580115
],
[
-47.84811895494444,
-11.262926072580115
],
[
-47.84833229445356,
-11.26349404961437
]
]
]
],
"type":"MultiPolygon"
},
"fonte":"PRODES bioma Cerrado - INPE",
"sensor":null,
"ano_inicio":2015.0,
"view_date":"27/08/2015",
"mainclass":"desmatamento"
},
"geometry":{
"coordinates":[
[
[
-47.84293165926863,
-11.26208899171354
],
[
-47.84293165926863,
-11.262220943841442
],
...
[
-47.84293165926863,
-11.26193687858404

22
 ],
[
-47.84293165926863,
-11.26208899171354
]
]
],
"type":"Polygon"
},
"type":"Feature"
}
],
"type":"FeatureCollection"
},
"media":[

],
"source_date":"2021-01-29T00:00:05-03:00",
"creation_date":"2021-06-22T15:48:40.534419-03:00"
}
}

Cada query (tipo de requisição) tem um conjunto de valores possíveis de resposta. O

query_parameters indicará qual foi o dado passado como parâmetro para a realização
da consulta e o response virá com o campo details que trará detalhes da resposta, tais
como as geometrias (features) de interseção (quando é utilizado uma consulta espacial).

23
Na aplicação Web, ao recuperar os detalhes da análise é possível visualizá-la no mapa:

Figura 13: Detalhe da análise no SIMFaz

Na aplicação Web, os itens são destacados em vermelho para indicar problema

socioambiental. Já os itens em verde destacam as análises que estão em conformidade
socioambiental. A escolha de realçar em vermelho ou verde se fundamenta nos valores
das respostas (Figura 6). Na integração via API cabe aos responsáveis por cada
integração como destacar as respostas.

Figura 14: Cores dos itens no socioambiental

24
Por outra parte, existe uma última categoria de análises, as análises não realizadas. Essas
são as análises que fazem parte do contrato do usuário autenticado mas que não podem
ser realizadas devido a ausência dos dados necessários no cadastro (no exemplo
anterior, o cadastro não possui um CAR nem um CAR do Pará, então as análises do LDI e
do Car Nacional não foram realizadas).

Essas situações são identificadas pela descrição da resposta que diz que não foi possível
realizar a consulta, tal como se apresenta na Figura 7.

Figura 15: Exemplo de análises não realizadas no SIMFaz

25
Consultas
O objetivo desta seção é descrever como os parâmetros passados no cadastro são
utilizados pelas diferentes queries disponíveis e como são apresentadas as respostas
(detalhadas) para a requisições (requests) destas queries.

Figura 16: Endpoint de captura de detalhes da(s) consulta(s).

Exemplo de resposta com detalhes de uma determinada consulta (GET

api/v1/queries/embargos_ibama_espacial):

{
"code": "embargos_ibama_espacial",
"name": "Embargos Ibama Espacial",
"description": "Embargos Ibama Espacial",
"required_parameters": "('cpf') OR ('cpnj') OR ('geometry') OR
('geometry' AND 'cpf') OR ('geometry' AND 'cnpj')",
"optional_parameters": "('date')",
"last_modification_date": "2012-06-07T22:50:19-03:00",
"creation_date": "2012-06-07T22:50:19-03:00"
}

● required_parameters: é uma lista com possíveis opções para parâmetros

obrigatórios da consulta. No caso na consulta Embargos Ibama Espacial, o valor
"('cpf') OR ('cpnj') OR ('geometry') OR ('geometry' AND 'cpf') OR ('geometry' AND
'cnpj')" significa que a consulta deve receber:
○ cpf;
○ cnpj;
○ geometria;
○ geometria e CPF;
○ geometria e CNPJ.

26
 ● optional_parameters é uma lista com possíveis opções para parâmetros
opcionais da consulta Embargos Ibama Espacial, o valor "('date')" significa que a
consulta pode receber uma data.

Requisição

Figura 17: Endpoint de criação ou captura de detalhes da(s) requisição(s).

Exemplo de requisição de consulta por geometria, sem parâmetro de data (busca pelo
dado mais recente). O parâmetro de geometria é ilustrado com dados reais, já que é
mais complexo que os parâmetros utilizados usualmente:

{
"query_parameters":{
"geometry":{
"type": "Polygon",
"coordinates": [ [ [ -55.016301808054038, -11.386921655736476 ],
[ -55.020683480420082, -11.403525887860452 ],
[ -55.00246494795072, -11.418977048309152 ],
[ -54.99231791720829, -11.411366775252329 ],
[ -54.987936244842246, -11.397760529484071 ],
[ -54.993470988883566, -11.387152270071532 ],
[ -55.012842593028203, -11.382770597705482 ],
[ -55.016301808054038, -11.386921655736476 ] ] ]
},
"date":"<YYYY-MM-DD>"
}
}

Tanto o CPF como o CNPJ podem ser passados sem pontuação ou com pontuação.
Enquanto a geometria é passada como GeoJson ou WKT (pode ser do tipo Polygon,
Point ou Multipolygon).

27
Resposta
Exemplo da resposta:

{
"id": 6644,
"request": 6757,
"success": true,
"value": "34.31",
"details": {
"type": "FeatureCollection",
"features": [
{
"type": "Feature",
"geometry": {
"coordinates": [
[
[
[
-55.013911,
-11.404295
],
[
-55.01807,
-11.400175
],
[
-55.015,
-11.386854
]
]
],
[
[
[
-55.014462,
-11.384518
],
[
-55.009786,
-11.36422
],
[
-54.984601,
-11.380244

28
 ]
]
]
],
"type": "MultiPolygon"
},
"properties": {
"intersection": {
"coordinates": [
[
[
[
-55.013911,
-11.404295
],
[
-55.01807,
-11.400175
],
[
-55.015,
-11.386854
]
]
],
[
[
[
-54.995913,
-11.386599910414242
],
[
-54.995913,
-11.387213
],
[
-54.997814,
-11.387158
]
]
],
[
[
[
-55.00622775215621,

29
 -11.384266811712244
],
[
-55.007596,
-11.386775
],
[
-55.00659,
-11.387487
]
]
]
],
"type": "MultiPolygon",
"properties": {
"area_m2": 3406721,
"area_percentage": 34.31
}
}
}
},
{
"type": "Feature",
"geometry": {
"coordinates": [
[
[
-54.9965,
-11.396581
],
[
-55.002558,
-11.409301
],
[
-55.005118,
-11.408317
]
]
],
"type": "Polygon"
},
"properties": {
"intersection": {
"coordinates": [

30
 [
[
-54.9965,
-11.396581
],
[
-55.002558,
-11.409301
],
[
-55.005118,
-11.408317
]
]
],
"type": "Polygon",
"properties": {
"area_m2": 1208767,
"area_percentage": 12.18
}
}
}
}
]
},
"media": [],
"source_date": "2019-06-05T00:02:08-03:00",
"creation_date": "2019-06-05T15:11:33.840461-03:00"
}

● request: indica o identificador da requisição referente à resposta;

● success: indica se o serviço foi capaz de acessar o registro histórico de
pendências;
● value: sumariza o conteúdo do resultado da pesquisa. Neste caso, se há embargo
ou não. O valor retornado é uma string (para manter consistência no formato de
resposta de todos os tipos de consultas) com um valor entre 0 (zero) e 100 (cem).
○ Se uma geometria é passada na consulta: Esse valor codifica a
porcentagem da geometria passada de parâmetros que corresponde a
embargos.

31
 ○ Se nenhuma geometria é passada na consulta (se usuário passar somente
CPF ou CNPJ): Esse valor é retornado como "0" se não houver embargo e
como "100" se houver embargo.
● creation_date: indica o momento que o resultado da consulta é produzido e
enviado ao consumidor;
● details: retorna detalhes sobre os embargos encontrados. Caso o usuário tenha
passado uma geometria na consulta, o campo details.properties.intersection vai
trazer as coordenadas das intersecções com os embargos, assim como a área
embargada (area_m2) e porcentagem da área da geometria consultada que está
embargada por um embargo específico (area_percentage).

Auditabilidade
A requisição realizada e a respectiva resposta podem ser acessada diversas vezes,
permanecendo armazenada por um período de 5 anos, utilizando o seguinte endpoint:

api/v1/queries/{query_code}/requests/{id}

Por padrão, um usuário só pode acessar requisições e respostas que estão associadas a
requisições geradas pelo próprio usuário. Caso um usuário tente acessar conteúdo sem
esse vínculo, a resposta será um HTTP Status Code 404 Not Found (que não confirma
nem nega a existência do conteúdo buscado, tampouco dá acesso indevido).

Listagem de todas requisições realizadas

O histórico de requisições pode ser recuperado e retorna uma lista semelhante à
seguinte:

{
"count": 3,
"next": null,
"previous": null,
"results": [
{
"id": 1,
"query_parameters": {
"geometry": {

32
 "coordinates": [
[
[
[
-57.8964,
-10.1152
],
[
-57.8966,
-10.1098
],
[
-57.9224,
-10.117
],
[
-57.921,
-10.1229
],
[
-57.8964,
-10.1152
]
]
]
],
"type": "MultiPolygon"
}
},
"response": 1,
"created_by": "<USERNAME>",
"contract": "<ID_CONTRATO>",
"creation_date": "2019-03-06T13:00:07.881289Z"
},
{
"id": 2,
"query_parameters": {
"cpf": "<CPF>"
},
"response": 2,
"created_by": "<USERNAME>",
"contract": "<ID_CONTRATO>",
"creation_date": "2019-03-06T13:01:12.902505Z"
}
]

33
 }

Os resultados retornados são paginados. Ou seja, o endpoint retorna uma quantidade

máxima de resultados por requisição. Caso existam mais resultados do que a quantidade
máxima, os resultados excedentes são disponibilizados em outra página (outra
requisição).

Para utilizar o recurso de paginação, é necessário adicionar os seguintes parâmetros à

chamada:
limit: define a quantidade de resultados por página;
offset: a partir de qual resultado a página é montada;
e.g., offset=100&limit=100 retorna a segunda página, offset=200&limit=100
retorna a terceira

Retorno de uma requisição específica

{
"id": 19,
"query_parameters": {
"cpf": "<CPF>"
},
"response": 19,
"created_by": "<USERNAME>",
"contract": "<ID_CONTRATO>",
"creation_date": "2019-03-06T19:12:43.540316Z"
}

● id é o próprio identificador da requisição, que foi enviado como parâmetro (no

caso do exemplo, teria sido '3');
● query_parameters são os parâmetros que foram passados no momento da
criação da requisição;
● response é o identificador associado à resposta retornada para a requisição. Este
valor só será vazio no caso de falha no serviço que impossibilite o retorno da
resposta - normalmente uma resposta deve existir para cada requisição, mesmo
nos casos em que não foi possível produzir o dado desejado (neste caso, a
resposta possui o campo success definido como false);

34
 ● source_date indica a data que o dado retornado foi
produzido/coletado/armazenado;
● created_by indica qual o username do usuário que fez a requisição;
● contract indica o identificador do contrato de serviço associado à consulta;
● creation_date indica o momento que a requisição foi registrada.

Retorno de uma resposta específica:

{
"id": 6722,
"request": 6839,
"success": true,
"value": "0",
"details": {
"type": "FeatureCollection",
"features": []
},
"media": [],
"source_date": "2019-06-05T00:02:08-03:00",
"creation_date": "2019-06-05T16:15:45.346021-03:00"
}

O mesmo padrão segue para todas as consultas no SIMFaz, a mudança dar-se-á no

campo value que tem valor numérico semelhante ao exemplo do Embargo Ibama
Espacial apresentado anteriormente, mas, as consultas que usam dados não espaciais
retornam valores distintos. A tabela a seguir apresenta os possíveis resultados para cada
uma das análises:

35
 Consulta Retorno com Problema Retorno sem Problema
Socioambiental Socioambiental

Desmatamento Prodes >0 0

Unidades de Conservação >0 0

Terras Indígenas >0 0

Emgargos Ibama Espacial >0 0

Embargos Ibama Certidão EXISTE PENDÊNCIA DE NADA CONSTA

EMBARGO

Embargos Ibama Histórico EXISTE PENDÊNCIA DE NADA CONSTA

(Lista) EMBARGO

LDI CAR Pará EXISTE PENDÊNCIA NA LISTA NADA CONSTA

DE DESMATAMENTO ILEGAL
DO PARÁ

Trabalho Escravo CONSTA NÃO CONSTA

Embargos SEMA/MT >0 0

Moratória da Soja CONSTA INEXISTÊNCIA DE AÇÃO

CIVIL PÚBLICA

No caso do CAR ou do INCRA, utilizado para recuperação de geometrias e não como

análises de alertas socioambientais, as consultas podem ser realizadas passando como
parâmetro o ponto como uma geometria GeoJson ou como um WKT, buscando-se,
portanto, a geometria a partir da coordenada geográfica, ou ainda passar o car (no caso
da busca pelo CAR) ou o código snci, sncr, sigef, ccir ou incra (no caso da busca pelo
INCRA).

36
Relatório de Uso da Terra

Método 1 - Criação de Consultas

Para a criação de relatórios de uso da terra, que permitem a análise histórica e pontual
de uma determinada área de interesse de acordo com os mapas de uso da terra que o
usuário possui em seu contrato, assim como os anos que o mesmo possui, é possível
criá-lo de duas maneiras diferentes. A primeira é com a utilização das consultas
individualmente, a partir do query_code do mapa de uso e do ano. Para esta opção, a
única diferença em relação à requisição apresentada anteriormente, é a inserção do ano
no parâmetro year. Caso haja dado para o ano especificado, o resultado será retornado.

Exemplo de requisição para uma consulta no mapa de soja para retornar os dados
referente ao ano de 2020:

{
"query_parameters":{
"geometry":{
"type": "Polygon",
"coordinates": [ [ [ -55.016301808054038, -11.386921655736476 ],
[ -55.020683480420082, -11.403525887860452 ],
[ -55.00246494795072, -11.418977048309152 ],
[ -54.99231791720829, -11.411366775252329 ],
[ -54.987936244842246, -11.397760529484071 ],
[ -54.993470988883566, -11.387152270071532 ],
[ -55.012842593028203, -11.382770597705482 ],
[ -55.016301808054038, -11.386921655736476 ] ] ]
},
"year":2020
}
}

Essa forma de requisição pode ser feita, portanto, em separado, e indicando quais os
anos e as consultas que deseja-se realizar, podendo assim o usuário montar seu próprio
relatório de uso da terra apenas com os anos e mapas desejados para determinada área.
Caso o ano não seja passado como parâmetro, sempre é utilizado o ano mais recente.

37
Método 2 - Relatório de Uso da Terra
A outra alternativa é a criação de um relatório de uso da terra para um cadastro, o qual
conterá o resultado para todos os mapas de uso da terra em todos os anos possíveis que
estejam dentro do contrato com a Agrosatélite.

Para essa operação, é necessário inicialmente realizar todo o procedimento de cadastro

de uma unidade, conforme apresentado anteriormente, e, de posse do ID da unidade
basta seguir o fluxo de :

1. Criação de uma área de análise;

2. Criação de um dossiê para a área de análise;
3. Criação do relatório de uso da terra.

Área de Análise
A área de análise é um objeto que possui um conjunto de geometrias (que devem estar
contidas dentro da unidade) que passarão por um processo de análise, seja o
monitoramento via imagens de satélite ou a análise de uso da terra.

Ela pode ser composta, portanto, de glebas incluídas dentro da área de interesse, ou, a
própria área de interesse.

Para criar uma área de análise, basta fazer um POST no endpoint de

analytical_report_boundaries passando como parâmetro o id da unidade e das
geometrias que se deseja utilizar como área de análise:

38
Exemplo:

{
boundaries: [1]
name: "Área de Análise da Fazenda Agrosatélite"
unit: 1
}

O campo de nome é opcional. Lembrando que o id das boundaries podem ser os

mesmos utilizados na própria área de interesse que compõem a unidade ou podem ser
ids de glebas que estão contidas dentro da área de interesse.

Uma vez criada a área de análise, passamos à criação do dossiê dessa área.

Dossiê de Área
O dossiê de uma área de análise é, portanto, um agrupamento de diferentes tipos de
relatórios para aquela área. Atualmente, possuímos na Agrosatélite apenas o dossiê
relacionado ao uso e cobertura da terra. A criação de um dossiê é bem simples, basta
passar o id da área de análise retornado pelo nosso POST e criar o nosso dossiê:

39
Exemplo:

{
analytical_report_boundary: 1
}

De posse do resultado do dossiê, podemos, então, começar a criar os nossos relatórios

de uso da terra.

Relatório de Uso da Terra

O último passo, portanto, é agora a criação do nosso relatório, que retornará uma lista
com todas as requisições referentes aos mapas de uso da terra para todos os anos
disponíveis dentro de um contrato.

A requisição para criar um relatório de uso da terra é assíncrona, devido a quantidade de

mapas que podem existir dentro de um contrato, podendo levar mais de 1 minuto para o
cálculo de interseção com todos os mapas, portanto, a requisição retornará o ID do
relatório com status de “PROCESSING”, e o usuário pode fazer a requisição para obter os
dados a qualquer momento ou criar um pooling para obter o status e requisitar o
resultado apenas quando o status estiver como “DONE”.

Para criar o relatório, o endpoint chamado é o de land_use

({host}/analytics/area_dossiers/{area_dossier_pk}/land_uses):

40
No qual, o único parâmetro necessário é enviado através da URL, que é o ID do dossiê
de área, obtido no passo anterior. O retorno é algo como:

{
"id": 1,
"requests": [],
"created_by": "xxx",
"status": "PROCESSING",
"creation_date": "2022-12-06T20:25:03.244631-03:00",
"last_modification_date": "2022-12-06T20:25:03.244665-03:00",
"is_active": true,
"area_dossier": 1
}
Retornado de maneira imediata, portanto, ainda sem resultados na lista de requests.

Para obter o resultado, pode-se fazer o GET no mesmo endpoint, mas, passando o id do
relatório (no caso do exemplo, o id 1):

41
Quando tiver concluído, teremos um retorno semelhante a:

{
"id": 1,
"requests": [
{
"id": 2,
"query": "mapa_de_soja",
"user": 1,
"sources": [{ "id": 1, "class": "boundary" }],
"query_parameters": {
"year": "2018",
"geometry": {
"type": "Polygon",
"coordinates": [
[
[-45.9976902013985, -10.193951429330966],
[-46.05881475466594, -10.295347236597365],
[-45.936565648131065, -10.393274955147831],
[-45.76890973059752, -10.379532558962907],
[-45.9976902013985, -10.193951429330966]
]
]
},
"discard_geometry": true
},
"response": {
"success": true,
"value": "63.92979970936842",
"details": {
"type": "FeatureCollection",
"features": [
{
"type": "Feature",
"properties": {
...
"intersection": {
"type": "Polygon",
"properties": {
"area_m2": 16790827,
"area_percentage": 5.266992919657305
},
"coordinates": [
[
[-45.93575972499997, -10.32990252899998],

42
 ...
]
]
}
}
},...
]
},
],
"created_by": "xxx",
"status": "DONE",
"creation_date": "2022-12-06T20:25:03.244631-03:00",
"last_modification_date": "2022-12-06T20:25:03.244665-03:00",
"is_active": true,
"area_dossier": 1
}

Assim, quando o status estiver como DONE, a resposta para o endpoint GET do uso da
terra retornará o resultado para todas as geometrias contidas na área de análise, para
todos os anos, para todos os mapas de uso da terra utilizados. Assim, com três
requisições, o usuário consegue já realizar toda a operação de captura dos dados de uso
da terra que, utilizando a opção de consulta a consulta, poderia ser feito com uma maior
morosidade.

Metódo 1 vs Método 2
A vantagem de utilizar o método 1 (de consultas separadas) é que pode-se construir um
relatório mais personalizado para cada área cadastrada, não precisando gerar dados
desnecessariamente para, por exemplo, uma área na qual deseja-se monitorar apenas
um tipo de cultura. Além disso, há ainda a vantagem de não ser um endpoint assíncrono,
obtendo o resultado de imediato, visto que é feito em um único mapa por vez.

Já o método 2 (criação do relatório de uso da terra) tem a vantagem da agilidade na

requisição, com poucas requisições pode-se obter um relatório estruturado comum em
todas as áreas analisadas, permite uma recuperação mais rápida de dado histórico, visto
que todos os relatórios de uso da terra para uma mesma área pode ser encontrada por
meio do dossiê e, por fim, não se faz necessário conhecer todos os códigos de mapa de
uso da terra nem os anos disponíveis pois tudo será feito com base nas permissões.

43
Campos Customizados

Figura 18: Endpoints de campos customizados (para cadastro/recuperação/alteração/remoção de campos

customizados)

Uma vez que se tenha os campos customizados disponíveis no ambiente do cliente, é

possível listá-los, e alterar os valores desses campos customizados nos cadastros.

Para dá valor a um campo customizado de um determinado cadastro basta utilizar os

seguintes parâmetros no JSON:

{
"value": "valor_do_campo_customizado",
"object_id": "id_do_cadastro"
}

Através do endpoint /custom_fields/{custom_field_pk}/values, no qual o

“custom_field_pk” é o identificador do campo customizado criado no ambiente do
cliente.

Esses campos customizados armazenam os valores como string e não são utilizados
para filtrar os cadastros, servem apenas para armazenar a informação.

Por ora, a criação de campos customizados fica a cargo da Agrosatélite. Em breve um

novo endpoint será disponibilizado para a criação e exclusão de novos campos
customizados.

44