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: "plataformaservicos@seg-social.pt" basePath: "/ptss/rest" tags: - name: "Conta Integrada" - name: "Qualificação" schemes: - "https" paths: /ci/comprovativos-pagamento/{ano-pagamento}: get: tags: - "Conta Integrada" summary: "CI-O080" operationId: "obterComprovativosPagamento" consumes: - "application/json" - "application/xml" produces: - "application/json" - "application/xml" parameters: - name: "ano-pagamento" in: "path" description: "Ano relativo aos pagamentos efetuados para o qual se pretende\ \ obter os comprovativos de pagamento." required: true type: "string" maxLength: 4 minLength: 4 x-example: "2023" - name: "niss-representado" in: "query" description: "Número de identificação na Segurança Social da entidade para\ \ a qual é pretendido a consulta dos comprovativos de pagamento.\r\n\r\n\ O NISS autenticado na Segurança Social direta tem que ter uma relação de\ \ representação com o niss representado.\r\n\r\nQuando não identificado\ \ este parâmetroé considerado que a consulta dos comprovativos de pagamento\ \ é para o NISS autenticado." required: false type: "string" maxLength: 11 minLength: 11 x-example: "19999999999" responses: 401: description: "Falha na autenticação" 403: description: "Operação não permitida" 400: description: "Pedido inválido" schema: $ref: "#/definitions/resultadoObterComprovativosPagamento" examples: application/json: {"codigoResultado": "7"} 500: description: "Erro interno do servidor" schema: $ref: "#/definitions/resultadoObterComprovativosPagamento" examples: application/json: {"codigoResultado": "0"} 200: description: "Operação efetuada com sucesso" schema: $ref: "#/definitions/resultadoObterComprovativosPagamento" 404: description: "Pesquisa sem resultados" schema: $ref: "#/definitions/resultadoObterComprovativosPagamento" examples: application/json: {"codigoResultado": "4"} /ci/documento-pagamento/consulta: get: tags: - "Conta Integrada" summary: "CI-O082" operationId: "obterDocumentosPagamento" consumes: - "application/json" - "application/xml" produces: - "application/json" - "application/xml" parameters: - name: "niss-representado" in: "query" description: "Número de identificação na Segurança Social da entidade para\ \ a qual é pretendido a consulta dos documentos de pagamento a pagamento.\r\ \n\r\nO NISS autenticado na Segurança Social direta tem que ter uma relaç\ ão de representação com o niss representado.\r\n\r\nQuando não identificado\ \ este parâmetro é considerado que a consulta dos documentos de pagamento\ \ é para o NISS autenticado." required: false type: "string" maxLength: 11 minLength: 11 x-example: "19999999999" responses: 401: description: "Falha na autenticação" 403: description: "Operação não permitida" 400: description: "Pedido inválido" schema: $ref: "#/definitions/resultadoConsultaDocumentoPagamento" examples: application/json: {"codigoResultado": "7"} 500: description: "Erro interno do servidor" schema: $ref: "#/definitions/resultadoConsultaDocumentoPagamento" examples: application/json: {"codigoResultado": "0"} 200: description: "Operação efetuada com sucesso" schema: $ref: "#/definitions/resultadoConsultaDocumentoPagamento" 404: description: "Pesquisa sem resultados" schema: $ref: "#/definitions/resultadoConsultaDocumentoPagamento" examples: application/json: {"codigoResultado": "4"} /ci/documento-pagamento/pedido-emissao: post: tags: - "Conta Integrada" summary: "CI-O084" operationId: "pedirEmissaoDocumentoPagamento" consumes: - "application/json" - "application/xml" produces: - "application/json" - "application/xml" parameters: - in: "body" name: "body" required: false schema: $ref: "#/definitions/PedidoEmissaoBodyVO" responses: 401: description: "Falha na autenticação" 403: description: "Operação não permitida" 400: description: "Pedido inválido" schema: $ref: "#/definitions/resultadoPedidoEmissaoDocumentoPagamento" examples: application/json: {"codigoResultado": "9"} 500: description: "Erro interno do servidor" schema: $ref: "#/definitions/resultadoPedidoEmissaoDocumentoPagamento" examples: application/json: {"codigoResultado": "0"} 200: description: "Operação efetuada com sucesso" schema: $ref: "#/definitions/resultadoPedidoEmissaoDocumentoPagamento" /ci/documento-pagamento/consulta-pedido/{chave}: get: tags: - "Conta Integrada" summary: "CI-O084" operationId: "obterPedidoEmissaoDocumentoPagamento" consumes: - "application/json" - "application/xml" produces: - "application/json" - "application/xml" parameters: - name: "chave" in: "path" description: "Identificação da chave do pedido de emissão de documento(s)\ \ de pagamento(s) a consultar." required: true type: "string" maxLength: 12 minLength: 1 x-example: "1302" responses: 401: description: "Falha na autenticação" 403: description: "Operação não permitida" 400: description: "Pedido inválido" schema: $ref: '#/definitions/resultadoConsultaPedidoEmissaoDocumento' examples: application/json: {"codigoResultado": "13"} 500: description: "Erro interno do servidor" schema: $ref: '#/definitions/resultadoConsultaPedidoEmissaoDocumento' examples: application/json: {"codigoResultado": "0"} 200: description: "Operação efetuada com sucesso" schema: $ref: '#/definitions/resultadoConsultaPedidoEmissaoDocumento' 404: description: "Pesquisa sem resultados" schema: $ref: '#/definitions/resultadoConsultaPedidoEmissaoDocumento' examples: application/json: {"codigoResultado": "13"} /ci/documento-pagamento/{identificador-documento}: put: tags: - "Conta Integrada" summary: "CI-O081" operationId: "cancelarDocumentoPagamento" consumes: - "application/json" - "application/xml" produces: - "application/json" - "application/xml" parameters: - name: "identificador-documento" in: "path" description: "Número do documento de pagamento a cancelar." required: true type: "string" maxLength: 12 minLength: 1 x-example: "99999" - name: "niss-representado" in: "query" description: "Número de identificação na Segurança Social da entidade para\ \ a qual é pretendido o cancelamento do documento de pagamento.\r\n\r\n\ O NISS autenticado na Segurança Social direta tem que ter uma relação de\ \ representação com o niss representado.\r\n\r\nQuando não identificado\ \ este parâmetro é considerado que o cancelamento do documento de pagamento\ \ é para o NISS autenticado." required: false type: "string" maxLength: 11 minLength: 11 x-example: "19999999999" responses: 401: description: "Falha na autenticação" 403: description: "Operação não permitida" 400: description: "Pedido inválido" schema: $ref: '#/definitions/resultadoCancelamentoDocumentoPagamento' examples: application/json: {"codigoResultado": "17"} 500: description: "Erro interno do servidor" schema: $ref: '#/definitions/resultadoCancelamentoDocumentoPagamento' examples: application/json: {"codigoResultado": "0"} 200: description: "Operação efetuada com sucesso" schema: $ref: '#/definitions/resultadoCancelamentoDocumentoPagamento' /qlf/tco/vinculos/pedido: post: tags: - "Qualificação" summary: "QLF-O1051" operationId: "registarPedidoVinculoEnquadramento" consumes: - "application/json" produces: - "application/json" parameters: - in: "body" name: "body" required: false schema: $ref: "#/definitions/comunicar-vinculo-trabalhador-enquadramento-input" responses: 204: description: "Operação efetuada com sucesso" 400: description: "Pedido inválido" 500: description: "Erro interno do servidor" definitions: comunicar-vinculo-trabalhador-enquadramento-input: type: "object" required: - "data-nascimento" - "enquadramento" - "inicio-contrato" - "local-trabalho" - "modalidade-contrato" - "niss-entidade-empregadora" - "niss-trabalhador" - "prestacao-trabalho" - "profissao" - "remuneracao-base" properties: niss-entidade-empregadora: type: "integer" format: "int64" example: 29999999999 description: "Número de identificação na Segurança Social da entidade empregadora" niss-trabalhador: type: "integer" format: "int64" example: 19999999999 description: "Número de identificação na Segurança Social do trabalhador" data-nascimento: type: "string" format: "date-time" example: "1993-07-21" description: "Data de nascimento do trabalhador" modalidade-contrato: type: "string" example: "E" description: "Modalidade de contrato de trabalho do trabalhador" enum: - "'A - Sem termo, tempo completo'" - "'C - Sem termo, tempo completo, intermitente ou atividade descontínua'" - "'AA - Sem termo, tempo completo, comissão de serviço'" - "'AB - Sem termo, tempo completo teletrabalho'" - "'S - Sem termo tempo completo trabalho temporário'" - "'B - Sem termo, tempo parcial'" - "'D - Sem termo, tempo parcial, intermitente ou atividade descontínua'" - "'BA - Sem termo, tempo parcial, comissão de serviço'" - "'BB - Sem termo, tempo parcial, teletrabalho'" - "'R - Sem termo, tempo parcial, trabalho temporário'" - "'E - A termo certo, tempo completo'" - "'EA - A termo certo, tempo completo, comissão de serviço'" - "'EB - A termo certo, tempo completo, teletrabalho'" - "'O - A termo certo, tempo completo, trabalho temporário'" - "'F - A termo certo, tempo parcial'" - "'FA - A termo certo, tempo parcial, comissão de serviço'" - "'FB - A termo certo, tempo parcial, teletrabalho'" - "'N - A termo certo, tempo parcial, trabalho temporário'" - "'G - A termo incerto, tempo completo'" - "'GA - A termo incerto, tempo completo, comissão de serviço'" - "'GB - A termo incerto, tempo completo, teletrabalho'" - "'Q - A termo incerto, tempo completo, trabalho temporário'" - "'H - A termo incerto, tempo parcial'" - "'HA - A termo incerto, tempo parcial, comissão de serviço'" - "'HB - A termo incerto, tempo parcial, teletrabalho'" - "'P - A termo incerto, tempo parcial, trabalho temporário'" - "'I - Muito curta duração'" prestacao-trabalho: type: "string" example: "P" description: "Prestação de trabalho do contrato do trabalhador" enum: - "'P - Presencial'" - "'T - Teletrabalho total'" - "'A - Teletrabalho parcial'" inicio-contrato: type: "string" format: "date-time" example: "2023-07-21" description: "Data de início do contrato de trabalho do trabalhador" fim-contrato: type: "string" format: "date-time" example: "2024-07-21" description: "Data de fim do contrato de trabalho do trabalhador" profissao: type: "string" example: "93130" description: "Código da profissão do contrato de trabalho de acordo com informação da Classificação Portuguesa das Profissões. O código de profissão a enviaré o código de 5 caracteres, sem o ponto" minLength: 5 maxLength: 5 remuneracao-base: type: "number" format: "double" example: 1500.58 description: "Remuneração base do contrato de trabalho do trabalhador" diuturnidades: type: "number" format: "double" example: 50.5 description: "Diurnidades do contrato de trabalho do trabalhador" percentagem-trabalho: type: "number" format: "double" example: 50.0 description: "Percentagem de trabalho do contrato do trabalhador" horas-trabalho: type: "number" format: "double" example: 30.0 description: "Número de horas de trabalho do contrato do trabalhador" dias-trabalho: type: "number" format: "double" example: 15.0 description: "Número de dias de trabalho do contrato do trabalhador" motivo-contrato: type: "string" example: "AEAT" description: "Motivo do contrato de trabalho do trabalhador" niss-trabalhador-substituir: type: "integer" format: "int64" example: 19999999998 description: "Número de identificação na Segurança Social do trabalhador a substituir" local-trabalho: type: "integer" format: "int32" example: 1 description: "Local de trabalho do trabalhador" enquadramento: type: "string" example: "REGE" description: "Enquadramento da prestação de trabalho" xml: name: "comunicar-vinculo-trabalhador-enquadramento-input" namespace: "http://app.seg-social.pt/xml/qlf/vinculo-trabalhador-enquadramento" PedidoEmissaoBodyVO: type: "object" required: - "ambito" properties: ambito: type: "integer" format: "int64" example: 11 description: "Identifica para que âmbito se pretende emitir os valores a pagar." enum: - "'11 - Contribuições - Entidade Empregadora'" - "'12 - Contribuições - Trabalhador Independente'" - "'13 - Contribuições - Seguro Social Voluntário'" - "'14 - Contribuições - Produtor Agrícola dos Açores'" - "'15 - Contribuições - Serviço Doméstico'" - "'16 - Contribuições - Entidade Contratante'" - "'17 - Contraordenações'" - "'18 - Acordos e planos prestacionais'" - "'19 - Outros Valorese'" - "'20 - Contribuições - Entidade Beneficiária'" nissRepresentado: type: "string" example: "19999999999" description: "Número de identificação na Segurança Social da entidade para\ \ a qual é pretendido emitir o(s) documento(s) de pagamento.\r\n\r\nO NISS\ \ autenticado na Segurança Social direta tem que ter uma relação de representaç\ ão com o niss representado.\r\n\r\nQuando não identificado este parâmetro é\ \ considerado que a emissão do(s) documento(s) de pagamento é para o NISS\ \ autenticado." minLength: 11 maxLength: 11 resultadoCancelamentoDocumentoPagamento: type: "object" required: - "codigoResultado" properties: codigoResultado: type: "string" example: "1" description: "Código indicador do sucesso ou insucesso no pedido de cancelamento do documento de pagamento." enum: - "'0 - Erro interno do servidor'" - "'1 - Sucesso'" - "'7 - A entidade representante não representa o NISS representado'" - "'8 - NISS inválido'" - "'17 - Documento de pagamento inválido para cancelamento'" mensagem: type: "string" description: "Mensagem adicional a complementar o resultado do pedido de cancelamento." resultadoConsultaPedidoEmissaoDocumento: type: "object" required: - "codigoResultado" properties: codigoResultado: type: "string" example: "1" description: "Código indicador do sucesso ou insucesso na obtenção de resposta ao pedido de emissão de documentos de pagamento." enum: - "'0 - Erro interno do servidor'" - "'1 - Sucesso'" - "'10 - Pedido em processamento'" - "'13 – Chave inválida'" - "'14 - Pedido expirado'" - "'15 - No momento, não foram identificados valores a pagar'" mensagem: type: "string" description: "Mensagem adicional a complementar o resultado à obtenção da resposta." resultado: type: "array" items: $ref: '#/definitions/ObterDocumentoPagamentoVO' resultadoPedidoEmissaoDocumentoPagamento: type: "object" required: - "codigoResultado" properties: codigoResultado: type: "string" example: "1" description: "Código indicador do sucesso ou insucesso na solicitação do pedido de emissão de documentos de pagamento." enum: - "'0 - Erro interno do servidor'" - "'1 - Sucesso'" - "'7 - A entidade representante não representa o NISS representado'" - "'8 - NISS inválido'" - "'9 - Âmbito de emissão de documento de pagamento inválido'" - "'10 - Pedido em processamento'" - "'11 - Tem uma resposta ao pedido ainda na validade'" mensagem: type: "string" description: "Mensagem adicional a complementar o resultado do pedido." chave: type: "number" example: "390" format: "int64" description: "Identificador do pedido documento de pagamento, que será a chave a utilizar para a obtenção do resultado do processamento do pedido. A chave é devolvida para o código resultado: 1, 10, 11, caso contrário é retornado a nulo." resultadoConsultaDocumentoPagamento: type: "object" required: - "codigoResultado" properties: codigoResultado: type: "string" example: "1" description: "Código indicador do sucesso ou insucesso na obtenção dos documentos de pagamento a pagamento." enum: - "'0 - Erro interno do servidor'" - "'1 - Sucesso'" - "'4 - Pesquisa sem resultados'" - "'7 - A entidade representante não representa o NISS representado'" - "'8 - NISS inválido'" mensagem: type: "string" description: "Mensagem adicional a complementar o resultado da consulta." resultado: description: "Lista de documentos de pagamento a pagamento." type: "array" items: $ref: "#/definitions/ObterDocumentoPagamentoVO" resultadoObterComprovativosPagamento: type: "object" required: - "codigoResultado" properties: codigoResultado: type: "string" example: "1" description: "Código indicador do sucesso ou insucesso na obtenção dos comprovativos de pagamento." enum: - "'0 - Erro interno do servidor'" - "'1 - Sucesso'" - "'4 - Pesquisa sem resultados'" - "'7 - A entidade representante não representa o NISS representado'" - "'8 - NISS inválido'" mensagem: type: "string" description: "Mensagem adicional a complementar no retorno da consulta dos comprovativos de pagamento." resultado: type: "array" items: $ref: "#/definitions/ComprovativoPagamentoVO" ObterDocumentoPagamentoVO: type: "object" required: - "niss" - "tipo" - "subtipo" - "descritivo" - "numeroDocumentoPagamento" - "dataValidade" - "valor" - "referenciaDocumentoPagamento" properties: niss: type: "integer" format: "int64" example: "19999999999" description: "Destinatário do documento de pagamento emitido." tipo: type: "string" description: "Descritivo do tipo de contexto do documento de pagamento." subtipo: type: "string" example: "Contribuições - Trabalhador Independente" description: "Descritivo do subtipo do contexto documento de pagamento." descritivo: type: "string" description: "Texto informativo relativo ao documento de pagamento." numeroDocumentoPagamento: type: "integer" format: "int64" example: 60569111 description: "Identificador do documento de pagamento emitido." dataValidade: type: "string" format: "date" example: "2023-11-04" description: "Data de validade de pagamento do documento de pagamento (formato YYYY-MM-DD)." valor: type: "number" format: "double" example: 311.63 description: "Valor a pagamento no documento de pagamento (formato 9999999999.99)." referenciaDocumentoPagamento: description: "Modalidades de pagamento disponibilizadas, atualmente, para o pagamento de um documento de pagamento." type: "object" required: - "pagamentoTesouraria" - "pagamentoTransferenciaBancaria" - "pagamentoMultibanco" - "pagamentoDebitoDireto" properties: pagamentoTesouraria: type: "string" example: "S" description: "Indicador de que o documento de pagamento é pagável na tesouraria." enum: - "'S – É possível efetuar pagamento por tesouraria'" - "'N – Não é possível efetuar pagamento por tesouraria'" pagamentoTransferenciaBancaria: description: "Dados para pagamento por transferência bancária caso o documento de pagamento é pagável por transferência bancária." type: "object" properties: iban: type: "string" example: "PT5001930566510900178546" description: "Referência iban a utilizar para o pagamento." swift: type: "string" example: "CTTVPTPL" description: "Referência bic/swift a utilizar para o pagamento." referenciaPagamentoInvalida: type: "string" description: "Motivo da não geração de uma referência iban." enum: - "'3 - Erro ao gerar um Iban'" pagamentoMultibanco: description: "Dados para pagamento por referência multibanco caso o documento de pagamento é pagável por referência multibanco." type: "object" properties: entidadeMultibanco: type: "integer" format: "int32" example: 21056 description: "Referência da entidade multibanco, caso não ocorra erro na geração da referência multibanco." referenciaMultibanco: type: "string" example: 999999999 description: "Referência da referência multibanco caso não ocorra erro na geração da referência multibanco." referenciaPagamentoInvalida: type: "string" description: "Motivo da não geração de uma referência multibanco." enum: - "'1 – Não é possível pagar por multibanco para valores superiores a 99.999,99 €'" - "'2 - Erro ao gerar uma referência multibanco'" pagamentoDebitoDireto: description: "Dados para pagamento por débito direto caso o documento de pagamento é pagável por débito em conta." type: "object" properties: numeroAutorizacao: type: "integer" format: "int64" example: "565" description: "Identificador da ADC." dataCobranca: type: "string" format: "date" description: "Data em que ocorrerá o débito em conta (formato YYYY-MM-DD)." ComprovativoPagamentoVO: type: "object" required: - "niss" - "dataPagamento" - "numeroDocumentoPagamento" - "mensagemNaturezaPagamento" - "valorPago" properties: niss: type: "integer" format: "int64" example: 19999999999 description: "Niss do documento de pagamento ao qual o pagamento foi imputado." dataPagamento: type: "string" format: "date" example: "2023-05-10" description: "Data em que o pagamento foi efetuado (formato YYYY-MM-DD)." numeroDocumentoPagamento: type: "integer" format: "int64" example: 59333665 description: "Identificador do documento de pagamento ao qual o pagamento foi imputado." mensagemNaturezaPagamento: type: "string" example: "O pagamento foi efetuado no multibanco na data 2023-05-10 com a referência 096526963 e a entidade 21111." description: "Descritivo identificador do modo de pagamento, data e referências utilizado." enum: - "'Multibanco - O pagamento foi efetuado no multibanco na data {0} com a referência {1} e a entidade {2}.'" - "'Multibanco - Serviço Especial - O pagamento foi efetuado por Multibanco - Serviço Especial na data {0} com o recibo {1}.'" - "'Tesouraria - Terminal de pagamento automático - O pagamento foi efetuado na tesouraria na data {0} por TPA.'" - "'Tesouraria - Numerário - O pagamento foi efetuado na tesouraria na data {0} em numerário.'" - "'Tesouraria - Vale de correio - O pagamento foi efetuado na tesouraria na data {0} por vale de correio.'" - "'Tesouraria - Cheque - O pagamento foi efetuado na tesouraria na data {0} por cheque com o nº {1} da conta nº {2} do banco com o código nº {3}.'" - "'Tesouraria - Outro - O pagamento foi efetuado na tesouraria na data {0} por outra modalidade de pagamento.'" - "'Transferência bancária - O pagamento foi efetuado por transferência bancária na data {0} com o Iban {1}.'" - "'Débito Direto - O pagamento foi efetuado por Débito Direto na data {0} com a autorização {1}.'" valorPago: type: "number" format: "double" example: 11.79 description: "Valor do pagamento (formato 9999999999.99)."