Solicitações e workflows

Solicitações é uma capacidade opcional da camada de plataforma que organiza pedidos em formulários, etapas, atividades e aprovações. Sua existência no código não confirma sua ativação no COBRES. O padrão é REQUESTS_ENABLED=false; a liberação depende da configuração do servidor, do catálogo instalado e das permissões da pessoa.

As demandas deste módulo possuem seu próprio processo. As tarefas de cobrança vinculadas à dívida continuam existindo com o fluxo operacional específico do COBRES; ao gerar certas atividades, o COBRES abre também uma demanda no quadro correspondente, sobre o devedor e relacionada à dívida e à tarefa. Se a demanda não puder ser aberta (catálogo ausente ou falta de permissão), a tarefa é criada normalmente. Com o módulo desligado, a demanda continua sendo registrada e só aparece nas telas quando o módulo for ligado.

Quadros de cobrança

O catálogo de produto traz a categoria Cobrança com cinco quadros prontos:

Quadro	Abre quando	Etapas
Retornar ligação	o devedor pede retorno	A ligar, Em contato, Retornada
Análise de contestação	o contato do devedor contesta a dívida	Recebida, Em análise, Aguardando documentos ou o credor, Contestação procedente ou improcedente
Conferência de pagamento	o devedor diz que vai pagar ou que pagou	A conferir, Conferindo, Aguardando a data prometida ou o comprovante, Pagamento confirmado ou não localizado
Renegociação	uma pessoa cria a atividade de renegociar	A renegociar, Montando proposta, Aguardando o devedor ou o credor, Acordo fechado ou Sem acordo
Revisão de suspensão	a cobrança é suspensa	A revisar, Em revisão, Aguardando informação, Cobrança retomada, Suspensão mantida ou Dívida encerrada

Mover a demanda registra a decisão e o motivo, mas não executa a ação na dívida: retomar, encerrar ou registrar o acordo continua na ficha da dívida.

• Checklist: a etapa de trabalho de contestação, pagamento, renegociação e suspensão traz itens a conferir; a decisão só é liberada com os obrigatórios concluídos.
• Atividade e quadro andam juntos: cancelar a atividade cancela o quadro e concluir Retornar ligação conclui o quadro. Nos demais, a decisão é registrada no quadro.
• Na ficha da dívida: cada atividade mostra o quadro e a etapa, e o bloco Quadros desta dívida lista os abertos e encerrados.
• Abrir à mão: em Demandas, escolha o sujeito Devedor, busque o devedor e a empresa.

Confirmar a disponibilidade

O backoffice consulta GET /api/v1/requests/capabilities. A resposta informa enabled, setup_state, catalog_revision, scope e actions para o operador atual. Essa porta responde mesmo com a capacidade desligada ou com o catálogo em preparação.

Situação	Efeito esperado
enabled: false	Módulo indisponível; suas demais rotas respondem requests_resource_unavailable
setup_state: pending	Catálogo em preparação; aguarde e atualize a página
setup_state: failed	Preparação falhou; a administração técnica precisa investigar
enabled: true e catálogo ready	Ações liberadas conforme as permissões e o escopo

Não use uma variável do frontend para liberar o recurso. A API revalida cada chamada; API e worker precisam operar com configurações compatíveis.

Preparar o catálogo

Com a capacidade disponível, a área Organização do backoffice oferece Workflows, Categorias e solicitações e Regras e responsáveis, conforme o acesso concedido.

1. Revise os modelos disponíveis e o processo que a organização pretende atender.
2. Prepare um rascunho de workflow com etapas, atividades, responsáveis e condições de conclusão.
3. Configure a categoria e o tipo de solicitação, incluindo o formulário e os sujeitos elegíveis.
4. Valide os problemas apresentados, publique a versão e confira a disponibilidade do tipo.
5. Faça uma abertura de conferência e confirme o encaminhamento antes de orientar a equipe.

Editar, publicar e ativar são ações distintas, protegidas por chaves como requests.workflows.manage, .publish e .activate; os tipos também usam requests.types.manage. Publicar uma nova versão não autoriza migrar indiscriminadamente demandas abertas: a migração tem permissão e fluxo próprios.

O catálogo instalado pode vir de uma biblioteca do produto ou do exemplo genérico da camada de plataforma. Uma organização já configurada conserva seu catálogo; a chegada de novos modelos não substitui automaticamente o processo que ela usa.

Atender uma demanda

A seção de demandas oferece lista, Quadros, Minhas atividades e Calendário. Abra a demanda pelo tipo disponível, confira o sujeito, a empresa quando aplicável e os campos obrigatórios. Atribuir a outra pessoa exige autorização própria; o responsável também precisa ser elegível para o caso.

No detalhe, use as transições disponíveis para avançar o trabalho. Confira atividades, anexos, histórico e entregas antes de concluir uma etapa. Diferencie conversa com o solicitante de notas internas: o público de cada mensagem faz parte do fluxo.

Demandas internas entre membros usam o sujeito member e não aparecem ao público externo. A abertura pelo portal depende de um provedor Audience compatível, de vínculo ativo e de tipos elegíveis. A capacidade habilitada, sozinha, não publica qualquer formulário no portal.

Conferência e diagnóstico

• Menu ausente: confirme a capacidade no servidor e as permissões do usuário; a organização selecionada também importa.
• Erro de preparação: requests_setup_pending e requests_setup_failed são respostas 503 do catálogo, não uma indicação de perda de sessão.
• Pessoa ou empresa indisponível: confira vínculo ativo, elegibilidade e escopo. Uma demanda sem empresa exige escopo total para abertura e leitura.
• Ação recusada: confira o estado atual, o responsável e as chaves exigidas. Não deduza autorização apenas pela leitura do cartão.
• Repetição pela API: os comandos usam request_nonce; o módulo recusa Idempotency-Key. Preserve a identificação do comando ao tratar uma falha de comunicação.

Registre o request_id e consulte erros e permissões para encaminhar o diagnóstico.