Horas de projeto para o faturamento

Quem vende serviço por hora fatura o que a equipe apontou — e só depois que o gestor aprovou. Na TAI, cada colaborador apropria horas em projetos de clientes; o responsável pelo subdepartamento do projeto aprova ou rejeita. A integração traz o cadastro do CRM para cá e leva os totais aprovados para o sistema de faturamento.

Quando usar	Clientes e projetos nascem no CRM; o faturamento ou o ERP cobra pelas horas aprovadas
Porta	REST · Webhook (horas decididas) · Agente (MCP)
Você vai precisar	Módulo GESTAO_PROJETOS; permissões PROJETO_CLIENTE (clientes), PROJETO (projetos e totais) e APROPRIACAO_APROVAR (ler as horas de todos); token JWT

Como funciona

CRM ── GET /cliente/cnpj/{cnpj} ── POST /cliente ──▶ TAI
CRM ── POST /projeto (cliente + subdepartamento) ──▶ TAI
colaboradores apontam horas ──▶ RASCUNHO ──▶ ENVIADO ──▶ APROVADO pelo responsável
faturamento ── GET /projeto/{id}/totalizador-horas-periodo ──▶ horas aprovadas por pessoa
TAI ── APROPRIACAO_APROVADA / APROPRIACAO_REJEITADA ──▶ webhook ──▶ faturamento (na hora)

Passo a passo

1. Ache ou crie o cliente.

   GET /cliente/cnpj/12345678000190
   Authorization: Bearer $TAI_TOKEN

   404 significa que ainda não existe:

   POST /cliente
   Content-Type: application/json
   
   {
     "nome": "Mercado Sol",
     "razaoSocial": "Mercado Sol Comércio de Alimentos Ltda",
     "cnpj": "12345678000190",
     "email": "compras@mercadosol.com.br"
   }

2. Crie o projeto. O subdepartamento é obrigatório e precisa ter um responsável: é essa pessoa quem aprova as horas do projeto.

   POST /projeto
   Content-Type: application/json
   
   {
     "nome": "Implantação ERP — Mercado Sol",
     "descricao": "Contrato 2026/118, banco de 200 horas",
     "cliente": { "id": 44 },
     "subDepartamento": { "id": 19 }
   }

   Guarde o id. Os projetos de um cliente saem em GET /projeto/cliente/{clienteId}.

3. Deixe a equipe apontar. Cada colaborador lança as próprias horas — na tela, pelo cronômetro, pela Tali ou pelo agente de IA dele. A apropriação nasce RASCUNHO, vai para ENVIADO e o responsável a deixa APROVADO ou REJEITADO com motivo.

4. Leve os totais aprovados para a fatura.

   GET /projeto/301/totalizador-horas-periodo?dataInicio=2026-10-01&dataFim=2026-10-31

   Uma linha por colaborador, com totalMinutos e totalFormatado, contando só horas aprovadas. Sem período, GET /projeto/301/totalizador-horas dá o total do projeto inteiro.

5. Detalhe, quando a fatura precisa. As apropriações do projeto no período, uma a uma:

   GET /apropriacao/projeto/301/periodo?dataInicio=2026-10-01%2000:00:00&dataFim=2026-10-31%2023:59:59

   Cada item traz colaborador, dataHoraInicio, dataHoraFim, duracaoMinutos, descricao, tarefa e status. Esta rota devolve todos os status — filtre APROVADO antes de faturar.

Receber cada aprovação na hora

Se o faturamento acumula as horas à medida que são aprovadas, em vez de ler o totalizador no fim do mês, crie um webhook assinando Uma apropriação de horas é aprovada (APROPRIACAO_APROVADA):

{
  "id": "evt_70288",
  "tipo": "APROPRIACAO_APROVADA",
  "descricao": "Uma apropriação de horas é aprovada",
  "versao": 1,
  "ocorridoEm": "2026-10-03T19:12:40.055Z",
  "empresa": { "id": 12, "nome": "Sua Empresa Ltda" },
  "dados": {
    "apropriacaoId": 55120,
    "projetoId": 301,
    "projetoNome": "Implantação ERP — Mercado Sol",
    "colaboradorId": 812,
    "aprovadorId": 640,
    "dataHoraInicio": "2026-10-02T12:00:00Z",
    "dataHoraFim": "2026-10-02T14:30:00Z",
    "motivo": null
  }
}

dataHoraInicio e dataHoraFim chegam em UTC. Uma apropriação de horas é rejeitada (APROPRIACAO_REJEITADA) tem os mesmos campos, com o motivo. Uma apropriação pode voltar a ser enviada e decidida de novo — cada decisão é um evento próprio: guarde o apropriacaoId e fique com a última decisão. O totalizador continua sendo a conferência do fim do período.

Lançar horas de outra ferramenta

O apontamento é sempre de quem está autenticado: POST /apropriacao grava a hora no colaborador do token, qualquer que seja o corpo. Um usuário de integração não lança horas em nome da equipe. Para trazer horas de um timer externo, cada pessoa conecta a própria credencial:

POST /apropriacao
Authorization: Bearer <token da própria pessoa>
Content-Type: application/json

{
  "projeto": { "id": 301 },
  "dataHoraInicio": "2026-10-02 09:00:00",
  "dataHoraFim": "2026-10-02 11:30:00",
  "descricao": "Parametrização do módulo fiscal"
}

Horário sobreposto a outra apropriação da mesma pessoa é recusado com 400 (POST /apropriacao/validar-sobreposicao confere antes). Depois, PUT /apropriacao/{id}/enviar manda para aprovação — ou PUT /apropriacao/enviar-lote envia todos os rascunhos da pessoa.

Pelo seu agente de IA

“Lance 2h30 ontem de manhã no projeto Implantação ERP — Mercado Sol: parametrização do módulo fiscal.”

Como o apontamento é sempre de quem conectou o agente, este é o uso natural do MCP: cada pessoa fala com o próprio agente e as horas caem no nome dela, em rascunho. Para o gestor: “quantas horas aprovadas o projeto Mercado Sol teve em outubro, por pessoa?”. Aprovar horas é ato de confirmação forte e não roda por agente externo — veja Escrita e segurança.

Cuidados

• Só horas aprovadas são faturáveis: o totalizador já conta assim; a lista detalhada não.
• Rascunho é editável; enviado não. Editar ou excluir só vale para RASCUNHO, e só pelo dono.
• Quem aprova é o responsável do subdepartamento do projeto. Projeto sem subdepartamento com responsável é recusado na criação.
• Formatos de data: o totalizador recebe yyyy-MM-dd; as listas de apropriações por período, yyyy-MM-dd HH:mm:ss (codifique o espaço na URL). Veja Datas e formatos.
• Cliente duplicado: procure pelo CNPJ antes de criar.