openapi: 3.0.0

info:
  title: Péntech Sales Partner API
  description: Sales Partner endpoints.
  version: 2.0.0
  termsOfService: https://pentech.hu/hu/felhasznalasi-feltetelek
  contact:
    name: Péntech Dev Team
    email: dev@pentech.hu

servers:
  - url: https://api.demo.pentech.hu/factoring
    description: Demo server for testing
  - url: https://api.pentech.hu/factoring
    description: Production server

security:
  - ApiKeyAuth: []

paths:
  /eligibility:
    get:
      summary: Check the contract eligibility of a creditor company and debtor company.
      tags:
        - SalesPartner
      security:
        - ApiKeyAuth: []
      parameters:
        - name: invoiceAmount
          description: Full invoice amount
          in: query
          required: true
          schema:
            type: number
            example: 1000000
        - name: invoicePeriod
          description: Days from today until invoice deadline (expected payout date by debtor)
          in: query
          required: true
          schema:
            type: number
            example: 60
        - name: invoiceCurrency
          description: Days from today until invoice deadline (expected payout date by debtor)
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/Currency'
        - name: creditorTaxNumber
          description: Tax number of the creditor (invoice issuer client)
          in: query
          required: true
          schema:
            $ref: '#/components/schemas/TaxNumber'
        - name: debtorTaxNumber
          description: Tax number of the debtor (invoice recipient)
          in: query
          required: true
          schema:
            $ref: '#/components/schemas/TaxNumber'
      responses:
        '200':
          description: >
            OK


            invoiceAmount = instant + rest + feeSum
          content:
            application/json:
              schema:
                type: object
                properties:
                  feePercent:
                    type: number
                    description: The ratio of all deductions compared to the full invoice amount.
                  feeSum:
                    type: number
                    description: The sum of all deductions (fees). This value is not final, as it's up to change on the daily BUBOR changes.
                  instant:
                    type: number
                    description: The amount to be paid as the first payment.
                  rest:
                    type: number
                    description: The amount to be paid when the debtor repays.
                  isEligible:
                    type: boolean
                    description: Factoring eligibility of the creditor company.
                  contract:
                    $ref: '#/components/schemas/Contract'

  /contracts:
    get:
      summary: List contracts matching the parameters.
      description: >
        With this endpoint, you can query all the contracts which was added with your API key.


        Query supports [PostgREST style horizontal filtering](https://postgrest.org/en/stable/api.html#horizontal-filtering-rows) (except Full-Text Search and Logical operators).

        If no valid operator is present, we prepand the value with "eq." to transform it to an equality filter.
      tags:
        - SalesPartner
      security:
        - ApiKeyAuth: []
      parameters:
        - name: id
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/Id'
        - name: creditorTaxNumber
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/TaxNumber'
        - name: creditorCountryCode
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/CountryCode'
        - name: debtorTaxNumber
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/TaxNumber'
        - name: debtorCountryCode
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/CountryCode'
      responses:
        '200':
          description: Search result
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Contract'
        '400':
          description: Parameter validation error (content structure TBD)

    post:
      summary: Request a new contract (factoring limit).
      description: Before sending any fundings, the creditor must go through Péntech's contracting process and sign the contract.
      tags:
        - SalesPartner
      security:
        - ApiKeyAuth: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ContractPost'
      responses:
        '201':
          description: CREATED
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: created
                  message:
                    type: string
                    example: Sales lead creation was successful
                  data:
                    type: object
                    properties:
                      redirectUrl:
                        type: string
                        description: This URL will take the user to either a prefilled registration page or the login page if the email exists in the system.
                        example: 'https://app.pentech.hu/saleslead?token=eyJyZWdpc3RyYXR...'

  /contracts/{contractId}/fundings:
    get:
      summary: List fundings of a specific contract matching the parameters.
      description: >
        With this endpoint, you can query all the fundings related to a specific contract, which was added with your API key.


        Query supports [PostgREST style horizontal filtering](https://postgrest.org/en/stable/api.html#horizontal-filtering-rows) (except Full-Text Search and Logical operators).

        If no valid operator is present, we prepand the value with "eq." to transform it to an equality filter.
      tags:
        - SalesPartner
      security:
        - ApiKeyAuth: []
      parameters:
        - name: 'contractId'
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/Id'
        - name: 'id'
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/Id'
        - name: 'amount'
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/Amount'
        - name: 'currency'
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/Currency'
        - name: 'invoiceNumber'
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/InvoiceNumber'
        - name: 'issueDate'
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/Date'
        - name: 'dueDate'
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/Date'
        - name: 'salesPartnerRecordId'
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/SalesPartnerRecordId'
      responses:
        '200':
          description: Search result
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Funding'
        '400':
          description: Parameter validation error (content structure TBD)
    post:
      summary: Request a new funding.
      description: The is the main API endpoint to interact with. Can be used to start a new transaction in Pentech's system and generate a redirect URL leads to a prefilled page.
      tags:
        - SalesPartner
      security:
        - ApiKeyAuth: []
      parameters:
        - name: 'contractId'
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/Id'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FundingPost'
      responses:
        '201':
          description: CREATED
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: created
                  message:
                    type: string
                    example: Sales lead creation was successful
                  data:
                    type: object
                    properties:
                      redirectUrl:
                        type: string
                        description: This URL will take the user to either a prefilled registration page or the login page if the email exists in the system.
                        example: 'https://app.pentech.hu/saleslead?token=eyJyZWdpc3RyYXR...'

  /contracts/{contractId}/fundings/{fundingId}:
    put:
      summary: >
        When any modification happens with an invoice after it's submission, the Sales Partner must inform Péntech about the changes.
      description: >
        This endpoint will delete the sales lead and reject the connected funding if the funding is not paid yet.
      tags:
        - SalesPartner
      security:
        - ApiKeyAuth: []
      parameters:
        - name: 'contractId'
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/Id'
        - name: 'fundingId'
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/Id'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FundingPut'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: received
                  message:
                    type: string

components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-Api-Key
  schemas:
    Id:
      type: string
    Amount:
      type: number
    SalesPartnerRecordId:
      description: Id of the resource in the caller's system. Optional
      type: string
      example: 'EQVR42mP8z8BQDwAE'
    UUID:
      type: string
      format: uuid4
      example: ffd4a209-5edd-45d8-b091-5dcc9ea239e3
    TaxNumber:
      type: string
      nullable: false
      pattern: /^(\d{8})$/
      example: '11112222'
      description: Must be the first 8 digit of the company tax number
    Date:
      type: string
      nullable: false
      pattern: /^(\d{4})-(\d{2})-(\d{2})$/
      example: '2022-02-22'
      description: ISO date
      externalDocs:
        url: https://en.wikipedia.org/wiki/ISO_8601
    DateTime:
      type: string
      nullable: false
      example: '2023-01-24 15:10:09.14484+00'
    Currency:
      description: If a currency conversion has occurred, the conversion rate at the date of the request has been used.
      type: string
      nullable: false
      example: 'EUR'
      enum:
        - 'HUF'
        - 'EUR'
    CountryCode:
      description: ISO 3166-1 2 letter country code
      type: string
      nullable: false
      example: 'HU'
      enum:
        - 'HU'
        # - 'PL'
        # - 'SK'
        # - 'RO'
      externalDocs:
        url: https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2
    InvoiceNumber:
      description: Invoice number
      type: string
      nullable: false
      example: '2021/00001'

    CompanyDetails:
      type: object
      properties:
        taxNumber:
          $ref: '#/components/schemas/TaxNumber'
        countryCode:
          $ref: '#/components/schemas/CountryCode'
        shortName:
          description: 'Display name of the company'
          type: string
          example: 'SUBIDUBI Kft.'
        longName:
          description: 'Full name of the company'
          type: string
          example: 'Sóder Uborka Banán Irodai Dolgok Utángyártását Beszerző Intézményi Korlátolt Felelősségű Társaság'

    Company:
      type: object
      properties:
        taxNumber:
          $ref: '#/components/schemas/TaxNumber'
        countryCode:
          $ref: '#/components/schemas/CountryCode'
        shortName:
          description: 'Display name of the company'
          type: string
          example: 'SUBIDUBI Kft.'
        longName:
          description: 'Full name of the company'
          type: string
          example: 'Sóder Uborka Banán Irodai Dolgok Utángyártását Beszerző Intézményi Korlátolt Felelősségű Társaság'
        name:
          description: 'Contact person'
          type: string
          example: 'Francia Eduárd'
        email:
          description: 'Contact email'
          type: string
          example: 'fr.edi@subidubi.hu'
        phone:
          description: 'Contact phone number, preferably in the following format: +36301112233'
          type: string
          example: '+36301112233'
    DebtorCompany:
      allOf:
        - $ref: '#/components/schemas/Company'
        - type: object
          properties:
            taxNumber:
              example: '33445566'
            shortName:
              example: 'BB Zrt.'
            longName:
              example: 'Big Buyer Zártkörűen Működő Részvénytársaság'
            name:
              example: 'Kontakt Kata'
            email:
              example: 'kata.k@bb.hu'
            phone:
              example: '+36209998877'

    PartnerStatus:
      type: string
      nullable: false
      example: 'missing'
      enum:
        - 'missing'
        - 'present'
    ContractStatus:
      type: string
      nullable: false
      example: 'active'
      description: >
        missing - Does not exist, or exists with a rejected history. -> new contract can be requested.
        draft - Contract was requested, but wasn't submitted in Péntech's system. User must finish and submit the contracting flow in Péntech App.
        under_approval - Contract was submitted, Péntech is working on getting the contract active.
        active - Active contract -> fundings can be requested.
      enum:
        - 'missing'
        - 'draft'
        - 'under_approval'
        - 'active'
    FundingStatus:
      type: string
      nullable: false
      example: 'closed'
      description: >
        draft - Funding wasn't submitted in Péntech's system. Requeirs user action in Péntech App.
        under_approval - Funding was submitted, Péntech is working on the funding.
        initial_payout - Funding was approved and the initial payout transferred to the creditor.
        closed - Debtor paid the invoice, Péntech closed the funding.
        under_collection - Debtor did not pay in time, Collection in progress.
        rejected - Funding was rejected by either party.
      enum:
        - 'missing'
        - 'draft'
        - 'under_approval'
        - 'initial_payout'
        - 'closed'
        - 'under_collection'
        - 'rejected'

    Contract:
      type: object
      properties:
        id:
          type: string
          description: Random-looking string with max 30. length
        createdAt:
          $ref: '#/components/schemas/DateTime'
        updatedAt:
          $ref: '#/components/schemas/DateTime'
        currency:
          $ref: '#/components/schemas/Currency'
        status:
          $ref: '#/components/schemas/ContractStatus'
        creditor:
          type: object
          nullable: true
          properties:
            schema:
              $ref: '#/components/schemas/CompanyDetails'
        debtor:
          type: object
          nullable: true
          properties:
            schema:
              $ref: '#/components/schemas/CompanyDetails'

    Funding:
      type: object
      properties:
        id:
          type: string
          description: Random-looking string with max 30. length
        createdAt:
          $ref: '#/components/schemas/DateTime'
        updatedAt:
          $ref: '#/components/schemas/DateTime'
        currency:
          $ref: '#/components/schemas/Currency'
        status:
          $ref: '#/components/schemas/ContractStatus'

        amount:
          $ref: '#/components/schemas/Amount'
        invoiceNumber:
          $ref: '#/components/schemas/InvoiceNumber'
        IssueDate:
          $ref: '#/components/schemas/Date'
        DueDate:
          $ref: '#/components/schemas/Date'
        SalesPartnerRecordId:
          $ref: '#/components/schemas/SalesPartnerRecordId'

    ContractPost:
      type: object
      required:
        - creditor
        - debtor
      properties:
        creditor:
          $ref: '#/components/schemas/Company'
        debtor:
          $ref: '#/components/schemas/DebtorCompany'

    FundingPost:
      description: Funding details
      type: object
      required:
        - amount
        - currency
        - invoiceNumber
        - issueDate
        - dueDate
        - image
      properties:
        amount:
          description: >
            Full invoice amount

            By default, we support any decimals in this value, but we'll round it to 2 decimals by default and to a round number for HUF currency.
          type: number
          example: 2000.42
        currency:
          $ref: '#/components/schemas/Currency'
        invoiceNumber:
          $ref: '#/components/schemas/InvoiceNumber'
        issueDate:
          $ref: '#/components/schemas/Date'
        dueDate:
          $ref: '#/components/schemas/Date'
        image:
          description: Invoice image / pdf in data URL format.
          type: string
          example: 'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8z8BQDwAEhQGAhKmMIQAAAABJRU5ErkJggg=='
        salesPartnerRecordId:
          $ref: '#/components/schemas/SalesPartnerRecordId'
        redirectUrl:
          description: An optional URL, where we redirect the user after submitting the funding request.
          type: string

    FundingPut:
      description: Funding details changed
      type: object
      required:
        - description
      properties:
        description:
          description: >
            Textual
          type: string
          example: 'Storno invoice issued'

tags:
  - name: SalesPartner
