raute-io Tracking API

openapi: 3.2.0
info:
  title: Raute Partner Tracking API
  version: 1.0.0
  summary: Push delivery orders into Raute and read tracking back out.
  description: 'Raute plans multi-stop delivery routes, tracks drivers live and captures proof of delivery. This API is how another system hands Raute the stops it needs delivered and reads back where each one is.


    Keys are issued by the account holder at https://www.raute.io/api-keys and are available on every plan. A key belongs to one company and can only ever see that company''s data; the company is taken from the key, never from the request.'
  contact:
    name: Raute
    url: https://www.raute.io/developers
servers:
- url: https://www.raute.io/api/v1
security:
- apiKey: []
tags:
- name: Tracking
  description: Where an order is, its ETA and its driver.
paths:
  /orders/{id}/tracking:
    get:
      tags:
      - Tracking
      summary: Track one order
      description: Accepts either the tracking:read or the orders:read scope. This is the narrowest useful endpoint and the right one behind a customer-facing tracking page.
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      - name: source
        in: query
        schema:
          type: string
        description: Set this to resolve id as your own external_id.
      responses:
        '200':
          description: Tracking for the order.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Tracking'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/InsufficientScope'
        '404':
          $ref: '#/components/responses/NotFound'
      operationId: getOrdersByIdTracking
      x-operation-id-source: derived
  /orders/tracking:
    get:
      tags:
      - Tracking
      summary: Look up tracking without a Raute id
      description: Accepts either the tracking:read or the orders:read scope. Give order_id, or give external_id together with source.
      parameters:
      - name: order_id
        in: query
        schema:
          type: string
      - name: external_id
        in: query
        schema:
          type: string
      - name: source
        in: query
        schema:
          type: string
      responses:
        '200':
          description: Tracking for the order.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Tracking'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/InsufficientScope'
        '404':
          $ref: '#/components/responses/NotFound'
      operationId: getOrdersTracking
      x-operation-id-source: derived
components:
  responses:
    Unauthorized:
      description: The key is missing, unknown or revoked.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    InsufficientScope:
      description: The key is valid but does not carry the scope this endpoint needs.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadRequest:
      description: The request was malformed or a required field was missing.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: No such record on this company.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              examples:
              - insufficient_scope
              - missing_field
              - invalid_json
            message:
              type: string
    Driver:
      type: object
      properties:
        id:
          type: string
        name:
          type:
          - string
          - 'null'
        phone:
          type:
          - string
          - 'null'
        email:
          type:
          - string
          - 'null'
        external_id:
          type:
          - string
          - 'null'
        external_source:
          type:
          - string
          - 'null'
    OrderStatus:
      type: string
      enum:
      - pending
      - assigned
      - in_progress
      - delivered
      - cancelled
    Tracking:
      type: object
      description: Where the order is, when it is expected and who is carrying it.
      properties:
        status:
          $ref: '#/components/schemas/OrderStatus'
        estimated_arrival:
          type:
          - string
          - 'null'
        route_index:
          type:
          - integer
          - 'null'
        delivered_at:
          type:
          - string
          - 'null'
          format: date-time
        proof_url:
          type:
          - string
          - 'null'
        signature_url:
          type:
          - string
          - 'null'
        driver:
          $ref: '#/components/schemas/Driver'
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: x-api-key
      description: 'A key created at https://www.raute.io/api-keys. The secret is shown once at creation and never again, because only its hash is stored. Each key carries scopes: tracking:read, orders:read, orders:write.'