openapi: 3.0.0
info:
  version: '1'
  title: Salesforce API
  description: >
    This API provides access to several CDQ API endpoints according to the 
    Salesforce object reference. Requests and responses are mapped from the  CDQ
    data model to the Salesforce object reference in order to simplify  service
    access from Salesforce integrations.
servers:
  - description: Production
    url: https://api.cdq.com/salesforce/rest
    x-cdq-soap-url: https://api.corporate-data-league.ch/salesforce/soap/v1
security:
  - apiKey: []
tags: []
paths:
  /referencedata/restv3/businesspartners/lookup:
    post:
      summary: Lookup Business Partners
      description: Lookup a business partner in all available data sources.
      tags:
        - Business Partners
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SalesforceBusinessPartnerLookupRequest'
            examples:
              lookupByEuVatIdPl:
                summary: Lookup business partner by identifier.
                value:
                  businessPartner:
                    addresses:
                      - country:
                          shortName: PL
                    identifiers:
                      - value: PL9280012700
                        type:
                          technicalKey: EU_VAT_ID_PL
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SalesforceBusinessPartnerLookupResult'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not Found
components:
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: X-API-KEY
  schemas:
    SalesforceBusinessPartnerLookupRequest:
      type: object
      description: Request to lookup a business partner in all available data sources.
      properties:
        name:
          type: string
          description: Name of the Business Partner.
          example: CDQ AG
        identifierType:
          type: string
          description: Identifier type of the Business Partner.
          example: EU_VAT_ID_DE
        identifierValue:
          type: string
          description: Identifier value of the Business Partner.
          example: DE123456789
        country:
          type: string
          description: Country of the Business Partner.
          example: DE
        city:
          type: string
          description: City of the Business Partner.
          example: Hamburg
        postCode:
          type: string
          description: Post code of the Business Partner.
          example: '20095'
        street:
          type: string
          description: Street of the Business Partner.
          example: Jungfernstieg
        houseNo:
          type: string
          description: House number of the Business Partner.
          example: '4'
        matchingThreshold:
          type: number
          format: double
          description: Matching threshold for the Business Partner.
          example: '0.5'
          minimum: 0
          maximum: 1
        maxCandidates:
          type: integer
          description: Maximum number of candidates to return. Default is 50.
          example: '50'
          minimum: 20
          maximum: 100
        pageSize:
          type: integer
          description: Number of items per page.
          example: '10'
        page:
          type: integer
          description: Current page number.
          example: '0'
          default: 0
        limitResults:
          type: integer
          description: Number of items per page.
          example: '100'
        startAfter:
          $ref: '#/components/schemas/StartAfter'
    SalesforceBusinessPartnerLookupResult:
      type: object
      description: Result of the Business Partner lookup.
      properties:
        pageSize:
          type: integer
          description: Number of items per page.
          example: '10'
        totals:
          $ref: '#/components/schemas/PageTotal'
        page:
          type: integer
          description: Current page number.
          example: '0'
        limitResults:
          type: integer
          description: Number of items per page.
          example: '100'
        startAfter:
          $ref: '#/components/schemas/StartAfter'
        nextStartAfter:
          $ref: '#/components/schemas/NextStartAfter'
        businessPartnerCandidates:
          type: array
          description: List of Business Partner candidates.
          items:
            $ref: '#/components/schemas/SalesforceBusinessPartnerLookupCandidate'
    SalesforceBusinessPartnerLookupCandidate:
      type: object
      description: Business Partner candidate.
      properties:
        cdqId:
          type: string
          description: CDQ ID of the Business Partner.
          example: cdq:businesspartner:cdqId:DE:123456789
        dataSource:
          $ref: '#/components/schemas/BusinessPartnerStorageDataSourceId'
        matchingScore:
          type: number
          description: Matching score of the Business Partner.
          example: '0.5'
        matchingClassification:
          type: string
          description: Matching classification of the Business Partner.
          example: DUPLICATE
        name:
          type: string
          description: Name of the Business Partner.
          example: CDQ AG
        legalForm:
          type: string
          description: Legal form of the Business Partner.
          example: AG
        status:
          type: string
          description: Status of the Business Partner.
          example: ACTIVE
        identifiers:
          type: array
          description: List of identifiers of the Business Partner.
          items:
            $ref: '#/components/schemas/SalesforceIdentifier'
        addresses:
          type: array
          description: List of addresses of the Business Partner.
          items:
            $ref: '#/components/schemas/SalesforceAddress'
    SalesforceAddress:
      type: object
      description: Address of a Business Partner.
      properties:
        country:
          type: string
          description: Country of the address.
          example: DE
        countryName:
          type: string
          description: Country name of the address.
          example: Germany
        region:
          type: string
          description: Region of the address.
          example: DE-BW
        regionName:
          type: string
          description: Region name of the address.
          example: Baden-Württemberg
        city:
          type: string
          description: City of the address.
          example: Stuttgart
        postCode:
          type: string
          description: Post code of the address.
          example: '70173'
        street:
          type: string
          description: Street of the address.
          example: Königstraße
        houseNo:
          type: string
          description: House number of the address.
          example: '10'
        building:
          type: string
          description: Building of the address.
          example: Dorotheen Quartier
        floor:
          type: string
          description: Floor of the address.
          example: '3'
        room:
          type: string
          description: Room of the address.
          example: '14'
        latitude:
          type: number
          description: Latitude of the address.
          example: '48.778'
        longitude:
          type: number
          description: Longitude of the address.
          example: '9.179'
    SalesforceIdentifier:
      type: object
      description: Identifier of a Business Partner.
      properties:
        identifierType:
          type: string
          description: Identifier type of the Business Partner.
          example: EU_VAT_ID_DE
        identifierValue:
          type: string
          description: Identifier value of the Business Partner.
          example: DE123456789
    StartAfter:
      type: string
      description: The ID which is used to read the page.
      example: '5712566172571652'
    PageTotal:
      description: Total number of items which can be paged.
      example: '67'
      type: integer
    NextStartAfter:
      type: string
      description: Provides a value to be used as a startAfter in next page request.
      example: '5712566172571652'
    BusinessPartnerStorageDataSourceId:
      type: string
      description: Unique identifier for a Data Source of the Storage.
      example: 648824a691d8d2503d65103e
