swagger: "2.0"
info:
  description: "Documentação técnica de webservices ReST disponibilizados na Plataforma de Serviços de Interoperabilidade."
  version: "1.0"
  title: "PSI Swagger"
  contact:
    name: "suporte-psi@seg-social.pt" 
basePath: "/ptss/rest"
tags:
- name: "Apuramento de Situação e Certificação de Documentos"

schemes:
- "https"
paths:
  /ascd/declaracao/situacao-contributiva:
    post:
      tags:
      - "Apuramento de Situação e Certificação de Documentos"
      summary: "ASCD-O113"
      operationId: "dscParceiros"
      consumes:
      - "application/json"
      produces:
      - "application/json"
      parameters:
      - in: "body"
        name: "body"
        required: false
        schema:
          $ref: "#/definitions/EmitirDSCParceirosRequest"
      responses:
        200:
          description: "Pedido registado com sucesso."
          examples:
            application/json:
             caminho: "/ptss/fraw/download/215372600/20260525_140024_6803001451384651_5705951263901614080.pdf"
             situacaoContributivaRegularizada: true
          schema:
            $ref: "#/definitions/EmitirDSCParceirosResponse"
                        
        400:
          description: |
            Erro de validação.

            Possíveis mensagens:
            - O campo niss solicitante é obrigatório
            - O campo niss solicitado é obrigatório            
            - O campo niss solicitante é inválido
            - O campo niss solicitado é inválido            
          schema:
            type: object
            properties:
              mensagem:
                type: string
                example: "O campo niss solicitante é obrigatório"
          examples:
            application/json:
              mensagem: "O campo niss solicitante é obrigatório"
        403:
          description: "Erro de permissão"
          schema:
            type: object
            properties:
              mensagem:
                type: string
                example: "O niss solicitante não possui relação de representação com o niss solicitado"
        500:
          description: "Erro inesperado"
          schema:
            type: object
            properties:
              mensagem:
                type: string
                example: "De momento não é possível visualizar o documento. Por favor, tente mais tarde."
      security:
      - fraw-operations:
        - "ASCD-O113"

definitions:
  EmitirDSCParceirosRequest:
    type: "object"
    required:    
    - nissSolicitante
    - nissSolicitado
    properties:     
      nissSolicitante:
        description: "Niss do solicitante da situação contributiva com 11 dígitos."
        type: "integer"
        format: "int64"
        example: 12345678911        
      nissSolicitado:
        description: "Niss de quem será apurada a situação contributiva com 11 dígitos."
        type: "integer"
        format: "int64"
        example: 12345678911        
  EmitirDSCParceirosResponse:
    type: "object"
    properties:
      caminho:
        description: "URL do documento gerado"
        type: "string"
        example: "/ptss/fraw/download/215372600/20260525_140024_6803001451384651_5705951263901614080.pdf"        
      situacaoContributivaRegularizada:
        description: "Situação contributiva do niss solicitado"
        type: "boolean"
        example: true