openapi: 3.0.0
info:
  title: Reports API
  version: v2
  x-logo:
    url: https://docs.goshippo.com/images/shippo-logo.svg
servers:
  - url: https://api.goshippo.com
security:
  - APIKeyHeader: []
tags:
  - name: Reports
    description: >-
      Use the Reports API to retrieve reports that have been scheduled or
      requested on demand. At the moment, only scheduled reports are supported. 

      1. Use  `/v2/reports/{report_type_uuid}/runs` to list the available
      reports.

      2. Use `/v2/reports/{report_type_uuid}/runs/{report_run_uuid}/download` to
      download the csv file of a report instance.
paths:
  /v2/reports/{report_type_uuid}/runs:
    get:
      tags:
        - Reports
      summary: Return list of reports
      operationId: list_report_runs
      description: >
        Returns a list of reports that can be downloaded.

        <br>

        A report type is a report that can be executed on a schedule and/or on
        demand. If you have requested Shippo a custom report, you will receive
        the report type UUID that represents that report type. With this report
        type UUID, you can call this endpoint to list all the available runs of
        your report.
      parameters:
        - name: report_type_uuid
          in: path
          schema:
            type: string
            format: uuid
            title: Report Type UUID
          required: true
          description: UUID of the report type
        - name: status
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/ReportStatus'
            title: Status
          description: >-
            Filters report runs by their current status. This is an optional
            parameter, but it's recommended setting it to SUCCEEDED if your
            integration doesn't handle the other statuses
        - name: mode
          in: query
          schema:
            $ref: '#/components/schemas/ReportInstanceMode'
            title: Mode
          required: false
          description: >-
            Filters results for only one report mode. (only scheduled reports
            are supported currently)
        - name: page
          in: query
          required: false
          schema:
            type: string
            description: Link to the next page
            example: bmV4dDs5MTsyMDI0LTA4LTA3VDE0OjQ1OjA4LjkyNzg1MSswMDowMA==
            title: Page
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            description: The upper limit to the number of resources returned
            default: 10
            title: Limit
          description: The upper limit to the number of results returned
      x-codeSamples:
        - lang: cURL
          label: cURL
          source: >-
            curl -i -X GET \

            'https://api.goshippo.com/v2/reports/{report_type_uuid}/runs?status=QUEUED&mode=ON_DEMAND&page=bmV4dDs5MTsyMDI0LTA4LTA3VDE0OjQ1OjA4LjkyNzg1MSswMDowMA==&limit=10'
            \

            -H 'Authorization:  ShippoToken <API_TOKEN>'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListReportRunResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v2/reports/{report_type_uuid}/runs/{report_run_uuid}/download:
    get:
      summary: Download report
      description: >-
        Returns a redirect URL to download the report file.

        <br>

        After processing the response from `/runs` endpoint, use the same
        `report_type_uuid` and the object_id of the report you want to
        retrieve. 

        <br>

        A successful response returns a 302 status code. Your client should
        automatically follow the redirected link to download the file. Some
        clients, such as Swagger UI, can include the `authorization` header when
        following the redirected link. This will cause the request to fail with
        a 400 Bad Request response. To avoid this issue, ensure that the
        `authorization` header is removed when the client follows the redirected
        URL.
      operationId: get_report_run_download_url
      tags:
        - Reports
      parameters:
        - name: report_type_uuid
          in: path
          required: true
          schema:
            type: string
            format: uuid
            title: Report Type Uuid
          description: UUID of the report type
        - name: report_run_uuid
          in: path
          required: true
          schema:
            type: string
            format: uuid
            title: Report Run UUID
          description: UUID of the report instance (object_id returned by /runs)
      x-codeSamples:
        - lang: cURL
          label: cURL
          source: >-
            curl -i -X GET \

            'https://api.goshippo.com/v2/reports/{report_type_uuid}/runs/{report_run_uuid}/download'
            \

            -H 'Authorization: ShippoToken <API_TOKEN>'
      responses:
        '302':
          description: Redirect to download URL
          headers:
            Location:
              schema:
                type: string
                format: uri
              description: >
                An URI to perform a HTTP GET to download the file content. 

                It is RFC-7231 compliant:
                https://datatracker.ietf.org/doc/html/rfc7231#section-6.4.3
              example:
                signed_url:
                  value: https://s3.amazonaws.com/your-bucket/your-file
                  summary: Redirect URI to download the file.
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    ReportStatus:
      type: string
      enum:
        - QUEUED
        - PROCESSING
        - SUCCEEDED
        - FAILED
      title: ReportStatus
    ReportInstanceMode:
      type: string
      enum:
        - ON_DEMAND
        - SCHEDULED
      title: ReportInstanceMode
    ListReportRunResponse:
      properties:
        resources:
          items:
            $ref: '#/components/schemas/ReportRunResponse'
          type: array
          title: Resources
        page_info:
          allOf:
            - $ref: '#/components/schemas/PageInfo'
      type: object
      title: ListReportRunResponse
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ReportRunResponse:
      properties:
        object_id:
          type: string
          format: uuid
          title: Object Id
          example: 079aa9eb-9c0c-484a-b4fb-6507b43cf722
        created_at:
          type: string
          format: date-time
          title: Created At
          example: '2021-09-01T00:00:00.000000Z'
        mode:
          allOf:
            - $ref: '#/components/schemas/ReportInstanceMode'
          example: ON_DEMAND
        status:
          allOf:
            - $ref: '#/components/schemas/ReportStatus'
          example: SUCCEEDED
      type: object
      required:
        - object_id
        - created_at
        - mode
        - status
      title: ReportRunResponse
    PageInfo:
      properties:
        next:
          type: string
          title: Next
          description: Link to the next page
          example: bmV4dDs5MTsyMDI0LTA4LTA3VDE0OjQ1OjA4LjkyNzg1MSswMDowMA==
        prev:
          type: string
          title: Prev
          description: Link to the previous page
          example: cHJldjs5MjsyMDI0LTA5LTA1VDEzOjQwOjE1Ljk2NjY1NCswMDowMA==
      type: object
      title: PageInfo
      description: Link to the next page and previous page
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
  securitySchemes:
    APIKeyHeader:
      in: header
      name: Authorization
      type: apiKey
