openapi: 3.1.0 info: title: Integração PunchClock - Solicitação de Extensão de Jornada version: 1.0.0 description: | API para solicitação de extensão de jornada de trabalho. Esta API permite que sistemas externos solicitem extensões de jornada para colaboradores, enviando notificações automáticas para os gestores responsáveis pela aprovação. ## Fluxo de Uso 1. O sistema cliente envia uma solicitação com os dados do colaborador e tempo extra desejado 2. A API valida a autenticação via `key` 3. A solicitação é registrada no banco de dados 4. Notificações são enviadas automaticamente para os gestores (e-mail e/ou WhatsApp) 5. O gestor pode aprovar ou rejeitar usando as APIs de aprovação ## Autenticação - Via campo `key` no corpo da requisição (JSON) - A key é uma string criptografada que identifica a empresa servers: - url: https://integrations.fhinck.com description: Produção - url: https://integrations-hml.fhinck.com description: Homologação paths: /requestExtension: get: summary: Health Check description: Verifica se o serviço está rodando operationId: integrationsRequestExtensionHealthCheck responses: "200": description: Serviço funcionando content: text/plain: schema: type: string example: RequestExtension service is running post: summary: Solicitar extensão de jornada description: | Cria uma nova solicitação de extensão de jornada de trabalho para um colaborador. A solicitação será registrada e notificações serão enviadas automaticamente para os gestores configurados. operationId: integrationsRequestExtension requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/RequestExtensionRequest" examples: exemploBasico: summary: Solicitação básica de 1 hora extra value: key: "SUA_CHAVE_DE_AUTENTICACAO" user: "michel.filho" extraTime: "2024-12-03 18:30:00" reqMinutes: 60 justification: "Projeto urgente com deadline apertado" exemploComGestor: summary: Solicitação com gestor específico value: key: "SUA_CHAVE_DE_AUTENTICACAO" user: "joao.silva" extraTime: "2024-12-03 19:00:00" reqMinutes: 120 justification: "Fechamento mensal do sistema financeiro" manager: "maria.gestora@empresa.com" responses: "200": description: Solicitação criada com sucesso content: application/json: schema: $ref: "#/components/schemas/RequestExtensionSuccessResponse" examples: sucesso: value: err: false message: "Solicitação de extensão criada com sucesso" requestTime: 3600 approvalLinkKey: "EXEMPLO-CHAVE-DO-LINK" "400": description: Requisição inválida content: application/json: schema: $ref: "#/components/schemas/RequestExtensionErrorResponse" examples: keyAusente: summary: Key não informada value: err: true message: "Campo key é obrigatório" code: "MISSING_KEY" keyInvalida: summary: Key inválida value: err: true message: "Key inválida" code: "INVALID_KEY" camposAusentes: summary: Campos obrigatórios ausentes value: err: true message: "Campos obrigatórios ausentes: user, reqMinutes" code: "MISSING_REQUIRED_FIELDS" formatoIncorreto: summary: Formato de data incorreto value: err: true msg: "NOT OK - EXTRATIME WRONG FORMAT" "500": description: Erro interno do servidor content: application/json: schema: $ref: "#/components/schemas/InternalErrorResponse" components: schemas: RequestExtensionRequest: type: object required: - key - user - extraTime - reqMinutes - justification properties: key: type: string description: | Chave única de autenticação do cliente (criptografada). Esta chave é fornecida pela Fhinck durante a integração. example: "SUA_CHAVE_DE_AUTENTICACAO" user: type: string description: | Identificador único do colaborador (login/username). Deve corresponder ao login cadastrado no sistema Fhinck. example: "michel.filho" extraTime: type: string format: date-time description: | Data e hora da solicitação de extensão. Formato: YYYY-MM-DD HH:mm:ss example: "2024-12-03 18:30:00" reqMinutes: type: integer minimum: 1 maximum: 480 description: | Quantidade de minutos extras solicitados. O valor será convertido para segundos internamente (reqMinutes * 60). example: 60 justification: type: string minLength: 1 maxLength: 500 description: | Justificativa para a solicitação de extensão. Este texto será exibido para o gestor no momento da aprovação. example: "Projeto urgente com deadline apertado" manager: type: string format: email description: | Email do gestor responsável pela aprovação (opcional). Se não informado, o sistema utilizará o gestor configurado para o colaborador. example: "gestor@empresa.com" RequestExtensionSuccessResponse: type: object properties: err: type: boolean description: Indica se houve erro (false = sucesso) example: false message: type: string description: Mensagem de retorno example: "Solicitação de extensão criada com sucesso" requestTime: type: integer description: | Tempo total solicitado em segundos. Este valor pode ser maior que o solicitado caso já existam solicitações anteriores do mesmo dia ainda não aprovadas. example: 3600 approvalLinkKey: type: string nullable: true description: | Chave do link de aprovação enviado ao gestor. Pode ser null se a empresa estiver em ambiente de homologação. example: "EXEMPLO-CHAVE-DO-LINK" RequestExtensionErrorResponse: type: object properties: err: type: boolean description: Indica se houve erro (true = erro) example: true message: type: string description: Mensagem descritiva do erro example: "Campo key é obrigatório" msg: type: string description: Mensagem alternativa de erro (usado em alguns cenários) example: "NOT OK - EXTRATIME WRONG FORMAT" code: type: string description: Código do erro para tratamento programático enum: - MISSING_KEY - INVALID_KEY - MISSING_REQUIRED_FIELDS - PROCESSING_ERROR example: "MISSING_KEY" InternalErrorResponse: type: object properties: error: type: string example: "Erro interno do servidor" message: type: string example: "Detalhes do erro"