# [Remote ID] Onboarding Service Provider

No contexto do serviço de Network RemoteID, 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. A especificação a ser seguida está definida pela ASTM F3411-22a. Ainda não foi definido a obrigatoriedade do item 4.4 "*Broadcast Remote ID".* Portanto, nessa página apenas será definido o uso dos itens 4.5 em diante.

### 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

### 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/dp-icea/Protocols/tree/main/remoteid](https://github.com/dp-icea/Protocols/tree/main/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>