Yokoy Invoice payment terms API

openapi: 3.2.0
info:
  description: Public API of the Yokoy Application
  title: Yokoy Card account Invoice payment terms API
  version: 1.41.0
servers:
- description: API server scoped to organization with ID `organizationId`
  url: https://api.yokoy.ai/v1/organizations/{organizationId}
  variables:
    organizationId:
      default: AbcDeF1234
      description: Yokoy organization ID
- description: API test server scoped to organization with ID `organizationId`
  url: https://api.test.yokoy.ai/v1/organizations/{organizationId}
  variables:
    organizationId:
      default: AbcDeF1234
      description: Yokoy organization ID
tags:
- description: Payment terms determine the expectation of payment agreed between the company and the supplier. By default, all payment terms can be used with any supplier of the legal entity. However, you can restrict a payment term to a specific supplier by setting `supplierSpecific` to `true` and associating the payment term ID in the Supplier master data.
  name: Invoice payment terms
paths:
  /legal-entities/{legalEntityId}/invoice-payment-terms:
    parameters:
    - $ref: '#/components/parameters/LegalEntityIdInPath'
    - $ref: '#/components/parameters/YokoyAuthMethod'
    - $ref: '#/components/parameters/YokoyCorrelationId'
    get:
      description: Returns all payment terms for the legal entity identified in the path.
      operationId: listPaymentTerms
      parameters:
      - $ref: '#/components/parameters/QueryFilter'
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  invoice-payment-terms:
                    items:
                      $ref: '#/components/schemas/InvoicePaymentTerms'
                    type: array
                type: object
          description: OK
        '400':
          $ref: '#/components/responses/InvalidFilter'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalError'
        '502':
          $ref: '#/components/responses/GatewayError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
      security:
      - OAuth2: []
      summary: List all payment terms
      tags:
      - Invoice payment terms
    post:
      description: Creates a new invoice payment term and returns the created entity.
      operationId: createPaymentTerm
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InvoicePaymentTerms'
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvoicePaymentTerms'
          description: Created
        '400':
          $ref: '#/components/responses/HttpValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalError'
        '502':
          $ref: '#/components/responses/GatewayError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
      security:
      - OAuth2: []
      summary: Create a payment term
      tags:
      - Invoice payment terms
  /legal-entities/{legalEntityId}/invoice-payment-terms/{paymentTermId}:
    parameters:
    - $ref: '#/components/parameters/LegalEntityIdInPath'
    - description: Yokoy unique ID of the invoice payment term.
      example: 06x2u4nagAMEq3gGoMch
      in: path
      name: paymentTermId
      required: true
      schema:
        pattern: '[\w-]+'
        type: string
    - $ref: '#/components/parameters/YokoyAuthMethod'
    - $ref: '#/components/parameters/YokoyCorrelationId'
    get:
      description: Retrieves an invoice payment term identified by its Yokoy unique ID.
      operationId: getPaymentTerm
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvoicePaymentTerms'
          description: OK
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalError'
        '502':
          $ref: '#/components/responses/GatewayError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
      security:
      - OAuth2: []
      summary: Get a payment term by ID
      tags:
      - Invoice payment terms
    patch:
      description: Updates an invoice payment term by replacing some attributes. The payment term is specified by its Yokoy unique ID. The whole entity is returned.
      operationId: modifyPaymentTerm
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: true
              description: Dictionary of invoice payment term attributes to update. Explicit null values mark attributes for deletion.
              type: object
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvoicePaymentTerms'
          description: OK
        '400':
          $ref: '#/components/responses/HttpValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalError'
        '502':
          $ref: '#/components/responses/GatewayError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
      security:
      - OAuth2: []
      summary: Modify a payment term
      tags:
      - Invoice payment terms
    put:
      description: Updates an invoice payment term, identified by its Yokoy unique ID, by replacing all attributes. The whole entity is returned.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InvoicePaymentTerms'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvoicePaymentTerms'
          description: OK
        '400':
          $ref: '#/components/responses/HttpValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalError'
        '502':
          $ref: '#/components/responses/GatewayError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
      security:
      - OAuth2: []
      summary: Update a payment term
      tags:
      - Invoice payment terms
components:
  parameters:
    LegalEntityIdInPath:
      description: Yokoy unique ID of the legal entity (company).
      example: aB9jQoE3HE
      in: path
      name: legalEntityId
      required: true
      schema:
        pattern: '[\w-]+'
        type: string
    YokoyAuthMethod:
      example: yokoy
      in: header
      name: X-Yk-Auth-Method
      required: true
      schema:
        enum:
        - yokoy
        type: string
    YokoyCorrelationId:
      description: Correlation ID that can be used to trace a request in the flow.
      example: 4ea8985e-80a2-40a0-8a40-401a1a1374b3
      in: header
      name: X-Yk-Correlation-Id
      required: false
      schema:
        type: string
    QueryFilter:
      description: Filter string used to restrict the data returned. You can use [SCIM specification](https://tools.ietf.org/html/rfc7644#section-3.4.2.2) filters.
      example: created ge 2024-03-02T09:00.000Z and customInformation.customField eq foo
      in: query
      name: filter
      schema:
        type: string
  schemas:
    InvoicePaymentTerms:
      properties:
        discounts:
          description: List of discounts applied if an invoice is paid within a given time-frame.
          items:
            properties:
              days:
                description: Days that determines early invoice payment. If paid within this period, a discount is applied to the invoice.
                example: 3
                type: number
              discount:
                description: Discount (percentage) applied to the invoice. For example, 5% == 5.
                example: 5
                type: number
            type: object
          type:
          - array
          - 'null'
        externalId:
          description: External reference to the payment term.
          example: externalId1
          type:
          - string
          - 'null'
        id:
          description: Yokoy unique ID of the invoice payment term.
          example: 06x2u4nagAMEq3gGoMch
          pattern: '[\w-]+'
          readOnly: true
          type: string
        name:
          description: Name of the payment term
          example: Supplier payment term - 90 days
          type: string
        netPaymentPeriod:
          description: Period (days) within which the payment is required.
          example: 90
          type: number
        supplierSpecific:
          default: false
          description: Restricts the payment term to a specific supplier. If set to `true`, the payment term can only be used with that supplier (specified by the payment term ID in the supplier payload). If set to `false`, the payment term is considered to be generic and can be used with any supplier of the legal entity.
          type: boolean
      required:
      - id
      - name
      type: object
    Error:
      properties:
        code:
          type: integer
        message:
          type: string
      required:
      - code
      - message
      type: object
    HttpError:
      properties:
        field:
          type: string
        message:
          type: string
      required:
      - field
      - message
      type: object
  responses:
    Unauthorized:
      content:
        application/json:
          example:
            code: 401
            message: Token expired
          schema:
            $ref: '#/components/schemas/Error'
      description: The server was unable to establish the identity of the client.
    GatewayError:
      content:
        application/json:
          example:
            code: 502
            message: Gateway error
          schema:
            $ref: '#/components/schemas/Error'
      description: An issue occurred in a downstream service. Please try again later.
    InvalidFilter:
      content:
        application/json:
          example:
            code: 400
            message: 'Invalid filter string: foo e bar'
          schema:
            $ref: '#/components/schemas/Error'
      description: The request was not valid.
    HttpValidationError:
      content:
        application/json:
          example:
            code: 400
            errors:
            - field: Yokoy Field
              message: Yokoy Field is mandatory
            message: Validation Error
          schema:
            $ref: '#/components/schemas/HttpError'
            additionalProperties: true
      description: The request was not valid.
    TooManyRequests:
      content:
        application/json:
          example:
            code: 429
            message: Too many requests
          schema:
            $ref: '#/components/schemas/Error'
      description: The request cannot be processed by the server due to too many concurrent requests.
    ServiceUnavailable:
      content:
        application/json:
          example:
            code: 503
            message: Service unavailable
          schema:
            $ref: '#/components/schemas/Error'
      description: The server is unavailable. Please try again later
    Forbidden:
      content:
        application/json:
          example:
            code: 403
            message: User not authorized to access organization
          schema:
            $ref: '#/components/schemas/Error'
      description: The client is not authorized to perform the requested operation.
    NotFound:
      content:
        application/json:
          example:
            code: 404
            message: Resource not found
          schema:
            $ref: '#/components/schemas/Error'
      description: The specified resource was not found.
    InternalError:
      content:
        application/json:
          example:
            code: 500
            message: Server error
          schema:
            $ref: '#/components/schemas/Error'
      description: An internal error occurred.
  securitySchemes:
    OAuth2:
      description: "Authentication to the Yokoy API relies on the standard OAuth2 client credentials flow.\n\n**1. Obtain an access token**\n\nPerform a `POST` request to\n`https://accounts.yokoy.ai/oauth2/token`. Pass the client ID\nand client secret as username and password in a basic auth\nheader. Set the content-type to\n`application/x-www-form-urlencoded` and specify\n`grant_type=client_credentials` in the body.\n\n> Note: For the Yokoy test environment, use `https://accounts.test.yokoy.ai/oauth2/token` instead.\n\nExample request for the client ID `ClientId` and client\nsecret `ClientSecret`:\n```\nPOST https://accounts.yokoy.ai/oauth2/token\nAuthorization: Basic Q2xpZW50SWQ6Q2xpZW50U2VjcmV0\nContent-Type: application/x-www-form-urlencoded\ngrant_type=client_credentials\n```\nIn this example, the string `Q2xpZW50SWQ6Q2xpZW50U2VjcmV0` is\nobtained by base64-encoding the string\n`ClientId:ClientSecret`, as required for basic access authentication.\n\n> Note: Yokoy does not require or use scopes.\n\n\nThe JSON response contains the access token in the attribute\n`access_token`. The response also contains the expiration in\nseconds.\n\nExample response:\n```\n{\n    \"access_token\": \"SOME_KEY\",\n    \"expires_in\": 3900,\n    \"token_type\": \"Bearer\"\n}\n```\n\n**2. Pass the bearer token**\n\nPass the access token from step 1 as a bearer token in subsequent requests to the API.\n\nExample header field for the example response from step 1:\n```\nAuthorization: Bearer 4lDvPkrBF87WHuyvlINQD\n```\n\nFor more information, see (Authentication & authorization)[https://developer.yokoy.ai/docs/overview/authentication].\n"
      flows:
        clientCredentials:
          scopes: {}
          tokenUrl: https://accounts[.test].yokoy.ai/oauth2/token
      type: oauth2