> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nekt.com/llms.txt
> Use this file to discover all available pages before exploring further.

# RastroSystem as a data source

> Bring data from RastroSystem to your Lakehouse.

RastroSystem is a Brazilian vehicle-tracking platform used by tracking companies to manage their fleet of monitored vehicles, trackers and SIM chips, their customers, installation and maintenance work orders, support tickets and billing. The connector reads your company's RastroSystem platform through its REST API v3 and brings vehicles with their last position, tracker events, geofence entries and exits, people, equipment, service orders, tickets and receivable and payable installments to your Lakehouse.

## Configuring RastroSystem as a Source

In the [Sources](https://app.nekt.ai/sources) tab, click on the "Add source" button located on the top right of your screen. Then, select the RastroSystem option from the list of connectors.

Click **Next** and you'll be prompted to add your access.

### 1. Add account access

RastroSystem has no API keys: the connector signs in with the **username and password of a RastroSystem platform user**, the same ones used to open your company's platform in the browser. Every company has its own platform address, such as `https://yourcompany.rastrosystem.com.br`.

<Tip>Create a dedicated user for Nekt instead of using a person's login, so a password change or a deactivated employee does not stop your syncs.</Tip>

<Warning>The connector reads only what this user is allowed to see. Give the user permission to list vehicles (`veiculos_ver_todos` to see every customer's vehicles), people, equipment, chips, service orders (`ordens_servico_listar`), tickets, the financial accounts (`menu_financeiro`) and the event report (`relatorios_rel_eventos`). If the user cannot read a stream you selected, the sync stops with a message naming the stream and the missing permission: grant it to the user or deselect the stream. A table is never replaced by incomplete data.</Warning>

The following configurations are available:

* **Platform URL**: the address of your company's RastroSystem platform, such as `https://yourcompany.rastrosystem.com.br`. The subdomain alone (`yourcompany`) is also accepted. Only addresses under `rastrosystem.com.br` are accepted, and the connection always uses HTTPS. Required.

* **Username**: the username of the RastroSystem user. Required.

* **Password**: the password of that user. Required.

* **Start Date**: the earliest date of vehicle events and geofence entries and exits to extract. The first sync, and every vehicle or geofence that appears later (a new vehicle, a tracker installed afterwards), is read from this date, so choose how much history you want to keep, such as the start of the year. The other tables are always extracted in full. Required, even if you do not select Vehicle Events or Geofence Events.

* **Events Lookback Days**: (Default: 2, minimum: 1) how many days are re-read before each vehicle's and geofence's sync point on every sync, so events that arrive late are not missed. Increase it if your trackers often stay out of coverage for several days (see Data Quality Considerations).

* **Requests Per Second**: (Default: 5) the maximum number of requests per second sent to RastroSystem. Keep the default unless RastroSystem asks for a lower rate.

Once you're done, click **Next**.

### 2. Select streams

Choose which data streams you want to sync. For faster extractions, select only the streams that are relevant to your analysis. You can select entire groups of streams or pick specific ones.

> Tip: The stream can be found more easily by typing its name.

<Info>Vehicle Events, Geofence Events, Person Details and Equipment Details make requests per vehicle, geofence, person or tracker. On large fleets they are the slowest streams, so select them only when you need them.</Info>

Select the streams and click **Next**.

### 3. Configure data streams

Customize how you want your data to appear in your catalog. Select the desired layer where the data will be placed, a folder to organize it inside the layer, a name for each table (which will effectively contain the fetched data) and the type of sync.

* **Layer**: choose between the existing layers on your catalog. This is where you will find your new extracted tables as the extraction runs successfully.
* **Folder**: a folder can be created inside the selected layer to group all tables being created from this new data source.
* **Table name**: we suggest a name, but feel free to customize it. You have the option to add a **prefix** to all tables at once and make this process faster!
* **Sync Type**: Vehicle Events and Geofence Events must use INCREMENTAL, which keeps the full event history and reads only new events on each sync (each vehicle and geofence keeps its own sync point). Every other stream is FULL\_TABLE: RastroSystem has no "changed since" filter, so each sync reads the current state of the registry. Read more about Sync Types [here](https://docs.nekt.com/get-started/core-concepts/types-of-sync).

<Warning>Do not use FULL\_TABLE, or a manual or additional full sync, for Vehicle Events and Geofence Events. A full sync re-reads events only from the **Start Date** and replaces the whole table: events older than the Start Date, and the entries and exits of geofences deleted in RastroSystem, are no longer available in RastroSystem and are removed from the table for good.</Warning>

Once you are done configuring, click **Next**.

### 4. Configure data source

Describe your data source for easy identification within your organization, not exceeding 140 characters.

To define your [Trigger](https://docs.nekt.com/runs/scheduling-and-triggers), consider how often you want data to be extracted from this source. This decision usually depends on how frequently you need the new table data updated (every day, once a week, or only at specific times).

Optionally, you can define some additional settings:

* Configure Delta Log Retention and determine for how long we should store old states of this table as it gets updated. Read more about this resource [here](https://docs.nekt.com/get-started/core-concepts/resource-control).
* Do not schedule an **Additional [Full Sync](https://docs.nekt.com/get-started/core-concepts/types-of-sync#additional-full-sync)** for this source if Vehicle Events or Geofence Events are selected: as explained above, it would remove from those tables every event older than the Start Date and the history of deleted geofences. The other streams already read their full state on every sync, so they do not need it.

Once you are ready, click **Next** to finalize the setup.

### 5. Check your new source

You can view your new source on the [Sources](https://app.nekt.ai/sources) page. If needed, manually trigger the source extraction by clicking on the arrow button. Once executed, your data will appear in your Catalog.

<Warning>For you to be able to see it on your [Catalog](https://app.nekt.ai/catalog), you need at least one successful source run.</Warning>

# Streams and Fields

## Available streams

The table below lists every stream, its **slug** (the exact identifier to pass when creating the source via API) and a short description.

| Stream | Slug | Description |
| - | - | - |
| Vehicles | `vehicles` | Vehicles with owner, tracker, default driver, group and last position. |
| Vehicle Events | `vehicle_events` | Tracker events (ignition, alarms, speeding and more) per vehicle. Incremental. |
| Event Types | `event_types` | Catalogue of event type codes. |
| Drivers | `drivers` | Drivers registered under each owner. |
| Vehicle Alerts | `vehicle_alerts` | Alerts configured on each vehicle. |
| People | `people` | Customers, suppliers, employees, technicians and consultants. |
| Person Details | `person_details` | Address, phones and employee data of each person. |
| Equipment | `equipment` | Trackers with their model and SIM chip. |
| Equipment Details | `equipment_details` | Online status, last contact and last position of each tracker. |
| Chips | `chips` | SIM chips used by the trackers. |
| Service Orders | `service_orders` | Installation and maintenance work orders. |
| Tickets | `tickets` | Customer support tickets. |
| Accounts Receivable | `accounts_receivable` | Installments to receive from customers. |
| Accounts Payable | `accounts_payable` | Installments to pay. |
| Geofences | `geofences` | Virtual fences and their linked vehicles. |
| Geofence Events | `geofence_events` | Entries into and exits from each geofence. Incremental. |
| Points of Interest | `points_of_interest` | Points of interest of the route planner. |
| Routes | `routes` | Planned routes with stops and vehicles. |

## Fields by stream

Small references (such as the owner or the vehicle group) are split into `_id` and `_nome` or `_descricao` columns, and the last position into `posicao_*` columns. Lists and free-form structures (geofence geometry, phone lists, device configuration, route stops) are JSON strings.

<AccordionGroup>
  <Accordion title="Vehicles">
    One row per vehicle, with its owner, tracker, default driver, group and the last position reported by the tracker.

    Primary key: `id`

    | Field | Type | Description |
    | :- | :- | :- |
    | `id` | Integer | Unique identifier of the vehicle. |
    | `placa` | String | License plate of the vehicle. |
    | `marca` | String | Vehicle make (brand). |
    | `modelo` | String | Vehicle model. |
    | `cor` | String | Vehicle color. |
    | `chassi` | String | Chassis number (VIN). |
    | `renavam` | String | RENAVAM registration number. |
    | `ano_modelo` | String | Model year. |
    | `ano_fabricacao` | String | Manufacturing year. |
    | `tipo_id` | Integer | Identifier of the vehicle type (car, motorcycle, truck, ...). |
    | `tipo_descricao` | String | Name of the vehicle type (car, motorcycle, truck, ...). |
    | `combustivel_key` | Integer | Numeric code of the fuel type. |
    | `combustivel_descricao` | String | Fuel type. |
    | `transmissao` | String | Transmission: M = manual, A = automatic. |
    | `status` | Integer | Vehicle status: 0 = inactive, 1 = active, 2 = in default (overdue). |
    | `pessoa_id` | Integer | Identifier of the person who owns the vehicle (titular). |
    | `pessoa_nome` | String | Name of the person who owns the vehicle (titular). |
    | `equipamento_id` | Integer | Identifier of the tracker installed in the vehicle (null when none). |
    | `equipamento_imei` | String | IMEI of the tracker installed in the vehicle. |
    | `posicao_latitude` | Number | Latitude of the last position reported by the tracker. |
    | `posicao_longitude` | Number | Longitude of the last position reported by the tracker. |
    | `posicao_endereco` | String | Street address of the last position, when RastroSystem resolved it. |
    | `posicao_data` | Datetime | Time of the last position as reported by the tracker device. |
    | `posicao_velocidade` | Number | Speed at the last position, in km/h. |
    | `posicao_curso` | Number | Heading at the last position, in degrees. |
    | `posicao_ignicao` | Boolean | Whether the ignition was on at the last position. |
    | `posicao_valida` | Boolean | Whether the GPS fix of the last position is reliable (false means the coordinate exists but should not be trusted). |
    | `odometro` | Number | Odometer in km: the tracker reading when available, otherwise the vehicle's accumulated total. |
    | `motorista_id` | Integer | Identifier of the default driver of the vehicle. |
    | `motorista_nome` | String | Name of the default driver of the vehicle. |
    | `grupo_id` | Integer | Identifier of the vehicle group. |
    | `grupo_descricao` | String | Name of the vehicle group. |
    | `cod_frota` | String | Fleet code of the vehicle. |
    | `id_externo` | String | Identifier of the vehicle in an external system. |
  </Accordion>

  <Accordion title="Vehicle Events">
    Events reported by each vehicle's tracker (ignition on/off, alarms, speeding and the other types listed in Event Types), read in date windows with one sync point per vehicle. Vehicles without a tracker are not queried.

    Primary key: `veiculo_id`, `id` · Replication key: `data_hora`

    | Field | Type | Description |
    | :- | :- | :- |
    | `veiculo_id` | Integer | Identifier of the vehicle of the event. |
    | `id` | Integer | Unique identifier of the event. |
    | `tipo` | String | Event type code (e.g. acc\_on, acc\_off); see the event\_types stream. |
    | `descricao` | String | Description of the event type. |
    | `data_hora` | Datetime | Date and time of the event, in the account's time zone. Used as the incremental replication key. |
    | `ignicao` | Boolean | Ignition state reported by the tracker with the event, when available. |
    | `latitude` | Number | Latitude where the event happened. |
    | `longitude` | Number | Longitude where the event happened. |
    | `endereco` | String | Street address of the event. |
  </Accordion>

  <Accordion title="Event Types">
    Catalogue of the event type codes used in Vehicle Events.

    Primary key: `tipo`

    | Field | Type | Description |
    | :- | :- | :- |
    | `tipo` | String | Event type code (e.g. acc\_on). |
    | `descricao` | String | Description of the event type (e.g. Ignição Ligada). |
  </Accordion>

  <Accordion title="Drivers">
    Drivers registered under each owner.

    Primary key: `id`

    | Field | Type | Description |
    | :- | :- | :- |
    | `id` | Integer | Unique identifier of the driver. |
    | `nome` | String | Name of the driver. |
    | `numero_cnh` | String | Driver's license (CNH) number. |
    | `categoria` | String | Driver's license category. |
    | `data_emissao` | Date | Issue date of the driver's license. |
    | `validade_cnh` | Date | Expiry date of the driver's license. |
    | `numero_cartao` | String | Driver identification card number. |
    | `telefone` | String | Phone number of the driver. |
    | `whatsapp` | Boolean | Whether the phone number uses WhatsApp. |
    | `pessoa_id` | Integer | Identifier of the person (owner) the driver belongs to. |
    | `pessoa_nome` | String | Name of the person (owner) the driver belongs to. |
  </Accordion>

  <Accordion title="Vehicle Alerts">
    One row per alert configured on a vehicle.

    Primary key: `veiculo_id`, `id`

    | Field | Type | Description |
    | :- | :- | :- |
    | `veiculo_id` | Integer | Identifier of the vehicle the alert is on. |
    | `veiculo_placa` | String | License plate of the vehicle. |
    | `veiculo_nome` | String | Display name of the vehicle. |
    | `id` | Integer | Identifier of the alert. |
    | `tipo` | Integer | Legacy numeric code of the alert type. |
    | `tipo_evento` | String | Event that triggers the alert (e.g. acc\_on, low\_battery, over\_speed). |
    | `descricao` | String | Description of the alert. |
    | `atributos` | String | Alert parameters such as thresholds or radius, which vary by type (JSON object). |
    | `habilitado` | Boolean | Whether the alert is enabled. |
    | `disparado` | Boolean | Whether the alert was firing at the time of the sync. |
  </Accordion>

  <Accordion title="People">
    Customers, suppliers, employees, technicians, consultants and other people registered in the platform.

    Primary key: `id`

    | Field | Type | Description |
    | :- | :- | :- |
    | `id` | Integer | Unique identifier of the person. |
    | `nome` | String | Full name or company name. |
    | `apelido_fantasia` | String | Nickname or trade name (nome fantasia). |
    | `cnpj_cpf` | String | CPF or CNPJ document number. |
    | `tipo_pessoa` | Integer | Person type: 1 = individual (física), 2 = company (jurídica). |
    | `status` | Integer | Status: 0 = inactive, 1 = active, 2 = in default (overdue), 3 = trial. |
    | `email` | String | E-mail address. |
    | `codigo` | String | Person code; for platform customers, their RastroSystem domain. |
    | `categoria_id` | Integer | Identifier of the person category (customer, consultant, technician, ...). |
    | `categoria_descricao` | String | Name of the person category (customer, consultant, technician, ...). |
    | `grupo_id` | Integer | Identifier of the person group. |
    | `grupo_descricao` | String | Name of the person group. |
    | `consultor_id` | Integer | Identifier of the sales consultant responsible for the person. |
    | `consultor_nome` | String | Name of the sales consultant responsible for the person. |
    | `id_externo` | String | Identifier of the person in an external system. |
    | `data_atualizacao` | Datetime | Date and time of the last change to the record. |
    | `telefone` | String | First phone number of the person. |
    | `informacoes_contratuais` | String | Employment data (role, admission and dismissal dates, salary, workload) for employees and consultants, when the user may see it (JSON object). |
  </Accordion>

  <Accordion title="Person Details">
    Address, phone list and employee data of each person. One request per person, so select it only when you need these fields.

    Primary key: `id`

    | Field | Type | Description |
    | :- | :- | :- |
    | `id` | Integer | Unique identifier of the person. |
    | `nome` | String | Full name or company name. |
    | `telefones` | String | Phone numbers with their WhatsApp/SMS notification flags (JSON array of objects). |
    | `endereco_id` | Integer | Identifier of the address. |
    | `endereco_logradouro` | String | Street of the address. |
    | `endereco_numero` | String | Street number. |
    | `endereco_complemento` | String | Address complement. |
    | `endereco_bairro` | String | Neighborhood. |
    | `endereco_cidade` | String | City. |
    | `endereco_uf` | String | State (UF). |
    | `endereco_cep` | String | Postal code (CEP). |
    | `ctps` | String | Work card (CTPS) number of the employee. |
    | `funcao` | String | Role of the employee. |
    | `data_admissao` | Date | Admission date of the employee. |
    | `data_demissao` | Date | Dismissal date of the employee. |
    | `salario` | Number | Salary of the employee. |
    | `carga_horaria` | Integer | Contracted workload of the employee. |
    | `comissao_rec` | Number | Recurring commission of the employee. |
    | `comissao_porcentagem` | Number | Commission percentage of the employee. |
    | `data_atualizacao` | Datetime | Date and time of the last change to the record. |
  </Accordion>

  <Accordion title="Equipment">
    Trackers (equipment) with their model and SIM chip.

    Primary key: `id`

    | Field | Type | Description |
    | :- | :- | :- |
    | `id` | Integer | Unique identifier of the tracker. |
    | `imei` | String | IMEI of the tracker. |
    | `modelo_id` | Integer | Identifier of the tracker model. |
    | `modelo_descricao` | String | Name of the tracker model. |
    | `modelo_fabricante` | String | Manufacturer of the tracker model. |
    | `chip_id` | Integer | Identifier of the SIM chip installed. |
    | `chip_numero` | String | Line number of the SIM chip. |
    | `chip_serial` | String | ICCID (serial) of the SIM chip. |
    | `chip_operadora` | String | Carrier of the SIM chip. |
    | `inativo` | Boolean | Whether the tracker is inactive. |
  </Accordion>

  <Accordion title="Equipment Details">
    Online status, last contact with the server, stock location, last position and device configuration of each tracker. One request per tracker.

    Primary key: `id`

    | Field | Type | Description |
    | :- | :- | :- |
    | `id` | Integer | Unique identifier of the tracker. |
    | `imei` | String | IMEI of the tracker. |
    | `estoque_id` | Integer | Identifier of the stock location of the tracker. |
    | `estoque_descricao` | String | Name of the stock location of the tracker. |
    | `em_transferencia` | Boolean | Whether the tracker is being transferred between stocks. |
    | `online` | Boolean | Whether the tracker was online at the time of the sync. |
    | `ultima_comunicacao` | Datetime | Last time the tracker talked to the server (different from posicao\_data, which is the time reported by the device). |
    | `posicao_latitude` | Number | Latitude of the last position reported by the tracker. |
    | `posicao_longitude` | Number | Longitude of the last position reported by the tracker. |
    | `posicao_endereco` | String | Street address of the last position, when RastroSystem resolved it. |
    | `posicao_data` | Datetime | Time of the last position as reported by the tracker device. |
    | `posicao_velocidade` | Number | Speed at the last position, in km/h. |
    | `posicao_curso` | Number | Heading at the last position, in degrees. |
    | `posicao_ignicao` | Boolean | Whether the ignition was on at the last position. |
    | `posicao_valida` | Boolean | Whether the GPS fix of the last position is reliable (false means the coordinate exists but should not be trusted). |
    | `attributes` | String | Device configuration; keys vary by tracker model (JSON object). |
  </Accordion>

  <Accordion title="Chips">
    SIM chips (data lines) used by the trackers.

    Primary key: `id`

    | Field | Type | Description |
    | :- | :- | :- |
    | `id` | Integer | Unique identifier of the SIM chip. |
    | `numero` | String | Line (phone) number of the chip. |
    | `serial` | String | ICCID (serial) of the chip. |
    | `operadora` | String | Carrier of the chip. |
    | `status` | String | Chip status: ativo, desativado or cancelado. |
  </Accordion>

  <Accordion title="Service Orders">
    Installation and maintenance work orders, with customer, technician, consultant, vehicle, status and dates.

    Primary key: `id`

    | Field | Type | Description |
    | :- | :- | :- |
    | `id` | Integer | Unique identifier of the service order. |
    | `numero` | String | Service order number (e.g. 0123/2026). |
    | `servico_id` | Integer | Identifier of the service category (type of the order). |
    | `servico_descricao` | String | Name of the service category (type of the order). |
    | `descricao` | String | Description of the service. |
    | `observacao` | String | Free-text notes, where the opening and cancellation reasons are recorded. |
    | `valor` | Number | Value of the service order. |
    | `duracao_servico_segundos` | Integer | Estimated duration of the service, in seconds. |
    | `criado_por_id` | Integer | Identifier of the user who opened the order. |
    | `criado_por_descricao` | String | Name of the user who opened the order. |
    | `cliente_id` | Integer | Identifier of the customer. |
    | `cliente_nome` | String | Name of the customer. |
    | `cliente_grupo_id` | Integer | Identifier of the internal group (unit/sector) of the customer. |
    | `cliente_grupo_descricao` | String | Name of the internal group (unit/sector) of the customer. |
    | `tecnico_id` | Integer | Identifier of the technician. |
    | `tecnico_nome` | String | Name of the technician. |
    | `tecnico_grupo_id` | Integer | Identifier of the internal group (unit/sector) of the technician. |
    | `tecnico_grupo_descricao` | String | Name of the internal group (unit/sector) of the technician. |
    | `consultor_id` | Integer | Identifier of the consultant. |
    | `consultor_nome` | String | Name of the consultant. |
    | `consultor_grupo_id` | Integer | Identifier of the internal group (unit/sector) of the consultant. |
    | `consultor_grupo_descricao` | String | Name of the internal group (unit/sector) of the consultant. |
    | `veiculo_id` | Integer | Identifier of the vehicle serviced. |
    | `veiculo_descricao` | String | Description of the vehicle as recorded on the order. |
    | `veiculo_placa` | String | License plate of the vehicle. |
    | `veiculo_chassi` | String | Chassis number of the vehicle. |
    | `veiculo_imei` | String | IMEI of the tracker linked to the order. |
    | `veiculo_modelo_equipamento` | String | Model of the tracker. |
    | `veiculo_grupo_id` | Integer | Identifier of the vehicle group. |
    | `veiculo_grupo_descricao` | String | Name of the vehicle group. |
    | `veiculo_local_instalacao` | String | Where the tracker is installed in the vehicle. |
    | `status_id` | Integer | Identifier of the status of the order. |
    | `status_descricao` | String | Name of the status of the order. |
    | `prioridade_id` | Integer | Identifier of the priority of the order. |
    | `prioridade_descricao` | String | Name of the priority of the order. |
    | `endereco` | String | Address where the service is done. |
    | `criado` | Datetime | Date and time the order was created. |
    | `data_agendamento` | Datetime | Scheduled date and time. |
    | `data_iniciada` | Datetime | First time the order moved to a started status. |
    | `data_finalizacao` | Datetime | Completion date and time; null when the order is not currently completed (also after being reopened or cancelled). |
  </Accordion>

  <Accordion title="Tickets">
    Customer support tickets (atendimentos) with their project, status, priority and responsible user.

    Primary key: `id`

    | Field | Type | Description |
    | :- | :- | :- |
    | `id` | Integer | Unique identifier of the ticket. |
    | `protocolo` | String | Protocol number of the ticket. |
    | `titulo` | String | Title of the ticket. |
    | `cliente_id` | Integer | Identifier of the customer. |
    | `cliente_nome` | String | Name of the customer. |
    | `cliente_codigo` | String | Customer code (their RastroSystem platform domain). |
    | `projeto_id` | Integer | Identifier of the project. |
    | `projeto_nome` | String | Name of the project. |
    | `projeto_finalizado` | Boolean | Whether the project is finished. |
    | `status_id` | Integer | Identifier of the ticket status. |
    | `status_descricao` | String | Name of the ticket status. |
    | `status_finalizado` | Boolean | Whether the status closes the ticket. |
    | `prioridade_id` | Integer | Identifier of the ticket priority. |
    | `prioridade_descricao` | String | Name of the ticket priority. |
    | `responsavel_destino_id` | Integer | Identifier of the user responsible for the ticket. |
    | `responsavel_destino_nome` | String | Name of the user responsible for the ticket. |
    | `criado` | Datetime | Date and time the ticket was opened. |
    | `modificado` | Datetime | Date and time of the last change. |
    | `data_encerramento` | Datetime | Date and time the ticket was closed. |
  </Accordion>

  <Accordion title="Accounts Receivable">
    Installments the company has to receive from its customers, with amounts, due and payment dates and payment links.

    Primary key: `id`

    | Field | Type | Description |
    | :- | :- | :- |
    | `id` | Integer | Unique identifier of the installment. |
    | `conta_id` | Integer | Identifier of the bill the installment belongs to. |
    | `descricao` | String | Description of the bill. |
    | `pessoa_id` | Integer | Identifier of the person the bill is from or to (titular). |
    | `pessoa_nome` | String | Name of the person the bill is from or to (titular). |
    | `parcela` | String | Installment position, e.g. 3 de 12. |
    | `valor` | Number | Amount of the installment. |
    | `valor_pago` | Number | Amount paid. |
    | `status` | String | Payment status: pago, aberto or vencido. |
    | `vencido` | Boolean | Whether the installment is overdue. |
    | `data_vencimento` | Datetime | Due date. |
    | `data_pagamento` | Date | Payment date. |
    | `forma_pagamento` | String | Payment method. |
    | `link_boleto` | String | Link to the bank slip (boleto). |
    | `linha_digitavel` | String | Typeable line (barcode) of the bank slip. |
    | `qrcode` | String | Pix QR code of the installment. |
    | `baixa_manual` | Boolean | Whether the installment was marked as paid manually. |
  </Accordion>

  <Accordion title="Accounts Payable">
    Installments the company has to pay.

    Primary key: `id`

    | Field | Type | Description |
    | :- | :- | :- |
    | `id` | Integer | Unique identifier of the installment. |
    | `conta_id` | Integer | Identifier of the bill the installment belongs to. |
    | `descricao` | String | Description of the bill. |
    | `pessoa_id` | Integer | Identifier of the person the bill is from or to (titular). |
    | `pessoa_nome` | String | Name of the person the bill is from or to (titular). |
    | `parcela` | String | Installment position, e.g. 3 de 12. |
    | `valor` | Number | Amount of the installment. |
    | `valor_pago` | Number | Amount paid. |
    | `status` | String | Payment status: pago, aberto or vencido. |
    | `vencido` | Boolean | Whether the installment is overdue. |
    | `data_vencimento` | Datetime | Due date. |
    | `data_pagamento` | Date | Payment date. |
    | `forma_pagamento` | String | Payment method. |
    | `link_boleto` | String | Link to the bank slip (boleto). |
    | `linha_digitavel` | String | Typeable line (barcode) of the bank slip. |
    | `qrcode` | String | Pix QR code of the installment. |
    | `baixa_manual` | Boolean | Whether the installment was marked as paid manually. |
  </Accordion>

  <Accordion title="Geofences">
    Virtual fences (polygons or circles) and the vehicles linked to them.

    Primary key: `id`

    | Field | Type | Description |
    | :- | :- | :- |
    | `id` | Integer | Unique identifier of the geofence. |
    | `nome` | String | Name of the geofence. |
    | `dono_id` | Integer | Identifier of the person who owns the geofence. |
    | `dono_nome` | String | Name of the person who owns the geofence. |
    | `geometria_tipo` | String | Shape of the geofence: poligono (polygon) or circulo (circle). |
    | `geometria` | String | Geometry of the geofence: polygon points, or circle center and radius in meters (JSON object). |
    | `alerta_entrada` | Boolean | Whether entering the geofence alerts. |
    | `alerta_saida` | Boolean | Whether leaving the geofence alerts. |
    | `qtd_veiculos` | Integer | Number of vehicles linked to the geofence. |
    | `veiculos` | String | Vehicles linked to the geofence with plate, fleet code and IMEI (JSON array). |
  </Accordion>

  <Accordion title="Geofence Events">
    Entries into and exits from each geofence, read in date windows with one sync point per geofence.

    Primary key: `cerca_id`, `id` · Replication key: `data_hora`

    | Field | Type | Description |
    | :- | :- | :- |
    | `cerca_id` | Integer | Identifier of the geofence. |
    | `cerca_nome` | String | Name of the geofence. |
    | `id` | Integer | Unique identifier of the passage. |
    | `veiculo_id` | Integer | Identifier of the vehicle. |
    | `veiculo_placa` | String | License plate of the vehicle. |
    | `veiculo_cod_frota` | String | Fleet code of the vehicle. |
    | `tipo` | String | Passage type: entrada (entry) or saida (exit). |
    | `data_hora` | Datetime | Date and time of the passage, in the account's time zone. Used as the incremental replication key. |
    | `latitude` | Number | Latitude of the passage. |
    | `longitude` | Number | Longitude of the passage. |
  </Accordion>

  <Accordion title="Points of Interest">
    Points of interest registered for the route planner.

    Primary key: `id`

    | Field | Type | Description |
    | :- | :- | :- |
    | `id` | Integer | Unique identifier of the point. |
    | `nome` | String | Name of the point. |
    | `grupo` | String | Group the point belongs to. |
    | `latitude` | Number | Latitude of the point. |
    | `longitude` | Number | Longitude of the point. |
    | `raio_metros` | Integer | Radius of the point, in meters. |
    | `desejavel` | Boolean | Whether the point is desirable (true) or undesirable (false) on a route. |
    | `cor` | String | Marker color on the map (hexadecimal). |
    | `endereco` | String | Street address of the point. |
    | `dono_id` | Integer | Identifier of the person who owns the point. |
    | `dono_nome` | String | Name of the person who owns the point. |
  </Accordion>

  <Accordion title="Routes">
    Planned routes with their stops and vehicles.

    Primary key: `id`

    | Field | Type | Description |
    | :- | :- | :- |
    | `id` | Integer | Unique identifier of the route. |
    | `nome` | String | Name of the route. |
    | `criado` | Datetime | Date and time the route was created. |
    | `qtd_paradas` | Integer | Number of stops in the route. |
    | `paradas` | String | Stops in order, with sequence, interval and point of interest (JSON array). |
    | `veiculos` | String | Vehicles linked to the route with their start time (JSON array). |
  </Accordion>
</AccordionGroup>

## Implementation Notes

### Data Quality Considerations

* Event dates (`data_hora`) and the dates sent to RastroSystem follow the time zone configured in your RastroSystem account.
* RastroSystem returns a tracker's events only since it was last moved from another vehicle, so a reused tracker does not carry the previous vehicle's history.
* When a geofence is deleted in RastroSystem, its entry and exit history can no longer be read; rows already in your Lakehouse are kept by INCREMENTAL syncs and lost on a full sync.
* Each vehicle and geofence keeps its own sync point. A vehicle or geofence seen for the first time is read from the Start Date; every sync then reads from its sync point minus **Events Lookback Days**.
* Trackers that lose coverage store their events and upload them later with the original date and time, so a sync point never moves past the point where late events can still arrive:
  * **Vehicles**: the sync point is the newest event already read. A vehicle with no new events moves at most to the day of its tracker's last reported position, never to "today" (a position dated in the future is ignored). When the tracker comes back and uploads what it stored, those events are read on the next sync.
  * **Geofences**: a geofence collects entries and exits of many vehicles, so after every sync its sync point is set to 30 days ago, with or without recent movement. Entries and exits uploaded up to 30 days late are read, at the cost of re-reading about the last 30 days of each geofence on every sync. The first sync of a geofence still reads from the Start Date.
* If a tracker returns from a long outage and sends a live event before uploading what it stored, and a sync runs in between, stored events older than that live event minus **Events Lookback Days** are not read. Increase **Events Lookback Days** if your fleet has trackers that stay out of coverage for long periods.
* Vehicles without a tracker have no events and are not queried. When a tracker is installed, the vehicle's events are read from the Start Date on the next sync.
* If the user is not allowed to read the events of some vehicles, those vehicles are skipped with one warning in the run log and their sync point is kept, so their events are read once access is granted. The warning repeats on every sync while the access is missing.
* The `posicao_*` columns of Vehicles and Equipment Details are a snapshot of the last position at sync time. For the history, use Vehicle Events.

### API Limits & Performance

* Vehicle Events, Geofence Events, Person Details and Equipment Details make requests per record, so their extraction time grows with the size of the fleet.
* Events are requested in windows of 30 days; RastroSystem accepts at most 31 days per request.
* If RastroSystem answers with an error page or an unexpected response, the connector retries a few times and then stops the sync, so a table is never replaced by incomplete data.
* The connector sends at most 5 requests per second by default and waits when RastroSystem asks it to slow down.

## Troubleshooting

| Error or symptom | What it means | What to do |
| :- | :- | :- |
| The run fails saying the username or password was rejected | RastroSystem did not accept the sign-in. | Check the username, the password and that the Platform URL is your company's address, then update the source. |
| The run fails saying the platform is blocked | RastroSystem reports the platform as blocked, usually for a pending payment. | Contact RastroSystem support to unblock the platform. |
| The sync stops saying the user is not allowed to read a stream | The RastroSystem user lacks the permission named in the message. | Grant the permission to the user in RastroSystem, or deselect the stream. |
| The sync stops saying the Platform URL is not a RastroSystem address, or that RastroSystem could not be reached | The Platform URL is not your company's `rastrosystem.com.br` address. | Fix the Platform URL in the source settings. |
| A warning says some vehicles' events could not be read | The user lacks `relatorios_rel_eventos` or access to those vehicles. | Grant the permission; the skipped vehicles catch up from where they stopped. |
| Vehicle Events is empty for a vehicle | The vehicle has no tracker. | Install or link a tracker to the vehicle in RastroSystem. |
| Fewer vehicles or service orders than in the platform | Without `veiculos_ver_todos` the user sees only its own customer's records. | Grant `veiculos_ver_todos` to the user. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.