openapi: 3.1.1
info:
  title: Django instant-invoice-share rendering API
  description: The classical Django service that powers the marketplace and most invoicing functionality.
  version: 2.0.0
servers:
- url: https://localhost
  description: Development
- url: https://apiv2.sandbox.hitchpin.com
  description: Sandbox
- url: https://apiv2.staging.hitchpin.com
  description: Staging
- url: https://apiv2.demo.hitchpin.com
  description: Demo
- url: https://apiv2.hitchpin.com
  description: Production
tags:
- name: rendering
paths:
  /render:
    put:
      operationId: RenderReceipt
      description: Get user data by its id
      parameters:
      - in: header
        name: Accept
        required: false
        schema:
          type: string
          enum:
          - application/pdf
          - image/svg+xml
      summary: Register a pre-printed receipt so that the client can securely retrieve the PDF copy.
      tags:
      - rendering
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RenderReceiptRequest'
      responses:
        '200':
          description: Response that can be used to retrieve the receipt PDF.
          content:
            application/pdf:
              schema:
                type: string
                format: binary
            image/svg+xml:
              schema:
                type: string
                format: binary
        '500':
          description: Could not render receipt.
          content:
            application/json:
              schema:
                type: object
                properties:
                  type:
                    type: string
                  message:
                    type: string
                required:
                - type
                - message
  /render-link:
    post:
      operationId: CreateReceiptUrl
      description: Create pre-rendered receipt the invoice id.
      summary: Register a pre-printed receipt so that the client can securely retrieve the PDF copy.
      tags:
      - rendering
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateRenderedReceiptUrlRequest'
      responses:
        '200':
          description: Response that can be used to retrieve the receipt PDF.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateRenderedReceiptUrlResponse'
        '404':
          description: Could not find rendered receipt.
          content:
            application/json:
              schema:
                type: object
                properties:
                  type:
                    type: string
                  message:
                    type: string
                required:
                - type
                - message
  /:
    post:
      operationId: ShortenUrl
      description: Create pre-rendered receipt the invoice id.
      summary: Register a pre-printed receipt so that the client can securely retrieve the PDF copy.
      tags:
      - rendering
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ShortenUrlRequest'
      responses:
        '200':
          description: Response that can be used to retrieve the receipt PDF.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ShortenUrlResponse'
        '404':
          description: Could not find rendered receipt.
          content:
            application/json:
              schema:
                $ref: ../common/ProblemDetails.schema.json
components:
  schemas:
    External:
      type: string
      default: P1D
      description: How long before the link stops working.
      externalDocs:
        description: Test suite for valid duration values.
        url: https://github.com/json-schema-org/JSON-Schema-Test-Suite/blob/main/tests/draft2020-12/optional/format/duration.json
    CreateRenderedReceiptUrlResponse:
      type: object
      properties:
        url:
          type: string
          format: uri
      required:
      - url
      description: Response with a URL to a previously rendered receipt.
    ShortenUrlResponse:
      type: object
      properties:
        shortUrl:
          type: string
          format: uri
      required:
      - shortUrl
    RenderReceiptRequest:
      type: object
      properties:
        receipt:
          type: object
          properties:
            invoice:
              type: object
              properties:
                shareHash:
                  type: string
                title:
                  type: string
                description:
                  type: string
                invoiceNumber:
                  type: string
                totalOwed:
                  type: object
                  properties:
                    currencyCode:
                      type: string
                      enum:
                      - usd
                    cents:
                      type: integer
                  required:
                  - currencyCode
                  - cents
                forName:
                  type: string
                  maxLength: 64
                attachments:
                  type: array
                  items:
                    allOf:
                    - type: object
                      properties:
                        id:
                          type: integer
                        localIdentifier:
                          type: string
                          maxLength: 256
                        timestamp:
                          type: string
                          format: date-time
                        updated:
                          type: string
                          format: date-time
                        showInLib:
                          type: boolean
                        user:
                          type: integer
                      required:
                      - user
                    - oneOf:
                      - type: object
                        properties:
                          attachmentType:
                            type: string
                            enum:
                            - document
                          document:
                            type: string
                            format: uri
                        required:
                        - attachmentType
                        - document
                      - type: object
                        properties:
                          attachmentType:
                            type: string
                            enum:
                            - image
                          image:
                            type: string
                            format: uri
                        required:
                        - attachmentType
                        - image
                      - type: object
                        properties:
                          attachmentType:
                            type: string
                            enum:
                            - text
                          text:
                            type: string
                        required:
                        - attachmentType
                        - text
                sender:
                  type: string
              required:
              - shareHash
              - title
              - description
              - invoiceNumber
              - totalOwed
              - forName
              - attachments
              - sender
            fees:
              type: array
              items:
                type: object
                properties:
                  amount:
                    type: object
                    properties:
                      currencyCode:
                        type: string
                        enum:
                        - usd
                      cents:
                        type: integer
                    required:
                    - currencyCode
                    - cents
                  description:
                    type: string
                required:
                - amount
                - description
              default: []
            paymentObjects:
              type: array
              items:
                type: object
                properties:
                  amount:
                    type: object
                    properties:
                      currencyCode:
                        type: string
                        enum:
                        - usd
                      cents:
                        type: integer
                    required:
                    - currencyCode
                    - cents
                  last4:
                    type: string
                    nullable: true
                    pattern: ^[0-9\*]{2}[0-9]{2}
                  paymentMethodName:
                    type: string
                required:
                - amount
                - paymentMethodName
            timestamp:
              type: string
              format: date-time
            updated:
              type: string
              format: date-time
            buyer:
              type: object
              properties:
                name:
                  type: string
                email:
                  type: string
                phone:
                  type: string
                address:
                  type: object
                  properties:
                    street1:
                      type: string
                    street2:
                      type: string
                      nullable: true
                    city:
                      type: string
                    state:
                      type: string
                    postalCode:
                      type: string
              required:
              - name
              - email
              - phone
              - address
            seller:
              type: object
              properties:
                name:
                  type: string
                email:
                  type: string
                phone:
                  type: string
                address:
                  type: object
                  properties:
                    street1:
                      type: string
                    street2:
                      type: string
                      nullable: true
                    city:
                      type: string
                    state:
                      type: string
                    postalCode:
                      type: string
                storefrontName:
                  type: string
              required:
              - name
              - email
              - phone
              - address
              - storefrontName
          required:
          - invoice
          - paymentObjects
          - timestamp
          - updated
          - buyer
          - seller
        format:
          anyOf:
          - type: string
            enum:
            - pdf
          - type: string
            enum:
            - svg
          default: pdf
        style:
          type: string
          enum:
          - modern
          default: modern
        branding:
          type: object
          nullable: true
          properties:
            logoUrl:
              type: string
      required:
      - receipt
      description: Request to render a receipt.
    CreateRenderedReceiptUrlRequest:
      type: object
      properties:
        shareHash:
          type: string
        format:
          anyOf:
          - type: string
            enum:
            - pdf
          - type: string
            enum:
            - svg
      required:
      - shareHash
      - format
      description: Request to get the URL of a previously rendered receipt.
    ShortenUrlRequest:
      type: object
      properties:
        url:
          type: string
          format: uri
        kind:
          type: string
          enum:
          - sqids
          - nanoids
        group:
          type: string
          description: Group to associate this short link with. This determines the shuffled alphabet to use, as well as what monotically increasing series to use for applicable sequencers.
        maxAge:
          $ref: '#/components/schemas/External'
        recordsRetention:
          type: string
          default: P1M
          description: How long to keep a record of this short link. This affects whether or not its possible to re-issue this short link again, as well as for what duration of time after expiration that the oritingal URL will return a 410 Gone. After retention period is up, it will start returning a 404.
        minEntropy:
          type: integer
          minimum: 4
          maximum: 128
          default: 20
          description: Minimum number of random characters to pull from.
        maxEntropy:
          type: integer
          minimum: 20
          maximum: 256
          default: 64
          description: Maximum number of random characters to pull from.
        template:
          type: string
      required:
      - url
      - kind
      - group
      - template
  securitySchemes:
    cookieAuth:
      type: apiKey
      in: cookie
      name: sessionid
    tokenAuth:
      type: apiKey
      in: header
      name: Authorization
      description: Token-based authentication with required prefix "Token"
x-speakeasy-retries:
  strategy: backoff
  backoff:
    initialInterval: 500
    maxInterval: 60000
    maxElapsedTime: 3600000
    exponent: 1.5
  statusCodes:
  - 5XX
  retryConnectionErrors: true
x-hp-version:
  branch: feature/2758-instant-invoicing-models
  commit_id: 130543d53be424bc7d33903988ae0e57d9d1ec32
  deploy_env: dev