openapi: 3.0.0
info:
  contact: {}
  title: Clients AR Account reports Suppliers API
  version: v1
servers:
- url: https://api.agicap.com
- url: https://api.agicap.internal
tags:
- name: Suppliers
paths:
  /public/suppliers/v1/entities/{entityId}:
    get:
      description: 'Returns the suppliers of an entity using cursor-based pagination, so ERP Connectivity can

        diff its catalog against Agicap. Pass the nextCursor of a previous page to fetch the next one.

        Use the optional erpId filter to look up a single supplier.'
      operationId: 2_Suppliers_List
      parameters:
      - description: Agicap entity identifier.
        example: 123456
        in: path
        name: entityId
        required: true
        schema:
          format: int32
          type: integer
      - description: Optional filter on a single ERP identifier.
        in: query
        name: erpId
        schema:
          type: string
      - description: Opaque cursor returned as nextCursor by the previous page.
        in: query
        name: cursor
        schema:
          type: string
      - description: Maximum number of suppliers per page (1 to 1000, default 1000).
        example: 1000
        in: query
        name: limit
        schema:
          default: 1000
          format: int32
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListSuppliersResponse'
          description: Your request has been successfully processed.
        '400':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
          description: Your request is invalid.
        '401':
          description: Unauthorized request.
        '403':
          description: Forbidden request.
        '429':
          description: Too many requests. Please try again later.
        '500':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
          description: An internal server occurred.
      security:
      - bearer_client_credentials:
        - agicap:public-api
      - bearerAuth: []
      summary: List the suppliers of an entity
      tags:
      - Suppliers
  /public/suppliers/v1/entities/{entityId}/sync:
    post:
      description: 'Pushes up to 1000 suppliers (create / update / delete) for an entity in a single call.

        Processing is synchronous and returns a syncId usable to fetch the row-by-row errors.

        If the same erpId appears more than once in a batch, all of its occurrences are rejected and reported as row errors.'
      operationId: 1_Suppliers_Sync
      parameters:
      - description: Agicap entity identifier.
        example: 123456
        in: path
        name: entityId
        required: true
        schema:
          format: int32
          type: integer
      requestBody:
        content:
          application/*+json:
            schema:
              $ref: '#/components/schemas/SyncSuppliersRequest'
          application/json:
            schema:
              $ref: '#/components/schemas/SyncSuppliersRequest'
          text/json:
            schema:
              $ref: '#/components/schemas/SyncSuppliersRequest'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SyncSuppliersResponse'
          description: Your request has been successfully processed.
        '400':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
          description: Your request is invalid.
        '401':
          description: Unauthorized request.
        '403':
          description: Forbidden request.
        '429':
          description: Too many requests. Please try again later.
        '500':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
          description: An internal server occurred.
      security:
      - bearer_client_credentials:
        - agicap:public-api
        - public-api:manage-suppliers
      - bearerAuth: []
      summary: Synchronize a batch of suppliers
      tags:
      - Suppliers
  /public/suppliers/v1/entities/{entityId}/sync/{syncId}:
    get:
      description: 'Returns the row-by-row errors of a previous synchronization, paginated.

        The syncId is the one returned by the synchronize endpoint.'
      operationId: 3_Suppliers_SyncErrors
      parameters:
      - description: Agicap entity identifier.
        example: 123456
        in: path
        name: entityId
        required: true
        schema:
          format: int32
          type: integer
      - description: Synchronization identifier returned by the synchronize endpoint.
        example: 1660e6c3-54fd-402f-be8e-7748efd94791
        in: path
        name: syncId
        required: true
        schema:
          format: uuid
          type: string
      - description: Opaque cursor returned as cursor.after by the previous page. Omit to fetch the first page.
        in: query
        name: after
        schema:
          type: string
      - description: Page size (1 to 200, default 50).
        example: 50
        in: query
        name: size
        schema:
          default: 50
          format: int32
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SupplierSyncErrorsResponse'
          description: Your request has been successfully processed.
        '400':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
          description: Your request is invalid.
        '401':
          description: Unauthorized request.
        '403':
          description: Forbidden request.
        '429':
          description: Too many requests. Please try again later.
        '500':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
          description: An internal server occurred.
      security:
      - bearer_client_credentials:
        - agicap:public-api
        - public-api:manage-suppliers
      - bearerAuth: []
      summary: Get the synchronization errors of a batch
      tags:
      - Suppliers
components:
  schemas:
    SupplierSyncErrorItem:
      additionalProperties: false
      properties:
        erpId:
          nullable: true
          type: string
        reason:
          nullable: true
          type: string
        rowNumber:
          format: int32
          type: integer
      type: object
    LegalAddressResponse:
      additionalProperties: false
      description: Legal address of a supplier, as returned by the suppliers endpoints.
      properties:
        city:
          description: City of the address.
          nullable: true
          type: string
        country:
          description: Country of the address (ISO 3166 2-letter code).
          nullable: true
          type: string
        number:
          description: Building / street number of the address (ISO 20022).
          nullable: true
          type: string
        postalCode:
          description: Postal / ZIP code of the address.
          nullable: true
          type: string
        state:
          description: State or region of the address.
          nullable: true
          type: string
        streetName:
          description: Street name of the address (ISO 20022).
          nullable: true
          type: string
      required:
      - country
      type: object
    SyncSuppliersRequest:
      additionalProperties: false
      description: Payload of a supplier synchronization batch.
      properties:
        suppliers:
          description: Suppliers to create, update or delete in this batch (up to 1000 items).
          items:
            $ref: '#/components/schemas/SupplierSyncItem'
          nullable: true
          type: array
      required:
      - suppliers
      type: object
    SupplierResponse:
      additionalProperties: false
      description: A supplier as returned by the suppliers endpoints.
      properties:
        contacts:
          description: Contacts of the supplier.
          items:
            $ref: '#/components/schemas/ContactResponse'
          nullable: true
          type: array
        createdAt:
          description: Date and time at which the supplier was first created in Agicap.
          format: date-time
          nullable: true
          type: string
        erpId:
          description: Identifier of the supplier in the client's ERP.
          nullable: true
          type: string
        id:
          description: Stable Agicap identifier of the supplier.
          example: 1660e6c3-54fd-402f-be8e-7748efd94791
          format: uuid
          type: string
        language:
          description: Preferred language of the supplier (ISO 639-1 code).
          nullable: true
          type: string
        legalAddress:
          $ref: '#/components/schemas/LegalAddressResponse'
        legalCompanyId:
          description: Legal company identifier of the supplier.
          nullable: true
          type: string
        legalName:
          description: Legal name of the supplier.
          nullable: true
          type: string
        name:
          description: Display name of the supplier.
          nullable: true
          type: string
        primaryContact:
          $ref: '#/components/schemas/ContactResponse'
        status:
          description: Lifecycle status of the supplier.
          nullable: true
          type: string
        tags:
          description: Free-form tags associated with the supplier.
          items:
            type: string
          nullable: true
          type: array
        thirdPartyCode:
          description: Third-party accounting code of the supplier.
          nullable: true
          type: string
        updatedAt:
          description: Date and time at which the supplier was last updated in Agicap.
          format: date-time
          nullable: true
          type: string
        vatCode:
          description: VAT code of the supplier.
          nullable: true
          type: string
      type: object
    ProblemDetails:
      additionalProperties: false
      properties:
        detail:
          nullable: true
          type: string
        instance:
          nullable: true
          type: string
        status:
          format: int32
          nullable: true
          type: integer
        title:
          nullable: true
          type: string
        type:
          nullable: true
          type: string
      type: object
    CursorDto:
      additionalProperties: false
      description: Opaque-token pagination cursor.
      properties:
        after:
          description: Opaque token to pass as the `after` query parameter to fetch the next page.
          nullable: true
          type: string
        isLastPage:
          description: Whether the current page is the last one.
          example: false
          type: boolean
        size:
          description: Number of errors per page.
          example: 50
          format: int32
          type: integer
      type: object
    ListSuppliersResponse:
      additionalProperties: false
      description: A cursor-paginated page of suppliers.
      properties:
        items:
          description: Suppliers of the current page.
          items:
            $ref: '#/components/schemas/SupplierResponse'
          nullable: true
          type: array
        nextCursor:
          description: Opaque cursor to pass back to fetch the next page, or null when the last page is reached.
          nullable: true
          type: string
      type: object
    ContactResponse:
      additionalProperties: false
      description: A contact attached to a supplier, as returned by the suppliers endpoints.
      properties:
        email:
          description: Email address of the contact.
          nullable: true
          type: string
        name:
          description: Full name of the contact.
          nullable: true
          type: string
        phone:
          description: Phone number of the contact.
          nullable: true
          type: string
        role:
          description: Role of the contact within the supplier organization.
          nullable: true
          type: string
      type: object
    SyncSuppliersResponse:
      additionalProperties: false
      description: Result of a supplier synchronization batch.
      properties:
        syncId:
          description: Identifier of the synchronization, used to fetch its row-by-row errors.
          example: 1660e6c3-54fd-402f-be8e-7748efd94791
          format: uuid
          type: string
      type: object
    LegalAddressDto:
      additionalProperties: false
      description: Legal address of a supplier.
      properties:
        city:
          description: City of the address.
          nullable: true
          type: string
        country:
          description: Country of the address (ISO 3166 2-letter code).
          nullable: true
          type: string
        number:
          description: Building / street number of the address (ISO 20022).
          nullable: true
          type: string
        postalCode:
          description: Postal / ZIP code of the address.
          nullable: true
          type: string
        state:
          description: State or region of the address.
          nullable: true
          type: string
        streetName:
          description: Street name of the address (ISO 20022).
          nullable: true
          type: string
      required:
      - country
      type: object
    SupplierSyncItem:
      additionalProperties: false
      description: A single supplier to create, update or delete within a synchronization batch.
      properties:
        contacts:
          description: Contacts of the supplier.
          items:
            $ref: '#/components/schemas/ContactDto'
          nullable: true
          type: array
        erpId:
          description: Identifier of the supplier in the client's ERP. Used to match the supplier on subsequent syncs.
          nullable: true
          type: string
        language:
          description: Preferred language of the supplier (ISO 639-1 code).
          nullable: true
          type: string
        legalAddress:
          $ref: '#/components/schemas/LegalAddressDto'
        legalCompanyId:
          description: Legal company identifier of the supplier (e.g. SIREN / VAT-free registration number).
          nullable: true
          type: string
        legalName:
          description: Legal name of the supplier, when it differs from the display name.
          nullable: true
          type: string
        name:
          description: Display name of the supplier.
          nullable: true
          type: string
        primaryContact:
          $ref: '#/components/schemas/ContactDto'
        status:
          description: Lifecycle status of the supplier as pushed by the ERP.
          nullable: true
          type: string
        tags:
          description: Free-form tags associated with the supplier.
          items:
            type: string
          nullable: true
          type: array
        thirdPartyCode:
          description: Third-party accounting code of the supplier.
          nullable: true
          type: string
        vatCode:
          description: VAT code of the supplier.
          nullable: true
          type: string
      type: object
    ContactDto:
      additionalProperties: false
      description: A contact attached to a supplier.
      properties:
        email:
          description: Email address of the contact.
          nullable: true
          type: string
        name:
          description: Full name of the contact.
          nullable: true
          type: string
        phone:
          description: Phone number of the contact.
          nullable: true
          type: string
        role:
          description: Role of the contact within the supplier organization.
          nullable: true
          type: string
      type: object
    SupplierSyncErrorsResponse:
      additionalProperties: false
      description: Cursor-paginated row-by-row errors of a previous supplier synchronization.
      properties:
        cursor:
          $ref: '#/components/schemas/CursorDto'
        items:
          description: Errors of the current page, one entry per failed row.
          items:
            $ref: '#/components/schemas/SupplierSyncErrorItem'
          nullable: true
          type: array
        status:
          description: Overall progress status of the synchronization.
          example: CompletedWithErrors
          nullable: true
          type: string
        syncId:
          description: Identifier of the synchronization the errors belong to.
          example: 1660e6c3-54fd-402f-be8e-7748efd94791
          format: uuid
          type: string
        totalCount:
          description: Total number of errors across all pages.
          example: 3
          format: int32
          type: integer
      type: object
  securitySchemes:
    bearer:
      bearerFormat: JWT
      scheme: bearer
      type: http
    bearerAuth:
      bearerFormat: OPAQUE
      scheme: bearer
      type: http