Qargo Use case / Accounting API

openapi: 3.2.0
info:
  title: Qargo TMS Use case / Accounting API
  description: For support, please contact integrations@qargo.com.
  version: 1.2.0
servers:
- url: https://api.qargo.com
tags:
- name: Use case / Accounting
  description: 'Required role: `API_ACCOUNTING`.


    See Accounting for more information.'
paths:
  /v1/webhook/billing-document-update:
    post:
      tags:
      - Use case / Accounting
      summary: External Billing Document (Invoice/Credit-Note) Update
      description: 'Update billing document metadata (invoices, credit notes) from an external accounting system.


        This webhook uses **Basic Auth** (webhook credentials), not the OAuth credentials used for the API.

        Contact integrations@qargo.com to request credentials.


        Use this endpoint to push document status changes or related metadata updates back to Qargo.

        This is typically triggered when your external accounting system processes billing documents.'
      operationId: billing-document-update-webhook
      security:
      - BasicAuthWebhookCredentials: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BillingDocumentUpdatePayload'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '400':
          description: Bad Request — invalid input or malformed request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationErrorResponse'
        '401':
          description: Unauthorized — missing or invalid authentication credentials
        '403':
          description: Forbidden — insufficient permissions for this operation
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '429':
          description: Too Many Requests — rate limit exceeded. See the `Retry-After` header
        '500':
          description: Internal Server Error
        '503':
          description: Service Unavailable — temporarily unable to handle the request
components:
  schemas:
    BillingDocumentUpdatePayload:
      properties:
        updates:
          items:
            $ref: '#/components/schemas/BillingDocumentUpdate'
          type: array
          title: Updates
          description: List of updates to process
      type: object
      title: BillingDocumentUpdatePayload
    FieldMatchInput:
      properties:
        matches_any:
          items:
            type: string
          type: array
          title: Matches Any
      type: object
      title: FieldMatchInput
    ValidationErrorResponse:
      properties:
        message:
          description: Human-readable summary of the validation failure
          title: Message
          type: string
        errors:
          description: One entry per validation failure. Always present and non-empty — a single failure yields a one-item array, so integrators can handle one and many the same way.
          items:
            $ref: '#/components/schemas/ValidationErrorDetail'
          minItems: 1
          title: Errors
          type: array
      required:
      - message
      - errors
      title: ValidationErrorResponse
      type: object
    BillingDocumentMatchTarget:
      properties:
        matches_all:
          items:
            $ref: '#/components/schemas/BillingDocumentMatchInput'
          type: array
          title: Matches All
      type: object
      title: BillingDocumentMatchTarget
    ValidationErrorDetail:
      properties:
        message:
          description: Human-readable summary of this validation failure
          title: Message
          type: string
        field:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          description: Name of the field that failed validation, if known
          title: Field
        path:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          description: JSON path to the field within the request payload (e.g. '$.consignor.address.country')
          title: Path
        detail:
          anyOf:
          - type: string
          - type: object
          - type: 'null'
          default: null
          description: Additional structured context about the failure, if provided by the backend
          title: Detail
      required:
      - message
      title: ValidationErrorDetail
      type: object
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    BillingDocumentUpdate:
      properties:
        sales_invoice:
          anyOf:
          - $ref: '#/components/schemas/SalesInvoiceUpdate'
          - type: 'null'
      type: object
      title: BillingDocumentUpdate
    SalesInvoiceMatch:
      properties:
        name:
          anyOf:
          - $ref: '#/components/schemas/FieldMatchInput'
          - type: 'null'
      type: object
      title: SalesInvoiceMatch
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    SalesInvoiceUpdate:
      properties:
        id:
          anyOf:
          - type: string
          - type: 'null'
          title: Id
        custom_fields:
          anyOf:
          - type: object
          - type: 'null'
          title: Custom Fields
        match:
          $ref: '#/components/schemas/BillingDocumentMatchTarget'
          description: Matcher for the billing document update, used to match to a billing document
      type: object
      title: SalesInvoiceUpdate
    BillingDocumentMatchInput:
      properties:
        sales_invoice:
          $ref: '#/components/schemas/SalesInvoiceMatch'
      type: object
      required:
      - sales_invoice
      title: BillingDocumentMatchInput
  securitySchemes:
    oAuth2ClientCredentials:
      type: oauth2
      flows:
        clientCredentials:
          scopes: {}
          tokenUrl: /v1/auth/token
    BasicAuthWebhookCredentials:
      type: http
      scheme: basic
x-tagGroups:
- name: Use cases
  tags:
  - Use case / Accounting
  - Use case / Customer portal
  - Use case / Document import
  - Use case / E-invoicing
  - Use case / Fleet dispatch
  - Use case / Intermodal [partner]
  - Use case / Location booking
  - Use case / Master data sync
  - Use case / Order
  - Use case / Subcontractor dispatch
  - Use case / Tracking
  - Use case / Trip import
  - Use case / Visibility
- name: API
  tags:
  - API / Accounting
  - API / Authentication
  - API / Company
  - API / Document
  - API / Order
  - API / Resource
  - API / Task
  - API / Trip
- name: System
  tags:
  - System
- name: Webhooks
  tags:
  - Webhooks / Inbound
  - Webhooks / Outbound
- name: ''
  tags: []