{"openapi":"3.1.0","info":{"title":"opontoup Open API","version":"1.0.0","description":"API Aberta e RESTful do opontoup para registro eletrônico de ponto (REP-P) em conformidade total com a Portaria 671/2021 MTE, emissão de arquivos fiscais (AFD/AEJ) e integração com o sistema de assinatura eletrônica Esigna.","contact":{"name":"Suporte Técnico opontoup","email":"suporte@opontoup.com.br","url":"https://opontoup.vercel.app"},"license":{"name":"Proprietária - opontoup Tecnologia"}},"servers":[{"url":"https://opontoup.vercel.app","description":"Servidor de Produção (Vercel Edge / São Paulo)"},{"url":"http://localhost:3000","description":"Ambiente de Desenvolvimento Local"}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-Opontoup-Key","description":"Chave de API emitida para o Tenant ou Master Secret do opontoup."},"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT / Token","description":"Token Bearer de autenticação de serviço."}},"schemas":{"TimeRecordInput":{"type":"object","required":["employee_cpf","record_type"],"properties":{"employee_cpf":{"type":"string","example":"123.456.789-00","description":"CPF do colaborador (com ou sem pontuação)"},"company_cnpj":{"type":"string","example":"54.892.102/0001-99","description":"CNPJ da empresa contratante"},"record_type":{"type":"string","enum":["ENTRY","LUNCH_START","LUNCH_END","EXIT"],"example":"ENTRY","description":"Tipo de marcação de ponto"},"source":{"type":"string","enum":["APP_MOBILE","KIOSK_TABLET","WEB","WHATSAPP","REP_C","IMPORTED"],"default":"WEB","example":"APP_MOBILE"},"recorded_at":{"type":"string","format":"date-time","example":"2026-10-09T08:00:00Z","description":"Data e hora no padrão ISO 8601 (UTC)"},"latitude":{"type":"number","example":-23.55052},"longitude":{"type":"number","example":-46.633308},"accuracy_meters":{"type":"number","example":8.5},"idempotency_key":{"type":"string","example":"punch_7f8c9b2a1e","description":"Identificador único da requisição para prevenir duplicidade"}}},"TimeRecordReceipt":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"nsr":{"type":"integer","example":1042},"recorded_at":{"type":"string","format":"date-time"},"record_type":{"type":"string"},"sha256_hash":{"type":"string","example":"a8f5e61c390234bdca7819e6d0421e64901b87ec34c49802e3b2e59e1ab308c4"},"receipt_text":{"type":"string","description":"Texto do comprovante do trabalhador nos termos da Portaria 671 MTE"}}},"CloseTimesheetInput":{"type":"object","required":["period","company_id","employee_id"],"properties":{"period":{"type":"string","example":"2026-10","description":"Mês de referência no formato AAAA-MM"},"company_id":{"type":"string","format":"uuid"},"employee_id":{"type":"string","format":"uuid"},"auto_notify_signers":{"type":"boolean","default":true}}}}},"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"paths":{"/api/v1/time-records":{"post":{"summary":"Registrar Marcação de Ponto (REP-P)","description":"Efetua o registro atômico e imutável de ponto em conformidade com a Portaria 671/2021 MTE. Gera automaticamente o NSR consecutivo e calcula o Hash SHA-256.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TimeRecordInput"}}}},"responses":{"201":{"description":"Ponto registrado com sucesso e comprovante fiscal emitido","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TimeRecordReceipt"}}}},"400":{"description":"CPF ou dados inválidos"},"401":{"description":"Não autorizado"},"422":{"description":"Erro de validação do schema"}}},"get":{"summary":"Consultar Registros de Ponto","description":"Lista marcações filtradas por colaborador, data e empresa.","parameters":[{"name":"employee_cpf","in":"query","schema":{"type":"string"},"description":"Filtrar por CPF do colaborador"},{"name":"company_cnpj","in":"query","schema":{"type":"string"},"description":"Filtrar por CNPJ da empresa"},{"name":"start_date","in":"query","schema":{"type":"string","format":"date"},"description":"Data inicial (AAAA-MM-DD)"},{"name":"end_date","in":"query","schema":{"type":"string","format":"date"},"description":"Data final (AAAA-MM-DD)"}],"responses":{"200":{"description":"Lista de batidas com paginação"}}}},"/api/v1/fiscal/afd":{"get":{"summary":"Exportar AFD Fiscal (Portaria 671 MTE)","description":"Gera o Arquivo Fonte de Dados (.txt posicional) oficial para apresentação aos Auditores Fiscais do Trabalho.","parameters":[{"name":"company_cnpj","in":"query","required":true,"schema":{"type":"string"}},{"name":"start_date","in":"query","required":true,"schema":{"type":"string"}},{"name":"end_date","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Arquivo texto formatado no padrão Anexo VIII Portaria 671/2021","content":{"text/plain":{"schema":{"type":"string"}}}}}}},"/api/v1/fiscal/aej":{"get":{"summary":"Exportar AEJ Fiscal (Arquivo Eletrônico de Jornada)","description":"Gera o arquivo JSON auditável de jornada contendo espelho completo, apuração de horas e marcações de ponto.","parameters":[{"name":"employee_cpf","in":"query","required":true,"schema":{"type":"string"}},{"name":"start_date","in":"query","required":true,"schema":{"type":"string"}},{"name":"end_date","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Estrutura do AEJ nos termos da Portaria 671 MTE"}}}},"/api/v1/timesheets/close":{"post":{"summary":"Fechar Espelho e Disparar Assinatura (Esigna)","description":"Consolida as horas mensais do colaborador e despacha o espelho para assinatura eletrônica jurídica no Esigna.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CloseTimesheetInput"}}}},"responses":{"201":{"description":"Espelho fechado e link de assinatura gerado"}}}},"/api/v1/employees":{"get":{"summary":"Listar Colaboradores","description":"Consulta colaboradores cadastrados com escalas e biometria.","responses":{"200":{"description":"Lista de colaboradores retornada com sucesso"}}},"post":{"summary":"Cadastrar Colaborador","description":"Cadastra novo colaborador com validação de CPF e escala.","responses":{"201":{"description":"Colaborador cadastrado"},"409":{"description":"CPF ou e-mail já existente"}}}},"/api/v1/adjustments":{"get":{"summary":"Listar Ajustes e Atestados","description":"Consulta solicitações de ajuste de ponto e atestados médicos.","responses":{"200":{"description":"Lista de ajustes"}}},"post":{"summary":"Solicitar Ajuste ou Enviar Atestado","description":"Submete novo pedido de ajuste de ponto para auditoria.","responses":{"201":{"description":"Solicitação registrada"}}}},"/api/v1/adjustments/{id}":{"patch":{"summary":"Aprovar ou Recusar Ajuste","description":"Aprova ou rejeita a solicitação de ajuste e lança no espelho se aprovado.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Status do ajuste atualizado"}}}},"/api/v1/timesheets":{"get":{"summary":"Listar Espelhos por Competência","description":"Retorna a relação de espelhos da competência com horas e assinaturas.","parameters":[{"name":"period","in":"query","schema":{"type":"string","example":"2026-10"}}],"responses":{"200":{"description":"Lista consolidada da competência"}}}},"/api/v1/dashboard/metrics":{"get":{"summary":"Métricas em Tempo Real do RH","description":"Consolida presenças do dia, batidas ímpares, atestados e espelhos assinados.","responses":{"200":{"description":"Métricas e feed recente"}}}},"/api/v1/time-records/batch":{"post":{"summary":"Sincronização em Lote de Batidas Offline","description":"Processa fila offline de batidas do app mobile com atomicidade e idempotência.","responses":{"200":{"description":"Lote processado com relatório individual"}}}},"/api/v1/bank-hours/summary":{"get":{"summary":"Extrato de Banco de Horas (CLT Art. 59)","description":"Consolida créditos, débitos e alerta de excesso legal de 2h/dia.","responses":{"200":{"description":"Extrato consolidado"}}}},"/api/v1/bank-hours/adjust":{"post":{"summary":"Lançamento Manual em Banco de Horas","description":"Registra crédito ou débito manual com justificativa legal auditável.","responses":{"201":{"description":"Ajuste efetuado"}}}},"/api/v1/webhooks/signature-completed":{"post":{"summary":"Webhook: Assinatura Concluída (Esigna)","description":"Recebe notificação assinada criptograficamente quando colaborador e gestor finalizam a assinatura do espelho.","responses":{"200":{"description":"Webhook processado com sucesso"},"401":{"description":"Assinatura HMAC inválida"}}}}}}