Pluggy SCR API

openapi: 3.2.0
info:
  title: Pluggy SCR API
  description: Pluggy's main API to review data and execute connectors
  license:
    name: MIT
  contact:
    email: hello@pluggy.ai
    name: Pluggy
    url: https://pluggy.ai
  version: 1.0.0
servers:
- url: https://api.pluggy.ai
  description: Pluggy API
tags:
- name: SCR
  description: Bacen's credit information system, consulted through a connected Open Finance item
paths:
  /items/{id}/scr:
    get:
      operationId: items-retrieve-scr
      summary: Retrieve SCR
      description: 'Retrieves the SCR (Bacen''s *Sistema de Informações de Crédito*) for the document behind a connected item.


        The SCR is the Banco Central''s official registry of credit operations: every loan, financing, limit and guarantee above R$200, reported by every financial institution. The response is Bacen''s own payload, forwarded unchanged.


        The item is not the source of the data — the SCR is keyed by the document alone. The item supplies the CPF/CNPJ and stands as the evidence of the account holder''s consent, which is why this is only available for Open Finance items whose document is known.


        Requires the SCR feature on your subscription. Talk to us if you want it enabled.


        Base dates are months, not days, and Bacen consolidates each one with a few months of delay. When `from` and `to` are omitted the last 4 available base dates are consulted, ending 2 months back from today — asking for the current month returns nothing, because Bacen has not closed it yet.


        **Sandbox.** An item created with the *Sandbox Open Finance* connector (`600`) returns a synthetic payload with exactly this schema, so you can integrate without connecting a real account. The values are deterministic — the same item and window always return the same response — no consultation reaches Bacen, and nothing is billed. The same checks apply as in production: the SCR feature must be enabled on your subscription, the item must be Open Finance, and `from`/`to` are validated; the sandbox additionally rejects windows longer than 60 base dates with `SCR_INVALID_REQUEST`.'
      responses:
        '200':
          description: SCR data for the item document
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScrResponse'
        '400':
          description: The SCR request was rejected as invalid. Check the databaseIni/databaseFim range.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GlobalErrorResponse'
              example:
                code: 400
                codeDescription: SCR_INVALID_REQUEST
                message: The SCR request was rejected as invalid. Check the databaseIni/databaseFim range.
        '403':
          description: This client is not enabled to query SCR data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GlobalErrorResponse'
              example:
                code: 403
                codeDescription: SCR_FEATURE_NOT_ENABLED
                message: This client is not enabled to query SCR data.
        '404':
          description: item not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GlobalErrorResponse'
              example:
                code: 404
                codeDescription: ITEM_NOT_FOUND
                message: item not found
        '422':
          description: SCR is only available for Open Finance items that have a known CPF or CNPJ.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GlobalErrorResponse'
              example:
                code: 422
                codeDescription: SCR_ITEM_NOT_SUPPORTED
                message: SCR is only available for Open Finance items that have a known CPF or CNPJ.
        '500':
          description: An error occurred while fetching the SCR data from the connector
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GlobalErrorResponse'
              example:
                code: 500
                codeDescription: SCR_FETCH_ERROR
                message: An error occurred while fetching the SCR data from the connector
        '502':
          description: Bacen's SCR service is temporarily unavailable. Please try again later.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GlobalErrorResponse'
              example:
                code: 502
                codeDescription: SCR_SERVICE_UNAVAILABLE
                message: Bacen's SCR service is temporarily unavailable. Please try again later.
                data:
                  correlationId: 8047f6e9-bb9e-4b04-8515-e2210dc4c544
      tags:
      - SCR
      security:
      - default: []
      parameters:
      - description: Item primary identifier
        in: path
        name: id
        required: true
        schema:
          type: string
          format: uuid
        example: d0e8448e-0156-4b4a-ae6c-3e2a6d9bff5c
      - description: First base date to consult, as YYYYMM. Defaults to 3 base dates before `to`
        in: query
        name: from
        required: false
        schema:
          type: string
          pattern: ^\d{4}(0[1-9]|1[0-2])$
        example: '202604'
      - description: Last base date to consult, as YYYYMM. Defaults to 2 months before the current one, which is the most recent base date Bacen has consolidated
        in: query
        name: to
        required: false
        schema:
          type: string
          pattern: ^\d{4}(0[1-9]|1[0-2])$
        example: '202607'
components:
  schemas:
    ScrAdditionalInfo:
      title: SCR Additional Info
      type: object
      properties:
        tp:
          type: string
          description: Type of the complementary information
        cd:
          type: string
          description: Code of the complementary information
        qtd:
          type: number
          description: Number of operations grouped under this entry
    ScrOperation:
      title: SCR Operation
      type: object
      description: 'A group of credit operations. The SCR does not return contracts one by one: it aggregates them by the combination of modality, source of funds, index and exchange variation.'
      properties:
        mod:
          type: string
          description: Bacen's code for the operation modality
        oriRec:
          type: string
          description: Bacen's code for the source of funds
        indx:
          type: string
          description: Bacen's code for the reference rate or index
        varCamb:
          type: string
          description: Bacen's code for the exchange rate variation
        subJDisc:
          type: string
          description: 'Present when the operation is under dispute: "D" for disagreement, "J" for sub judice, "JD" for both'
        resVenc:
          $ref: '#/components/schemas/ScrMaturityBalances'
        lsGar:
          type: array
          items:
            $ref: '#/components/schemas/ScrGuarantee'
          description: Guarantees backing the operations in this group
        lsInfAd:
          type: array
          items:
            $ref: '#/components/schemas/ScrAdditionalInfo'
          description: Complementary information reported for this group
    ScrGuarantee:
      title: SCR Guarantee
      type: object
      properties:
        tp:
          type: string
          description: Bacen's code for the guarantee type
        qtd:
          type: number
          description: Number of operations grouped under this type
    ScrDatabase:
      title: SCR Base Date
      type: object
      description: One consulted base date, and what the SCR holds for the client in it
      properties:
        dtb:
          type: number
          description: The base date, as YYYYMM. Numeric, not a string
          example: 202607
        msg:
          type: string
          description: Bacen's message for this base date, when it has one — for example that the base date is not available for consultation
        docProc:
          type: string
          description: Percentage of the expected 3040 documents already incorporated by Bacen for this base date. A low value means the picture is still partial
        volProc:
          type: string
          description: Percentage of the expected operation volume already accepted for this base date
        qtdIfs:
          type: number
          description: Number of financial institutions where the client has operations
        qtdCongFinc:
          type: number
          description: Number of financial conglomerates where the client has operations
        dtbIniRel:
          type: string
          description: Start of the client's relationship with the national financial system
        coobAss:
          type: number
          description: Co-obligation assumed by the client in credit assignments, in BRL
        coobRec:
          type: number
          description: Co-obligation received in credit assignments, in BRL
        lsOp:
          type: array
          items:
            $ref: '#/components/schemas/ScrOperation'
          description: Operation groups reported for this base date
    ScrValidationMessage:
      title: SCR Validation Message
      type: object
      properties:
        codigo:
          type: string
        mensagem:
          type: string
    GlobalErrorResponse:
      title: Global Error Response Schema
      type: object
      required:
      - code
      - message
      properties:
        code:
          type: number
        message:
          type: string
        codeDescription:
          type: string
          description: Distinctive code description, useful to distinguish the error.
        data:
          type: object
          description: Additional data related to the error, if any
          properties: {}
      example:
        code: 500
        codeDescription: INTERNAL_SERVER_ERROR
        message: Internal Server Error
    ScrResponse:
      title: SCR
      type: object
      description: Bacen's SCR response, forwarded exactly as the Banco Central returns it — field names, codes and all. Nothing is renamed or normalised, so a value read here is the same value an institution reads at the source.
      required:
      - dtbConsult
      - cdCli
      - tpCli
      properties:
        dtbConsult:
          type: string
          description: The base dates consulted
          example: 202604 a 202607
        cdCli:
          type: string
          description: 'The consulted document: the CPF for an individual, or the 8-digit CNPJ root for a company'
        tpCli:
          type: string
          enum:
          - '1'
          - '2'
          description: 'Type of client: "1" for an individual, "2" for a legal entity'
        lsDtb:
          type: array
          items:
            $ref: '#/components/schemas/ScrDatabase'
          description: One entry per consulted base date. A base date with no data for the client is still listed, with no operations
        listaDeMensagensDeValidacao:
          type: array
          items:
            $ref: '#/components/schemas/ScrValidationMessage'
          description: Validation messages raised by Bacen for this request
    ScrMaturityBalances:
      title: SCR Maturity Balances
      type: object
      description: 'Balance of the operation group split across Bacen''s maturity vertices, in BRL. Each key is a vertex code and belongs to one of three families: amounts not yet due (a payment up to 14 days late still counts here), amounts overdue graded by how old the delay is, and a few categories that are not time windows at all. The window behind each individual code is defined by Bacen''s DOC3040 reference — read it there rather than inferring it from the number. Only the vertices that carry a value are present.'
      properties:
        v20:
          type: number
        v40:
          type: number
        v60:
          type: number
        v80:
          type: number
        v110:
          type: number
        v120:
          type: number
        v130:
          type: number
        v140:
          type: number
        v150:
          type: number
        v160:
          type: number
        v165:
          type: number
        v170:
          type: number
        v175:
          type: number
        v180:
          type: number
        v190:
          type: number
        v199:
          type: number
        v205:
          type: number
        v210:
          type: number
        v220:
          type: number
        v230:
          type: number
        v240:
          type: number
        v245:
          type: number
        v250:
          type: number
        v255:
          type: number
        v260:
          type: number
        v270:
          type: number
        v280:
          type: number
        v290:
          type: number
        v310:
          type: number
        v320:
          type: number
  securitySchemes:
    default:
      type: apiKey
      name: X-API-KEY
      in: header
x-provenance:
  method: harvested
  publisher: Pluggy
  source: https://v2.docs.pluggy.ai/openapi/pluggy-api.json
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)