Celcoin Guarantee API

openapi: 3.0.1
info:
  title: billissuance-settlement-webservice AnnotationCompetenceCalendar Guarantee API
  version: v1.0.0
servers:
- url: https://sandbox.openfinance.celcoin.dev/billissuance/v1
tags:
- name: Guarantee
paths:
  /guarantee/get-links:
    get:
      tags:
      - Guarantee
      summary: Consults the employment links associated with a specific document.
      parameters:
      - name: document
        in: query
        required: true
        schema:
          type: string
      - name: consigneeId
        in: query
        required: true
        schema:
          type: string
          format: uuid
      - name: agencyId
        in: query
        required: true
        schema:
          type: string
          format: uuid
      - name: token-data
        in: header
        description: Authorization Token (only if needed)
        schema:
          type: string
      - name: correspAgentId
        in: header
        description: Bank Correspondent Agent Id
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetLinksResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /guarantee/get-data:
    get:
      tags:
      - Guarantee
      summary: Retrieves comprehensive data associated with a specific document.
      parameters:
      - name: document
        in: query
        required: true
        schema:
          type: string
      - name: consigneeId
        in: query
        required: true
        schema:
          type: string
      - name: agencyId
        in: query
        required: true
        schema:
          type: string
      - name: periods
        in: query
        schema:
          type: integer
          format: int32
      - name: registration
        in: query
        schema:
          type: string
      - name: token-data
        in: header
        description: Authorization Token (only if needed)
        schema:
          type: string
      - name: correspAgentId
        in: header
        description: Bank Correspondent Agent Id
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CheckBalanceContractResponse'
        '202':
          description: Accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /guarantee:
    post:
      tags:
      - Guarantee
      summary: Initiates or schedules an annotation registration process.
      parameters:
      - name: Pin
        in: header
        schema:
          type: string
      - name: correspAgentId
        in: header
        description: Bank Correspondent Agent Id
        schema:
          type: string
      requestBody:
        description: Annotation request
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GuaranteeRequest'
          text/json:
            schema:
              $ref: '#/components/schemas/GuaranteeRequest'
          application/*+json:
            schema:
              $ref: '#/components/schemas/GuaranteeRequest'
      responses:
        '202':
          description: Accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GuaranteeResponse'
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GuaranteeResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /guarantee/anticipation:
    post:
      tags:
      - Guarantee
      summary: Realiza a antecipação de pagamento de parcelas específicas.
      parameters:
      - name: correspAgentId
        in: header
        description: Bank Correspondent Agent Id
        schema:
          type: string
      requestBody:
        description: Antecipação de parcelas request
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AnticipationInstallmentsRequest'
          text/json:
            schema:
              $ref: '#/components/schemas/AnticipationInstallmentsRequest'
          application/*+json:
            schema:
              $ref: '#/components/schemas/AnticipationInstallmentsRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnticipationInstallmentsResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /guarantee/{annotationId}:
    patch:
      tags:
      - Guarantee
      summary: Alter data from annotation (Amortization)
      parameters:
      - name: annotationId
        in: path
        description: Id from annotation
        required: true
        schema:
          type: string
          format: uuid
      - name: Pin
        in: header
        schema:
          type: string
      - name: correspAgentId
        in: header
        description: Bank Correspondent Agent Id
        schema:
          type: string
      requestBody:
        description: Request
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GuaranteeAlterRequest'
          text/json:
            schema:
              $ref: '#/components/schemas/GuaranteeAlterRequest'
          application/*+json:
            schema:
              $ref: '#/components/schemas/GuaranteeAlterRequest'
      responses:
        '202':
          description: Accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GuaranteeAlterResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    delete:
      tags:
      - Guarantee
      summary: Delete an annotation
      parameters:
      - name: annotationId
        in: path
        description: ''
        required: true
        schema:
          type: string
          format: uuid
      - name: reason
        in: query
        description: ''
        schema:
          $ref: '#/components/schemas/ReasonEndContract'
      - name: correspAgentId
        in: header
        description: Bank Correspondent Agent Id
        schema:
          type: string
      responses:
        '202':
          description: Accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteGuaranteeResponse'
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteGuaranteeResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /guarantee/contract:
    post:
      tags:
      - Guarantee
      summary: Send annotation contract data
      parameters:
      - name: correspAgentId
        in: header
        description: Bank Correspondent Agent Id
        schema:
          type: string
      requestBody:
        description: ''
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ContractDataRequest'
          text/json:
            schema:
              $ref: '#/components/schemas/ContractDataRequest'
          application/*+json:
            schema:
              $ref: '#/components/schemas/ContractDataRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContractDataResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /guarantee/{actionType}/{annotationId}:
    get:
      tags:
      - Guarantee
      parameters:
      - name: actionType
        in: path
        required: true
        schema:
          type: string
      - name: annotationId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConsentResponse'
  /guarantee/authorization-data:
    post:
      tags:
      - Guarantee
      summary: Authorize consult data
      parameters:
      - name: correspAgentId
        in: header
        description: Bank Correspondent Agent Id
        schema:
          type: string
      requestBody:
        description: ''
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AuthorizationDataRequest'
          text/json:
            schema:
              $ref: '#/components/schemas/AuthorizationDataRequest'
          application/*+json:
            schema:
              $ref: '#/components/schemas/AuthorizationDataRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthorizationDataResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /guarantee/annotation:
    get:
      tags:
      - Guarantee
      summary: Consult annotation status
      parameters:
      - name: annotationId
        in: query
        description: ''
        schema:
          type: string
          format: uuid
      - name: correspAgentId
        in: header
        description: Bank Correspondent Agent Id
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConsultAnnotationResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /guarantee/{annotationId}/revert-refinancing:
    delete:
      tags:
      - Guarantee
      summary: Revert refinancing of an annotation.
      parameters:
      - name: annotationId
        in: path
        description: annotationId to reverse
        required: true
        schema:
          type: string
          format: uuid
      - name: reason
        in: query
        required: true
        schema:
          $ref: '#/components/schemas/ReasonReversal'
      - name: Pin
        in: header
        schema:
          type: string
      - name: correspAgentId
        in: header
        description: Bank Correspondent Agent Id
        schema:
          type: string
      responses:
        '202':
          description: Accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteRefinancingResponse'
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteRefinancingResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /guarantee/{annotationId}/reactivate:
    put:
      tags:
      - Guarantee
      summary: Reactivate an annotation
      parameters:
      - name: annotationId
        in: path
        description: Id from annotation
        required: true
        schema:
          type: string
          format: uuid
      - name: Pin
        in: header
        schema:
          type: string
      - name: correspAgentId
        in: header
        description: Bank Correspondent Agent Id
        schema:
          type: string
      responses:
        '202':
          description: Accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReactivateAnnotationResponse'
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReactivateAnnotationResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /guarantee/{annotationId}/suspend:
    put:
      tags:
      - Guarantee
      summary: Suspend annotation.
      parameters:
      - name: correspAgentId
        in: header
        description: Bank Correspondent Agent Id
        schema:
          type: string
      - name: annotationId
        in: path
        description: annotationId to reverse
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '202':
          description: Accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnnotationSuspendResponse'
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnnotationSuspendResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /guarantee/anticipation/cancel:
    post:
      tags:
      - Guarantee
      summary: Cancela a liquidação antecipada de parcelas na Dataprev (CT), revertendo o contrato à programação normal de descontos na competência informada.
      parameters:
      - name: correspAgentId
        in: header
        description: Bank Correspondent Agent Id
        schema:
          type: string
      requestBody:
        description: Identificador da averbação e competência (YYYY-MM).
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CancelAnticipationRequest'
          text/json:
            schema:
              $ref: '#/components/schemas/CancelAnticipationRequest'
          application/*+json:
            schema:
              $ref: '#/components/schemas/CancelAnticipationRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CancelAnticipationResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service Unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /guarantee/{annotationId}/cancel-processing:
    put:
      tags:
      - Guarantee
      summary: Cancel an annotation process
      parameters:
      - name: annotationId
        in: path
        description: Id from annotation
        required: true
        schema:
          type: string
          format: uuid
      - name: correspAgentId
        in: header
        description: Bank Correspondent Agent Id
        schema:
          type: string
      responses:
        '202':
          description: Accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CancelProcessAnnotationResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /guarantee/change-ownership:
    post:
      tags:
      - Guarantee
      summary: change the ownership of the annotation
      parameters:
      - name: correspAgentId
        in: header
        description: Bank Correspondent Agent Id
        schema:
          type: string
      requestBody:
        description: ''
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChangeOwnershipRequest'
          text/json:
            schema:
              $ref: '#/components/schemas/ChangeOwnershipRequest'
          application/*+json:
            schema:
              $ref: '#/components/schemas/ChangeOwnershipRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChangeOwnershipResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /guarantee/list-annotations:
    get:
      tags:
      - Guarantee
      summary: Consult a list of annotations from a relative agency
      parameters:
      - name: tokenData
        in: query
        schema:
          type: string
      - name: consultType
        in: query
        schema:
          $ref: '#/components/schemas/ConsultAnnotationType'
      - name: consigneeId
        in: query
        required: true
        schema:
          type: string
          format: uuid
      - name: agencyId
        in: query
        required: true
        schema:
          type: string
          format: uuid
      - name: document
        in: query
        schema:
          type: string
      - name: registration
        in: query
        schema:
          type: string
      - name: productType
        in: query
        schema:
          $ref: '#/components/schemas/TypeProduct'
      - name: page
        in: query
        schema:
          type: integer
          format: int32
      - name: pageSize
        in: query
        schema:
          type: integer
          format: int32
      - name: initDate
        in: query
        schema:
          type: string
          format: date-time
      - name: endDate
        in: query
        schema:
          type: string
          format: date-time
      - name: operationId
        in: query
        schema:
          type: string
      - name: contractNumber
        in: query
        schema:
          type: string
      - name: annotationStatus
        in: query
        schema:
          $ref: '#/components/schemas/StatusContract'
      - name: correspAgentId
        in: header
        description: Bank Correspondent Agent Id
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConsultAnnotationListResponse'
        '204':
          description: No Content
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /guarantee/{annotationId}/change-portability-identifier:
    patch:
      tags:
      - Guarantee
      summary: Alter portability identifier from annotation
      parameters:
      - name: annotationId
        in: path
        description: Id from annotation
        required: true
        schema:
          type: string
          format: uuid
      - name: correspAgentId
        in: header
        description: Bank Correspondent Agent Id
        schema:
          type: string
      requestBody:
        description: Request
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PortabilityChangeUniqueNumberRequest'
          text/json:
            schema:
              $ref: '#/components/schemas/PortabilityChangeUniqueNumberRequest'
          application/*+json:
            schema:
              $ref: '#/components/schemas/PortabilityChangeUniqueNumberRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PortabilityAlterUniqueNumberResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /guarantee/{annotationId}/change-portability-owner:
    patch:
      tags:
      - Guarantee
      summary: Alter portability owner from annotation
      parameters:
      - name: annotationId
        in: path
        description: Id from annotation
        required: true
        schema:
          type: string
          format: uuid
      - name: correspAgentId
        in: header
        description: Bank Correspondent Agent Id
        schema:
          type: string
      requestBody:
        description: Request
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PortabilityAlterOwnerRequest'
          text/json:
            schema:
              $ref: '#/components/schemas/PortabilityAlterOwnerRequest'
          application/*+json:
            schema:
              $ref: '#/components/schemas/PortabilityAlterOwnerRequest'
      responses:
        '202':
          description: Accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PortabilityAlterOwnerResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /guarantee/guarantee-portability:
    put:
      tags:
      - Guarantee
      summary: Exclude contracts by portability
      parameters:
      - name: correspAgentId
        in: header
        description: Bank Correspondent Agent Id
        schema:
          type: string
      requestBody:
        description: ''
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExcludeByPortabilityRequest'
          text/json:
            schema:
              $ref: '#/components/schemas/ExcludeByPortabilityRequest'
          application/*+json:
            schema:
              $ref: '#/components/schemas/ExcludeByPortabilityRequest'
      responses:
        '202':
          description: Accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExcludeByPortabilityResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /guarantee/list-balance-check:
    get:
      tags:
      - Guarantee
      summary: Consult a list of balance checks
      parameters:
      - name: consigneeId
        in: query
        required: true
        schema:
          type: string
          format: uuid
      - name: agencyId
        in: query
        required: true
        schema:
          type: string
          format: uuid
      - name: balanceCheckId
        in: query
        schema:
          type: string
          format: uuid
      - name: document
        in: query
        schema:
          type: string
      - name: page
        in: query
        schema:
          type: integer
          format: int32
      - name: pageSize
        in: query
        schema:
          type: integer
          format: int32
      - name: initDate
        in: query
        schema:
          type: string
          format: date-time
      - name: endDate
        in: query
        schema:
          type: string
          format: date-time
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListBalanceCheckResponse'
        '204':
          description: No Content
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /guarantee/list-payment-notes:
    get:
      tags:
      - Guarantee
      summary: Consult list of payment note.
      parameters:
      - name: consigneeId
        in: query
        required: true
        schema:
          type: string
          format: uuid
      - name: agencyId
        in: query
        required: true
        schema:
          type: str

# --- truncated at 32 KB (69 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/celcoin/refs/heads/main/openapi/celcoin-guarantee-api-openapi.yml