BTG Pactual Settlement API

openapi: 3.2.0
info:
  title: SCF - Risco Sacado Settlement API
  description: Esta API tem a finalidade de contratar Antecipações de Recebíveis. Para autenticação é necessário a utilização do fluxo de client credentials para autenticação na documentação da API. `AUTENTICAÇÃO -> Fluxos de Autenticação -> Client Credentials`
  version: 1.4.1
  contact:
    name: Time BTG Empresas
    email: ol-it-btgempresas@btgpactual.com
servers:
- url: https://api.sandbox.empresas.btgpactual.com/v1/scf
  description: SANDBOX URL
- url: https://api.empresas.btgpactual.com/v1/scf
  description: PROD URL
tags:
- name: Settlement
paths:
  /settlements/{settlementId}:
    get:
      tags:
      - Settlement
      description: O objetivo dessa rota é pesquisar um pedido de liquidação previamente cadastrado.
      parameters:
      - in: path
        name: settlementId
        description: Id da liquidação
        schema:
          description: Identificador
          type: string
          example: 3382cc6f-1c59-4423-b364-c837deaf110d
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    description: Identificador da liquidação
                    type: string
                    example: 3382cc6f-1c59-4423-b364-c837deaf110e
                  payment:
                    type: object
                    properties:
                      account:
                        type: object
                        description: Dados da conta bancária
                        properties:
                          bank:
                            description: Código do banco
                            type: string
                          agency:
                            description: Agência da conta bancária
                            type: string
                          number:
                            description: Número da conta bancária
                            type: string
                          digit:
                            description: Dígito da conta bancária
                            type: string
                        title: AccountSchema
                      method:
                        enum:
                        - pix
                        - ted
                        type: string
                        example: ted
                      code:
                        description: Identificador a ser preenchido na transferência via PIX ou TED.
                        type: string
                        example: c3357540-fa15-4dbf-844c-1ce70ddb0d6c
                      maturityDate:
                        description: Timestamp (ISO 8601) da data e hora limite para expiração do pagamento. O pagamento deve ser realizado até essa hora, caso contrário, a liquidação será cancelada.
                        type: string
                        example: '2023-02-01T18:00:00.000Z'
                  trades:
                    type: array
                    items:
                      required:
                      - identification
                      - paidDate
                      - paidAmount
                      type: object
                      properties:
                        tradeId:
                          description: Identificador do trade
                          type: string
                        amount:
                          description: Valor de pagamento da transação
                          type: string
                        amount_settled:
                          description: Valor já pago do recebivel
                          type: string
                        status:
                          description: Status do trade
                          enum:
                          - PROCESSING
                          - PROCESSED
                          - CANCELLED
                          - INVALID
                          type: string
                          title: SettlementTradeStatusSchema
                        reason:
                          description: Descrição do status
                          type: string
                  status:
                    description: Status da liquidação
                    enum:
                    - CREATED
                    - VALIDATING
                    - INVALID
                    - WAITING_FOR_PAYMENT
                    - PROCESSED
                    - EXPIRED
                    type: string
                    title: SettlementStatusSchema
                title: SettlementReadSchema
          description: Sucesso na consulta do pedido de liquidação.
        '400':
          description: Erro de validação
          content:
            application/json:
              schema:
                type: object
                required:
                - errorCode
                - message
                properties:
                  errorCode:
                    type: integer
                  message:
                    type: string
                  errorDetails:
                    type: array
                    items:
                      type: object
                      properties:
                        target:
                          type: string
                        code:
                          type: string
                          enum:
                          - STQF0001
                          - STQF0002
                          - STQF0003
                          - STQF0004
                          - STQF0005
                          - STQF0006
                          - STQF0007
                          - STQF0008
                          - STQF0009
                          - STQF0010
                          - STQF0011
                          - STQF0012
                          - STQF0013
                          - STQF0014
                          - STQF0015
                          - STQF0016
                          - STQF0017
                          - STQF0018
                          description: "___\nErrors:\n * STQF0001 - Identificação do pagador não preenchido\n * STQF0002 - Identificação do pagador inválido\n * STQF0003 - Identificação do pagador não relacionado com as entidades de um ou mais trades\n * STQF0004 - Pagamento não preenchido\n * STQF0005 - Método de pagamento não preenchido\n * STQF0006 - Método de pagamento inválido\n * STQF0007 - Trade não preenchido\n * STQF0008 - Existem trades duplicados na coleção\n * STQF0009 - Identificador do Trade inválido\n * STQF0010 - Identificador do Trade não encontrado\n * STQF0011 - Trade já liquidado previamente\n * STQF0012 - Trade sendo processado em outro pedido de liquidação\n * STQF0013 - Valor do trade inválido\n * STQF0014 - Valor do trade menor ou igual a zero\n * STQF0015 - Valor do trade diferente do valor de vencimento do recebivel\n * STQF0016 - Valor do trade indisponível\n * STQF0017 - Identificador da liquidação inválido\n * STQF0018 - Liquidação não encontrada\n"
                          title: ValidationErrorsSettlementEnumSchema
                title: SettlementBadRequestResponseSchema
        '401':
          description: Não autorizado
        default:
          description: Erro
          content:
            application/json:
              schema:
                type: object
                required:
                - errorCode
                - message
                properties:
                  errorCode:
                    type: integer
                  message:
                    type: string
                title: ErrorResponseSchema
      security:
      - oauth2:
        - empresas.btgpactual.com/scf/settlements
        - empresas.btgpactual.com/scf/settlements.readonly
      x-docs-url: https://developers.empresas.btgpactual.com/docs/api-specs-target/SCF%20-%20Risco%20Sacado/consultar-um-pedido-de-liquidacao-cadastrado
      summary: Get settlements by settlement id
      x-summary-source: derived
      operationId: getSettlementsBySettlementId
      x-operation-id-source: derived
  /settlements:
    post:
      tags:
      - Settlement
      description: O objetivo dessa rota é cadastrar um pedido de liquidação de recebiveis.
      requestBody:
        description: Dados de liquidação
        content:
          application/json:
            schema:
              required:
              - payment
              - trades
              - payerTaxId
              type: object
              properties:
                payerTaxId:
                  description: Documento do pagador
                  type: string
                payment:
                  type: object
                  properties:
                    method:
                      description: Método de pagamento para a transferência, Pix ou Ted
                      enum:
                      - pix
                      - ted
                      type: string
                      example: ted
                trades:
                  type: array
                  items:
                    required:
                    - tradeId
                    - amount
                    type: object
                    properties:
                      tradeId:
                        description: Identificador do trade
                        type: string
                      amount:
                        description: Valor de pagamento da transação
                        type: string
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    description: Identificador da liquidação
                    type: string
                    example: 3382cc6f-1c59-4423-b364-c837deaf110e
                  payment:
                    type: object
                    properties:
                      method:
                        enum:
                        - pix
                        - ted
                        type: string
                        example: ted
                      maturityDate:
                        description: Timestamp (ISO 8601) da data e hora limite para expiração do pagamento. O pagamento deve ser realizado até essa hora, caso contrário, a liquidação será cancelada.
                        type: string
                        example: '2023-02-01T18:00:00.000Z'
                  trades:
                    type: array
                    items:
                      required:
                      - identification
                      - paidDate
                      - paidAmount
                      type: object
                      properties:
                        tradeId:
                          description: Identificador do trade
                          type: string
                        amount:
                          description: Valor de pagamento da transação
                          type: string
                        amount_settled:
                          description: Valor já pago do recebivel
                          type: string
                        status:
                          description: Status do trade
                          enum:
                          - PROCESSING
                          - PROCESSED
                          - CANCELLED
                          - INVALID
                          type: string
                          title: SettlementTradeStatusSchema
                  status:
                    description: Status da liquidação
                    enum:
                    - CREATED
                    - VALIDATING
                    - INVALID
                    - WAITING_FOR_PAYMENT
                    - PROCESSED
                    - EXPIRED
                    type: string
                    title: SettlementStatusSchema
                title: SettlementSchema
          description: Pedido de liquidação cadastrado com sucesso.
        '400':
          description: Erro de validação
          content:
            application/json:
              schema:
                type: object
                required:
                - errorCode
                - message
                properties:
                  errorCode:
                    type: integer
                  message:
                    type: string
                  errorDetails:
                    type: array
                    items:
                      type: object
                      properties:
                        target:
                          type: string
                        code:
                          type: string
                          enum:
                          - STQF0001
                          - STQF0002
                          - STQF0003
                          - STQF0004
                          - STQF0005
                          - STQF0006
                          - STQF0007
                          - STQF0008
                          - STQF0009
                          - STQF0010
                          - STQF0011
                          - STQF0012
                          - STQF0013
                          - STQF0014
                          - STQF0015
                          - STQF0016
                          - STQF0017
                          - STQF0018
                          description: "___\nErrors:\n * STQF0001 - Identificação do pagador não preenchido\n * STQF0002 - Identificação do pagador inválido\n * STQF0003 - Identificação do pagador não relacionado com as entidades de um ou mais trades\n * STQF0004 - Pagamento não preenchido\n * STQF0005 - Método de pagamento não preenchido\n * STQF0006 - Método de pagamento inválido\n * STQF0007 - Trade não preenchido\n * STQF0008 - Existem trades duplicados na coleção\n * STQF0009 - Identificador do Trade inválido\n * STQF0010 - Identificador do Trade não encontrado\n * STQF0011 - Trade já liquidado previamente\n * STQF0012 - Trade sendo processado em outro pedido de liquidação\n * STQF0013 - Valor do trade inválido\n * STQF0014 - Valor do trade menor ou igual a zero\n * STQF0015 - Valor do trade diferente do valor de vencimento do recebivel\n * STQF0016 - Valor do trade indisponível\n * STQF0017 - Identificador da liquidação inválido\n * STQF0018 - Liquidação não encontrada\n"
                          title: ValidationErrorsSettlementEnumSchema
                title: SettlementBadRequestResponseSchema
        '401':
          description: Não autorizado
        default:
          description: Erro
          content:
            application/json:
              schema:
                type: object
                required:
                - errorCode
                - message
                properties:
                  errorCode:
                    type: integer
                  message:
                    type: string
                title: ErrorResponseSchema
      security:
      - oauth2:
        - empresas.btgpactual.com/scf/settlements
      x-docs-url: https://developers.empresas.btgpactual.com/docs/api-specs-target/SCF%20-%20Risco%20Sacado/criar-pedido-de-liquidacao-de-recebiveis
      summary: Create settlements
      x-summary-source: derived
      operationId: postSettlements
      x-operation-id-source: derived
components:
  securitySchemes:
    oauth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://id.sandbox.btgpactual.com/oauth2/token
          scopes:
            empresas.btgpactual.com/scf/borderos: Scope to borderos
            empresas.btgpactual.com/scf/borderos.readonly: Scope to borderos read
            empresas.btgpactual.com/scf/companies: Scope to companies
            empresas.btgpactual.com/scf/companies.readonly: Scope to companies read
            empresas.btgpactual.com/scf/operations: Scope to operations
            empresas.btgpactual.com/scf/operations.readonly: Scope to operations read
            empresas.btgpactual.com/scf/receivables: Scope to receivables
            empresas.btgpactual.com/scf/receivables.readonly: Scope to receivables read
            empresas.btgpactual.com/scf/settlements: Scope to settlements
            empresas.btgpactual.com/scf/settlements.readonly: Scope to settlements read
            empresas.btgpactual.com/scf/trades: Scope to trades
            empresas.btgpactual.com/scf/trades.readonly: Scope to trades read
            empresas.btgpactual.com/payer-onboardings: Scope to financiers-payer
x-reassembled-from:
  source: https://developers.empresas.btgpactual.com/docs/api-specs-target/
  method: Operation objects decoded verbatim from the "api" payload that the provider's Docusaurus OpenAPI docs embed in each reference page chunk (/assets/js/*.js); grouped by info.title; jsonRequestBodyExample and postman keys dropped.
  chunks:
  - https://developers.empresas.btgpactual.com/assets/js/58e6a5f6.d603bf94.js
  - https://developers.empresas.btgpactual.com/assets/js/0e797970.5126fe3c.js
  - https://developers.empresas.btgpactual.com/assets/js/4ac3e447.07b626b1.js
  - https://developers.empresas.btgpactual.com/assets/js/17b7cd34.31efc121.js
  - https://developers.empresas.btgpactual.com/assets/js/69c7c660.61e0039c.js
  - https://developers.empresas.btgpactual.com/assets/js/d83fedfc.69d77805.js
  - https://developers.empresas.btgpactual.com/assets/js/091533f9.2c5d3d51.js
  - https://developers.empresas.btgpactual.com/assets/js/51cd407d.7f26ecb2.js
  - https://developers.empresas.btgpactual.com/assets/js/522d5b94.745f73fc.js
  - https://developers.empresas.btgpactual.com/assets/js/a9f41984.1f49d7c9.js
  - https://developers.empresas.btgpactual.com/assets/js/10287afc.7e9c97f3.js
  - https://developers.empresas.btgpactual.com/assets/js/6687c7ea.dec258dc.js
  - https://developers.empresas.btgpactual.com/assets/js/fb9f95a5.4835ae79.js
  - https://developers.empresas.btgpactual.com/assets/js/0938da15.d9b57531.js