# Onboarding Provedores Tracking (Ensaio)

Onboarding para novos provedores do serviço de Tracking para o Ensaio de mar/2024

# Introdução

### Tracking / Network Remote ID

Tracking, Network Remote ID, ou simplesmente Net-RID, é um serviço que permite uma aeronave não tripulada (UAS) prover sua localização, identificação de seu operador e outras informações operacionais relevantes, que podem ser obtidas por entidades autorizadas como órgãos fiscalizadores, outros provedores operando na mesma área, ou até mesmo a população em geral.

Para fornecer o serviço de Net-RID, o provedor deve ser capaz de trocar informações com outros provedores utilizando a interface definida no padrão internacional [ASTM 3411-22a - Standard Specification for Remote ID and Tracking](https://www.astm.org/f3411-22a.html). Para possibilitar a interoperabilidade dos participantes e provedores, deve ser fornecido o serviço de "Service Discovery", que permite a descoberta de outros provedores atuando na mesma área.

<div drawio-diagram="125"><img src="https://servicos2.decea.mil.br/br-utm/wiki/uploads/images/drawio/2023-12/drawing-3-1702641413.png" alt=""/></div>

Diagrama: Modelo conceitual

A ASTM também indica a seguinte documentação de API, como sugestão de interfaces para comunicação entre os serviços acima, que pode ser encontrada no padrão OpenAPI em: [https://github.com/uastech/standards/tree/astm\_rid\_api\_2.1/remoteid](https://github.com/uastech/standards/tree/astm_rid_api_2.1/remoteid)

Para nosso ensaio, seguiremos inicialmente a proposta acima, com possibilidade de alterações conforme o grupo achar necessário.

### Service Discovery

Conforme previsto no padrão ASTM F3411-22a, o service discovery deve possibilitar com que provedores descubram outros provedores atuando na mesma região, para que estes possam se comunicar. No cenário de comunicação HTTP, descobrir um provedor significa conhecer seu endereço web (url) para poder enviar requisições HTTP, em endpoints pré-definidos.

Para isso, a Linux Foundation possui um projeto chamado [InterUSS Platform](https://interussplatform.org/) que possui uma implementação do service discovery de maneira distribuída e sincronizada, denominado DSS (Discovery and Synchronization Service). Distribuído significa que várias entidades podem subir suas próprias instâncias do serviço, descentralizando e garantindo que não exista um ponto único de falha. Sincronizado significa que mesmo que haja múltiplas instâncias, todas possuem as mesmas informações ao mesmo tempo.

No escopo do ensaio, será utilizado o DSS sem nenhuma modificação inicial. Porém, para simplificação dos testes, o serviço possuirá somente uma instância, provida pelo DECEA. Isso permite que os potenciais provedores possam focar em implementar suas responsabilidades específicas e agilizar os processos do ensaio.

### Serviços BR-UTM

Seguindo a matriz de serviços que devem ser atendidos pelo BR-UTM, ao final do ensaio esperamos atender de forma completa o serviço de Discovery Service com o DSS, e o de Tracking and Location Service com o Net-RID. Também esperamos atender de forma parcial o Activity Reporting System com o Display Service do Net-RID.

<div drawio-diagram="127"><img src="https://servicos2.decea.mil.br/br-utm/wiki/uploads/images/drawio/2023-12/drawing-3-1702647159.png" alt=""/></div>

# Onboarding Service Provider

No contexto do serviço de Tracking, um Service Provider é um provedor USS que é capaz de receber dos seus drones os dados de localização em tempo real, e disponibilizar esses dados on demand em uma API também em tempo real.

### Pré-requisitos técnicos

Para um USS se tornar um provedor de Tracking existem os seguintes pré-requisitos técnicos que não estão no escopo dessa documentação, ficando a critério do provedor como implementar esses pré-requisitos:

1. Possuir um servidor HTTP para solicitar e receber as requisições listadas abaixo
2. Possuir infraestrutura para obter os dados de posição instantânea do drone. Esses dados devem estar disponíveis em tempo real no servidor HTTP

### Autenticação

Para o ensaio, a autenticação será feita em um serviço OAuth centralizado do DECEA, ainda a ser descrito.

### Fluxograma

<div drawio-diagram="173"><img src="https://servicos2.decea.mil.br/br-utm/wiki/uploads/images/drawio/2024-01/drawing-3-1704906440.png" alt=""/></div>

### Endpoints

A dinâmica de comunicação entre Service Provider, Display Provider e DSS está descrita na norma ASTM 3411-22a. Para facilitar o entendimento, alguns possíveis cenários de utilização estão descritos na página [Cenários](https://servicos2.decea.mil.br/br-utm/wiki/books/documentacao-tecnica/page/cenarios "Cenários").

O padrão seguido no ensaio será o descrito em [https://github.com/uastech/standards/tree/astm\_rid\_api\_2.1/remoteid](https://github.com/uastech/standards/tree/astm_rid_api_2.1/remoteid)

Conforme o padrão OpenAPI acima, os endpoints que o Service Provider precisará prover

---

<table border="1" class="align-center" id="bkmrk-get-%2Fuss%2Fflights" style="font-family: var(--font-body); font-size: 14px; width: 100%; height: 29.8px; border-width: 0px;"><colgroup><col style="width: 75px;"></col><col></col></colgroup><tbody><tr style="height: 29.8px;"><td style="height: 29.8px; border-width: 0px; background-clip: padding-box; color: white; border-radius: 5px; background-color: rgb(97, 175, 254);">**GET**</td><td class="align-left" style="height: 29.8px; border-width: 0px;">/uss/flights</td></tr></tbody></table>

Endpoint onde os Display Providers obterão os dados de tracking das aeronaves sob responsabilidade do Service Provider em uma determinada área

<details id="bkmrk-query-parameters-vie"><summary>Query Parameters</summary>

<table border="1" style="border-collapse: collapse; width: 100%; height: 193.969px;"><colgroup><col style="width: 33.3333%;"></col><col style="width: 33.3333%;"></col><col style="width: 33.3333%;"></col></colgroup><tbody><tr style="height: 113.781px;"><td style="height: 113.781px;">view</td><td style="height: 113.781px;">Área da solicitação, representada por dois pontos no formato `lat1,lng1,lat2,lng2`. Os pontos são as extremidades da diagonal de um quadrado, onde esse quadrado representa a área da solicitação</td><td style="height: 113.781px;">29.978,31.132,29.980,31.135</td></tr><tr style="height: 80.1875px;"><td style="height: 80.1875px;">recent\_positions\_duration</td><td style="height: 80.1875px;">Se for maior que zero, indica que a requisição deve enviar todas as posições do drone nos últimos N segundos. Valor máximo: 60.

Se for zero, indica que deve ser enviado apenas a última posição do drone

</td><td style="height: 80.1875px;">60</td></tr></tbody></table>

</details><details id="bkmrk-response-%7B-%22timestam"><summary>Response</summary>

```json
{
  "timestamp": {
    "value": "1985-04-12T23:20:50.52Z",
    "format": "RFC3339"
  },
  "flights": [
    {
      "id": "PR-333334433.0dfe0e82-fd7a-44d9-af17-7fdd42751b45",
      "aircraft_type": "Helicopter",
      "current_state": RIDAircraftState,
      "operating_area": OperatingArea,
      "simulated": false,
      "recent_positions" = [ RIDRecentAircraftPosition ]
    }
  ],
  "no_isas_present": false
}
```

<table border="1" style="border-collapse: collapse; width: 100%; height: 438.109px;"><colgroup><col style="width: 50%;"></col><col style="width: 50%;"></col></colgroup><tbody><tr style="height: 29.7969px;"><td style="height: 29.7969px;">timestamp</td><td style="height: 29.7969px;">Horário em que o Service Provider recebeu a requisição</td></tr><tr style="height: 124.953px;"><td style="height: 124.953px;">flights.id</td><td style="height: 124.953px;">ID único do provedor que identifica um voo em particular. Deverá vir no formato: "UAS\_ID.FLIGHT\_ID", onde UAS\_ID é código SISANT da aeronave, e FLIGHT\_ID é o uuid da solicitação do voo realizada no ECO-UTM.

</td></tr><tr style="height: 63.3906px;"><td style="height: 63.3906px;">flights.aircraft\_type</td><td style="height: 63.3906px;">Tipo de aeronave no padrão ICAO. Para drones, o tipo = Helicopter. Para drones de asa fixa que conseguem decolar verticalmente, o tipo = "HybridLift"</td></tr><tr style="height: 29.7969px;"><td style="height: 29.7969px;">flights.current\_state</td><td style="height: 29.7969px;">Dados do tracking de fato da aeronave, no momento atual.</td></tr><tr style="height: 63.3906px;"><td style="height: 63.3906px;">flights.operating\_area</td><td style="height: 63.3906px;">A área que a aeronave se encontra. Deve ser usado apenas quando o campo "flights.current\_state" não está preenchido.</td></tr><tr style="height: 63.3906px;"><td style="height: 63.3906px;">flights.recent\_positions</td><td style="height: 63.3906px;">Lista de posições recentes da aeronave. Deve ser informado apenas quando as "recent\_positions" foram requisitadas.</td></tr><tr style="height: 63.3906px;"><td style="height: 63.3906px;">no\_isas\_present</td><td style="height: 63.3906px;">Indica se o provedor não possui nenhuma ISA na região informada. Caso esse valor retorne verdadeiro, o requisitante deve parar de realizar requisições para a área.</td></tr></tbody></table>

</details>---

<table border="1" class="align-center" id="bkmrk-get-%2Fuss%2Fflights%2F%7Bid" style="font-family: var(--font-body); font-size: 14px; width: 100%; height: 29.7969px; border-width: 0px;"><colgroup><col style="width: 9.25926%;"></col><col style="width: 90.7407%;"></col></colgroup><tbody><tr style="height: 29.7969px;"><td style="height: 29.7969px; border-width: 0px; background-clip: padding-box; color: white; border-radius: 5px; background-color: #61affe;">**GET**</td><td class="align-left" style="height: 29.7969px; border-width: 0px;">/uss/flights/{id}/details</td></tr></tbody></table>

Endpoint onde os Display Providers obterão dados específicos de um determinado voo

<details id="bkmrk-path-parameters-id-i"><summary>Path Parameters</summary>

<table border="1" style="border-collapse: collapse; width: 100%; height: 29.7969px;"><colgroup><col style="width: 50.0642%;"></col><col style="width: 25.0321%;"></col><col style="width: 25.0321%;"></col></colgroup><tbody><tr style="height: 29.7969px;"><td style="height: 29.7969px;">id</td><td style="height: 29.7969px;">ID único do provedor para identificar o voo</td><td>b41f2785-1182-4c2e-82d5-f72f754b3fe2.0dfe0e82-fd7a-44d9-af17-7fdd42751b45</td></tr></tbody></table>

</details><details id="bkmrk-response-%7B-%22details%22"><summary>Response</summary>

```json
{
  "details": {
    "id": "b41f2785-1182-4c2e-82d5-f72f754b3fe2.0dfe0e82-fd7a-44d9-af17-7fdd42751b45",
    },
    "uas_id": {
      "registration_id": "PR-333334433",
    },
    "operator_id": "HUKMBB",
    "operator_location": {
      "position": {
        "lng": -118.456,
        "lat": 34.123
      },
      "altitude": {
        "value": 19.5,
        "reference": "W84",
        "units": "M"
      },
      "altitude_type": "Takeoff"
    },
    "operation_description": "Descrição do voo, mesma descrição informada no SARPAS"
  }
}
```

<table border="1" style="border-collapse: collapse; width: 100%; height: 178.781px;"><colgroup><col style="width: 50%;"></col><col style="width: 50%;"></col></colgroup><tbody><tr style="height: 29.7969px;"><td style="height: 29.7969px;">uas\_id</td><td style="height: 29.7969px;">Código SISANT da aeronave</td></tr><tr style="height: 29.7969px;"><td style="height: 29.7969px;">operator\_id</td><td style="height: 29.7969px;">Código SARPAS do operador</td></tr><tr style="height: 29.7969px;"><td style="height: 29.7969px;">operator\_location</td><td style="height: 29.7969px;">Localização do operador. Opcional</td></tr><tr style="height: 29.7969px;"><td style="height: 29.7969px;">operation\_description</td><td style="height: 29.7969px;">Descrição da Operação conforme solicitação no SARPAS</td></tr></tbody></table>

</details>---

<table border="1" class="align-center" id="bkmrk-get-%2Fuss%2Fidentificat" style="font-family: var(--font-body); font-size: 14px; width: 100%; height: 29.7969px; border-width: 0px;"><colgroup><col style="width: 9.25926%;"></col><col style="width: 90.7407%;"></col></colgroup><tbody><tr style="height: 29.7969px;"><td style="height: 29.7969px; border-width: 0px; background-clip: padding-box; color: white; border-radius: 5px; background-color: #61affe;">**GET**</td><td class="align-left" style="height: 29.7969px; border-width: 0px;">/uss/identification\_service\_areas/{id}</td></tr></tbody></table>

Endpoint para obter o volume 4D de uma ISA controlada pelo Service Provider

<details id="bkmrk-path-parameters-id-u"><summary>Path Parameters</summary>

<table border="1" style="border-collapse: collapse; width: 100%; height: 29.7969px;"><colgroup><col style="width: 50.0642%;"></col><col style="width: 25.0321%;"></col><col style="width: 25.0321%;"></col></colgroup><tbody><tr style="height: 29.7969px;"><td style="height: 29.7969px;">id</td><td style="height: 29.7969px;">UUID da área possuída pelo provedor</td><td>UUID</td></tr></tbody></table>

</details><details id="bkmrk-response-%7B-%22extents%22"><summary>Response</summary>

```json
{
  "extents": {
    "volume": {
      "outline_circle": {
        "center": {
          "lng": -118.456,
          "lat": 34.123
        },
        "radius": {
          "value": 300.183,
          "units": "M"
        }
      },
      "outline_polygon": {
        "vertices": [
          {
            "lng": -118.456,
            "lat": 34.123
          },
          {
            "lng": -118.456,
            "lat": 34.123
          },
          {
            "lng": -118.456,
            "lat": 34.123
          }
        ]
      },
      "altitude_lower": {
        "value": 19.5,
        "reference": "W84",
        "units": "M"
      },
      "altitude_upper": {
        "value": 19.5,
        "reference": "W84",
        "units": "M"
      }
    },
    "time_start": {
      "value": "1985-04-12T23:20:50.52Z",
      "format": "RFC3339"
    },
    "time_end": {
      "value": "1985-04-12T23:20:50.52Z",
      "format": "RFC3339"
    }
  }
}
```

<table border="1" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 50%;"></col><col style="width: 50%;"></col></colgroup><tbody><tr><td>volume</td><td>Volume 4D da área específica</td></tr></tbody></table>

</details>### Interação com DSS

O Service Provider, conforme definido no padrão ASTM3411-22a, deve criar entidades de área 4D denominadas Identification Service Area (ISA), onde este proverá o serviço de tracking. Os endpoints expostos pelo DSS estão descritos no arquivo OpenAPI descrito acima.

---

Como exemplo, o endpoint abaixo é onde o Service Provider realizará a criação da ISA no DSS:

<table border="1" class="align-center" id="bkmrk-put-%2Fdss%2Fidentificat" style="font-family: var(--font-body); font-size: 14px; width: 100%; height: 29.7969px; border-width: 0px;"><colgroup><col style="width: 9.25926%;"></col><col style="width: 90.7407%;"></col></colgroup><tbody><tr style="height: 29.7969px;"><td style="height: 29.7969px; border-width: 0px; background-clip: padding-box; color: white; border-radius: 5px; background-color: #fca130;">**PUT**</td><td class="align-left" style="height: 29.7969px; border-width: 0px;">/dss/identification\_service\_area/{id}</td></tr></tbody></table>

Endpoint exposto pelo DSS onde o Service Provider realizará a criação da ISA. Essa área deve ser idêntica à area solicitada e aprovada no Sarpas

<details id="bkmrk-path-param-id-uuid-g"><summary>Path Param</summary>

<table border="1" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 50%;"></col><col style="width: 50%;"></col></colgroup><tbody><tr><td>id</td><td>UUID da ISA. Deve ser o mesmo UUID devolvido pelo ECO-UTM após a criação da solicitação de voo.  
</td></tr></tbody></table>

</details><details id="bkmrk-body-%7B-%22extents%22%3A-%7B-"><summary>Body</summary>

```json
{
  "extents": {
    "volume": {
      "outline_circle": {
        "center": {
          "lng": -118.456,
          "lat": 34.123
        },
        "radius": {
          "value": 300.183,
          "units": "M"
        }
      },
      "outline_polygon": {
        "vertices": [
          {
            "lng": -118.456,
            "lat": 34.123
          },
          {
            "lng": -118.456,
            "lat": 34.123
          },
          {
            "lng": -118.456,
            "lat": 34.123
          }
        ]
      },
      "altitude_lower": {
        "value": 19.5,
        "reference": "W84",
        "units": "M"
      },
      "altitude_upper": {
        "value": 19.5,
        "reference": "W84",
        "units": "M"
      }
    },
    "time_start": {
      "value": "1985-04-12T23:20:50.52Z",
      "format": "RFC3339"
    },
    "time_end": {
      "value": "1985-04-12T23:20:50.52Z",
      "format": "RFC3339"
    }
  },
  "uss_base_url": "https://example.com/rid"
}
```

Campos notáveis

<table border="1" style="border-collapse: collapse; width: 100%; height: 76.3907px;"><colgroup><col style="width: 50%;"></col><col style="width: 50%;"></col></colgroup><tbody><tr style="height: 46.5938px;"><td style="height: 46.5938px;">volume</td><td style="height: 46.5938px;">Polígono **OU** círculo da área, idêntico ao definido no SARPAS</td></tr><tr style="height: 29.7969px;"><td style="height: 29.7969px;">altitude\_lower, altitude\_upper</td><td style="height: 29.7969px;">Altitude geodésica (WSG84, W84) máxima e mínima em metros.

</td></tr><tr><td>time\_start, time\_end</td><td>Horário de início e fim da área. Todos os horários devem estar no timezone Zulo (UTC+0). O único formato suportado é "RFC3339"

</td></tr><tr><td>uss\_base\_url</td><td>URL a qual o Service Provider irá responder à solicitações. Não deve conter uma barra '/' ao final. Sugere-se utilizar uma URL e não um IP.

</td></tr></tbody></table>

</details><details id="bkmrk-response-%7B-%22subscrib"><summary>Response</summary>

```json
{
  "subscribers": [],
  "service_area": {
    "uss_base_url": "https://example.com/rid",
    "owner": "myuss",
    "time_start": {
      "value": "1985-04-12T23:20:50.52Z",
      "format": "RFC3339"
    },
    "time_end": {
      "value": "1985-04-12T23:20:50.52Z",
      "format": "RFC3339"
    },
    "version": "string",
    "id": "string"
  }
}
```

Campos notáveis

<table border="1" style="border-collapse: collapse; width: 100%; height: 141.781px;"><colgroup><col style="width: 50%;"></col><col style="width: 50%;"></col></colgroup><tbody><tr style="height: 63.3906px;"><td style="height: 63.3906px;">subcribers</td><td style="height: 63.3906px;">Lista dos atuais subcribers dessa área. Caso a lista não esteja vazia, é **OBRIGATÓRIO** o envio da ISA para cada um dos subscribers listados</td></tr><tr style="height: 78.3906px;"><td style="height: 78.3906px;">version</td><td style="height: 78.3906px;">Versão da ISA, gerado pelo DSS, para garantia de integridade. É necessário utilizar esse campo para atualizar ou deletar uma ISA.</td></tr></tbody></table>

</details>

# Cadastro Service Provider

Para os **ensaios de Março/24**, os interessados em fornecer serviços deverão realizar o cadastro de seus respectivos provedores conforme mostrado abaixo. Após a aprovação do cadastro, uma API Key será disponibilizada, liberando acesso aos *endpoints* listados mais adiante.

### Cadastro

Acesse o BR-UTM Forms (URL a definir) e siga os passos:

1. Vá para a área de provedores  
    [![BR-UTM Forms - Página Inicial](https://servicos2.decea.mil.br/br-utm/wiki/uploads/images/gallery/2024-01/scaled-1680-/image.png)](https://servicos2.decea.mil.br/br-utm/wiki/uploads/images/gallery/2024-01/image.png)
2. O responsável pelo provedor cria uma conta e utiliza as mesmas credenciais para acessos futuros  
    [![BR-UTM Forms - Página de cadastro](https://servicos2.decea.mil.br/br-utm/wiki/uploads/images/gallery/2024-01/scaled-1680-/c7Rimage.png)](https://servicos2.decea.mil.br/br-utm/wiki/uploads/images/gallery/2024-01/c7Rimage.png)
3. Acesse o Dashboard  
    [![BR-UTM Forms - Página de acesso](https://servicos2.decea.mil.br/br-utm/wiki/uploads/images/gallery/2024-01/scaled-1680-/UYHimage.png)](https://servicos2.decea.mil.br/br-utm/wiki/uploads/images/gallery/2024-01/UYHimage.png)
4. No menu superior, clique em "Your Provider"; ou, nas opções do Dashboard, clique em "Register your provider"[![BR-UTM Forms - Página principal (dashboard)](https://servicos2.decea.mil.br/br-utm/wiki/uploads/images/gallery/2024-01/scaled-1680-/Knwimage.png)](https://servicos2.decea.mil.br/br-utm/wiki/uploads/images/gallery/2024-01/Knwimage.png)
5. Na tela a qual você foi redirecionado, clique em "Register". Você verá o formulário mostrado abaixo (os campos podem ser diferentes no momento do seu acesso)[![BR-UTM Forms - Página casdastro de provedor](https://servicos2.decea.mil.br/br-utm/wiki/uploads/images/gallery/2024-01/scaled-1680-/m6Himage.png)](https://servicos2.decea.mil.br/br-utm/wiki/uploads/images/gallery/2024-01/m6Himage.png)
6. Após o preenchimento correto do formulário, os dados cadastrais de seu provedor serão enviados para análise[![BR-UTM Forms - Página do provedor](https://servicos2.decea.mil.br/br-utm/wiki/uploads/images/gallery/2024-01/scaled-1680-/bUTimage.png)](https://servicos2.decea.mil.br/br-utm/wiki/uploads/images/gallery/2024-01/bUTimage.png)
7. Assim que o cadastro for aprovado, sua API Key será disponibilizada na própria página  
    [![BR-UTM Forms - Página do provedor (status aprovado)](https://servicos2.decea.mil.br/br-utm/wiki/uploads/images/gallery/2024-01/scaled-1680-/yJoimage.png)](https://servicos2.decea.mil.br/br-utm/wiki/uploads/images/gallery/2024-01/yJoimage.png)

### Uso da API Key  


Com sua API Key, você pode gerar um *token* de autenticação para realizar ações programaticamente no ECO-UTM em nome de um usuário:

1. Associe um usuário ao seu provedor, passando o SARPAS ID dele nos parâmetros e sua API Key no *header* da requisição;
2. Crie um *token* de autenticação de usuário, passando o SARPAR ID do usuário e sua API Key no *body* requisição;
3. Aprove o *token* recém-criado, passando o SARPAS ID no parâmetro da requisição.

Com ambas as chaves em mãos, você será capaz de fazer requisições nos *endpoints* listados na seção a seguir.

### Lista de endpoints  


**A lista completa de *endpoints* também está disponível [neste arquivo OpenAPI](https://servicos2.decea.mil.br/br-utm/wiki/attachments/31) e [nesta coleção no Insomina.](https://servicos2.decea.mil.br/br-utm/wiki/attachments/32)**

#### ECO-UTM

A URL base para os seguintes *endpoints* é [`http://kong.icea.decea.mil.br:64235/eco-utm/v1/`](http://kong.icea.decea.mil.br:64235/eco-utm/v1/)

---

<table border="1" class="align-center" id="bkmrk-put-%2Fdss%2Fidentificat" style="border-collapse: collapse; width: 100%; height: 29.8px; border: 0px solid rgb(206, 212, 217);"><colgroup><col style="width: 9.25926%;"></col><col style="width: 90.7407%;"></col></colgroup><tbody><tr style="height: 29.8px;"><td style="height: 29.8px; border-width: 0px; background-clip: padding-box; color: white; border-radius: 5px; background-color: rgb(252, 161, 48); border-color: rgb(206, 212, 217);">**PUT**</td><td class="align-left" style="height: 29.8px; border-width: 0px; border-color: rgb(206, 212, 217);">/providers/user\_token/{token}/assign</td></tr></tbody></table>

Associar usuário e provedor

<details id="bkmrk-path-param-id-uuid-g"><summary>Headers</summary>

<table border="1" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 50%;"></col><col style="width: 50%;"></col></colgroup><tbody><tr><td>apikey</td><td>API Key disponível no BR-UTM Forms</td></tr></tbody></table>

</details><details id="bkmrk-path-param-token-o%C2%A0t"><summary>Path Param</summary>

<table border="1" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 50%;"></col><col style="width: 50%;"></col></colgroup><tbody><tr><td>token  
</td><td>SARPAS ID do usuário</td></tr></tbody></table>

</details><details id="bkmrk-body-%7B-%22extents%22%3A-%7B-"><summary>Body</summary>

```json
{
  "data": {
    "provider_secret": "your-provider-api-key",
    "provider_id": "kong-consumer-custom-id"
    
  }
}
```

Campos notáveis

<table border="1" style="border-collapse: collapse; width: 100%; height: 220px;"><colgroup><col style="width: 50.0642%;"></col><col style="width: 50.0642%;"></col></colgroup><tbody><tr style="height: 46.6px;"><td style="height: 46.6px;">provider\_secret</td><td style="height: 46.6px;">API Key disponível no BR-UTM Forms  
</td></tr><tr style="height: 57.8px;"><td style="height: 57.8px;">provider\_id</td><td style="height: 57.8px;"><span style="color: rgb(0, 0, 0);">\[OPCIONAL\] Custom ID do Kong associado ao Consumer</span>

</td></tr></tbody></table>

</details><details id="bkmrk-response-%7B-%22subscrib"><summary>Response</summary>

<table border="1" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 50%;"></col><col style="width: 50%;"></col></colgroup><tbody><tr><td>200  
</td><td>Success  
</td></tr><tr><td>404  
</td><td>User not found</td></tr></tbody></table>

</details>---

<table border="1" class="align-center" id="bkmrk-get-%2Fuss%2Fidentificat" style="font-family: var(--font-body); font-size: 14px; width: 100%; height: 29.8px; border-width: 0px;"><colgroup><col style="width: 9.25926%;"></col><col style="width: 90.7407%;"></col></colgroup><tbody><tr style="height: 29.8px;"><td style="height: 29.8px; border-width: 0px; background-clip: padding-box; color: white; border-radius: 5px; background-color: rgb(73, 204, 144);">**POST**</td><td class="align-left" style="height: 29.8px; border-width: 0px;">/providers/auth</td></tr></tbody></table>

Gerar token de autenticação

<details id="bkmrk-headers-apikey-api-k"><summary>Headers</summary>

<table border="1" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 50%;"></col><col style="width: 50%;"></col></colgroup><tbody><tr><td>apikey</td><td>API Key disponível no BR-UTM Forms</td></tr></tbody></table>

</details><details id="bkmrk-body-%7B-%22data%22%3A-%7B-%22pr"><summary>Body</summary>

```json
{
  "data": {
    "provider_secret": "",
    "provider_id": "",
    "user_id": ""
  }
}
```

Campos notáveis

<table border="1" style="border-collapse: collapse; width: 100%; height: 139.8px;"><colgroup><col style="width: 50.0642%;"></col><col style="width: 50.0642%;"></col></colgroup><tbody><tr style="height: 46.6px;"><td style="height: 46.6px;">provider\_secret</td><td style="height: 46.6px;">API Key disponível no BR-UTM Forms  
</td></tr><tr style="height: 57.8px;"><td style="height: 57.8px;">provider\_id</td><td style="height: 57.8px;"><span style="color: rgb(224, 62, 45);"><span style="color: rgb(0, 0, 0);">\[OPCIONAL\] Custom ID do Kong associado ao Consumer</span></span>

</td></tr><tr style="height: 35.4px;"><td style="height: 35.4px;">user\_id  
</td><td style="height: 35.4px;"><span style="color: rgb(224, 62, 45);"><span style="color: rgb(0, 0, 0);">SARPAS ID do usuário</span>  
</span>

</td></tr></tbody></table>

</details><details id="bkmrk-response-%7B-%22extents%22"><summary>Response</summary>

<table border="1" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 50%;"></col><col style="width: 50%;"></col></colgroup><tbody><tr><td>204

</td><td>Success</td></tr><tr><td>404

</td><td>User not found  
</td></tr><tr><td>412

</td><td>Invalid provider and user relationship

</td></tr><tr><td>500

</td><td>Internal server error  
</td></tr></tbody></table>

</details>---

<table border="1" class="align-center" id="bkmrk-get-%2Fuss%2Fflights" style="font-family: var(--font-body); font-size: 14px; width: 100%; height: 29.8px; border-width: 0px;"><colgroup><col style="width: 75px;"></col><col></col></colgroup><tbody><tr style="height: 29.8px;"><td style="height: 29.8px; border-width: 0px; background-clip: padding-box; color: white; border-radius: 5px; background-color: rgb(97, 175, 254);">**GET**</td><td class="align-left" style="height: 29.8px; border-width: 0px;">/user-keys/{user-id}</td></tr></tbody></table>

Aprovar token de autenticação do provedor associado ao usuário

<details id="bkmrk-query-parameters-vie"><summary>Path Param</summary>

<table border="1" style="border-collapse: collapse; width: 100%; height: 193.969px;"><colgroup><col style="width: 50.0642%;"></col><col style="width: 50.0642%;"></col></colgroup><tbody><tr style="height: 113.781px;"><td style="height: 113.781px;">user-id</td><td style="height: 113.781px;"><span style="color: rgb(0, 0, 0);">SARPAR ID do usuário</span>  
</td></tr></tbody></table>

</details><details id="bkmrk-bearer-token-que-tok"><summary>Bearer</summary>

<table border="1" style="border-collapse: collapse; width: 100%; height: 193.969px;"><colgroup><col style="width: 50.0642%;"></col><col style="width: 50.0642%;"></col></colgroup><tbody><tr style="height: 113.781px;"><td style="height: 113.781px;">token</td><td style="height: 113.781px;"><span style="color: rgb(224, 62, 45);"><span style="color: rgb(0, 0, 0);">Bearer token gerado</span></span>  
</td></tr></tbody></table>

</details><details id="bkmrk-response-%7B-%22timestam"><summary>Response</summary>

<table border="1" style="border-collapse: collapse; width: 100%; height: 31.3833px;"><colgroup><col style="width: 50%;"></col><col style="width: 50%;"></col></colgroup><tbody><tr style="height: 31.3833px;"><td style="height: 31.3833px;">200</td><td style="height: 31.3833px;">Success  
</td></tr><tr><td>500  
</td><td>Error  
</td></tr></tbody></table>

</details>---

<table border="1" class="align-center" id="bkmrk-get-%2Fpilots%2Fflights" style="font-family: var(--font-body); font-size: 14px; width: 100%; height: 29.8px; border-width: 0px;"><colgroup><col style="width: 9.25926%;"></col><col style="width: 90.7407%;"></col></colgroup><tbody><tr style="height: 29.8px;"><td style="height: 29.8px; border-width: 0px; background-clip: padding-box; color: white; border-radius: 5px; background-color: rgb(73, 204, 144);">**POST**</td><td class="align-left" style="height: 29.8px; border-width: 0px;">/pilots/flights</td></tr></tbody></table>

Cria uma solicitação de voo para um espaço aéreo descrito na requisição

<details id="bkmrk-headers-apikey-api-k-1"><summary>Headers</summary>

<table border="1" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 50%;"></col><col style="width: 50%;"></col></colgroup><tbody><tr><td>apikey</td><td>API Key disponível no BR-UTM Forms</td></tr></tbody></table>

</details><details id="bkmrk-bearer-token-que-tok-1"><summary>Bearer</summary>

<table border="1" style="border-collapse: collapse; width: 100%; height: 29.8px;"><colgroup><col style="width: 50.0642%;"></col><col style="width: 50.0642%;"></col></colgroup><tbody><tr style="height: 29.8px;"><td style="height: 29.8px;">token</td><td style="height: 29.8px;">Bearer token gerado  
</td></tr></tbody></table>

</details><details id="bkmrk-body-%7B-%22data%22%3A-%7B-%22ty"><summary>Body</summary>

```json
{
    "data": {
        "type": "/pilots/flights",
        "attributes": {
            "airplane_id": "1ed0e6d9-e88e-6812-bd5f-0242ac12001c",
            "operation": {
                "aircrafts": [
                   {
                        "id": 4,
                        "uuid": "1ed0e6d9-e88e-6812-bd5f-0242ac12001c"
                   }
                ],
                "flight": {
                    "pilots": ["QGRK"],
                    "date": {
                        "start_day": "2025-12-16",
                        "start_hour": "08:00",
                        "finish_day": "2025-12-16",
                        "finish_hour": "09:00"
                    },
                    "type": "VLOS",
                    "observations": "teste",
                    "communication": {
                        "id": "1",
                        "ats_call_type": "vhf-fm",
                        "rpa_call_type": "vhf-am",
                        "rps": [
                            {
                                "name": "1",
                                "lat": "1",
                                "lng": "1",
                                "contact_info": "1",
                                "radius": 100
                            }
                        ]
                    },
                    "sarpas_code": "OJMN",
                    "area": {
                        "asa_id": "283797ce-73e9-4395-adcf-6c6119b3f20f",
                        "takeoff_point": [-34.993236064910896,-8.02209168418088],
                        "landing_point": [-34.993236064910896,-8.02209168418088],
                        "required_route": {
                            "geojson": {
      "type": "Feature",
      "properties": {},
      "geometry": {
        "type": "Polygon",
        "coordinates": [
					[
						[
							-24.080093705511494,
							-49.0539316478104
						],
						[
							-24.081153158442177,
							-49.05006533240442
						],
						[
							-24.08503406183282,
							-49.052976909391695
						],
						[
							-24.082881359600847,
							-49.055986687210066
						],
						[
							-24.080093705511494,
							-49.0539316478104
						]
					]
				]
      }
    }
                            },
                            "flight_type": "height",
                            "flight_distance": 100
                        },
                        "documents": []
                    },
                    "basic_information": {
                        "name": "teste 2",
                        "type": "101",
                        "agree_terms": 1
                    }
                }
            }
        }
    }
```

Campos notáveis

<table border="1" style="border-collapse: collapse; width: 100%; height: 139.8px;"><colgroup><col style="width: 50.0642%;"></col><col style="width: 50.0642%;"></col></colgroup><tbody><tr style="height: 46.6px;"><td style="height: 46.6px;">provider\_secret</td><td style="height: 46.6px;">API Key disponível no BR-UTM Forms  
</td></tr><tr style="height: 57.8px;"><td style="height: 57.8px;">provider\_id</td><td style="height: 57.8px;"><span style="color: rgb(224, 62, 45);"><span style="color: rgb(0, 0, 0);">\[OPCIONAL\] Custom ID do Kong associado ao Consumer</span></span>

</td></tr><tr style="height: 35.4px;"><td style="height: 35.4px;">user\_id  
</td><td style="height: 35.4px;"><span style="color: rgb(224, 62, 45);"><span style="color: rgb(0, 0, 0);">SARPAR ID do usuário</span>  
</span>

</td></tr></tbody></table>

</details><details id="bkmrk-response-%7B-%7D-%C2%A0"><summary>Response</summary>

<table border="1" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 50%;"></col><col style="width: 50%;"></col></colgroup><tbody><tr><td>200  
</td><td>Success</td></tr></tbody></table>

</details>---

<table border="1" class="align-center" id="bkmrk-get-%2Fbypass%2Fcategori" style="font-family: var(--font-body); font-size: 14px; width: 100%; height: 29.8px; border-width: 0px;"><colgroup><col style="width: 9.25926%;"></col><col style="width: 90.7407%;"></col></colgroup><tbody><tr style="height: 29.8px;"><td style="height: 29.8px; border-width: 0px; background-clip: padding-box; color: white; border-radius: 5px; background-color: rgb(97, 175, 254);">**GET**</td><td class="align-left" style="height: 29.8px; border-width: 0px;">/bypass/categorize/{solicitationProtocol}</td></tr></tbody></table>

Categoriza uma solicitação de voo por número de protocolo

<details id="bkmrk-headers-apikey-api-k-2"><summary>Headers</summary>

<table border="1" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 50%;"></col><col style="width: 50%;"></col></colgroup><tbody><tr><td>apikey</td><td>API Key disponível no BR-UTM Forms</td></tr></tbody></table>

</details><details id="bkmrk-bearer-token-que-tok-2"><summary>Bearer</summary>

<table border="1" style="border-collapse: collapse; width: 100%; height: 29.8px;"><colgroup><col style="width: 50.0642%;"></col><col style="width: 50.0642%;"></col></colgroup><tbody><tr style="height: 29.8px;"><td style="height: 29.8px;">token</td><td style="height: 29.8px;"><span style="color: rgb(0, 0, 0);">Bearer token gerado</span></td></tr></tbody></table>

</details><details id="bkmrk-path-param-solicitat"><summary>Path Param</summary>

<table border="1" style="border-collapse: collapse; width: 100%; height: 10px;"><colgroup><col style="width: 50.0642%;"></col><col style="width: 50.0642%;"></col></colgroup><tbody><tr style="height: 10px;"><td style="height: 10px;">solicitationProtocol</td><td style="height: 10px;"><span style="color: rgb(0, 0, 0);">Número de protocolo da solicitação</span></td></tr></tbody></table>

</details><details id="bkmrk-response-%7B-%7D-%C2%A0-1"><summary>Response</summary>

<table border="1" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 50%;"></col><col style="width: 50%;"></col></colgroup><tbody><tr><td>200  
</td><td>Success</td></tr><tr><td>404  
</td><td>Solicitation not found  
</td></tr><tr><td>500  
</td><td>Error  
</td></tr></tbody></table>

</details>---

<table border="1" class="align-center" id="bkmrk-get-%2Fbypass%2Fanalyze%2F" style="font-family: var(--font-body); font-size: 14px; width: 100%; height: 29.8px; border-width: 0px;"><colgroup><col style="width: 9.25926%;"></col><col style="width: 90.7407%;"></col></colgroup><tbody><tr style="height: 29.8px;"><td style="height: 29.8px; border-width: 0px; background-clip: padding-box; color: white; border-radius: 5px; background-color: rgb(97, 175, 254);">**GET**</td><td class="align-left" style="height: 29.8px; border-width: 0px;">/bypass/analyze/{solicitationProtocol}</td></tr></tbody></table>

Analisa uma solicitação de voo por número de protocolo

<details id="bkmrk-headers-apikey-api-k-3"><summary>Headers</summary>

<table border="1" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 50%;"></col><col style="width: 50%;"></col></colgroup><tbody><tr><td>apikey</td><td>API Key disponível no BR-UTM Forms</td></tr></tbody></table>

</details><details id="bkmrk-bearer-token-que-tok-3"><summary>Bearer</summary>

<table border="1" style="border-collapse: collapse; width: 100%; height: 10px;"><colgroup><col style="width: 50.0642%;"></col><col style="width: 50.0642%;"></col></colgroup><tbody><tr style="height: 10px;"><td style="height: 10px;">token</td><td style="height: 10px;"><span style="color: rgb(224, 62, 45);"><span style="color: rgb(0, 0, 0);">Bearer token gerado</span></span></td></tr></tbody></table>

</details><details id="bkmrk-path-param-solicitat-1"><summary>Path Param</summary>

<table border="1" style="border-collapse: collapse; width: 100%; height: 10px;"><colgroup><col style="width: 50.0642%;"></col><col style="width: 50.0642%;"></col></colgroup><tbody><tr style="height: 10px;"><td style="height: 10px;">solicitationProtocol</td><td style="height: 10px;"><span style="color: rgb(224, 62, 45);"><span style="color: rgb(0, 0, 0);">Número de protocolo da solicitação</span></span></td></tr></tbody></table>

</details><details id="bkmrk-response-%7B-%7D-%C2%A0-2"><summary>Response</summary>

<table border="1" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 50%;"></col><col style="width: 50%;"></col></colgroup><tbody><tr><td>200  
</td><td>Success</td></tr><tr><td>404  
</td><td>Solicitation protocol not found  
</td></tr><tr><td>500  
</td><td>Error  
</td></tr></tbody></table>

</details>---

<table border="1" class="align-center" id="bkmrk-get-%2Fuser-aircraft" style="font-family: var(--font-body); font-size: 14px; width: 100%; height: 29.8px; border-width: 0px;"><colgroup><col style="width: 9.25926%;"></col><col style="width: 90.7407%;"></col></colgroup><tbody><tr style="height: 29.8px;"><td style="height: 29.8px; border-width: 0px; background-clip: padding-box; color: white; border-radius: 5px; background-color: rgb(97, 175, 254);">**GET**</td><td class="align-left" style="height: 29.8px; border-width: 0px;">/user-aircraft  
</td></tr></tbody></table>

Busca todas as aeronaves de um usuário identificado pelo token de sessão

<details id="bkmrk-headers-apikey-api-k-4"><summary>Headers</summary>

<table border="1" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 50%;"></col><col style="width: 50%;"></col></colgroup><tbody><tr><td>apikey</td><td>API Key disponível no BR-UTM Forms</td></tr></tbody></table>

</details><details id="bkmrk-bearer-token-que-tok-4"><summary>Bearer</summary>

<table border="1" style="border-collapse: collapse; width: 100%; height: 10px;"><colgroup><col style="width: 50.0642%;"></col><col style="width: 50.0642%;"></col></colgroup><tbody><tr style="height: 10px;"><td style="height: 10px;">token</td><td style="height: 10px;"><span style="color: rgb(224, 62, 45);"><span style="color: rgb(0, 0, 0);">Bearer token gerado</span></span></td></tr></tbody></table>

</details><details id="bkmrk-response-%7B-%7D-%C2%A0-3"><summary>Response</summary>

<table border="1" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 50%;"></col><col style="width: 50%;"></col></colgroup><tbody><tr><td>200  
</td><td>Success</td></tr></tbody></table>

</details>---

<table border="1" class="align-center" id="bkmrk-get-%2Fshared-aircraft" style="font-family: var(--font-body); font-size: 14px; width: 100%; height: 29.8px; border-width: 0px;"><colgroup><col style="width: 9.25926%;"></col><col style="width: 90.7407%;"></col></colgroup><tbody><tr style="height: 29.8px;"><td style="height: 29.8px; border-width: 0px; background-clip: padding-box; color: white; border-radius: 5px; background-color: rgb(97, 175, 254);">**GET**  
</td><td class="align-left" style="height: 29.8px; border-width: 0px;">/shared-aircraft-user  
</td></tr></tbody></table>

Busca todas as aeronaves compartilhadas com um usuário identificado pelo token de sessão

<details id="bkmrk-headers-apikey-api-k-5"><summary>Headers</summary>

<table border="1" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 50%;"></col><col style="width: 50%;"></col></colgroup><tbody><tr><td>apikey</td><td>API Key disponível no BR-UTM Forms</td></tr></tbody></table>

</details><details id="bkmrk-bearer-token-que-tok-5"><summary>Bearer</summary>

<table border="1" style="border-collapse: collapse; width: 100%; height: 10px;"><colgroup><col style="width: 50.0642%;"></col><col style="width: 50.0642%;"></col></colgroup><tbody><tr style="height: 10px;"><td style="height: 10px;">token</td><td style="height: 10px;"><span style="color: rgb(0, 0, 0);">Bearer token gerado</span></td></tr></tbody></table>

</details><details id="bkmrk-response-%7B-%7D-%C2%A0-4"><summary>Response</summary>

<table border="1" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 50%;"></col><col style="width: 50%;"></col></colgroup><tbody><tr><td>200  
</td><td>Success</td></tr></tbody></table>

</details>---

<table border="1" class="align-center" id="bkmrk-post-%2Fuser%2Fflight%2Fai" style="font-family: var(--font-body); font-size: 14px; width: 100%; height: 29.8px; border-width: 0px;"><colgroup><col style="width: 9.25926%;"></col><col style="width: 90.7407%;"></col></colgroup><tbody><tr style="height: 29.8px;"><td style="height: 29.8px; border-width: 0px; background-clip: padding-box; color: white; border-radius: 5px; background-color: rgb(73, 204, 144);">**POST**</td><td class="align-left" style="height: 29.8px; border-width: 0px;">/user/flight/aircrafts</td></tr></tbody></table>

Busca todas as aeronaves em voo, opcionalmente incluindo compartilhadas, de um usuário identificado pelo ID enviado na requisição

<details id="bkmrk-headers-apikey-api-k-6"><summary>Headers</summary>

<table border="1" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 50%;"></col><col style="width: 50%;"></col></colgroup><tbody><tr><td>apikey</td><td>API Key disponível no BR-UTM Forms</td></tr></tbody></table>

</details><details id="bkmrk-bearer-token-que-tok-6"><summary>Bearer</summary>

<table border="1" style="border-collapse: collapse; width: 100%; height: 29.8px;"><colgroup><col style="width: 50.0642%;"></col><col style="width: 50.0642%;"></col></colgroup><tbody><tr style="height: 29.8px;"><td style="height: 29.8px;">token</td><td style="height: 29.8px;"><span style="color: rgb(224, 62, 45);"><span style="color: rgb(0, 0, 0);">Bearer token gerado</span></span></td></tr></tbody></table>

</details><details id="bkmrk-body-%7B-%22user_informa"><summary>Body</summary>

```json
{
  "user_information_id": "1ed4b29e-8fe0-60aa-aefd-0242ac120019",
  "shared": true
}
```

Campos notáveis

<table border="1" style="border-collapse: collapse; width: 100%; height: 139.8px;"><colgroup><col style="width: 50.0642%;"></col><col style="width: 50.0642%;"></col></colgroup><tbody><tr style="height: 46.6px;"><td style="height: 46.6px;">user\_information\_id</td><td style="height: 46.6px;"><span style="color: rgb(0, 0, 0);">SARPAS ID do usuário</span>  
</td></tr><tr><td>shared  
</td><td><span style="color: rgb(0, 0, 0);">\[OPCIONAL\] Incluir aeronaves compartilhadas  
</span></td></tr></tbody></table>

</details><details id="bkmrk-response-%7B-%7D-%C2%A0-5"><summary>Response</summary>

<table border="1" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 50%;"></col><col style="width: 50%;"></col></colgroup><tbody><tr><td>200  
</td><td>Success</td></tr></tbody></table>

</details>---

<table border="1" class="align-center" id="bkmrk-get-%2Fflight-status" style="font-family: var(--font-body); font-size: 14px; width: 100%; height: 29.8px; border-width: 0px;"><colgroup><col style="width: 9.25926%;"></col><col style="width: 90.7407%;"></col></colgroup><tbody><tr style="height: 29.8px;"><td style="height: 29.8px; border-width: 0px; background-clip: padding-box; color: white; border-radius: 5px; background-color: rgb(97, 175, 254);">**GET**  
</td><td class="align-left" style="height: 29.8px; border-width: 0px;">/flight-status  
</td></tr></tbody></table>

Lista os status do voo de um usuário identificado pelo token de sessão

<details id="bkmrk-headers-apikey-api-k-8"><summary>Headers</summary>

<table border="1" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 50%;"></col><col style="width: 50%;"></col></colgroup><tbody><tr><td>apikey</td><td>API Key disponível no BR-UTM Forms</td></tr></tbody></table>

</details><details id="bkmrk-bearer-token-que-tok-8"><summary>Bearer</summary>

<table border="1" style="border-collapse: collapse; width: 100%; height: 10px;"><colgroup><col style="width: 50.0642%;"></col><col style="width: 50.0642%;"></col></colgroup><tbody><tr style="height: 10px;"><td style="height: 10px;">token</td><td style="height: 10px;"><span style="color: rgb(0, 0, 0);">Bearer token gerado</span>  
</td></tr></tbody></table>

</details><details id="bkmrk-response-%C2%A0-1"><summary>Response</summary>

200

</details>#### ASA

A URL base para os seguintes *endpoints* é `<a href="http://kong.icea.decea.mil.br:64236/api/">http://kong.icea.decea.mil.br:64236/api/</a>`

---

<table border="1" class="align-center" id="bkmrk-post-%2Fpolygon%2F%7Bpolyg" style="font-family: var(--font-body); font-size: 14px; width: 100%; height: 29.8px; border-width: 0px;"><colgroup><col style="width: 9.25926%;"></col><col style="width: 90.7407%;"></col></colgroup><tbody><tr style="height: 29.8px;"><td style="height: 29.8px; border-width: 0px; background-clip: padding-box; color: white; border-radius: 5px; background-color: rgb(73, 204, 144);">**POST**</td><td class="align-left" style="height: 29.8px; border-width: 0px;">/polygon/{polygonId}/{userUuid}</td></tr></tbody></table>

Cria uma área no ASA dados os identificadores do polígono e usuário

<details id="bkmrk-headers-apikey-api-k-9"><summary>Headers</summary>

<table border="1" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 50%;"></col><col style="width: 50%;"></col></colgroup><tbody><tr><td>apikey</td><td>API Key disponível no BR-UTM Forms</td></tr></tbody></table>

</details><details id="bkmrk-bearer-token-que-tok-9"><summary>Bearer</summary>

<table border="1" style="border-collapse: collapse; width: 100%; height: 29.8px;"><colgroup><col style="width: 50.0642%;"></col><col style="width: 50.0642%;"></col></colgroup><tbody><tr style="height: 29.8px;"><td style="height: 29.8px;">token</td><td style="height: 29.8px;"><span style="color: rgb(0, 0, 0);">Bearer token gerado</span>  
</td></tr></tbody></table>

</details><details id="bkmrk-path-param-polygonid"><summary>Path Param</summary>

<table border="1" style="border-collapse: collapse; width: 100%; height: 10px;"><colgroup><col style="width: 50.0642%;"></col><col style="width: 50.0642%;"></col></colgroup><tbody><tr style="height: 10px;"><td style="height: 10px;">polygonId</td><td style="height: 10px;">ID (definido pelo solicitante) do polígono criado  
</td></tr><tr><td>userUuid  
</td><td>SARPAS ID do usuário  
</td></tr></tbody></table>

</details><details id="bkmrk-body-%7B-%22type%22%3A-%22feat"><summary>Body</summary>

```json
{
    "type": "Feature",
    "properties": {
      "poligonoId": "283797ce-73e9-4395-adcf-6c6119b3f20f",
      "perfil": "1",
      "datasHoras": "{\"date1\":\"2023-11-30\",\"date2\":\"2023-11-30\",\"hora1\":\"14:00\",\"hora2\":\"15:00\"}",
      "elevacoes": {
        "criarAreaMaximo": 10,
        "criarAreaMinimo": 0,
        "criarAreaMaximoFt": 32.8084,
        "criarAreaMinimoFt": 0,
        "criarAreaNome": "",
        "criarAreaDescricao": "",
        "alturaEditavelMetros": "10",
        "alturaEditavelPes": 32.8084,
        "dataInicio": "2025-12-12",
        "dataTermino": "2025-12-12",
        "horaInicio": "08:00",
        "horaTermino": "09:00",
        "update": []
      },
      "raio": 0,
      "altura": "10",
      "formato": "poligono",
      "contextoId": 1,
      "pontoDecolagem": {
        "latLng": {
          "lat": -24.098672973607677,
          "lng": -48.909985432572751,
          "valido": true
        },
        "unidade": "gms",
        "elevationM": 10,
        "elevationFt": 32.8084,
        "valido": true
      }
    },
    "geometry": {
      "type": "Polygon",
      "coordinates": [
					[
						[
							-24.080093705511494,
							-49.0539316478104
						],
						[
							-24.081153158442177,
							-49.05006533240442
						],
						[
							-24.08503406183282,
							-49.052976909391695
						],
						[
							-24.082881359600847,
							-49.055986687210066
						],
						[
							-24.080093705511494,
							-49.0539316478104
						]
					]
				]
    }
  }
```

Campos notáveis

<table border="1" style="border-collapse: collapse; width: 100%; height: 139.8px;"><colgroup><col style="width: 50.0642%;"></col><col style="width: 50.0642%;"></col></colgroup><tbody><tr style="height: 46.6px;"><td style="height: 46.6px;">  
</td><td style="height: 46.6px;"> </td></tr></tbody></table>

</details><details id="bkmrk-response-%7B-voo_id%3A-s"><summary>Response</summary>

```json
{
  voo_id: string
}
```

<table border="1" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 50.0642%;"></col><col style="width: 50.0642%;"></col></colgroup><tbody><tr><td>voo\_id</td><td>  
</td></tr></tbody></table>

</details>---

<table border="1" class="align-center" id="bkmrk-get-%2Fpolygon%2F%7Bsolici" style="font-family: var(--font-body); font-size: 14px; width: 100%; height: 29.8px; border-width: 0px;"><colgroup><col style="width: 9.25926%;"></col><col style="width: 90.7407%;"></col></colgroup><tbody><tr style="height: 29.8px;"><td style="height: 29.8px; border-width: 0px; background-clip: padding-box; color: white; border-radius: 5px; background-color: rgb(97, 175, 254);">**GET**</td><td class="align-left" style="height: 29.8px; border-width: 0px;">/polygon/{solicitationProtocol}/result</td></tr></tbody></table>

<span style="color: rgb(0, 0, 0);">Obter resultado da solicitação de área</span>

<details id="bkmrk-headers-apikey-api-k-10"><summary>Headers</summary>

<table border="1" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 50%;"></col><col style="width: 50%;"></col></colgroup><tbody><tr><td>apikey</td><td>API Key disponível no BR-UTM Forms</td></tr></tbody></table>

</details><details id="bkmrk-bearer-token-que-tok-10"><summary>Bearer</summary>

<table border="1" style="border-collapse: collapse; width: 100%; height: 10px;"><colgroup><col style="width: 50.0642%;"></col><col style="width: 50.0642%;"></col></colgroup><tbody><tr style="height: 10px;"><td style="height: 10px;">token</td><td style="height: 10px;"><span style="color: rgb(0, 0, 0);">Bearer token gerado</span>  
</td></tr></tbody></table>

</details><details id="bkmrk-path-param-solicitat-2"><summary>Path Param</summary>

<table border="1" style="border-collapse: collapse; width: 100%; height: 10px;"><colgroup><col style="width: 50.0642%;"></col><col style="width: 50.0642%;"></col></colgroup><tbody><tr style="height: 10px;"><td style="height: 10px;">solicitationProtocol</td><td style="height: 10px;">Número de protocolo da solicitação de área</td></tr></tbody></table>

</details><details id="bkmrk-response-200-ok"><summary>Response</summary>

200 OK

</details>

# Onboarding Display Provider

No contexto do serviço de Tracking, um Display Provider é um provedor USS que tem objetivo de exibir a posição de drones em tempo real para seus usuários.

### Pré-requisitos técnicos

Para um USS se tornar um provedor de display de Tracking existem os seguintes pré-requisitos técnicos que não estão no escopo dessa documentação, ficando a critério do provedor como implementar esses pré-requisitos:

1. Possuir um servidor HTTP para solicitar e receber requisições
2. Possuir App para visualização de posição de drones

### Autenticação

Para o ensaio, a autenticação será feita em um serviço OAuth centralizado do DECEA, ainda a ser descrito.

### Endpoints

A dinâmica de comunicação entre Service Provider, Display Provider e DSS está descrita na norma ASTM 3411-22a. Para facilitar o entendimento, alguns possíveis cenários de utilização estão descritos na página [Cenários](https://servicos2.decea.mil.br/br-utm/wiki/books/documentacao-tecnica/page/cenarios "Cenários").

O padrão seguido no ensaio será o descrito em [https://github.com/uastech/standards/tree/astm\_rid\_api\_2.1/remoteid](https://github.com/uastech/standards/tree/astm_rid_api_2.1/remoteid)

Conforme o padrão OpenAPI acima, os endpoints que o Display Provider precisará prover:

<table border="1" class="align-center" id="bkmrk-get-%2Fuss%2Fflights" style="font-family: var(--font-body); font-size: 14px; width: 100%; height: 29.8px; border-width: 0px;"><colgroup><col style="width: 75px;"></col><col></col></colgroup><tbody><tr style="height: 29.8px;"><td style="height: 29.8px; border-width: 0px; background-clip: padding-box; color: white; border-radius: 5px; background-color: rgb(73, 204, 144);">**POST**</td><td class="align-left" style="height: 29.8px; border-width: 0px;">/uss/identification\_service\_areas/{id}</td></tr></tbody></table>

<details id="bkmrk-path-parameters-id-u-1"><summary>Path Parameters</summary>

<table border="1" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 50%;"></col><col style="width: 50%;"></col></colgroup><tbody><tr><td>id</td><td>UUID da ISA</td></tr></tbody></table>

</details><details id="bkmrk-request-body-%7B-%22serv"><summary>Request Body</summary>

</details>### Interação com DSS

O Service Provider, conforme definido no padrão ASTM3411-22a, deve criar entidades de Subscription em uma área específica, para encontrar os atuais Service Providers, e também para receberem notificações caso novos provedores se registrem na área. Os endpoints expostos pelo DSS estão descritos no arquivo OpenAPI descrito acima.

Como exemplo, o endpoint abaixo é para criação de Subscriptions:

<table border="1" class="align-center" id="bkmrk-put-%2Fdss%2Fidentificat" style="font-family: var(--font-body); font-size: 14px; width: 100%; height: 29.7969px; border-width: 0px;"><colgroup><col style="width: 9.25926%;"></col><col style="width: 90.7407%;"></col></colgroup><tbody><tr style="height: 29.7969px;"><td style="height: 29.7969px; border-width: 0px; background-clip: padding-box; color: white; border-radius: 5px; background-color: #fca130;">**PUT**</td><td class="align-left" style="height: 29.7969px; border-width: 0px;">/dss/subscriptions/{id}</td></tr></tbody></table>

<details id="bkmrk-path-parameters-id-u"><summary>Path Parameters</summary>

<table border="1" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 50%;"></col><col style="width: 50%;"></col></colgroup><tbody><tr><td>id</td><td>UUID da Subscription, criado pelo Display Provider</td></tr></tbody></table>

</details><details id="bkmrk-request-body-%7B-%22exte"><summary>Request Body</summary>

```json
{
  "extents": {
    "volume": {
      "outline_circle": {
        "center": {
          "lng": -118.456,
          "lat": 34.123
        },
        "radius": {
          "value": 300.183,
          "units": "M"
        }
      },
      "outline_polygon": {
        "vertices": [
          {
            "lng": -118.456,
            "lat": 34.123
          },
          {
            "lng": -118.456,
            "lat": 34.123
          },
          {
            "lng": -118.456,
            "lat": 34.123
          }
        ]
      },
      "altitude_lower": {
        "value": 19.5,
        "reference": "W84",
        "units": "M"
      },
      "altitude_upper": {
        "value": 19.5,
        "reference": "W84",
        "units": "M"
      }
    },
    "time_start": {
      "value": "1985-04-12T23:20:50.52Z",
      "format": "RFC3339"
    },
    "time_end": {
      "value": "1985-04-12T23:20:50.52Z",
      "format": "RFC3339"
    }
  },
  "uss_base_url": "https://example.com/rid"
}
```

Campos notáveis

<table border="1" style="border-collapse: collapse; width: 100%; height: 76.3907px;"><colgroup><col style="width: 50%;"></col><col style="width: 50%;"></col></colgroup><tbody><tr style="height: 46.5938px;"><td style="height: 46.5938px;">volume</td><td style="height: 46.5938px;">Polígono **OU** círculo da área, idêntico ao definido no SARPAS</td></tr><tr style="height: 29.7969px;"><td style="height: 29.7969px;">altitude\_lower, altitude\_upper</td><td style="height: 29.7969px;">Altitude geodésica (WSG84, W84) máxima e mínima em metros.

</td></tr><tr><td>time\_start, time\_end</td><td>Horário de início e fim da área. Todos os horários devem estar no timezone Zulo (UTC+0). O único formato suportado é "RFC3339"

</td></tr><tr><td>uss\_base\_url</td><td>URL a qual o Service Provider irá responder à solicitações. Não deve conter uma barra '/' ao final. Sugere-se utilizar uma URL e não um IP.

</td></tr></tbody></table>

</details><details id="bkmrk-response-body-%7B-%22ser"><summary>Response Body</summary>

```json
{
  "service_areas": [],
  "subscription": {
    "id": "string",
    "uss_base_url": "https://example.com/rid",
    "owner": "myuss",
    "notification_index": 0,
    "time_end": {
      "value": "1985-04-12T23:20:50.52Z",
      "format": "RFC3339"
    },
    "time_start": {
      "value": "1985-04-12T23:20:50.52Z",
      "format": "RFC3339"
    },
    "version": "string"
  }
}
```

<table border="1" style="border-collapse: collapse; width: 100%; height: 122.984px;"><colgroup><col style="width: 50%;"></col><col style="width: 50%;"></col></colgroup><tbody><tr style="height: 63.3906px;"><td style="height: 63.3906px;">service\_areas</td><td style="height: 63.3906px;">Lista de ISAs já existentes no volume 4D. Caso a lista não esteja vazia, o Display Provider deve solicitar os dados de telemetria para as URLs definidas na lista</td></tr><tr style="height: 29.7969px;"><td style="height: 29.7969px;">version</td><td style="height: 29.7969px;">Versão da Subscription, gerado pelo DSS, para garantia de integridade. É necessário utilizar esse campo para atualizar ou deletar uma Subscription.</td></tr></tbody></table>

</details>

# Cenários

#### Cenário 1:

Apenas um Service provider e nenhum Display provider na área durante o Voo

<div drawio-diagram="255"><img src="https://servicos2.decea.mil.br/br-utm/wiki/uploads/images/drawio/2024-02/drawing-3-1709118152.png" alt=""/></div>

#### Cenário 2:

Service provider cria área onde já existe uma Subscription (Display Provider)

<div drawio-diagram="115"><img src="https://servicos2.decea.mil.br/br-utm/wiki/uploads/images/drawio/2023-12/drawing-3-1702578626.png" alt=""/></div>

#### Cenário 3:

Criação de Subscription onde já exista ISA

<div drawio-diagram="116"><img src="https://servicos2.decea.mil.br/br-utm/wiki/uploads/images/drawio/2023-12/drawing-3-1702578754.png" alt=""/></div>

#### Cenário 4:

Usuário do Display Provider deseja visualizar uma área. Nessa área já existe um Service Provider (USS 1), e durante a exibição, um novo Service Provider (USS 2) inicia operações na área. Esse cenário foi adaptado da documentação do InterUSS DSS.

<div drawio-diagram="128"><img src="https://servicos2.decea.mil.br/br-utm/wiki/uploads/images/drawio/2023-12/drawing-3-1702692143.png" alt=""/></div>