{"openapi":"3.1.0","info":{"title":"Prumo API","version":"1.0.0","description":"API pública da Prumo. Uma chave pertence a uma organização e enxerga exatamente o que o papel de quem a criou enxerga."},"servers":[{"url":"https://api.goprumo.com.br/functions/v1/api/v1"}],"security":[{"bearerAuth":[]}],"tags":[{"name":"Conta e organização","description":"A chave já sabe de qual organização ela é. Nenhum endereço aceita um id de organização por fora."},{"name":"Membros e convites","description":"Membros são as contas com acesso ao produto. O proprietário nunca pode ser alterado nem removido pela API, e uma chave não mexe na própria conta."},{"name":"Funcionários","description":"O quadro que alimenta toda competência. Desligar é um endereço próprio, porque a data entra na mesma escrita."},{"name":"Folha de pagamento","description":"A competência congela o quadro e as tabelas fiscais na abertura. Todo lançamento é recalculado pelo mesmo motor que a tela usa."},{"name":"Holerites","description":"Duas origens convivem: o holerite que sai da folha e o PDF enviado em lote. A assinatura em si só acontece na sessão do funcionário, nunca pela API."},{"name":"Cobrança","description":"A fatura nasce quando a folha é aprovada, com o número de pessoas congelado naquele instante."},{"name":"Análise financeira","description":"As demonstrações, os indicadores e as carteiras montados a partir do balancete importado. A importação por aqui recebe JSON já normalizado: o parser de planilha continua só na tela."},{"name":"Férias","description":"O período aquisitivo sai da admissão e o saldo é consumido do mais antigo para o mais novo. O que for aprovado entra na folha da competência em que cai."},{"name":"Ponto","description":"A batida é registro imutável: só um ajuste aprovado corrige, e o horário antigo continua no histórico. Espelho, saldo do dia e banco de horas saem derivados das batidas, nunca gravados."},{"name":"Suporte","description":"Os chamados que os clientes da sua empresa abrem pelo link público de suporte. O prazo de resposta corre de segunda a sábado, das 7h às 18h."},{"name":"Benefícios","description":"O catálogo é da organização e a adesão é da pessoa. O valor da adesão vence o do plano quando existe, e a situação sai das datas: nada de ativo ou encerrado é gravado."},{"name":"Compras","description":"A requisição anda em três etapas: quem pede abre, suprimentos confere e o financeiro libera. A trilha e o alerta de preço são derivados, nunca gravados, e o fornecedor é só nome e CNPJ, sem cadastro."},{"name":"Admissão e desligamento","description":"O ciclo de entrada e de saída como processo. A admissão prende um checklist na ficha do funcionário e segura a situação em onboarding até tudo fechar; o desligamento guarda motivo, aviso prévio e checklist de saída, e congela as verbas rescisórias na conclusão. A prévia das verbas é recalculada a cada leitura e nunca vem do corpo da requisição."}],"paths":{"/v1/me":{"get":{"operationId":"get-me","summary":"Quem sou eu","description":"Devolve a chave, a pessoa que a criou, a organização e o nível de cada permissão desse papel. Permissão: qualquer chave.","tags":["Conta e organização"],"parameters":[],"responses":{"200":{"description":"A organização, o ator e o mapa de permissões.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}}},"/v1/organization":{"get":{"operationId":"get-organization","summary":"Dados da empresa","description":"Cadastro completo da organização da chave. Permissão: qualquer chave.","tags":["Conta e organização"],"parameters":[],"responses":{"200":{"description":"A organização.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}},"patch":{"operationId":"patch-organization","summary":"Atualizar a empresa","description":"Muda só os campos enviados. O CNPJ é imutável e qualquer campo desconhecido faz a requisição falhar. Permissão: manage_members.","tags":["Conta e organização"],"parameters":[],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"legalName":{"type":"string","nullable":true,"description":"Razão social."},"tradeName":{"type":"string","nullable":true,"description":"Nome fantasia."},"cnae":{"type":"string","nullable":true,"description":"CNAE principal."},"street":{"type":"string","nullable":true,"description":"Logradouro."},"city":{"type":"string","nullable":true,"description":"Cidade."},"state":{"type":"string","nullable":true,"description":"Sigla do estado, duas letras."},"postalCode":{"type":"string","nullable":true,"description":"CEP, oito dígitos, só números."},"taxRegime":{"type":"string","enum":["simples","general"],"description":"Regime tributário."},"ratRate":{"type":"number","description":"RAT como fração: 0.02 é 2%. Vai de 0 a 0.03."},"paydayRule":{"type":"string","nullable":true,"description":"Regra de pagamento."},"pjVacationPaid":{"type":"string","description":"Se as férias de PJ são remuneradas ou descontadas pro rata."},"employerUnion":{"type":"string","nullable":true,"description":"Sindicato patronal."},"digitalCertificateExpiresAt":{"type":"string","nullable":true,"description":"Validade do certificado digital, AAAA-MM-DD."}}},"example":{"tradeName":"Vale Norte Distribuidora","ratRate":0.02}}}},"responses":{"200":{"description":"A organização já atualizada.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}}},"/v1/organization/close":{"post":{"operationId":"close-organization","summary":"Encerrar a organização","description":"Marca a organização como encerrada. Todas as chaves param de funcionar em seguida. Permissão: manage_members.","tags":["Conta e organização"],"parameters":[],"responses":{"200":{"description":"A organização encerrada.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}}},"/v1/permissions":{"get":{"operationId":"get-permissions","summary":"Matriz de permissões","description":"O nível de cada permissão para cada papel desta organização. Permissão: qualquer chave.","tags":["Conta e organização"],"parameters":[],"responses":{"200":{"description":"Uma lista de papel, permissão e nível.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}}},"/v1/members":{"get":{"operationId":"list-members","summary":"Listar membros","description":"Quem tem acesso a esta organização, com papel e última visita. Permissão: qualquer chave.","tags":["Membros e convites"],"parameters":[{"name":"limit","in":"query","required":false,"description":"Até 1000. Padrão 50.","schema":{"type":"number"}},{"name":"offset","in":"query","required":false,"description":"Deslocamento da página.","schema":{"type":"number"}}],"responses":{"200":{"description":"Lista paginada de membros.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}},"post":{"operationId":"create-member","summary":"Criar membro","description":"Cria a conta já confirmada e dá acesso a esta organização. Entregue a senha à pessoa. Permissão: manage_members.","tags":["Membros e convites"],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"fullName":{"type":"string","description":"Nome completo."},"email":{"type":"string","description":"E-mail de acesso."},"password":{"type":"string","description":"Mínimo de 10 caracteres."},"role":{"type":"string","enum":["finance","hr","accountant","employee"],"description":"Papel."}},"required":["fullName","email","password","role"]},"example":{"fullName":"Marina Toledo","email":"marina@valenorte.com.br","password":"uma-senha-forte","role":"hr"}}}},"responses":{"200":{"description":"O membro criado.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}}},"/v1/members/{userId}":{"patch":{"operationId":"update-member","summary":"Trocar o papel","description":"Muda o papel de um membro. Permissão: manage_members.","tags":["Membros e convites"],"parameters":[{"name":"userId","in":"path","required":true,"description":"Id da conta.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"role":{"type":"string","enum":["finance","hr","accountant","employee"],"description":"Novo papel."}},"required":["role"]},"example":{"role":"finance"}}}},"responses":{"200":{"description":"O membro atualizado.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}},"delete":{"operationId":"delete-member","summary":"Remover membro","description":"Tira o acesso da pessoa a esta organização. A conta continua existindo. Permissão: manage_members.","tags":["Membros e convites"],"parameters":[{"name":"userId","in":"path","required":true,"description":"Id da conta.","schema":{"type":"string"}}],"responses":{"200":{"description":"O id removido.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}}},"/v1/invitations":{"get":{"operationId":"list-invitations","summary":"Listar convites","description":"Convites pendentes. Passe status=all para ver também os aceitos e revogados. Permissão: manage_members.","tags":["Membros e convites"],"parameters":[{"name":"status","in":"query","required":false,"description":"Inclui convites já aceitos ou revogados.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Até 1000. Padrão 50.","schema":{"type":"number"}},{"name":"offset","in":"query","required":false,"description":"Deslocamento da página.","schema":{"type":"number"}}],"responses":{"200":{"description":"Lista paginada de convites.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}},"post":{"operationId":"create-invitation","summary":"Convidar por e-mail","description":"Cria o convite e dispara o e-mail com o link de aceite. Permissão: manage_members.","tags":["Membros e convites"],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","description":"Para quem vai o convite."},"role":{"type":"string","enum":["finance","hr","accountant","employee"],"description":"Papel."}},"required":["email","role"]},"example":{"email":"novo@valenorte.com.br","role":"hr"}}}},"responses":{"200":{"description":"O convite criado.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}}},"/v1/invitations/{invitationId}/resend":{"post":{"operationId":"resend-invitation","summary":"Reenviar convite","description":"Estende a validade por mais sete dias e manda o e-mail de novo. Permissão: manage_members.","tags":["Membros e convites"],"parameters":[{"name":"invitationId","in":"path","required":true,"description":"Id do convite.","schema":{"type":"string"}}],"responses":{"200":{"description":"O convite atualizado.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}}},"/v1/invitations/{invitationId}":{"delete":{"operationId":"revoke-invitation","summary":"Revogar convite","description":"Invalida um convite ainda não aceito. Permissão: manage_members.","tags":["Membros e convites"],"parameters":[{"name":"invitationId","in":"path","required":true,"description":"Id do convite.","schema":{"type":"string"}}],"responses":{"200":{"description":"O convite revogado.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}}},"/v1/employees":{"get":{"operationId":"list-employees","summary":"Listar funcionários","description":"Traz o quadro ativo. Passe status=all para incluir quem foi desligado. Permissão: view_all_employees (ver).","tags":["Funcionários"],"parameters":[{"name":"status","in":"query","required":false,"description":"Inclui desligados.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Até 1000. Padrão 50.","schema":{"type":"number"}},{"name":"offset","in":"query","required":false,"description":"Deslocamento da página.","schema":{"type":"number"}}],"responses":{"200":{"description":"Lista paginada de funcionários.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}},"post":{"operationId":"create-employee","summary":"Cadastrar funcionário","description":"Cria a ficha. Com o objeto access a pessoa também ganha conta para assinar o próprio holerite, e aí o e-mail é obrigatório. Permissão: manage_employees, mais manage_members quando access.role não é employee.","tags":["Funcionários"],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"fullName":{"type":"string","description":"Nome completo."},"cpf":{"type":"string","description":"Com ou sem pontuação."},"jobTitle":{"type":"string","description":"Cargo."},"hiredOn":{"type":"string","description":"Admissão, AAAA-MM-DD."},"contractType":{"type":"string","enum":["permanent","temporary","pj"],"description":"Tipo de contrato. PJ não entra em INSS, IRRF nem FGTS."},"baseSalary":{"type":"number","description":"Salário base em reais."},"contractEndsOn":{"type":"string","nullable":true,"description":"Obrigatório no contrato temporário."},"email":{"type":"string","nullable":true,"description":"E-mail do funcionário."},"pisNis":{"type":"string","nullable":true,"description":"Onze dígitos."},"weeklyHours":{"type":"number","nullable":true,"description":"Jornada semanal."},"ctps":{"type":"string","nullable":true,"description":"CTPS."},"unionName":{"type":"string","nullable":true,"description":"Sindicato."},"costCenter":{"type":"string","nullable":true,"description":"Centro de custo."},"employmentStatus":{"type":"string","enum":["active","on_vacation"],"description":"Situação. Padrão active."},"dependentsCount":{"type":"number","description":"De 0 a 20."},"bankName":{"type":"string","nullable":true,"description":"Banco."},"bankBranch":{"type":"string","nullable":true,"description":"Agência."},"bankAccount":{"type":"string","nullable":true,"description":"Conta."},"pixKey":{"type":"string","nullable":true,"description":"Chave PIX."},"mealAllowance":{"type":"number","nullable":true,"description":"Vale refeição."},"transportAllowance":{"type":"number","nullable":true,"description":"Vale transporte."},"childcareAllowance":{"type":"number","nullable":true,"description":"Auxílio creche."},"healthPlan":{"type":"number","nullable":true,"description":"Plano de saúde."},"access":{"type":"object","description":"password e role para criar a conta de acesso."}},"required":["fullName","cpf","jobTitle","hiredOn","contractType","baseSalary"]},"example":{"fullName":"Adilson Ferreira da Silva","cpf":"024.118.402-92","jobTitle":"operador de empilhadeira","hiredOn":"2026-03-01","contractType":"permanent","baseSalary":3240,"dependentsCount":2}}}},"responses":{"200":{"description":"O funcionário criado.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}}},"/v1/employees/batch":{"post":{"operationId":"batch-employees","summary":"Importar em lote","description":"Cadastra até mil funcionários de uma vez. Um CPF já registrado é ignorado, nunca atualizado, como na importação por planilha. Permissão: manage_employees.","tags":["Funcionários"],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"employees":{"type":"array","items":{"type":"object"},"description":"Cada item tem os mesmos campos de POST /v1/employees, sem access."}},"required":["employees"]},"example":{"employees":[{"fullName":"Adilson Ferreira da Silva","cpf":"024.118.402-92","jobTitle":"operador de empilhadeira","hiredOn":"2026-03-01","contractType":"permanent","baseSalary":3240,"dependentsCount":2}]}}}},"responses":{"200":{"description":"Quantos foram criados, quantos foram ignorados e quais CPFs.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}}},"/v1/employees/{employeeId}":{"get":{"operationId":"get-employee","summary":"Ver funcionário","description":"A ficha completa de uma pessoa. Permissão: view_all_employees (ver).","tags":["Funcionários"],"parameters":[{"name":"employeeId","in":"path","required":true,"description":"Id do funcionário.","schema":{"type":"string"}}],"responses":{"200":{"description":"O funcionário.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}},"patch":{"operationId":"update-employee","summary":"Atualizar funcionário","description":"Muda só os campos enviados. Para desligar, use o endereço de desligamento. Permissão: manage_employees.","tags":["Funcionários"],"parameters":[{"name":"employeeId","in":"path","required":true,"description":"Id do funcionário.","schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{}},"example":{"baseSalary":3600,"jobTitle":"conferente de carga"}}}},"responses":{"200":{"description":"O funcionário atualizado.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}}},"/v1/employees/{employeeId}/terminate":{"post":{"operationId":"terminate-employee","summary":"Desligar","description":"Marca o desligamento. A data não pode ser futura nem anterior à admissão. Permissão: manage_employees.","tags":["Funcionários"],"parameters":[{"name":"employeeId","in":"path","required":true,"description":"Id do funcionário.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"terminatedOn":{"type":"string","description":"AAAA-MM-DD."}},"required":["terminatedOn"]},"example":{"terminatedOn":"2026-09-30"}}}},"responses":{"200":{"description":"O funcionário desligado.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}}},"/v1/employees/{employeeId}/bank-proof":{"get":{"operationId":"get-bank-proof","summary":"Baixar o comprovante bancário","description":"Devolve uma URL assinada que vale 60 segundos. Permissão: view_all_employees (ver).","tags":["Funcionários"],"parameters":[{"name":"employeeId","in":"path","required":true,"description":"Id do funcionário.","schema":{"type":"string"}}],"responses":{"200":{"description":"url e expiresAt.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}},"post":{"operationId":"upload-bank-proof","summary":"Anexar o comprovante bancário","description":"Envio multipart. Substitui o anterior, que é apagado do armazenamento. Permissão: manage_employees.","tags":["Funcionários"],"parameters":[{"name":"employeeId","in":"path","required":true,"description":"Id do funcionário.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"type":"string","format":"binary","description":"PDF, PNG ou JPEG de até 5 MB."}},"required":["file"]}}}},"responses":{"200":{"description":"O funcionário atualizado.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}}},"/v1/employees/{employeeId}/grant-access":{"post":{"operationId":"grant-access","summary":"Dar acesso ao holerite","description":"Manda o e-mail de acesso para o funcionário assinar os próprios holerites. Permissão: issue_payslips.","tags":["Funcionários"],"parameters":[{"name":"employeeId","in":"path","required":true,"description":"Id do funcionário.","schema":{"type":"string"}}],"responses":{"200":{"description":"O e-mail para onde o acesso foi enviado.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}}},"/v1/employees/{employeeId}/payslips":{"get":{"operationId":"employee-payslips","summary":"Holerites da pessoa","description":"Os holerites vindos da folha e os enviados por PDF, em duas listas. Permissão: view_payroll (ver).","tags":["Funcionários"],"parameters":[{"name":"employeeId","in":"path","required":true,"description":"Id do funcionário.","schema":{"type":"string"}}],"responses":{"200":{"description":"fromPayroll e uploaded.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}}},"/v1/payroll-runs":{"get":{"operationId":"list-payroll-runs","summary":"Listar competências","description":"Da mais recente para a mais antiga. Permissão: view_payroll (ver).","tags":["Folha de pagamento"],"parameters":[{"name":"limit","in":"query","required":false,"description":"Até 1000. Padrão 50.","schema":{"type":"number"}},{"name":"offset","in":"query","required":false,"description":"Deslocamento da página.","schema":{"type":"number"}}],"responses":{"200":{"description":"Lista paginada de competências.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}},"post":{"operationId":"open-payroll-run","summary":"Abrir competência","description":"Copia o quadro ativo para dentro da folha, fixa as tabelas vigentes e já calcula todo mundo. Sem período, abre o mês corrente. Permissão: edit_payroll_entries.","tags":["Folha de pagamento"],"parameters":[],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"period":{"type":"string","description":"AAAA-MM. Padrão: mês corrente."},"payOn":{"type":"string","description":"Data de pagamento, AAAA-MM-DD. Padrão: dia 5 do mês seguinte."}}},"example":{"period":"2026-09"}}}},"responses":{"200":{"description":"A competência aberta.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}}},"/v1/payroll-runs/{runId}":{"get":{"operationId":"get-payroll-run","summary":"Ver competência","description":"A competência com o total de pessoas, o custo do empregador, os itens calculados e os lançamentos. Permissão: view_payroll (ver).","tags":["Folha de pagamento"],"parameters":[{"name":"runId","in":"path","required":true,"description":"Id da competência.","schema":{"type":"string"}}],"responses":{"200":{"description":"A competência, items e entries.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}}},"/v1/payroll-runs/{runId}/entries/{employeeId}":{"put":{"operationId":"put-payroll-entry","summary":"Lançar horas e descontos","description":"Substitui o lançamento da pessoa e recalcula o item na hora. Só funciona enquanto a competência está em conferência. Permissão: edit_payroll_entries.","tags":["Folha de pagamento"],"parameters":[{"name":"runId","in":"path","required":true,"description":"Id da competência.","schema":{"type":"string"}},{"name":"employeeId","in":"path","required":true,"description":"Id do funcionário.","schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"overtime50Minutes":{"type":"number","description":"Hora extra 50% em minutos."},"overtime100Minutes":{"type":"number","description":"Hora extra 100% em minutos."},"nightMinutes":{"type":"number","description":"Adicional noturno em minutos."},"absenceDays":{"type":"number","description":"Faltas em dias, aceita meio dia."},"vacationDays":{"type":"number","description":"Dias de férias gozados na competência."},"vacationSoldDays":{"type":"number","description":"Dias vendidos como abono pecuniário."},"advanceThirteenth":{"type":"string","description":"Paga a primeira parcela do 13º junto das férias."},"unionDues":{"type":"number","description":"Contribuição sindical em reais."},"salaryAdvance":{"type":"number","description":"Adiantamento em reais."}}},"example":{"overtime50Minutes":600,"unionDues":25.5}}}},"responses":{"200":{"description":"O item recalculado.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}}},"/v1/payroll-runs/{runId}/recompute":{"post":{"operationId":"recompute-payroll-run","summary":"Recalcular a competência","description":"Refaz o cálculo de todos os itens com as tabelas vigentes para o período. Permissão: edit_payroll_entries.","tags":["Folha de pagamento"],"parameters":[{"name":"runId","in":"path","required":true,"description":"Id da competência.","schema":{"type":"string"}}],"responses":{"200":{"description":"A competência.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}}},"/v1/payroll-runs/{runId}/approve":{"post":{"operationId":"approve-payroll-run","summary":"Aprovar","description":"Fecha o mês e cria a fatura da competência. Se a cobrança não estiver configurada, billingError explica e a fatura fica registrada sem link de pagamento. Permissão: approve_payroll.","tags":["Folha de pagamento"],"parameters":[{"name":"runId","in":"path","required":true,"description":"Id da competência.","schema":{"type":"string"}}],"responses":{"200":{"description":"A competência aprovada e billingError.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}}},"/v1/payroll-runs/{runId}/reopen":{"post":{"operationId":"reopen-payroll-run","summary":"Reabrir","description":"Volta a competência para conferência e recalcula. Recusa se já houver holerite emitido. Permissão: approve_payroll.","tags":["Folha de pagamento"],"parameters":[{"name":"runId","in":"path","required":true,"description":"Id da competência.","schema":{"type":"string"}}],"responses":{"200":{"description":"A competência reaberta.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}}},"/v1/payroll-runs/{runId}/pay":{"post":{"operationId":"pay-payroll-run","summary":"Marcar como paga","description":"Registra o pagamento da folha aprovada. Permissão: approve_payroll.","tags":["Folha de pagamento"],"parameters":[{"name":"runId","in":"path","required":true,"description":"Id da competência.","schema":{"type":"string"}}],"responses":{"200":{"description":"A competência paga.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}}},"/v1/payroll-runs/{runId}/payslips":{"get":{"operationId":"list-run-payslips","summary":"Holerites da competência","description":"Os holerites emitidos para essa competência. Permissão: view_payroll (ver).","tags":["Folha de pagamento"],"parameters":[{"name":"runId","in":"path","required":true,"description":"Id da competência.","schema":{"type":"string"}}],"responses":{"200":{"description":"Lista de holerites.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}},"post":{"operationId":"issue-run-payslips","summary":"Emitir holerites","description":"Emite em lote para toda a competência aprovada. Emitir duas vezes não duplica. Permissão: issue_payslips.","tags":["Folha de pagamento"],"parameters":[{"name":"runId","in":"path","required":true,"description":"Id da competência.","schema":{"type":"string"}}],"responses":{"200":{"description":"Quantos holerites foram emitidos agora.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}}},"/v1/tax-tables":{"get":{"operationId":"get-tax-tables","summary":"Tabelas de INSS e IRRF","description":"As faixas e parâmetros em vigor para a competência pedida. Permissão: qualquer chave.","tags":["Folha de pagamento"],"parameters":[{"name":"period","in":"query","required":false,"description":"AAAA-MM. Padrão: mês corrente.","schema":{"type":"string"}}],"responses":{"200":{"description":"inss, irrf e parameters.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}}},"/v1/payslips":{"get":{"operationId":"list-payslips","summary":"Listar holerites da folha","description":"Filtra por funcionário ou por competência. Permissão: view_payroll (ver).","tags":["Holerites"],"parameters":[{"name":"employeeId","in":"query","required":false,"description":"Só os de uma pessoa.","schema":{"type":"string"}},{"name":"payrollRunId","in":"query","required":false,"description":"Só os de uma competência.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Até 1000. Padrão 50.","schema":{"type":"number"}},{"name":"offset","in":"query","required":false,"description":"Deslocamento da página.","schema":{"type":"number"}}],"responses":{"200":{"description":"Lista paginada de holerites.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}}},"/v1/payslips/{payslipId}":{"get":{"operationId":"get-payslip","summary":"Ver holerite da folha","description":"O holerite com a competência e todos os valores do item de folha. Permissão: view_payroll (ver).","tags":["Holerites"],"parameters":[{"name":"payslipId","in":"path","required":true,"description":"Id do holerite.","schema":{"type":"string"}}],"responses":{"200":{"description":"O holerite, o período e o item.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}}},"/v1/payslip-uploads":{"get":{"operationId":"list-payslip-uploads","summary":"Listar lotes de PDF","description":"Cada lote traz a caixa de assinatura e as páginas já distribuídas por funcionário. Permissão: view_payroll (ver).","tags":["Holerites"],"parameters":[{"name":"limit","in":"query","required":false,"description":"Até 1000. Padrão 50.","schema":{"type":"number"}},{"name":"offset","in":"query","required":false,"description":"Deslocamento da página.","schema":{"type":"number"}}],"responses":{"200":{"description":"Lista paginada de lotes com suas páginas.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}},"post":{"operationId":"create-payslip-upload","summary":"Enviar holerites em PDF","description":"Envio multipart. O plano diz qual página de qual arquivo é de quem e onde a assinatura vai ser carimbada. O PDF é fatiado por página no servidor. Permissão: issue_payslips.","tags":["Holerites"],"parameters":[],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"files":{"type":"string","format":"binary","description":"Um ou mais PDFs, até 10 MB cada e 30 MB somados."},"plan":{"type":"string","description":"box com x, y, width e height em fração da página, rotation 0, 90, 180 ou 270, e pages com fileIndex, pageIndex, employeeId e label. Até 60 páginas."}},"required":["files","plan"]}}}},"responses":{"200":{"description":"O lote criado com as páginas.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}}},"/v1/uploaded-payslips/{payslipId}":{"get":{"operationId":"get-uploaded-payslip","summary":"Ver holerite em PDF","description":"Situação de uma página do lote, incluindo quando foi assinada. Permissão: view_payroll (ver).","tags":["Holerites"],"parameters":[{"name":"payslipId","in":"path","required":true,"description":"Id da página.","schema":{"type":"string"}}],"responses":{"200":{"description":"O holerite enviado.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}},"delete":{"operationId":"delete-uploaded-payslip","summary":"Remover holerite em PDF","description":"Apaga a página e o arquivo. Recusa se já estiver assinada. O lote some sozinho quando fica vazio. Permissão: issue_payslips.","tags":["Holerites"],"parameters":[{"name":"payslipId","in":"path","required":true,"description":"Id da página.","schema":{"type":"string"}}],"responses":{"200":{"description":"O id removido.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}}},"/v1/uploaded-payslips/{payslipId}/file":{"get":{"operationId":"get-uploaded-payslip-file","summary":"Baixar o PDF","description":"URL assinada de 60 segundos para o original ou para o documento já assinado. Permissão: view_payroll (ver).","tags":["Holerites"],"parameters":[{"name":"payslipId","in":"path","required":true,"description":"Id da página.","schema":{"type":"string"}},{"name":"kind","in":"query","required":false,"description":"Padrão original.","schema":{"type":"string","enum":["original","signed"]}}],"responses":{"200":{"description":"url e expiresAt.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}}},"/v1/invoices":{"get":{"operationId":"list-invoices","summary":"Listar faturas","description":"Da competência mais recente para a mais antiga. Permissão: view_billing (ver).","tags":["Cobrança"],"parameters":[{"name":"limit","in":"query","required":false,"description":"Até 1000. Padrão 50.","schema":{"type":"number"}},{"name":"offset","in":"query","required":false,"description":"Deslocamento da página.","schema":{"type":"number"}}],"responses":{"200":{"description":"Lista paginada de faturas.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}}},"/v1/invoices/{invoiceId}/charge":{"post":{"operationId":"charge-invoice","summary":"Gerar o link de pagamento","description":"Refaz a cobrança na AbacatePay e devolve a fatura com o link. Recusa fatura já paga. Permissão: view_billing.","tags":["Cobrança"],"parameters":[{"name":"invoiceId","in":"path","required":true,"description":"Id da fatura.","schema":{"type":"string"}}],"responses":{"200":{"description":"A fatura com providerUrl.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}}},"/v1/financial-periods":{"get":{"operationId":"list-financial-periods","summary":"Listar competências disponíveis","description":"Da mais recente para a mais antiga, só as importações concluídas. Permissão: view_financials (ver).","tags":["Análise financeira"],"parameters":[],"responses":{"200":{"description":"Lista de competências com o id da importação em uso.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}}},"/v1/financial-overview":{"get":{"operationId":"get-financial-overview","summary":"Visão geral da competência","description":"O índice de saúde, os totais do mês, os sinais de atenção e a série de doze meses. Permissão: view_financials (ver).","tags":["Análise financeira"],"parameters":[{"name":"competencia","in":"query","required":false,"description":"Competência a analisar. Padrão: a mais recente.","schema":{"type":"string"}},{"name":"comparar","in":"query","required":false,"description":"previous_month, same_month_last_year, twelve_month_average, budget ou year_to_date.","schema":{"type":"string"}}],"responses":{"200":{"description":"Índice de saúde, totais, sinais e série mensal.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}}},"/v1/financial-statements/income":{"get":{"operationId":"get-income-statement","summary":"Demonstração do resultado","description":"As linhas do resultado com comparativo, variação e peso sobre a receita, mais a decomposição do lucro. Permissão: view_financials (ver).","tags":["Análise financeira"],"parameters":[{"name":"competencia","in":"query","required":false,"description":"Competência a analisar.","schema":{"type":"string"}},{"name":"comparar","in":"query","required":false,"description":"Base de comparação.","schema":{"type":"string"}}],"responses":{"200":{"description":"Linhas do resultado e passos da decomposição.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}}},"/v1/financial-statements/balance":{"get":{"operationId":"get-balance-sheet","summary":"Balanço patrimonial","description":"Ativo, passivo e patrimônio líquido por grupo, mais a leitura de capital de giro. Permissão: view_financials (ver).","tags":["Análise financeira"],"parameters":[{"name":"competencia","in":"query","required":false,"description":"Competência a analisar.","schema":{"type":"string"}},{"name":"comparar","in":"query","required":false,"description":"Base de comparação.","schema":{"type":"string"}}],"responses":{"200":{"description":"Grupos do balanço, totais, diferença e estrutura de capital de giro.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}}},"/v1/financial-statements/cash-flow":{"get":{"operationId":"get-cash-flow","summary":"Fluxo de caixa","description":"Método indireto, com operação, investimento, financiamento e a variação do saldo. Permissão: view_financials (ver).","tags":["Análise financeira"],"parameters":[{"name":"competencia","in":"query","required":false,"description":"Competência a analisar.","schema":{"type":"string"}},{"name":"comparar","in":"query","required":false,"description":"Base de comparação.","schema":{"type":"string"}}],"responses":{"200":{"description":"As três atividades e a conciliação do saldo.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}}},"/v1/financial-indicators":{"get":{"operationId":"list-financial-indicators","summary":"Indicadores","description":"Dezessete indicadores em quatro famílias, com faixa de referência e meta. Permissão: view_financials (ver).","tags":["Análise financeira"],"parameters":[{"name":"competencia","in":"query","required":false,"description":"Competência a analisar.","schema":{"type":"string"}},{"name":"comparar","in":"query","required":false,"description":"Base de comparação.","schema":{"type":"string"}}],"responses":{"200":{"description":"Lista de indicadores com valor, anterior, faixa e meta.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}}},"/v1/receivables":{"get":{"operationId":"get-receivables","summary":"Carteira de recebíveis","description":"Faixas de vencimento, clientes e concentração na data de referência da competência. Permissão: view_financials (ver).","tags":["Análise financeira"],"parameters":[{"name":"competencia","in":"query","required":false,"description":"Competência a analisar.","schema":{"type":"string"}}],"responses":{"200":{"description":"Faixas, clientes e concentração.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}}},"/v1/payables":{"get":{"operationId":"get-payables","summary":"Carteira de pagáveis","description":"Janelas de vencimento e os títulos em aberto na data de referência da competência. Permissão: view_financials (ver).","tags":["Análise financeira"],"parameters":[{"name":"competencia","in":"query","required":false,"description":"Competência a analisar.","schema":{"type":"string"}}],"responses":{"200":{"description":"Janelas de vencimento e títulos.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}}},"/v1/ledger-imports":{"get":{"operationId":"list-ledger-imports","summary":"Listar importações","description":"Da mais recente para a mais antiga, em qualquer estado. Permissão: view_financials (ver).","tags":["Análise financeira"],"parameters":[{"name":"limit","in":"query","required":false,"description":"Até 1000. Padrão 50.","schema":{"type":"number"}},{"name":"offset","in":"query","required":false,"description":"Deslocamento da página.","schema":{"type":"number"}}],"responses":{"200":{"description":"Lista paginada de importações.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}},"post":{"operationId":"create-ledger-import","summary":"Importar balancete","description":"Recebe o plano de contas e os saldos já normalizados. Contas sem destino recebem a sugestão do Prumo. Permissão: manage_financials.","tags":["Análise financeira"],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"period":{"type":"string","description":"Competência da importação."},"sourceSystem":{"type":"string","description":"Sistema contábil de origem."},"accounts":{"type":"array","items":{"type":"object"},"description":"code, name e, se quiser, statementLine e costBehavior."},"balances":{"type":"array","items":{"type":"object"},"description":"code, period e closingBalance, com débito e crédito opcionais."}},"required":["period","accounts","balances"]},"example":{"period":"2026-08","sourceSystem":"dominio","accounts":[{"code":"1.1.1.01","name":"Caixa e equivalentes"}],"balances":[{"code":"1.1.1.01","period":"2026-08","closingBalance":18700}]}}}},"responses":{"200":{"description":"A importação criada, em rascunho.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}}},"/v1/ledger-imports/{importId}":{"get":{"operationId":"get-ledger-import","summary":"Ver uma importação","description":"Com os arquivos do envio e o resultado das conferências. Permissão: view_financials (ver).","tags":["Análise financeira"],"parameters":[{"name":"importId","in":"path","required":true,"description":"Id da importação.","schema":{"type":"string"}}],"responses":{"200":{"description":"A importação, seus arquivos e as conferências.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}}},"/v1/ledger-imports/{importId}/complete":{"post":{"operationId":"complete-ledger-import","summary":"Concluir a importação","description":"Recusa enquanto houver conferência que impede concluir. Substitui a importação anterior da mesma competência. Permissão: manage_financials.","tags":["Análise financeira"],"parameters":[{"name":"importId","in":"path","required":true,"description":"Id da importação.","schema":{"type":"string"}}],"responses":{"200":{"description":"A importação concluída.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}}},"/v1/ledger-accounts":{"get":{"operationId":"list-ledger-accounts","summary":"Listar o plano de contas","description":"Com o destino nas demonstrações, o comportamento de custo e a confiança da sugestão. Permissão: view_financials (ver).","tags":["Análise financeira"],"parameters":[{"name":"limit","in":"query","required":false,"description":"Até 1000. Padrão 50.","schema":{"type":"number"}},{"name":"offset","in":"query","required":false,"description":"Deslocamento da página.","schema":{"type":"number"}}],"responses":{"200":{"description":"Lista paginada de contas.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}}},"/v1/ledger-accounts/{accountId}":{"patch":{"operationId":"update-ledger-account","summary":"Classificar uma conta","description":"Grava o destino como decisão manual, e as próximas importações passam a respeitá-la. Permissão: manage_financials.","tags":["Análise financeira"],"parameters":[{"name":"accountId","in":"path","required":true,"description":"Id da conta.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"statementLine":{"type":"string","description":"Destino nas demonstrações."},"costBehavior":{"type":"string","description":"variable, fixed ou unreviewed."}},"required":["statementLine"]},"example":{"statementLine":"administrative_expenses","costBehavior":"fixed"}}}},"responses":{"200":{"description":"A conta com o mapeamento novo.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}}},"/v1/financial-settings":{"get":{"operationId":"get-financial-settings","summary":"Ver metas e pesos","description":"As metas, os limites de alerta, os pesos do índice e as preferências de cálculo. Permissão: view_financials (ver).","tags":["Análise financeira"],"parameters":[],"responses":{"200":{"description":"As configurações do módulo.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}},"patch":{"operationId":"update-financial-settings","summary":"Alterar metas e pesos","description":"Só os campos enviados mudam. Os cinco pesos precisam somar 100. Permissão: manage_financials.","tags":["Análise financeira"],"parameters":[],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"targetNetMargin":{"type":"number","description":"Meta de margem líquida, em fração."},"alertNetDebtEbitda":{"type":"number","description":"Limite de dívida líquida sobre EBITDA."},"weightLiquidity":{"type":"number","description":"Peso da liquidez no índice."},"daysInMonth":{"type":"number","description":"Dias no mês usados nos prazos médios."}}},"example":{"targetNetMargin":0.07,"alertNetDebtEbitda":2.5}}}},"responses":{"200":{"description":"As configurações depois da alteração.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}}},"/v1/financial-scenarios":{"get":{"operationId":"list-financial-scenarios","summary":"Listar conjuntos de cenários","description":"Do mais recente para o mais antigo, com as premissas de cada cenário. Permissão: view_financials (ver).","tags":["Análise financeira"],"parameters":[{"name":"limit","in":"query","required":false,"description":"Até 1000. Padrão 50.","schema":{"type":"number"}},{"name":"offset","in":"query","required":false,"description":"Deslocamento da página.","schema":{"type":"number"}}],"responses":{"200":{"description":"Lista paginada de conjuntos.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}},"post":{"operationId":"create-financial-scenario-set","summary":"Salvar um conjunto de cenários","description":"Um conjunto guarda as premissas dos cenários conservador, base e otimista. Permissão: manage_financials.","tags":["Análise financeira"],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"Nome do conjunto."},"period":{"type":"string","description":"Competência de partida."},"scenarios":{"type":"array","items":{"type":"object"},"description":"Até três cenários, um por slot."}},"required":["name","period","scenarios"]},"example":{"name":"Renovação do limite, banco Itaú","period":"2026-08","scenarios":[{"slot":"base","revenueGrowth":0.03,"netMargin":0.025,"expenseInflation":0.05,"dsoDays":46,"dpoDays":44,"capex":420000,"debtRaise":500000}]}}}},"responses":{"200":{"description":"O id do conjunto criado.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}}},"/v1/financial-scenario-projection":{"get":{"operationId":"get-financial-scenario-projection","summary":"Projeção dos três cenários","description":"A base de doze meses e o resultado projetado nos cenários conservador, base e otimista. Permissão: view_financials (ver).","tags":["Análise financeira"],"parameters":[{"name":"competencia","in":"query","required":false,"description":"Competência de partida.","schema":{"type":"string"}}],"responses":{"200":{"description":"A base e os três cenários com suas premissas.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}}},"/v1/ledger-imports/{importId}/receivables":{"post":{"operationId":"save-receivable-titles","summary":"Enviar a carteira de recebíveis","description":"Substitui os títulos daquela data de referência. Clientes novos entram no cadastro. Permissão: manage_financials.","tags":["Análise financeira"],"parameters":[{"name":"importId","in":"path","required":true,"description":"Id da importação.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"asOf":{"type":"string","description":"Data de referência da carteira."},"titles":{"type":"array","items":{"type":"object"},"description":"counterparty, document, dueOn e amount, com issuedOn e settledAmount opcionais."}},"required":["asOf","titles"]},"example":{"asOf":"2026-08-31","titles":[{"counterparty":"Rede Norte Sul","document":"NF 24.881","issuedOn":"2026-07-13","dueOn":"2026-08-12","amount":148200}]}}}},"responses":{"200":{"description":"A data de referência e quantos títulos entraram.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}}},"/v1/ledger-imports/{importId}/payables":{"post":{"operationId":"save-payable-titles","summary":"Enviar a carteira de pagáveis","description":"Mesma forma da carteira de recebíveis, com categoria e custo ao ano por título. Permissão: manage_financials.","tags":["Análise financeira"],"parameters":[{"name":"importId","in":"path","required":true,"description":"Id da importação.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"asOf":{"type":"string","description":"Data de referência da carteira."},"titles":{"type":"array","items":{"type":"object"},"description":"counterparty, document, dueOn, amount e category entre supplier, payroll, tax e loan."}},"required":["asOf","titles"]},"example":{"asOf":"2026-08-31","titles":[{"counterparty":"Banco Itaú","category":"loan","document":"Parcela 12/48","dueOn":"2026-09-10","amount":120000,"annualRate":0.214}]}}}},"responses":{"200":{"description":"A data de referência e quantos títulos entraram.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}}},"/v1/ledger-imports/{importId}/validate":{"post":{"operationId":"validate-ledger-import","summary":"Rodar as conferências","description":"Roda as sete checagens sobre a competência e grava o resultado. É o que libera concluir. Permissão: manage_financials.","tags":["Análise financeira"],"parameters":[{"name":"importId","in":"path","required":true,"description":"Id da importação.","schema":{"type":"string"}}],"responses":{"200":{"description":"A lista de conferências com severidade, valor e detalhe.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}}},"/v1/ledger-accounts/batch":{"post":{"operationId":"save-ledger-mappings","summary":"Classificar contas em lote","description":"Grava o destino de várias contas de uma vez, como decisão manual. Permissão: manage_financials.","tags":["Análise financeira"],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"mappings":{"type":"array","items":{"type":"object"},"description":"code, statementLine e costBehavior opcional."}},"required":["mappings"]},"example":{"mappings":[{"code":"4.2.1.19","statementLine":"administrative_expenses","costBehavior":"fixed"}]}}}},"responses":{"200":{"description":"Quantas contas foram gravadas.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}}},"/v1/financial-cash-projection":{"get":{"operationId":"get-financial-cash-projection","summary":"Projeção de treze semanas","description":"Entradas, saídas e saldo semana a semana, com as mesmas premissas da tela. Permissão: view_financials (ver).","tags":["Análise financeira"],"parameters":[{"name":"competencia","in":"query","required":false,"description":"Competência de partida.","schema":{"type":"string"}},{"name":"atrasoMaiorCliente","in":"query","required":false,"description":"Dias de atraso a aplicar aos títulos do maior cliente.","schema":{"type":"number"}},{"name":"inadimplencia","in":"query","required":false,"description":"Fração a reduzir de toda entrada prevista.","schema":{"type":"number"}},{"name":"adiarMaiorPagamento","in":"query","required":false,"description":"Tira o maior pagamento da semana em que vence.","schema":{"type":"string"}},{"name":"captacao","in":"query","required":false,"description":"Valor de capital de giro a injetar.","schema":{"type":"number"}},{"name":"captacaoSemana","in":"query","required":false,"description":"Semana da injeção, de 1 a 13. Padrão 3.","schema":{"type":"number"}}],"responses":{"200":{"description":"Saldo de partida, menor saldo, saldo final e as treze semanas.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}}},"/v1/financial-payment-calendar":{"get":{"operationId":"get-financial-payment-calendar","summary":"Calendário de compromissos","description":"As treze semanas de pagáveis empilhadas por categoria. A folha entra pela competência aprovada. Permissão: view_financials (ver).","tags":["Análise financeira"],"parameters":[{"name":"competencia","in":"query","required":false,"description":"Competência de partida.","schema":{"type":"string"}}],"responses":{"200":{"description":"As semanas com total e recorte por categoria.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}}},"/v1/financial-breakeven":{"get":{"operationId":"get-financial-breakeven","summary":"Ponto de equilíbrio","description":"Estrutura de custo entre fixo e variável, margem de contribuição, ponto de equilíbrio e sensibilidade. Permissão: view_financials (ver).","tags":["Análise financeira"],"parameters":[{"name":"competencia","in":"query","required":false,"description":"Competência a analisar.","schema":{"type":"string"}}],"responses":{"200":{"description":"O resultado da competência e as contas com o comportamento de custo.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}}},"/v1/financial-risk":{"get":{"operationId":"get-financial-risk","summary":"Estrutura e risco","description":"Necessidade de capital de giro, saldo de tesouraria, tipo de estrutura, Kanitz, Altman e perfil da dívida. Permissão: view_financials (ver).","tags":["Análise financeira"],"parameters":[{"name":"competencia","in":"query","required":false,"description":"Competência a analisar.","schema":{"type":"string"}}],"responses":{"200":{"description":"Estrutura, solvência, série de doze meses e contratos de dívida.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}}},"/v1/financial-people":{"get":{"operationId":"get-financial-people","summary":"Pessoas e resultado","description":"O custo de pessoal do balancete cruzado com a folha da competência, por centro de custo. Permissão: view_financials (ver).","tags":["Análise financeira"],"parameters":[{"name":"competencia","in":"query","required":false,"description":"Competência a analisar.","schema":{"type":"string"}}],"responses":{"200":{"description":"Custo, quadro, receita e lucro por pessoa, composição e centros de custo.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}}},"/v1/financial-settings/changes":{"get":{"operationId":"list-financial-setting-changes","summary":"Histórico de alterações","description":"Cada mudança de meta, limite ou peso, com autor e data. Permissão: view_financials (ver).","tags":["Análise financeira"],"parameters":[{"name":"limit","in":"query","required":false,"description":"Até 1000. Padrão 50.","schema":{"type":"number"}},{"name":"offset","in":"query","required":false,"description":"Deslocamento da página.","schema":{"type":"number"}}],"responses":{"200":{"description":"Lista paginada de alterações.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}}},"/v1/financial-reports":{"get":{"operationId":"list-financial-reports","summary":"Listar pacotes gerados","description":"Do mais recente para o mais antigo, com as seções que entraram e o número de páginas. Permissão: view_financials (ver).","tags":["Análise financeira"],"parameters":[{"name":"limit","in":"query","required":false,"description":"Até 1000. Padrão 50.","schema":{"type":"number"}},{"name":"offset","in":"query","required":false,"description":"Deslocamento da página.","schema":{"type":"number"}}],"responses":{"200":{"description":"Lista paginada de pacotes.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}},"post":{"operationId":"create-financial-report","summary":"Gerar o pacote em PDF","description":"Monta o PDF com as seções escolhidas, registra o pacote e devolve o arquivo em base64. Permissão: manage_financials.","tags":["Análise financeira"],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"Nome do pacote."},"period":{"type":"string","description":"Competência do pacote."},"scope":{"type":"string","description":"month, quarter, year_to_date ou twelve_months."},"sections":{"type":"array","items":{"type":"object"},"description":"cover, summary, income, balance, cash, indicators, receivables, people e quality."}},"required":["name","period","scope","sections"]},"example":{"name":"Pacote completo, banco Itaú","period":"2026-08","scope":"month","sections":["cover","summary","income","balance","cash","indicators","receivables","people","quality"]}}}},"responses":{"200":{"description":"O pacote registrado e o PDF em base64.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}}},"/v1/vacation-requests":{"get":{"operationId":"list-vacation-requests","summary":"Listar pedidos de férias","description":"Do período mais recente para o mais antigo. Permissão: view_vacations (ver).","tags":["Férias"],"parameters":[{"name":"status","in":"query","required":false,"description":"Filtra pela situação.","schema":{"type":"string","enum":["pending","approved","rejected","cancelled"]}},{"name":"employeeId","in":"query","required":false,"description":"Filtra por funcionário.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Até 1000. Padrão 50.","schema":{"type":"number"}},{"name":"offset","in":"query","required":false,"description":"Deslocamento da página.","schema":{"type":"number"}}],"responses":{"200":{"description":"Lista paginada de pedidos.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}},"post":{"operationId":"schedule-vacation","summary":"Agendar férias","description":"Lança férias já combinadas com a pessoa: o registro nasce aprovado, com a chave como solicitante e aprovadora. O aviso de 30 dias e a regra do dia de início não se aplicam aqui. Contrato PJ recusa abono e adiantamento de 13º. Permissão: manage_vacations.","tags":["Férias"],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"employeeId":{"type":"string","description":"Id do funcionário."},"startsOn":{"type":"string","description":"Primeiro dia, AAAA-MM-DD."},"endsOn":{"type":"string","description":"Último dia, AAAA-MM-DD."},"soldDays":{"type":"number","description":"Abono pecuniário em dias, até um terço do direito."},"advanceThirteenth":{"type":"string","description":"Paga a primeira parcela do 13º junto."},"note":{"type":"string","nullable":true,"description":"Observação livre."}},"required":["employeeId","startsOn","endsOn"]},"example":{"employeeId":"27e68007-0000-0000-0000-000000000000","startsOn":"2026-11-02","endsOn":"2026-11-16","soldDays":5}}}},"responses":{"200":{"description":"O pedido criado, já aprovado.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}}},"/v1/vacation-requests/{requestId}":{"get":{"operationId":"get-vacation-request","summary":"Ver pedido de férias","description":"O pedido com o período aquisitivo que ele consome e a decisão registrada. Permissão: view_vacations (ver).","tags":["Férias"],"parameters":[{"name":"requestId","in":"path","required":true,"description":"Id do pedido.","schema":{"type":"string"}}],"responses":{"200":{"description":"O pedido.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}}},"/v1/vacation-requests/{requestId}/approve":{"post":{"operationId":"approve-vacation-request","summary":"Aprovar","description":"Aprova um pedido que ainda está aguardando e atualiza o lançamento das competências em conferência. Recusa aprovar o próprio pedido, a não ser que a chave seja do proprietário. Permissão: manage_vacations.","tags":["Férias"],"parameters":[{"name":"requestId","in":"path","required":true,"description":"Id do pedido.","schema":{"type":"string"}}],"responses":{"200":{"description":"O pedido aprovado.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}}},"/v1/vacation-requests/{requestId}/reject":{"post":{"operationId":"reject-vacation-request","summary":"Recusar","description":"Recusa um pedido aguardando decisão. A justificativa é obrigatória e aparece para o funcionário. Permissão: manage_vacations.","tags":["Férias"],"parameters":[{"name":"requestId","in":"path","required":true,"description":"Id do pedido.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"note":{"type":"string","description":"Motivo da recusa."}},"required":["note"]},"example":{"note":"Fechamento do trimestre nessa semana."}}}},"responses":{"200":{"description":"O pedido recusado.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}}},"/v1/vacation-requests/{requestId}/cancel":{"post":{"operationId":"cancel-vacation-request","summary":"Cancelar","description":"Cancela um pedido aguardando ou umas férias aprovadas que ainda não começaram. Permissão: manage_vacations.","tags":["Férias"],"parameters":[{"name":"requestId","in":"path","required":true,"description":"Id do pedido.","schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"note":{"type":"string","nullable":true,"description":"Motivo do cancelamento."}}},"example":{"note":"Remarcado a pedido da pessoa."}}}},"responses":{"200":{"description":"O pedido cancelado.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}}},"/v1/employees/{employeeId}/vacation-balance":{"get":{"operationId":"get-employee-vacation-balance","summary":"Saldo de férias do funcionário","description":"Um período aquisitivo por ano de casa, com direito, dias gozados, vendidos, aguardando decisão e saldo. Marca o período que já passou do prazo de concessão. Permissão: view_vacations (ver).","tags":["Férias"],"parameters":[{"name":"employeeId","in":"path","required":true,"description":"Id do funcionário.","schema":{"type":"string"}}],"responses":{"200":{"description":"policy e a lista de períodos com o saldo de cada um.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}}},"/v1/time-punches":{"get":{"operationId":"list-time-punches","summary":"Listar batidas","description":"Da mais recente para a mais antiga. Batida substituída por ajuste ou apagada não aparece. Permissão: view_timesheets (ver).","tags":["Ponto"],"parameters":[{"name":"employeeId","in":"query","required":false,"description":"Filtra por funcionário.","schema":{"type":"string"}},{"name":"from","in":"query","required":false,"description":"Primeiro dia da janela, AAAA-MM-DD.","schema":{"type":"string"}},{"name":"to","in":"query","required":false,"description":"Último dia da janela, AAAA-MM-DD.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Até 1000. Padrão 50.","schema":{"type":"number"}},{"name":"offset","in":"query","required":false,"description":"Deslocamento da página.","schema":{"type":"number"}}],"responses":{"200":{"description":"Lista paginada de batidas.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}},"post":{"operationId":"record-time-punch","summary":"Lançar batida","description":"Registra uma batida em nome do funcionário, com origem manual. Recusa duplicata no mesmo instante e tipo. Permissão: manage_timesheets.","tags":["Ponto"],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"employeeId":{"type":"string","description":"Id do funcionário."},"punchedAt":{"type":"string","description":"Instante da batida em ISO 8601."},"kind":{"type":"string","enum":["entry","break_start","break_end","exit"],"description":"Qual batida do dia."}},"required":["employeeId","punchedAt","kind"]},"example":{"employeeId":"27e68007-0000-4000-8000-000000000000","punchedAt":"2026-09-09T11:02:00.000Z","kind":"entry"}}}},"responses":{"200":{"description":"A batida criada.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}}},"/v1/employees/{employeeId}/timesheet":{"get":{"operationId":"get-employee-timesheet","summary":"Espelho do funcionário","description":"O mês dia a dia, com jornada, saldo, situação e origem de cada linha, mais os totais, o banco de horas e o que iria para a folha. Permissão: view_timesheets (ver).","tags":["Ponto"],"parameters":[{"name":"employeeId","in":"path","required":true,"description":"Id do funcionário.","schema":{"type":"string"}},{"name":"period","in":"query","required":false,"description":"Competência AAAA-MM. Padrão: o mês corrente.","schema":{"type":"string"}}],"responses":{"200":{"description":"O espelho do mês, derivado das batidas.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}}},"/v1/time-board":{"get":{"operationId":"get-time-board","summary":"Painel do ponto","description":"Quem está na jornada agora, com o total do mês e as pendências abertas de cada pessoa. Permissão: view_timesheets (ver).","tags":["Ponto"],"parameters":[{"name":"period","in":"query","required":false,"description":"Competência AAAA-MM. Padrão: o mês corrente.","schema":{"type":"string"}}],"responses":{"200":{"description":"O painel da equipe na competência.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}}},"/v1/time-adjustments":{"get":{"operationId":"list-time-adjustments","summary":"Listar ajustes","description":"Do pedido mais recente para o mais antigo. Permissão: view_timesheets (ver).","tags":["Ponto"],"parameters":[{"name":"status","in":"query","required":false,"description":"Filtra pela situação.","schema":{"type":"string","enum":["pending","approved","rejected","cancelled"]}},{"name":"employeeId","in":"query","required":false,"description":"Filtra por funcionário.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Até 1000. Padrão 50.","schema":{"type":"number"}},{"name":"offset","in":"query","required":false,"description":"Deslocamento da página.","schema":{"type":"number"}}],"responses":{"200":{"description":"Lista paginada de ajustes.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}},"post":{"operationId":"open-time-adjustment","summary":"Abrir ajuste","description":"Abre a correção em nome do funcionário. Fica pendente até a aprovação: enquanto isso o dia conta pelo que foi batido. Permissão: manage_timesheets.","tags":["Ponto"],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"employeeId":{"type":"string","description":"Id do funcionário."},"workDate":{"type":"string","description":"Dia do espelho, AAAA-MM-DD."},"kind":{"type":"string","enum":["add","change","remove"],"description":"O que fazer com a batida."},"punchKind":{"type":"string","enum":["entry","break_start","break_end","exit"],"description":"Qual batida do dia."},"punchId":{"type":"string","nullable":true,"description":"Batida existente. Obrigatório fora do tipo add."},"proposedAt":{"type":"string","nullable":true,"description":"Horário correto em ISO 8601. Obrigatório fora do tipo remove."},"reason":{"type":"string","description":"O que aconteceu no dia."}},"required":["employeeId","workDate","kind","punchKind","reason"]},"example":{"employeeId":"27e68007-0000-4000-8000-000000000000","workDate":"2026-09-03","kind":"add","punchKind":"exit","reason":"saiu direto para a transportadora e esqueceu de bater","proposedAt":"2026-09-03T20:06:00.000Z"}}}},"responses":{"200":{"description":"O ajuste criado, ainda pendente.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}}},"/v1/time-adjustments/{adjustmentId}/approve":{"post":{"operationId":"approve-time-adjustment","summary":"Aprovar ajuste","description":"Grava a batida corrigida e marca a antiga como substituída. O espelho e o banco de horas são recalculados na leitura seguinte. Permissão: manage_timesheets.","tags":["Ponto"],"parameters":[{"name":"adjustmentId","in":"path","required":true,"description":"Id do ajuste.","schema":{"type":"string"}}],"responses":{"200":{"description":"O ajuste aprovado.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}}},"/v1/time-adjustments/{adjustmentId}/reject":{"post":{"operationId":"reject-time-adjustment","summary":"Recusar ajuste","description":"A justificativa é obrigatória e aparece para o funcionário. O espelho continua como está. Permissão: manage_timesheets.","tags":["Ponto"],"parameters":[{"name":"adjustmentId","in":"path","required":true,"description":"Id do ajuste.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"note":{"type":"string","description":"Motivo da recusa."}},"required":["note"]},"example":{"note":"o relógio registrou a saída às 17:06"}}}},"responses":{"200":{"description":"O ajuste recusado.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}}},"/v1/work-schedules":{"get":{"operationId":"list-work-schedules","summary":"Listar jornadas","description":"As jornadas da organização, com dias de trabalho, intervalo mínimo e tolerância. Permissão: view_timesheets (ver).","tags":["Ponto"],"parameters":[],"responses":{"200":{"description":"As jornadas cadastradas.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}},"post":{"operationId":"create-work-schedule","summary":"Criar jornada","description":"O alvo diário sai da jornada semanal dividida pelos dias de trabalho. Permissão: manage_timesheets.","tags":["Ponto"],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"Nome da jornada."},"weeklyMinutes":{"type":"number","description":"Jornada semanal em minutos."},"workdays":{"type":"array","items":{"type":"object"},"description":"Dias ISO de trabalho, de 1 a 7."},"breakMinutes":{"type":"number","description":"Intervalo mínimo em minutos. Padrão 60."},"toleranceMinutes":{"type":"number","description":"Tolerância diária em minutos. Padrão 10."},"isDefault":{"type":"string","description":"Vira a jornada de quem não tem uma."}},"required":["name","weeklyMinutes","workdays"]},"example":{"name":"44h · seg a sex","weeklyMinutes":2640,"workdays":[1,2,3,4,5],"breakMinutes":60,"toleranceMinutes":10,"isDefault":true}}}},"responses":{"200":{"description":"A jornada criada.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}}},"/v1/work-schedules/{scheduleId}":{"patch":{"operationId":"update-work-schedule","summary":"Atualizar jornada","description":"Reescreve a jornada inteira. Espelhos já lidos são recalculados na leitura seguinte. Permissão: manage_timesheets.","tags":["Ponto"],"parameters":[{"name":"scheduleId","in":"path","required":true,"description":"Id da jornada.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"Nome da jornada."},"weeklyMinutes":{"type":"number","description":"Jornada semanal em minutos."},"workdays":{"type":"array","items":{"type":"object"},"description":"Dias ISO de trabalho, de 1 a 7."},"breakMinutes":{"type":"number","description":"Intervalo mínimo em minutos."},"toleranceMinutes":{"type":"number","description":"Tolerância diária em minutos."},"isDefault":{"type":"string","description":"Vira a jornada de quem não tem uma."}},"required":["name","weeklyMinutes","workdays"]},"example":{"name":"30h · seg a sex","weeklyMinutes":1800,"workdays":[1,2,3,4,5]}}}},"responses":{"200":{"description":"A jornada atualizada.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}}},"/v1/time-imports":{"get":{"operationId":"list-time-imports","summary":"Listar importações","description":"Os lotes já gravados, do mais recente para o mais antigo. Permissão: view_timesheets (ver).","tags":["Ponto"],"parameters":[{"name":"limit","in":"query","required":false,"description":"Até 1000. Padrão 50.","schema":{"type":"number"}},{"name":"offset","in":"query","required":false,"description":"Deslocamento da página.","schema":{"type":"number"}}],"responses":{"200":{"description":"Lista paginada de importações.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}},"post":{"operationId":"import-time-punches","summary":"Importar batidas","description":"Grava um lote já normalizado. A leitura do arquivo é da tela: a API recebe batidas com funcionário resolvido. Repetida no mesmo instante e tipo é ignorada. Permissão: manage_timesheets.","tags":["Ponto"],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"fileName":{"type":"string","description":"Nome do arquivo de origem."},"fileKind":{"type":"string","enum":["csv","xlsx","afd"],"description":"Formato do arquivo."},"punches":{"type":"array","items":{"type":"object"},"description":"As batidas a gravar, até 20.000."}},"required":["fileName","fileKind","punches"]},"example":{"fileName":"afd-setembro-2026.txt","fileKind":"afd","punches":[{"employeeId":"27e68007-0000-4000-8000-000000000000","punchedAt":"2026-09-01T11:02:00.000Z","kind":"entry","nsr":"1042"}]}}}},"responses":{"200":{"description":"O lote gravado, com o que entrou e o que foi ignorado.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}}},"/v1/time-periods/close":{"post":{"operationId":"close-time-period","summary":"Fechar período do ponto","description":"Leva as extras e as faltas do mês para o lançamento da folha, com origem relógio de ponto. Recusa se houver ajuste pendente ou se a competência não estiver em rascunho. Permissão: manage_timesheets.","tags":["Ponto"],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"employeeId":{"type":"string","description":"Id do funcionário."},"period":{"type":"string","description":"Competência como AAAA-MM-01."}},"required":["employeeId","period"]},"example":{"employeeId":"27e68007-0000-4000-8000-000000000000","period":"2026-09-01"}}}},"responses":{"200":{"description":"As horas lançadas na folha em rascunho.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}}},"/v1/support-tickets":{"get":{"operationId":"list-support-tickets","summary":"Listar chamados","description":"Do que teve mensagem mais recente para o mais antigo. Permissão: view_tickets (ver).","tags":["Suporte"],"parameters":[{"name":"status","in":"query","required":false,"description":"Filtra pela situação.","schema":{"type":"string","enum":["open","in_progress","resolved"]}},{"name":"category","in":"query","required":false,"description":"Filtra pela categoria.","schema":{"type":"string","enum":["delivery","order","billing","damage","account","other"]}},{"name":"assigneeId","in":"query","required":false,"description":"Filtra pelo responsável.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Até 1000. Padrão 50.","schema":{"type":"number"}},{"name":"offset","in":"query","required":false,"description":"Deslocamento da página.","schema":{"type":"number"}}],"responses":{"200":{"description":"Lista paginada de chamados.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}},"post":{"operationId":"create-support-ticket","summary":"Abrir chamado","description":"Registra um chamado em nome de um cliente já cadastrado na organização. Permissão: manage_tickets.","tags":["Suporte"],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"requesterId":{"type":"string","description":"Id do usuário cliente que pediu."},"subject":{"type":"string","description":"Assunto, até 160 caracteres."},"category":{"type":"string","enum":["delivery","order","billing","damage","account","other"],"description":"Categoria do chamado."},"priority":{"type":"string","enum":["high","normal","low"],"description":"Padrão normal."},"body":{"type":"string","description":"A primeira mensagem, até 4000 caracteres."}},"required":["requesterId","subject","category","body"]},"example":{"requesterId":"0f3d4a2c-6f9a-4a3e-9f1a-2b5c7d8e9f01","subject":"Segunda via da fatura de agosto","category":"billing","priority":"normal","body":"Preciso da segunda via com o vencimento reprogramado."}}}},"responses":{"200":{"description":"O chamado criado.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}}},"/v1/support-tickets/{ticketId}":{"get":{"operationId":"get-support-ticket","summary":"Ver chamado","description":"Os dados de um chamado, sem as mensagens. Permissão: view_tickets (ver).","tags":["Suporte"],"parameters":[{"name":"ticketId","in":"path","required":true,"description":"Id do chamado.","schema":{"type":"string"}}],"responses":{"200":{"description":"O chamado.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}}},"/v1/support-tickets/{ticketId}/messages":{"get":{"operationId":"list-support-messages","summary":"Listar mensagens","description":"A conversa inteira, da mais antiga para a mais nova, incluindo as notas internas. Permissão: view_tickets (ver).","tags":["Suporte"],"parameters":[{"name":"ticketId","in":"path","required":true,"description":"Id do chamado.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Até 1000. Padrão 50.","schema":{"type":"number"}},{"name":"offset","in":"query","required":false,"description":"Deslocamento da página.","schema":{"type":"number"}}],"responses":{"200":{"description":"Lista paginada de mensagens.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}},"post":{"operationId":"create-support-message","summary":"Responder","description":"Grava a resposta do atendimento. Com internal, vira nota interna: o cliente não vê e o prazo não é marcado como respondido. Permissão: manage_tickets.","tags":["Suporte"],"parameters":[{"name":"ticketId","in":"path","required":true,"description":"Id do chamado.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"body":{"type":"string","description":"A mensagem, até 4000 caracteres."},"internal":{"type":"string","description":"Padrão false."}},"required":["body"]},"example":{"body":"Emiti a segunda via com o vencimento reprogramado.","internal":false}}}},"responses":{"200":{"description":"A mensagem criada.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}}},"/v1/support-tickets/{ticketId}/assign":{"post":{"operationId":"assign-support-ticket","summary":"Atribuir","description":"Define o responsável. Envie null para devolver o chamado à triagem. Permissão: manage_tickets.","tags":["Suporte"],"parameters":[{"name":"ticketId","in":"path","required":true,"description":"Id do chamado.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"assigneeId":{"type":"string","nullable":true,"description":"Quem atende."}},"required":["assigneeId"]},"example":{"assigneeId":"0f3d4a2c-6f9a-4a3e-9f1a-2b5c7d8e9f01"}}}},"responses":{"200":{"description":"O chamado atualizado.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}}},"/v1/support-tickets/{ticketId}/priority":{"post":{"operationId":"set-support-ticket-priority","summary":"Mudar prioridade","description":"A prioridade define o prazo de primeira resposta e de solução. Permissão: manage_tickets.","tags":["Suporte"],"parameters":[{"name":"ticketId","in":"path","required":true,"description":"Id do chamado.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"priority":{"type":"string","enum":["high","normal","low"],"description":"Nova prioridade."}},"required":["priority"]},"example":{"priority":"high"}}}},"responses":{"200":{"description":"O chamado atualizado.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}}},"/v1/support-tickets/{ticketId}/status":{"post":{"operationId":"set-support-ticket-status","summary":"Mudar situação","description":"Cada mudança deixa uma mensagem de sistema na conversa. Permissão: manage_tickets.","tags":["Suporte"],"parameters":[{"name":"ticketId","in":"path","required":true,"description":"Id do chamado.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["open","in_progress","resolved"],"description":"Nova situação."}},"required":["status"]},"example":{"status":"resolved"}}}},"responses":{"200":{"description":"O chamado atualizado.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}}},"/v1/support-metrics":{"get":{"operationId":"get-support-metrics","summary":"Painel de SLA","description":"Os números dos últimos 14 dias: primeira resposta média, dentro do SLA, tempo de resolução, reaberturas, volume por dia, quebra por categoria e carga por atendente. Tudo em minutos úteis. Permissão: view_tickets (ver).","tags":["Suporte"],"parameters":[],"responses":{"200":{"description":"O painel do período.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}}},"/v1/support-macros":{"get":{"operationId":"list-support-macros","summary":"Listar respostas prontas","description":"Da mais usada para a menos usada. Permissão: view_tickets (ver).","tags":["Suporte"],"parameters":[{"name":"limit","in":"query","required":false,"description":"Até 1000. Padrão 50.","schema":{"type":"number"}},{"name":"offset","in":"query","required":false,"description":"Deslocamento da página.","schema":{"type":"number"}}],"responses":{"200":{"description":"Lista paginada de respostas prontas.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}},"post":{"operationId":"create-support-macro","summary":"Criar resposta pronta","description":"Os campos entre chaves são preenchidos na hora de responder: {nome}, {chamado}, {atendente}, {sla} e {assunto}. Permissão: manage_tickets.","tags":["Suporte"],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"label":{"type":"string","description":"Nome curto, até 80 caracteres."},"category":{"type":"string","enum":["delivery","order","billing","damage","account","other"],"nullable":true,"description":"Null é a resposta geral."},"body":{"type":"string","description":"O texto, até 4000 caracteres."}},"required":["label","body"]},"example":{"label":"Recebido e em análise","category":"delivery","body":"Oi, {nome}. Recebi o chamado {chamado} e já estou verificando. Volto aqui em até {sla}."}}}},"responses":{"200":{"description":"A resposta pronta criada.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}}},"/v1/support-macros/{macroId}":{"patch":{"operationId":"update-support-macro","summary":"Editar resposta pronta","description":"Reescreve nome, categoria e texto. A contagem de uso não muda. Permissão: manage_tickets.","tags":["Suporte"],"parameters":[{"name":"macroId","in":"path","required":true,"description":"Id da resposta pronta.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"label":{"type":"string","description":"Nome curto, até 80 caracteres."},"category":{"type":"string","enum":["delivery","order","billing","damage","account","other"],"nullable":true,"description":"Null é a resposta geral."},"body":{"type":"string","description":"O texto, até 4000 caracteres."}},"required":["label","body"]},"example":{"label":"Recebido e em análise","category":"delivery","body":"Oi, {nome}. Recebi o chamado {chamado} e já estou verificando."}}}},"responses":{"200":{"description":"A resposta pronta atualizada.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}},"delete":{"operationId":"delete-support-macro","summary":"Remover resposta pronta","description":"Some da lista e do campo de resposta. Não mexe nas mensagens já enviadas. Permissão: manage_tickets.","tags":["Suporte"],"parameters":[{"name":"macroId","in":"path","required":true,"description":"Id da resposta pronta.","schema":{"type":"string"}}],"responses":{"200":{"description":"O id removido.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}}},"/v1/benefit-plans":{"get":{"operationId":"list-benefit-plans","summary":"Listar planos de benefício","description":"Em ordem alfabética. Traz só os planos ativos, a não ser que status venha como all. Permissão: view_all_employees.","tags":["Benefícios"],"parameters":[{"name":"category","in":"query","required":false,"description":"Filtra pela categoria.","schema":{"type":"string","enum":["health_plan","dental_plan","life_insurance","meal_voucher","food_voucher","transport_voucher","childcare","education","gym","fuel","other"]}},{"name":"status","in":"query","required":false,"description":"all inclui os arquivados. Padrão live.","schema":{"type":"string","enum":["live","all"]}},{"name":"limit","in":"query","required":false,"description":"Até 1000. Padrão 50.","schema":{"type":"number"}},{"name":"offset","in":"query","required":false,"description":"Deslocamento da página.","schema":{"type":"number"}}],"responses":{"200":{"description":"Lista paginada de planos.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}},"post":{"operationId":"create-benefit-plan","summary":"Cadastrar plano","description":"Cria um plano no catálogo da organização. O nome não se repete dentro da mesma organização. Os dois valores são o padrão que a adesão herda quando não traz valor próprio. Permissão: manage_employees.","tags":["Benefícios"],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"Nome do plano, até 120 caracteres."},"category":{"type":"string","enum":["health_plan","dental_plan","life_insurance","meal_voucher","food_voucher","transport_voucher","childcare","education","gym","fuel","other"],"description":"Categoria do benefício."},"provider":{"type":"string","nullable":true,"description":"Operadora ou fornecedor."},"employerCost":{"type":"number","description":"Custo mensal do empregador. Padrão 0."},"employeeCost":{"type":"number","description":"Desconto mensal do funcionário. Padrão 0."},"notes":{"type":"string","nullable":true,"description":"Observação livre, até 1000 caracteres."}},"required":["name","category"]},"example":{"name":"Unimed Nacional Enfermaria","category":"health_plan","provider":"Unimed","employerCost":182,"employeeCost":48}}}},"responses":{"200":{"description":"O plano criado.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}}},"/v1/benefit-plans/{planId}":{"patch":{"operationId":"update-benefit-plan","summary":"Editar plano","description":"Muda só o que vier no corpo. Mudar o valor do plano não reescreve as adesões que já têm valor próprio. Permissão: manage_employees.","tags":["Benefícios"],"parameters":[{"name":"planId","in":"path","required":true,"description":"Id do plano.","schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"Nome do plano, até 120 caracteres."},"category":{"type":"string","enum":["health_plan","dental_plan","life_insurance","meal_voucher","food_voucher","transport_voucher","childcare","education","gym","fuel","other"],"description":"Categoria do benefício."},"provider":{"type":"string","nullable":true,"description":"Operadora ou fornecedor."},"employerCost":{"type":"number","description":"Custo mensal do empregador."},"employeeCost":{"type":"number","description":"Desconto mensal do funcionário."},"notes":{"type":"string","nullable":true,"description":"Observação livre, até 1000 caracteres."}}},"example":{"employerCost":195.5,"employeeCost":52}}}},"responses":{"200":{"description":"O plano atualizado.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}},"delete":{"operationId":"archive-benefit-plan","summary":"Arquivar plano","description":"Arquiva o plano em vez de apagar: as adesões já registradas continuam de pé e o plano some das adesões novas. Arquivar de novo devolve o mesmo plano. Permissão: manage_employees.","tags":["Benefícios"],"parameters":[{"name":"planId","in":"path","required":true,"description":"Id do plano.","schema":{"type":"string"}}],"responses":{"200":{"description":"O plano com archivedAt preenchido.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}}},"/v1/employees/{employeeId}/benefits":{"get":{"operationId":"list-employee-benefits","summary":"Benefícios de uma pessoa","description":"Da adesão mais recente para a mais antiga, com a situação derivada das datas. Permissão: view_all_employees.","tags":["Benefícios"],"parameters":[{"name":"employeeId","in":"path","required":true,"description":"Id do funcionário.","schema":{"type":"string"}}],"responses":{"200":{"description":"As adesões da pessoa.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}},"post":{"operationId":"create-employee-benefit","summary":"Vincular a um plano","description":"Registra a adesão. Recusa plano arquivado e recusa uma segunda adesão aberta no mesmo plano. Os dois valores só entram quando esta pessoa paga diferente do catálogo. Permissão: manage_employees.","tags":["Benefícios"],"parameters":[{"name":"employeeId","in":"path","required":true,"description":"Id do funcionário.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"benefitPlanId":{"type":"string","description":"Id do plano."},"startedOn":{"type":"string","description":"Primeiro dia, AAAA-MM-DD."},"endedOn":{"type":"string","nullable":true,"description":"Último dia, AAAA-MM-DD."},"employerCost":{"type":"number","nullable":true,"description":"Custo próprio do empregador nesta adesão."},"employeeCost":{"type":"number","nullable":true,"description":"Desconto próprio do funcionário nesta adesão."},"note":{"type":"string","nullable":true,"description":"Observação livre, até 500 caracteres."}},"required":["benefitPlanId","startedOn"]},"example":{"benefitPlanId":"6811aaf9-0000-0000-0000-000000000000","startedOn":"2026-10-01","employerCost":340,"employeeCost":102}}}},"responses":{"200":{"description":"A adesão criada.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}}},"/v1/employee-benefits/{benefitId}":{"patch":{"operationId":"update-employee-benefit","summary":"Editar adesão","description":"Muda só o que vier no corpo. Encerrar é mandar endedOn; o fim não pode ser anterior ao início. Permissão: manage_employees.","tags":["Benefícios"],"parameters":[{"name":"benefitId","in":"path","required":true,"description":"Id da adesão.","schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"benefitPlanId":{"type":"string","description":"Troca o plano da adesão."},"startedOn":{"type":"string","description":"Primeiro dia, AAAA-MM-DD."},"endedOn":{"type":"string","nullable":true,"description":"Último dia, AAAA-MM-DD."},"employerCost":{"type":"number","nullable":true,"description":"Custo próprio do empregador nesta adesão."},"employeeCost":{"type":"number","nullable":true,"description":"Desconto próprio do funcionário nesta adesão."},"note":{"type":"string","nullable":true,"description":"Observação livre, até 500 caracteres."}}},"example":{"endedOn":"2026-12-31"}}}},"responses":{"200":{"description":"A adesão atualizada.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}},"delete":{"operationId":"delete-employee-benefit","summary":"Remover adesão","description":"Apaga o registro de vez, para desfazer um lançamento errado. Para encerrar sem perder o histórico, mande endedOn no PATCH. Permissão: manage_employees.","tags":["Benefícios"],"parameters":[{"name":"benefitId","in":"path","required":true,"description":"Id da adesão.","schema":{"type":"string"}}],"responses":{"200":{"description":"O id removido.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}}},"/v1/purchase-requests":{"get":{"operationId":"list-purchase-requests","summary":"Listar requisições","description":"Da mais recente para a mais antiga, com a etapa e as duas decisões da trilha em cada linha. Permissão: view_purchases.","tags":["Compras"],"parameters":[{"name":"stage","in":"query","required":false,"description":"Filtra pela etapa da trilha.","schema":{"type":"string","enum":["supply","finance","approved","rejected"]}},{"name":"category","in":"query","required":false,"description":"Filtra pela categoria da compra.","schema":{"type":"string","enum":["office","it","facilities","packaging","furniture","uniforms","services","other"]}},{"name":"limit","in":"query","required":false,"description":"Até 1000. Padrão 50.","schema":{"type":"number"}},{"name":"offset","in":"query","required":false,"description":"Deslocamento da página.","schema":{"type":"number"}}],"responses":{"200":{"description":"Lista paginada de requisições.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}},"post":{"operationId":"create-purchase-request","summary":"Abrir requisição","description":"Abre a requisição na etapa de suprimentos. Cada item vira ou reaproveita uma linha do catálogo, e o preço da última compra aprovada do mesmo item é gravado junto para a comparação. Permissão: request_own_purchase.","tags":["Compras"],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","description":"Título do pedido, até 160 caracteres."},"category":{"type":"string","enum":["office","it","facilities","packaging","furniture","uniforms","services","other"],"description":"Categoria da compra. Padrão other."},"supplierName":{"type":"string","description":"Fornecedor de referência."},"supplierCnpj":{"type":"string","nullable":true,"description":"CNPJ com 14 dígitos, sem pontuação."},"costCenter":{"type":"string","nullable":true,"description":"Centro de custo, até 32 caracteres."},"department":{"type":"string","nullable":true,"description":"Setor de quem pede."},"note":{"type":"string","nullable":true,"description":"Justificativa que entra na trilha."},"items":{"type":"array","items":{"type":"object"},"description":"De 1 a 40 itens com descrição, quantidade, unidade e preço unitário."}},"required":["title","supplierName","items"]},"example":{"title":"Papel A4 e suprimentos de escritório","category":"office","supplierName":"Nordeste Papelaria","supplierCnpj":"98765432000198","costCenter":"ADM-01","items":[{"description":"Papel A4 75g, resma","quantity":40,"unitLabel":"resma","unitPrice":24.9}]}}}},"responses":{"200":{"description":"A requisição criada, na etapa supply.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}}},"/v1/purchase-requests/{requestId}":{"get":{"operationId":"get-purchase-request","summary":"Ver requisição","description":"A requisição com os itens, o preço da última compra de cada um e as duas decisões da trilha. Permissão: view_purchases.","tags":["Compras"],"parameters":[{"name":"requestId","in":"path","required":true,"description":"Id da requisição.","schema":{"type":"string"}}],"responses":{"200":{"description":"A requisição e os itens.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}}},"/v1/purchase-requests/{requestId}/approve":{"post":{"operationId":"approve-purchase-request","summary":"Aprovar a etapa corrente","description":"Aprova a etapa em que a requisição está: suprimentos exige manage_purchases e manda para o financeiro, o financeiro exige approve_purchases e encerra a trilha. Requisição fora dessas duas etapas devolve purchase_stage_mismatch. Permissão: manage_purchases ou approve_purchases, conforme a etapa.","tags":["Compras"],"parameters":[{"name":"requestId","in":"path","required":true,"description":"Id da requisição.","schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"note":{"type":"string","nullable":true,"description":"Comentário que fica na trilha."}}},"example":{"note":"Três cotações levantadas, preço dentro da faixa."}}}},"responses":{"200":{"description":"A requisição na etapa seguinte.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}}},"/v1/purchase-requests/{requestId}/reject":{"post":{"operationId":"reject-purchase-request","summary":"Reprovar a requisição","description":"Devolve a requisição ao solicitante. O motivo é obrigatório e fica registrado na trilha. Permissão: manage_purchases ou approve_purchases, conforme a etapa.","tags":["Compras"],"parameters":[{"name":"requestId","in":"path","required":true,"description":"Id da requisição.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"note":{"type":"string","description":"Motivo da reprovação."}},"required":["note"]},"example":{"note":"14% acima da última compra sem justificativa."}}}},"responses":{"200":{"description":"A requisição reprovada.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}}},"/v1/purchase-requests/{requestId}/messages":{"get":{"operationId":"list-purchase-messages","summary":"Ler a conversa do pedido","description":"Da mais antiga para a mais recente, incluindo as marcas de sistema que cada decisão deixa. Permissão: view_purchases.","tags":["Compras"],"parameters":[{"name":"requestId","in":"path","required":true,"description":"Id da requisição.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Até 1000. Padrão 50.","schema":{"type":"number"}},{"name":"offset","in":"query","required":false,"description":"Deslocamento da página.","schema":{"type":"number"}}],"responses":{"200":{"description":"Lista paginada de mensagens.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}},"post":{"operationId":"create-purchase-message","summary":"Escrever na conversa do pedido","description":"Registra uma dúvida de produto, de preço ou de aprovação. A marca de sistema é escrita só pela trilha. Permissão: view_purchases.","tags":["Compras"],"parameters":[{"name":"requestId","in":"path","required":true,"description":"Id da requisição.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"kind":{"type":"string","enum":["product","price","approval"],"description":"Assunto da mensagem."},"body":{"type":"string","description":"Texto da mensagem, até 4000 caracteres."}},"required":["kind","body"]},"example":{"kind":"price","body":"A Nordeste segurou o preço até sexta."}}}},"responses":{"200":{"description":"A mensagem criada.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}}},"/v1/purchase-items":{"get":{"operationId":"list-purchase-items","summary":"Listar o catálogo de itens","description":"Em ordem alfabética. O catálogo se forma sozinho: cada item citado numa requisição entra aqui. Permissão: view_purchases.","tags":["Compras"],"parameters":[{"name":"limit","in":"query","required":false,"description":"Até 1000. Padrão 50.","schema":{"type":"number"}},{"name":"offset","in":"query","required":false,"description":"Deslocamento da página.","schema":{"type":"number"}}],"responses":{"200":{"description":"Lista paginada de itens do catálogo.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}}},"/v1/purchase-items/{itemId}":{"patch":{"operationId":"update-purchase-item","summary":"Ajustar a faixa de referência","description":"Grava o piso e o teto que definem quando o item entra em alerta. Os dois vêm juntos, em ordem, ou os dois vêm nulos para tirar a faixa. Permissão: manage_purchases.","tags":["Compras"],"parameters":[{"name":"itemId","in":"path","required":true,"description":"Id do item do catálogo.","schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"bandMin":{"type":"number","nullable":true,"description":"Piso da faixa."},"bandMax":{"type":"number","nullable":true,"description":"Teto da faixa."}}},"example":{"bandMin":21.4,"bandMax":25.2}}}},"responses":{"200":{"description":"O item com a faixa atualizada.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}}},"/v1/purchase-items/{itemId}/prices":{"get":{"operationId":"get-purchase-item-prices","summary":"Ver a série de preço do item","description":"Oito meses de preço por fornecedor, derivados das requisições aprovadas, com a última compra, a média, o melhor preço já pago e a variação no período. Permissão: view_purchases.","tags":["Compras"],"parameters":[{"name":"itemId","in":"path","required":true,"description":"Id do item do catálogo.","schema":{"type":"string"}}],"responses":{"200":{"description":"O item, os meses da janela, uma série por fornecedor e as estatísticas.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}}},"/v1/purchase-quotes":{"get":{"operationId":"list-purchase-quotes","summary":"Listar cotações","description":"Da mais recente para a mais antiga. Permissão: view_purchases.","tags":["Compras"],"parameters":[{"name":"status","in":"query","required":false,"description":"Filtra pela situação da cotação.","schema":{"type":"string","enum":["open","closed"]}},{"name":"limit","in":"query","required":false,"description":"Até 1000. Padrão 50.","schema":{"type":"number"}},{"name":"offset","in":"query","required":false,"description":"Deslocamento da página.","schema":{"type":"number"}}],"responses":{"200":{"description":"Lista paginada de cotações.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}},"post":{"operationId":"create-purchase-quote","summary":"Abrir cotação","description":"Um item, o volume, o preço-alvo e os fornecedores convidados. A proposta inicial de cada fornecedor é opcional e, quando vem, já entra como a primeira rodada. Permissão: manage_purchases.","tags":["Compras"],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"itemDescription":{"type":"string","description":"Item cotado."},"quantity":{"type":"number","description":"Volume da cotação."},"unitLabel":{"type":"string","description":"Unidade do volume. Padrão unidade."},"targetPrice":{"type":"number","description":"Preço-alvo por unidade."},"lastBuyPrice":{"type":"number","nullable":true,"description":"Preço da última compra, para medir a economia."},"suppliers":{"type":"array","items":{"type":"object"},"description":"De 1 a 10 fornecedores com nome, CNPJ opcional e proposta inicial opcional."}},"required":["itemDescription","quantity","targetPrice","suppliers"]},"example":{"itemDescription":"Papel A4 75g, resma","quantity":120,"unitLabel":"resma","targetPrice":22,"lastBuyPrice":24.9,"suppliers":[{"name":"Nordeste Papelaria","cnpj":"98765432000198","value":24.9}]}}}},"responses":{"200":{"description":"A cotação criada.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}}},"/v1/purchase-quotes/{quoteId}":{"get":{"operationId":"get-purchase-quote","summary":"Ver cotação","description":"A cotação com os fornecedores e todas as rodadas de cada um, da mais antiga para a mais recente. Permissão: view_purchases.","tags":["Compras"],"parameters":[{"name":"quoteId","in":"path","required":true,"description":"Id da cotação.","schema":{"type":"string"}}],"responses":{"200":{"description":"A cotação, os fornecedores e as rodadas.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}}},"/v1/purchase-quotes/{quoteId}/rounds":{"post":{"operationId":"create-purchase-quote-round","summary":"Registrar rodada","description":"Proposta do fornecedor, contraproposta nossa ou aceite. O aceite fecha a cotação, e cotação fechada não recebe rodada nova. Permissão: manage_purchases.","tags":["Compras"],"parameters":[{"name":"quoteId","in":"path","required":true,"description":"Id da cotação.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"quoteSupplierId":{"type":"string","description":"Fornecedor da cotação."},"kind":{"type":"string","enum":["offer","counter","accepted"],"description":"Tipo da rodada."},"value":{"type":"number","description":"Preço por unidade."},"note":{"type":"string","nullable":true,"description":"Observação da rodada, até 500 caracteres."}},"required":["quoteSupplierId","kind","value"]},"example":{"quoteSupplierId":"8f3c…","kind":"counter","value":22.4,"note":"Lote fechado à vista."}}}},"responses":{"200":{"description":"A rodada registrada.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}}},"/v1/purchase-quotes/{quoteId}/request":{"post":{"operationId":"create-request-from-quote","summary":"Gerar requisição da cotação","description":"Transforma o aceite em requisição, com o preço fechado e o fornecedor vencedor, na etapa de suprimentos. Sem rodada de aceite devolve purchase_quote_not_accepted. Permissão: manage_purchases.","tags":["Compras"],"parameters":[{"name":"quoteId","in":"path","required":true,"description":"Id da cotação.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","description":"Título do pedido."},"category":{"type":"string","enum":["office","it","facilities","packaging","furniture","uniforms","services","other"],"description":"Categoria da compra. Padrão other."},"costCenter":{"type":"string","nullable":true,"description":"Centro de custo."},"department":{"type":"string","nullable":true,"description":"Setor de quem pede."}},"required":["title"]},"example":{"title":"Papel A4 negociado","category":"office","costCenter":"ADM-01"}}}},"responses":{"200":{"description":"A requisição gerada.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}}},"/v1/purchase-metrics":{"get":{"operationId":"get-purchase-metrics","summary":"Números do mês","description":"O que está em aprovação, o que foi aprovado no mês, a economia negociada, o prazo médio de aprovação e o gasto por categoria. Tudo derivado das requisições, nada gravado. Permissão: view_purchases.","tags":["Compras"],"parameters":[{"name":"month","in":"query","required":false,"description":"Competência no formato AAAA-MM. Padrão o mês corrente.","schema":{"type":"string"}}],"responses":{"200":{"description":"Os números do mês e o gasto por categoria.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}}},"/v1/admissions":{"get":{"operationId":"list-admissions","summary":"Admissões em andamento","description":"Quem está em onboarding, com o progresso do checklist derivado das tarefas. Nada de percentual gravado. Permissão: view_all_employees (ver).","tags":["Admissão e desligamento"],"parameters":[{"name":"limit","in":"query","required":false,"description":"Itens por página, até 1000. Padrão 50.","schema":{"type":"number"}},{"name":"offset","in":"query","required":false,"description":"Quantos itens pular.","schema":{"type":"number"}}],"responses":{"200":{"description":"Uma página de admissões com o progresso de cada uma.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}},"post":{"operationId":"open-admission","summary":"Abrir admissão","description":"Passa a situação do funcionário para onboarding e materializa o checklist padrão do tipo de contrato. O funcionário precisa ter e-mail, senão devolve admission_needs_email. Permissão: manage_employees.","tags":["Admissão e desligamento"],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"employeeId":{"type":"string","description":"Id do funcionário ativo."}},"required":["employeeId"]},"example":{"employeeId":"3f1c8f2e-1f4a-4a1b-9a3e-2c9d5b7e1a01"}}}},"responses":{"200":{"description":"O id do funcionário e o checklist criado.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}}},"/v1/admissions/{employeeId}":{"get":{"operationId":"get-admission","summary":"Detalhe da admissão","description":"A admissão aberta de um funcionário, com o checklist e o progresso. Permissão: view_all_employees (ver).","tags":["Admissão e desligamento"],"parameters":[{"name":"employeeId","in":"path","required":true,"description":"Id do funcionário.","schema":{"type":"string"}}],"responses":{"200":{"description":"A admissão, o progresso e as tarefas.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}}},"/v1/admissions/{employeeId}/tasks":{"post":{"operationId":"add-admission-tasks","summary":"Acrescentar tarefas à admissão","description":"Inclui tarefas no fim do checklist de entrada. Até 40 por chamada. Permissão: manage_employees.","tags":["Admissão e desligamento"],"parameters":[{"name":"employeeId","in":"path","required":true,"description":"Id do funcionário.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"tasks":{"type":"array","items":{"type":"object"},"description":"Lista de tarefas com title, kind, owner, required e dueOn."}},"required":["tasks"]},"example":{"tasks":[{"title":"Crachá","kind":"task","owner":"company","required":false,"dueOn":"2026-09-20"}]}}}},"responses":{"200":{"description":"O checklist atualizado.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}}},"/v1/admissions/{employeeId}/complete":{"post":{"operationId":"complete-admission","summary":"Concluir admissão","description":"Passa a situação para active. Recusa com admission_tasks_pending enquanto houver tarefa obrigatória em aberto. Permissão: manage_employees.","tags":["Admissão e desligamento"],"parameters":[{"name":"employeeId","in":"path","required":true,"description":"Id do funcionário.","schema":{"type":"string"}}],"responses":{"200":{"description":"O id do funcionário e a situação resultante.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}}},"/v1/admissions/{employeeId}/cancel":{"post":{"operationId":"cancel-admission","summary":"Cancelar admissão","description":"Apaga o checklist de entrada e devolve a situação para active. O cadastro permanece. Permissão: manage_employees.","tags":["Admissão e desligamento"],"parameters":[{"name":"employeeId","in":"path","required":true,"description":"Id do funcionário.","schema":{"type":"string"}}],"responses":{"200":{"description":"O id do funcionário e a situação resultante.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}}},"/v1/lifecycle-tasks/{taskId}":{"get":{"operationId":"get-lifecycle-task","summary":"Uma tarefa","description":"A tarefa de admissão ou de desligamento, com o documento entregue e a conferência. Permissão: view_all_employees (ver).","tags":["Admissão e desligamento"],"parameters":[{"name":"taskId","in":"path","required":true,"description":"Id da tarefa.","schema":{"type":"string"}}],"responses":{"200":{"description":"A tarefa.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}},"patch":{"operationId":"set-lifecycle-task","summary":"Concluir ou reabrir tarefa","description":"Marca a tarefa como concluída ou a devolve para pendente. Reabrir também limpa o documento entregue e a data de envio. Permissão: manage_employees.","tags":["Admissão e desligamento"],"parameters":[{"name":"taskId","in":"path","required":true,"description":"Id da tarefa.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"done":{"type":"string","description":"true conclui, false reabre."},"note":{"type":"string","nullable":true,"description":"Observação da conferência."}},"required":["done"]},"example":{"done":true,"note":"documento conferido"}}}},"responses":{"200":{"description":"A tarefa atualizada.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}},"delete":{"operationId":"remove-lifecycle-task","summary":"Remover tarefa","description":"Tira do checklist uma tarefa que não se aplica. Permissão: manage_employees.","tags":["Admissão e desligamento"],"parameters":[{"name":"taskId","in":"path","required":true,"description":"Id da tarefa.","schema":{"type":"string"}}],"responses":{"200":{"description":"O id removido.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}}},"/v1/terminations":{"get":{"operationId":"list-terminations","summary":"Desligamentos","description":"Os processos de saída da organização, do mais recente para o mais antigo. Permissão: view_all_employees (ver).","tags":["Admissão e desligamento"],"parameters":[{"name":"status","in":"query","required":false,"description":"Filtra pela situação do processo.","schema":{"type":"string","enum":["open","completed","cancelled"]}},{"name":"limit","in":"query","required":false,"description":"Itens por página, até 1000. Padrão 50.","schema":{"type":"number"}},{"name":"offset","in":"query","required":false,"description":"Quantos itens pular.","schema":{"type":"number"}}],"responses":{"200":{"description":"Uma página de desligamentos.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}},"post":{"operationId":"open-termination","summary":"Abrir desligamento","description":"Registra motivo, aviso prévio e último dia, e materializa o checklist de saída. O cadastro do funcionário só muda na conclusão. Um desligamento aberto por pessoa. Permissão: manage_employees.","tags":["Admissão e desligamento"],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"employeeId":{"type":"string","description":"Id do funcionário ativo."},"reason":{"type":"string","enum":["dismissal_without_cause","dismissal_with_cause","resignation","mutual_agreement","contract_end","retirement","death"],"description":"Motivo do desligamento. Ele limita o aviso possível e a multa do FGTS."},"notice":{"type":"string","enum":["worked","indemnified","none"],"description":"Tipo de aviso prévio."},"noticeDays":{"type":"number","description":"Dias de aviso, de 0 a 90. Com notice none e dias maiores que zero, o aviso é descontado."},"notifiedOn":{"type":"string","description":"Data do aviso, AAAA-MM-DD."},"lastDay":{"type":"string","description":"Último dia de trabalho, AAAA-MM-DD."},"note":{"type":"string","nullable":true,"description":"Observação do processo."}},"required":["employeeId","reason","notice","noticeDays","notifiedOn","lastDay"]},"example":{"employeeId":"3f1c8f2e-1f4a-4a1b-9a3e-2c9d5b7e1a01","reason":"dismissal_without_cause","notice":"indemnified","noticeDays":30,"notifiedOn":"2026-09-01","lastDay":"2026-09-01"}}}},"responses":{"200":{"description":"O desligamento aberto.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}}},"/v1/terminations/{terminationId}":{"get":{"operationId":"get-termination","summary":"Detalhe do desligamento","description":"O processo, o checklist de saída e o progresso dele. Permissão: view_all_employees (ver).","tags":["Admissão e desligamento"],"parameters":[{"name":"terminationId","in":"path","required":true,"description":"Id do desligamento.","schema":{"type":"string"}}],"responses":{"200":{"description":"O desligamento, o progresso e as tarefas.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}}},"/v1/terminations/{terminationId}/settlement":{"get":{"operationId":"get-termination-settlement","summary":"Verbas rescisórias","description":"A prévia calculada agora enquanto o processo está aberto, ou os valores congelados quando ele foi concluído. O campo frozen diz qual dos dois veio. Permissão: view_all_employees (ver).","tags":["Admissão e desligamento"],"parameters":[{"name":"terminationId","in":"path","required":true,"description":"Id do desligamento.","schema":{"type":"string"}}],"responses":{"200":{"description":"As verbas linha a linha, o bruto, os descontos e o líquido.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}}},"/v1/terminations/{terminationId}/tasks":{"post":{"operationId":"add-termination-tasks","summary":"Acrescentar tarefas à saída","description":"Inclui tarefas no fim do checklist de desligamento. Até 40 por chamada. Permissão: manage_employees.","tags":["Admissão e desligamento"],"parameters":[{"name":"terminationId","in":"path","required":true,"description":"Id do desligamento.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"tasks":{"type":"array","items":{"type":"object"},"description":"Lista de tarefas com title, kind, owner, required e dueOn."}},"required":["tasks"]},"example":{"tasks":[{"title":"Devolver notebook","kind":"task","owner":"employee","required":true,"dueOn":"2026-09-30"}]}}}},"responses":{"200":{"description":"O checklist atualizado.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}}},"/v1/terminations/{terminationId}/complete":{"post":{"operationId":"complete-termination","summary":"Concluir desligamento","description":"Recalcula as verbas no servidor, congela o resultado, marca o desligamento no cadastro e grava a data de saída. O corpo não carrega valores. Recusa com termination_tasks_pending enquanto houver tarefa obrigatória aberta. Permissão: manage_employees.","tags":["Admissão e desligamento"],"parameters":[{"name":"terminationId","in":"path","required":true,"description":"Id do desligamento.","schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"exitInterviewNote":{"type":"string","nullable":true,"description":"Entrevista de desligamento."}}},"example":{"exitInterviewNote":"saiu para uma proposta melhor"}}}},"responses":{"200":{"description":"O desligamento concluído, com as verbas congeladas.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}}},"/v1/terminations/{terminationId}/cancel":{"post":{"operationId":"cancel-termination","summary":"Cancelar desligamento","description":"Encerra o processo sem desligar ninguém. O funcionário continua ativo e o checklist é preservado. Permissão: manage_employees.","tags":["Admissão e desligamento"],"parameters":[{"name":"terminationId","in":"path","required":true,"description":"Id do desligamento.","schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"note":{"type":"string","nullable":true,"description":"Motivo do cancelamento."}}},"example":{"note":"acordo revertido"}}}},"responses":{"200":{"description":"O desligamento cancelado.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"A chave gerada em Integrações e API."}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"fields":{"type":"object","additionalProperties":{"type":"string"}}},"required":["code","message"]}},"required":["error"]}},"responses":{"Error":{"description":"Erro com código estável e mensagem em português.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}