raute-io Orders API

openapi: 3.2.0
info:
  title: Raute Partner Orders 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: Orders
  description: Create, read, update and cancel delivery orders.
paths:
  /orders:
    get:
      tags:
      - Orders
      summary: List orders
      description: Requires the orders:read scope.
      parameters:
      - name: status
        in: query
        schema:
          $ref: '#/components/schemas/OrderStatus'
      - name: delivery_date
        in: query
        schema:
          type: string
          format: date
      - name: source
        in: query
        description: Filter to orders created with this external_source.
        schema:
          type: string
      - name: limit
        in: query
        schema:
          type: integer
          default: 50
      - name: offset
        in: query
        schema:
          type: integer
          default: 0
      responses:
        '200':
          description: A page of orders.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Order'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/InsufficientScope'
        '429':
          $ref: '#/components/responses/RateLimited'
      operationId: getOrders
      x-operation-id-source: derived
    post:
      tags:
      - Orders
      summary: Create an order
      description: Requires the orders:write scope. The address is geocoded on creation. If it cannot be placed on the map the order is still created and the response carries a warning, but the stop will not appear on a route until the address is corrected.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NewOrder'
      responses:
        '201':
          description: The order was created.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Order'
                  created:
                    type: boolean
                  warning:
                    type:
                    - string
                    - 'null'
                    description: Present when the address could not be geocoded.
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/InsufficientScope'
        '429':
          $ref: '#/components/responses/RateLimited'
      operationId: postOrders
      x-operation-id-source: derived
  /orders/{id}:
    parameters:
    - name: id
      in: path
      required: true
      schema:
        type: string
      description: The Raute order id, or your own external_id when source is supplied.
    - name: source
      in: query
      schema:
        type: string
      description: Set this to resolve id as your own external_id rather than a Raute id.
    get:
      tags:
      - Orders
      summary: Read one order
      description: Requires the orders:read scope.
      responses:
        '200':
          description: The order.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Order'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/InsufficientScope'
        '404':
          $ref: '#/components/responses/NotFound'
      operationId: getOrdersById
      x-operation-id-source: derived
    patch:
      tags:
      - Orders
      summary: Update an order
      description: Requires the orders:write scope. Cannot assign a driver or mark an order delivered.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrderPatch'
      responses:
        '200':
          description: The updated order.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Order'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/InsufficientScope'
        '404':
          $ref: '#/components/responses/NotFound'
      operationId: patchOrdersById
      x-operation-id-source: derived
    delete:
      tags:
      - Orders
      summary: Cancel an order
      description: Requires the orders:write scope.
      parameters:
      - name: reason
        in: query
        schema:
          type: string
          default: Cancelled via partner API
      responses:
        '200':
          description: The order was cancelled.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/InsufficientScope'
        '404':
          $ref: '#/components/responses/NotFound'
      operationId: deleteOrdersById
      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'
    NotFound:
      description: No such record on this company.
      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'
    RateLimited:
      description: Too many requests. Read and write limits are set per key.
      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
    OrderStatus:
      type: string
      enum:
      - pending
      - assigned
      - in_progress
      - delivered
      - cancelled
    NewOrder:
      type: object
      required:
      - customer_name
      - address
      properties:
        customer_name:
          type: string
        address:
          type: string
          description: A full street address. It is geocoded on creation.
        city:
          type:
          - string
          - 'null'
        state:
          type:
          - string
          - 'null'
        zip_code:
          type:
          - string
          - 'null'
        phone:
          type:
          - string
          - 'null'
        notes:
          type: string
        order_type:
          type: string
          enum:
          - delivery
          - pickup
          default: delivery
        order_number:
          type:
          - string
          - 'null'
          description: Your own human readable number. Generated if omitted.
        external_id:
          type:
          - string
          - 'null'
          description: The id of this order in your system. Lets you address it later without storing Raute ids.
        source:
          type: string
          default: api
          description: A name for your system, used with external_id to address orders.
        delivery_date:
          type:
          - string
          - 'null'
          format: date
        time_window_start:
          type:
          - string
          - 'null'
        time_window_end:
          type:
          - string
          - 'null'
    OrderPatch:
      type: object
      description: Any subset of the writable fields on NewOrder. A driver cannot be assigned and an order cannot be marked delivered through this API.
      properties:
        customer_name:
          type: string
        address:
          type: string
        city:
          type: string
        state:
          type: string
        zip_code:
          type: string
        phone:
          type: string
        notes:
          type: string
        delivery_date:
          type: string
          format: date
        time_window_start:
          type: string
        time_window_end:
          type: string
    Order:
      type: object
      properties:
        id:
          type: string
        order_number:
          type:
          - string
          - 'null'
        external_id:
          type:
          - string
          - 'null'
        external_source:
          type:
          - string
          - 'null'
        status:
          $ref: '#/components/schemas/OrderStatus'
        customer_name:
          type:
          - string
          - 'null'
        phone:
          type:
          - string
          - 'null'
        address:
          type:
          - string
          - 'null'
        city:
          type:
          - string
          - 'null'
        state:
          type:
          - string
          - 'null'
        zip_code:
          type:
          - string
          - 'null'
        latitude:
          type:
          - number
          - 'null'
        longitude:
          type:
          - number
          - 'null'
        notes:
          type:
          - string
          - 'null'
        order_type:
          type:
          - string
          - 'null'
        delivery_date:
          type:
          - string
          - 'null'
          format: date
        time_window_start:
          type:
          - string
          - 'null'
        time_window_end:
          type:
          - string
          - 'null'
        estimated_arrival:
          type:
          - string
          - 'null'
        driver_id:
          type:
          - string
          - 'null'
        delivered_at:
          type:
          - string
          - 'null'
          format: date-time
        delivered_lat:
          type:
          - number
          - 'null'
        delivered_lng:
          type:
          - number
          - 'null'
        signature_url:
          type:
          - string
          - 'null'
        proof_url:
          type:
          - string
          - 'null'
          description: Photo captured at the door.
        signed_by_name:
          type:
          - string
          - 'null'
        signature_required:
          type:
          - boolean
          - 'null'
        route_index:
          type:
          - integer
          - 'null'
          description: Position of this stop on the driver's route.
        tracking_token:
          type:
          - string
          - 'null'
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
  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.'