Skip to main content

Gestão de Viagens (Trips)

O módulo de viagens foi projetado para Transportadoras, Embarcadores e Operadores de Frota registrarem e rastrearem a locomoção de cargas entre pontos de coleta (origem) e entrega (destino). As requisições são processadas em lote (batch) para alta performance.

Status da Viagem​

O campo status reflete o ciclo de vida de cada viagem:

StatusQuando ocorre
PLANNEDViagem criada — motorista ainda não iniciou
IN_TRANSITViagem iniciada — motorista a caminho do destino
CHECKED_INCheck-in realizado no terminal de destino. Atribuído automaticamente pelo servidor GateIn ao confirmar o check-in
ON_GOINGMotorista passou pela cancela e está em operação no terminal. Atribuído pelo servidor do terminal via PUT /api/v1/trips ao confirmar a passagem
COMPLETEDOperação encerrada
DELETEDViagem cancelada/removida
note

Assim como nos agendamentos, o status CHECKED_IN é definido automaticamente. Já o ON_GOING deve ser aplicado pelo servidor do terminal após confirmar que o veículo passou pela cancela.

Schemas​

Driver​

note

Os campos marcados com * são obrigatórios.

CampoTipoDescrição
*tax_idstringCPF ou CNPJ do motorista (apenas números)
*driver_license_numberstringNúmero da CNH
*license_categorystringCategoria de habilitação (ex: C, D, E)

Trip​

CampoTipoDescrição
*refstringReferência única da viagem no seu TMS/ERP (ex: número do MDF-e ou CT-e). Usada em todas as consultas e atualizações
*layout_refstringCódigo do layout dinâmico de viagem (card e modal) associado. Define como a viagem é exibida no app do motorista
license_platestringPlaca do caminhão/carreta
summarystringObservações ou detalhes adicionais da rota
window_startstring ISO-8601Início previsto da viagem
window_endstring ISO-8601Término previsto
start_toleranceintegerMargem de tolerância em minutos antes do início (default: 0)
end_toleranceintegerMargem de tolerância em minutos após o término (default: 0)
custom_dataobjectMetadados dinâmicos estruturados da viagem

Dados Geográficos de Origem​

CampoTipoDescrição
from_locationstringDescrição textual da origem (ex: Fábrica de Cimento Votorantim)
origin_streetstringNome da rua/avenida
origin_numberstringNúmero predial
origin_citystringCidade
origin_statestringEstado (sigla com 2 caracteres, ex: SP)
origin_countrystringPaís
origin_zipstringCEP (apenas números)
origin_latfloatLatitude para geofencing (ex: -20.1219)
origin_lngfloatLongitude para geofencing (ex: -44.1997)

Dados Geográficos de Destino​

CampoTipoDescrição
to_locationstringDescrição textual do destino (ex: Centro de Distribuição Cajamar)
destiny_streetstringNome da rua/avenida
destiny_numberstringNúmero predial
destiny_citystringCidade
destiny_statestringEstado (sigla com 2 caracteres)
destiny_countrystringPaís
destiny_zipstringCEP (apenas números)
destiny_latfloatLatitude do destino
destiny_lngfloatLongitude do destino

Criar Viagem(ns) (POST)​

Endpoint: POST /api/v1/trips — 201 Created

note

Este endpoint aceita tanto um único objeto quanto uma lista (array) de objetos para criação em lote.

Regras de Negócio​

Importante:

  • Fail-Fast (Chaves Duplicadas): Se algum ref já existir associado à sua empresa, toda a transação falha (409 Conflict).
  • Fail-Fast (Layout Inválido): Referências de layout inexistentes retornam 400 Bad Request.

Payload de Exemplo​

[
  {
    "driver": {
      "tax_id": "98765432109",
      "driver_license_number": "1234567890",
      "license_category": "D"
    },
    "trip": {
      "ref": "TR-MDFE-4819",
      "layout_ref": "layout-mineracao-v2",
      "license_plate": "BRA2E19",
      "window_start": "2026-07-16T06:00:00Z",
      "window_end": "2026-07-16T18:00:00Z",
      "start_tolerance": 30,
      "end_tolerance": 60,
      "from_location": "Sede Mineradora Brumadinho",
      "origin_city": "Brumadinho",
      "origin_state": "MG",
      "origin_lat": -20.1219,
      "origin_lng": -44.1997,
      "to_location": "Porto de Tubarão",
      "destiny_city": "Vitória",
      "destiny_state": "ES",
      "destiny_lat": -20.2878,
      "destiny_lng": -40.2882,
      "summary": "Transporte de Minério de Ferro bruto.",
      "custom_data": {
        "mdf_key": "31260712345678901234580010000048191000048198"
      }
    }
  }
]

Exemplos de Código​

cURL​

curl -X POST "https://api.gatein.com/api/v1/trips" \
  -H "X-API-Key: sk_live_suachave" \
  -H "Content-Type: application/json" \
  -d '[{"driver":{"tax_id":"98765432109","driver_license_number":"1234567890","license_category":"D"},"trip":{"ref":"TR-MDFE-4819","layout_ref":"layout-mineracao-v2","license_plate":"BRA2E19"}}]'

Python​

import requests

url = "https://api.gatein.com/api/v1/trips"
headers = {"X-API-Key": "sk_live_suachave", "Content-Type": "application/json"}
payload = [
    {
        "driver": {"tax_id": "98765432109", "driver_license_number": "1234567890", "license_category": "D"},
        "trip": {
            "ref": "TR-MDFE-4819",
            "layout_ref": "layout-mineracao-v2",
            "license_plate": "BRA2E19",
            "from_location": "Filial SP",
            "to_location": "Porto Santos"
        }
    }
]

response = requests.post(url, headers=headers, json=payload)
print(response.json())

Atualizar Viagem(ns) (PUT)​

Endpoint: PUT /api/v1/trips

note

Este endpoint aceita tanto um único objeto de atualização quanto uma lista (array) de objetos para atualização em lote.

Campos Protegidos (não editáveis)​

CampoMotivo
idChave primária interna
trucking_company_idVínculo de propriedade imutável
refChave de referência externa — usada como identificador
driver_idIdentidade do motorista vinculado

Payload de Exemplo​

[
  {
    "ref": "TR-MDFE-4819",
    "trip": {
      "license_plate": "NEW3A21",
      "status": "ON_GOING",
      "summary": "Veículo passou pela cancela do terminal."
    }
  }
]

Cancelar / Deletar Viagem(ns) (DELETE)​

Endpoint: DELETE /api/v1/trips

note

Este endpoint aceita tanto uma única string de referência quanto um array de strings para cancelamento em lote.

Altera o status da viagem para DELETED. Exemplo de envio em lote:

["TR-MDFE-4819"]

Consultar Logs e Histórico de Rastreamento (GET)​

Endpoint: GET /api/v1/trips/logs

Query Parameters​

ParâmetroTipoDescrição
refsstring[]Repita o parâmetro para múltiplos valores: ?refs=TR-MDFE-4819&refs=TR-MDFE-4820

Resposta de Exemplo​

{
  "success": true,
  "data": [
    {
      "ref": "TR-MDFE-4819",
      "found": true,
      "data": {
        "trip": {
          "ref": "TR-MDFE-4819",
          "layout_ref": "layout-mineracao-v2",
          "license_plate": "BRA2E19",
          "status": "CHECKED_IN",
          "from_location": "Sede Mineradora Brumadinho",
          "to_location": "Porto de Tubarão",
          "origin_city": "Brumadinho",
          "origin_state": "MG",
          "destiny_city": "Vitória",
          "destiny_state": "ES",
          "created_at": "2026-07-16T05:00:00Z",
          "updated_at": "2026-07-16T06:30:00Z"
        },
        "driver": {
          "tax_id": "98765432109",
          "driver_license_number": "1234567890",
          "driver_license_category": "D"
        },
        "logs": [
          { "event": "checked_in", "message": "Check-in realizado no terminal.", "created_at": "2026-07-16T06:30:00.000000" },
          { "event": "created", "message": "Viagem criada via API.", "created_at": "2026-07-16T05:00:00.000000" }
        ]
      }
    }
  ]
}

Erros Comuns​

HTTPcodeCausa
400EMPTY_PAYLOADArray vazio enviado no body
400INVALID_LAYOUT_REFlayout_ref não existe para esta transportadora
409DUPLICATE_KEYUm ou mais refs já existem no banco
404REFS_NOT_FOUNDrefs informados no PUT/DELETE não foram encontrados