Réguas de Cobrança — Regras de Negócio

1. Conceito

A Régua de Cobrança é um conjunto de etapas sequenciais que define como o time de cobrança da empresa deve atuar sobre os contratos da carteira. Cada etapa combina um gatilho (quando agir) e uma ação (o que fazer), executados em sequência conforme o avanço do atraso ou de condições específicas do título.

A régua não interfere em cálculos financeiros — juros, multa e desconto são configurados no nível do contrato e do título (ver Contratos.md e Titulos.md). O papel da régua é exclusivamente operacional: orientar e automatizar as atividades do time de cobrança.

Uma empresa pode criar quantas réguas desejar. Não existe régua global obrigatória — cada contrato pode ter sua própria régua atribuída, ou nenhuma. Réguas são criadas livremente pela empresa a partir do momento em que acessa o módulo de Gestão de Portfolio.

Escopo da v1: A única ação implementada na v1 é a geração de atividade no módulo de Atividades (ACTIVITY). Os demais tipos de ação (EMAIL, SMS, CALL, NEGATIVATION, PROTEST) estão modelados e previstos para versões futuras, conforme descrito na seção 6.

2. Estruturas de Dados

2.1. CollectionRule

Campo	Tipo	Obrigatório	Descrição
`id`	UUID	Sim	Identificador único da régua.
`companyId`	UUID	Sim	Empresa à qual a régua pertence.
`name`	String	Sim	Nome da régua (ex: "Cobrança Padrão", "Grandes Contas"). Único por empresa.
`description`	String	Não	Descrição do propósito ou critério de uso da régua.
`status`	Enum	Sim	Estado: `ACTIVE`, `INACTIVE`.
`createdBy`	UUID	Sim	Usuário que criou a régua.
`createdAt`	DateTime	Sim	Data de criação.
`updatedAt`	DateTime	Sim	Data da última atualização.

2.2. CollectionStep

Cada etapa pertence a uma régua e define exatamente um gatilho e uma ação. As etapas são executadas em ordem crescente de stepOrder.

Campo	Tipo	Obrigatório	Descrição
`id`	UUID	Sim	Identificador único da etapa.
`collectionRuleId`	UUID	Sim	Régua à qual a etapa pertence.
`stepOrder`	Integer	Sim	Ordem de execução da etapa dentro da régua. Único por régua. Começa em `1`.
`triggerType`	Enum	Sim	Tipo do gatilho: `DAYS_BEFORE_DUE`, `ON_DUE_DATE`, `DAYS_AFTER_DUE`, `STATUS_CHANGE`.
`triggerValue`	Integer	Condicional	Valor numérico do gatilho em dias. Obrigatório para `DAYS_BEFORE_DUE` e `DAYS_AFTER_DUE`. Ignorado para `ON_DUE_DATE` e `STATUS_CHANGE`.
`triggerStatus`	Enum	Condicional	Status que dispara a etapa. Obrigatório quando `triggerType = STATUS_CHANGE`. Valores: `OVERDUE`, `PARTIALLY_PAID`.
`actionType`	Enum	Sim	Tipo da ação executada: `ACTIVITY`, `EMAIL`, `SMS`, `CALL`, `NEGATIVATION`, `PROTEST`.
`actionConfig`	Object	Não	Configurações específicas da ação. Estrutura varia conforme `actionType`. Ver seção 2.3.
`isActive`	Boolean	Sim	Indica se a etapa está ativa. Etapas inativas são ignoradas na execução. Default: `true`.
`createdAt`	DateTime	Sim	Data de criação.
`updatedAt`	DateTime	Sim	Data da última atualização.

2.3. actionConfig por tipo de ação

`ACTIVITY` (v1 — implementado)

{
  "activityType": "CALL",
  "title": "Ligar para cliente — título vencido há 3 dias",
  "description": "Verificar motivo do atraso e negociar prazo de pagamento.",
  "priority": "HIGH",
  "dueDaysAfterTrigger": 1
}

Campo	Tipo	Descrição
`activityType`	Enum	Tipo da atividade gerada: `CALL`, `EMAIL`, `MEETING`, `OTHER`.
`title`	String	Título da atividade criada no módulo de Atividades.
`description`	String	Descrição/instrução para o responsável pela atividade.
`priority`	Enum	Prioridade: `LOW`, `MEDIUM`, `HIGH`.
`dueDaysAfterTrigger`	Integer	Prazo em dias para conclusão da atividade, contado a partir do disparo.

`EMAIL` (roadmap)

{
  "templateId": "uuid-do-template",
  "subject": "Lembrete de vencimento — {{contractCode}}",
  "sendCopyTo": ["financeiro@empresa.com"]
}

`SMS` (roadmap)

{
  "templateId": "uuid-do-template"
}

`CALL` (roadmap)

{
  "assignToUserId": "uuid-do-usuario",
  "script": "Roteiro de ligação para cobranças em atraso."
}

`NEGATIVATION` (roadmap)

{
  "bureau": "SERASA",
  "notifyClientDaysBefore": 5
}

`PROTEST` (roadmap)

{
  "cartorio": "1º Cartório de Protestos",
  "notifyClientDaysBefore": 5
}

2.4. CollectionRuleTarget (Vínculo da Régua)

Define quais contratos ou clientes estão associados a uma régua. Quando o vínculo é por cliente, todos os contratos ativos daquele cliente são avaliados pela régua. Quando é por contrato, apenas aquele contrato específico é avaliado.

Campo	Tipo	Obrigatório	Descrição
`id`	UUID	Sim	Identificador único do vínculo.
`collectionRuleId`	UUID	Sim	Referência à régua de cobrança.
`targetType`	Enum	Sim	Tipo do alvo: `CONTRACT` ou `CLIENT`.
`contractId`	UUID	Condicional	Referência ao contrato vinculado. Obrigatório quando `targetType = CONTRACT`.
`clientId`	UUID	Condicional	Referência ao cliente vinculado. Obrigatório quando `targetType = CLIENT`. Todos os contratos ativos do cliente são avaliados pela régua.
`assignedBy`	UUID	Sim	Usuário que realizou o vínculo.
`assignedAt`	DateTime	Sim	Data e hora do vínculo.
`createdAt`	DateTime	Sim	Data de criação do registro.

2.5. CollectionStepExecution (Log de Execução)

Registra cada vez que uma etapa foi executada para um título específico.

Campo	Tipo	Obrigatório	Descrição
`id`	UUID	Sim	Identificador único da execução.
`collectionStepId`	UUID	Sim	Etapa que foi executada.
`collectionRuleId`	UUID	Sim	Régua à qual a etapa pertence. Desnormalizado.
`receivableId`	UUID	Sim	Título que disparou a execução.
`contractId`	UUID	Sim	Contrato pai do título. Desnormalizado.
`companyId`	UUID	Sim	Empresa. Desnormalizado.
`executedAt`	DateTime	Sim	Data e hora da execução.
`status`	Enum	Sim	Resultado: `SUCCESS`, `FAILED`.
`failureReason`	String	Não	Motivo da falha técnica, quando `status = FAILED`.
`resultRef`	UUID	Não	Referência ao objeto criado pela ação (ex: ID da atividade gerada).
`createdAt`	DateTime	Sim	Data de criação do registro.

3. Regras de Negócio

RN-RULE-001: Criação livre de réguas

A empresa pode criar quantas réguas desejar a partir do momento em que acessa o módulo de Gestão de Portfolio. Não existe régua global obrigatória nem limite de réguas por empresa.

RN-RULE-002: Nome único por empresa

O campo name deve ser único dentro do escopo da empresa. Tentativas de criar réguas com nome duplicado devem ser rejeitadas com erro específico.

RN-RULE-003: Atribuição ao contrato

A régua é atribuída no nível do contrato via collectionRuleId (ver Contratos.md). Contratos sem régua atribuída (collectionRuleId = null) não têm etapas de cobrança executadas automaticamente.

RN-RULE-004: Etapas ordenadas e únicas

O campo stepOrder deve ser único dentro de uma régua. A execução das etapas respeita estritamente a ordem crescente. Não é possível ter duas etapas com o mesmo stepOrder na mesma régua.

RN-RULE-005: Execução sequencial com intervalo de dias

As etapas são executadas em sequência. A próxima etapa só é elegível para execução após o gatilho da etapa atual ser satisfeito. O job de execução avalia diariamente os títulos elegíveis para cada etapa.

RN-RULE-006: Condição de elegibilidade por título

Uma etapa só é executada para um título se todas as condições abaixo forem verdadeiras: o título está em status = PENDING, PARTIALLY_PAID ou OVERDUE; a etapa ainda não foi executada para aquele título com status = SUCCESS; e o gatilho da etapa foi satisfeito.

RN-RULE-007: Etapa ignorada por pagamento

Se um título for liquidado (PAID) antes de uma etapa ser executada, todas as etapas pendentes para aquele título são automaticamente marcadas como SKIPPED no log de execução.

RN-RULE-008: Gatilho DAYS_BEFORE_DUE

Disparado quando a data atual é exatamente triggerValue dias antes do dueDate do título. Aplicável apenas a títulos PENDING.

RN-RULE-009: Gatilho ON_DUE_DATE

Disparado no próprio dia do vencimento (dueDate). Aplicável a títulos PENDING ou PARTIALLY_PAID.

RN-RULE-010: Gatilho DAYS_AFTER_DUE

Disparado quando a data atual é exatamente triggerValue dias após o dueDate. Aplicável a títulos OVERDUE ou PARTIALLY_PAID.

RN-RULE-011: Gatilho STATUS_CHANGE

Disparado quando o título transita para o triggerStatus configurado. A avaliação ocorre no mesmo job que processa as transições automáticas de status dos títulos.

RN-RULE-013: Ações de roadmap não executáveis na v1

Etapas configuradas com actionType diferente de ACTIVITY são aceitas no cadastro mas não serão executadas na v1 — o job simplesmente as ignora sem gerar registro no log de execução. Nenhum status de falha ou motivo é registrado. Essas etapas passarão a ser executadas automaticamente quando a integração correspondente for implementada.

RN-RULE-016: Vínculo por contrato

Quando targetType = CONTRACT, a régua é avaliada exclusivamente para os títulos daquele contrato. O contractId informado deve pertencer à mesma empresa da régua.

RN-RULE-017: Vínculo por cliente

Quando targetType = CLIENT, a régua é avaliada para todos os contratos ativos do cliente na carteira da empresa. Contratos futuros do mesmo cliente, criados após o vínculo, também passam a ser avaliados automaticamente pela régua.

RN-RULE-018: Precedência de vínculo

Um contrato pode estar coberto simultaneamente por um vínculo direto (CONTRACT) e por um vínculo via cliente (CLIENT). Nesse caso, o vínculo direto por contrato tem precedência — a régua vinculada diretamente ao contrato é a que será executada. Caso o contrato possua collectionRuleId preenchido (ver Contratos.md), este também prevalece sobre vínculos via CollectionRuleTarget.

RN-RULE-019: Unicidade de vínculo por contrato

Um contrato pode estar vinculado a no máximo uma régua via CollectionRuleTarget do tipo CONTRACT. Tentativas de vincular um contrato já associado a outra régua devem ser rejeitadas com erro específico.

RN-RULE-014: Desativação de régua em uso

Uma régua ACTIVE referenciada por contratos ativos não pode ser desativada diretamente. O usuário deve primeiro reatribuir os contratos a outra régua ou remover a atribuição antes de desativar.

RN-RULE-015: Exclusão lógica

Réguas nunca são deletadas fisicamente. Desativação via status = INACTIVE.

4. Padrão de Erros

Os erros comuns de autenticação, autorização e servidor seguem o padrão definido em Carteiras.md (seção 4.1 e 4.2).

Códigos de erro específicos de réguas

Status	Código	Descrição
`404 Not Found`	`COLLECTION_RULE_NOT_FOUND`	Régua não encontrada ou não pertence à empresa do contexto.
`404 Not Found`	`COLLECTION_STEP_NOT_FOUND`	Etapa não encontrada ou não pertence à régua informada.
`409 Conflict`	`COLLECTION_RULE_NAME_ALREADY_EXISTS`	Já existe uma régua com este nome para a empresa.
`422 Unprocessable Entity`	`DUPLICATE_STEP_ORDER`	Já existe uma etapa com este `stepOrder` nesta régua.
`422 Unprocessable Entity`	`MISSING_TRIGGER_VALUE`	`triggerValue` é obrigatório para os `triggerType` `DAYS_BEFORE_DUE` e `DAYS_AFTER_DUE`.
`422 Unprocessable Entity`	`MISSING_TRIGGER_STATUS`	`triggerStatus` é obrigatório quando `triggerType = STATUS_CHANGE`.
`422 Unprocessable Entity`	`COLLECTION_RULE_IN_USE`	A régua está referenciada por contratos ativos e não pode ser desativada.
`422 Unprocessable Entity`	`COLLECTION_RULE_INACTIVE`	Não é possível adicionar ou editar etapas em uma régua inativa.
`409 Conflict`	`CONTRACT_ALREADY_TARGETED`	O contrato já está vinculado a outra régua via `CollectionRuleTarget`.
`422 Unprocessable Entity`	`TARGET_COMPANY_MISMATCH`	O contrato ou cliente informado não pertence à empresa da régua.

5. Endpoints

`POST /v2/companies/:companyId/portfolio/collection-rules`

Cria uma nova régua de cobrança.

Permissão requerida: collection_rule:create

Request body:

{
  "name": "Cobrança Grandes Contas",
  "description": "Régua para contratos acima de R$ 500.000 com abordagem personalizada."
}

Response 201 Created:

{
  "id": "cr1a2b3c4-0000-0000-0000-000000000001",
  "companyId": "a1b2c3d4-0000-0000-0000-000000000001",
  "name": "Cobrança Grandes Contas",
  "description": "Régua para contratos acima de R$ 500.000 com abordagem personalizada.",
  "status": "ACTIVE",
  "createdBy": "d290f1ee-6c54-4b01-90e6-d701748f0851",
  "createdAt": "2025-03-17T09:00:00Z",
  "updatedAt": "2025-03-17T09:00:00Z"
}

Erros específicos:

Status	Código	Descrição
`409 Conflict`	`COLLECTION_RULE_NAME_ALREADY_EXISTS`	Já existe uma régua com este nome para a empresa.

`GET /v2/companies/:companyId/portfolio/collection-rules`

Lista as réguas de cobrança da empresa.

Permissão requerida: collection_rule:read

Query params:

Parâmetro	Tipo	Obrigatório	Descrição
`status`	Enum	Não	Filtrar por `ACTIVE` ou `INACTIVE`.
`page`	Integer	Não	Número da página. Default: `1`.
`pageSize`	Integer	Não	Itens por página. Default: `20`. Máximo: `100`.

Response 200 OK:

{
  "data": [
    {
      "id": "cr1a2b3c4-0000-0000-0000-000000000001",
      "companyId": "a1b2c3d4-0000-0000-0000-000000000001",
      "name": "Cobrança Grandes Contas",
      "description": "Régua para contratos acima de R$ 500.000 com abordagem personalizada.",
      "status": "ACTIVE",
      "createdBy": "d290f1ee-6c54-4b01-90e6-d701748f0851",
      "createdAt": "2025-03-17T09:00:00Z",
      "updatedAt": "2025-03-17T09:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "pageSize": 20,
    "nextPage": false
  }
}

`GET /v2/companies/:companyId/portfolio/collection-rules/:collectionRuleId`

Retorna o detalhe de uma régua com suas etapas.

Permissão requerida: collection_rule:read

Response 200 OK:

{
  "id": "cr1a2b3c4-0000-0000-0000-000000000001",
  "companyId": "a1b2c3d4-0000-0000-0000-000000000001",
  "name": "Cobrança Grandes Contas",
  "description": "Régua para contratos acima de R$ 500.000 com abordagem personalizada.",
  "status": "ACTIVE",
  "createdBy": "d290f1ee-6c54-4b01-90e6-d701748f0851",
  "createdAt": "2025-03-17T09:00:00Z",
  "updatedAt": "2025-03-17T09:00:00Z",
  "steps": [
    {
      "id": "cs1a2b3c4-0000-0000-0000-000000000001",
      "stepOrder": 1,
      "triggerType": "DAYS_BEFORE_DUE",
      "triggerValue": 3,
      "triggerStatus": null,
      "actionType": "ACTIVITY",
      "actionConfig": {
        "activityType": "EMAIL",
        "title": "Enviar lembrete de vencimento",
        "description": "Contato preventivo antes do vencimento do título.",
        "priority": "LOW",
        "dueDaysAfterTrigger": 1
      },
      "isActive": true,
      "createdAt": "2025-03-17T09:00:00Z",
      "updatedAt": "2025-03-17T09:00:00Z"
    },
    {
      "id": "cs1a2b3c4-0000-0000-0000-000000000002",
      "stepOrder": 2,
      "triggerType": "DAYS_AFTER_DUE",
      "triggerValue": 3,
      "triggerStatus": null,
      "actionType": "ACTIVITY",
      "actionConfig": {
        "activityType": "CALL",
        "title": "Ligar para cliente — título vencido há 3 dias",
        "description": "Verificar motivo do atraso e negociar prazo de pagamento.",
        "priority": "HIGH",
        "dueDaysAfterTrigger": 1
      },
      "isActive": true,
      "createdAt": "2025-03-17T09:00:00Z",
      "updatedAt": "2025-03-17T09:00:00Z"
    }
  ]
}

`PATCH /v2/companies/:companyId/portfolio/collection-rules/:collectionRuleId`

Atualiza os dados de uma régua. Apenas name e description são editáveis.

Permissão requerida: collection_rule:update

Request body:

{
  "name": "Cobrança Grandes Contas — Revisada",
  "description": "Régua para contratos acima de R$ 500.000 com abordagem consultiva."
}

Response 200 OK:

{
  "id": "cr1a2b3c4-0000-0000-0000-000000000001",
  "companyId": "a1b2c3d4-0000-0000-0000-000000000001",
  "name": "Cobrança Grandes Contas — Revisada",
  "description": "Régua para contratos acima de R$ 500.000 com abordagem consultiva.",
  "status": "ACTIVE",
  "createdBy": "d290f1ee-6c54-4b01-90e6-d701748f0851",
  "createdAt": "2025-03-17T09:00:00Z",
  "updatedAt": "2025-03-20T10:00:00Z"
}

Erros específicos:

Status	Código	Descrição
`409 Conflict`	`COLLECTION_RULE_NAME_ALREADY_EXISTS`	O novo nome já existe em outra régua da empresa.
`422 Unprocessable Entity`	`COLLECTION_RULE_INACTIVE`	Não é possível editar uma régua inativa.

`PATCH /v2/companies/:companyId/portfolio/collection-rules/:collectionRuleId/status`

Ativa ou desativa uma régua.

Permissão requerida: collection_rule:delete

Request body:

{
  "status": "INACTIVE"
}

Response 200 OK:

{
  "id": "cr1a2b3c4-0000-0000-0000-000000000001",
  "status": "INACTIVE",
  "updatedAt": "2025-03-20T11:00:00Z"
}

Erros específicos:

Status	Código	Descrição
`422 Unprocessable Entity`	`COLLECTION_RULE_IN_USE`	A régua está referenciada por contratos ativos e não pode ser desativada.

{
  "error": "COLLECTION_RULE_IN_USE",
  "message": "Não é possível desativar esta régua pois ela está associada a contratos ativos.",
  "details": {
    "activeContractsCount": 12
  }
}

`POST /v2/companies/:companyId/portfolio/collection-rules/:collectionRuleId/steps`

Adiciona uma nova etapa à régua.

Permissão requerida: collection_rule:update

Request body:

{
  "stepOrder": 3,
  "triggerType": "DAYS_AFTER_DUE",
  "triggerValue": 15,
  "actionType": "ACTIVITY",
  "actionConfig": {
    "activityType": "CALL",
    "title": "Segunda tentativa de contato — 15 dias de atraso",
    "description": "Negociar acordo formal de pagamento.",
    "priority": "HIGH",
    "dueDaysAfterTrigger": 1
  },
  "isActive": true
}

Response 201 Created:

{
  "id": "cs1a2b3c4-0000-0000-0000-000000000003",
  "collectionRuleId": "cr1a2b3c4-0000-0000-0000-000000000001",
  "stepOrder": 3,
  "triggerType": "DAYS_AFTER_DUE",
  "triggerValue": 15,
  "triggerStatus": null,
  "actionType": "ACTIVITY",
  "actionConfig": {
    "activityType": "CALL",
    "title": "Segunda tentativa de contato — 15 dias de atraso",
    "description": "Negociar acordo formal de pagamento.",
    "priority": "HIGH",
    "dueDaysAfterTrigger": 1
  },
  "isActive": true,
  "createdAt": "2025-03-20T09:00:00Z",
  "updatedAt": "2025-03-20T09:00:00Z"
}

Erros específicos:

Status	Código	Descrição
`422 Unprocessable Entity`	`DUPLICATE_STEP_ORDER`	Já existe uma etapa com este `stepOrder` nesta régua.
`422 Unprocessable Entity`	`MISSING_TRIGGER_VALUE`	`triggerValue` é obrigatório para os `triggerType` `DAYS_BEFORE_DUE` e `DAYS_AFTER_DUE`.
`422 Unprocessable Entity`	`MISSING_TRIGGER_STATUS`	`triggerStatus` é obrigatório quando `triggerType = STATUS_CHANGE`.
`422 Unprocessable Entity`	`COLLECTION_RULE_INACTIVE`	Não é possível adicionar etapas a uma régua inativa.

`PATCH /v2/companies/:companyId/portfolio/collection-rules/:collectionRuleId/steps/:stepId`

Atualiza uma etapa existente.

Permissão requerida: collection_rule:update

Request body (todos os campos são opcionais):

{
  "triggerValue": 10,
  "actionConfig": {
    "activityType": "CALL",
    "title": "Contato — 10 dias de atraso",
    "description": "Negociar acordo.",
    "priority": "HIGH",
    "dueDaysAfterTrigger": 1
  }
}

Response 200 OK:

{
  "id": "cs1a2b3c4-0000-0000-0000-000000000003",
  "collectionRuleId": "cr1a2b3c4-0000-0000-0000-000000000001",
  "stepOrder": 3,
  "triggerType": "DAYS_AFTER_DUE",
  "triggerValue": 10,
  "triggerStatus": null,
  "actionType": "ACTIVITY",
  "actionConfig": {
    "activityType": "CALL",
    "title": "Contato — 10 dias de atraso",
    "description": "Negociar acordo.",
    "priority": "HIGH",
    "dueDaysAfterTrigger": 1
  },
  "isActive": true,
  "createdAt": "2025-03-20T09:00:00Z",
  "updatedAt": "2025-03-20T10:00:00Z"
}

`DELETE /v2/companies/:companyId/portfolio/collection-rules/:collectionRuleId/steps/:stepId`

Remove uma etapa da régua.

Permissão requerida: collection_rule:update

Response 204 No Content

Erros específicos:

Status	Código	Descrição
`404 Not Found`	`COLLECTION_STEP_NOT_FOUND`	Etapa não encontrada ou não pertence à régua informada.

`POST /v2/companies/:companyId/portfolio/collection-rules/:collectionRuleId/targets`

Vincula um contrato ou cliente à régua de cobrança.

Permissão requerida: collection_rule:update

Request body — vínculo por contrato:

{
  "targetType": "CONTRACT",
  "contractId": "b9d3f1aa-22cc-4e72-b430-1e45a3d6e001"
}

Request body — vínculo por cliente:

{
  "targetType": "CLIENT",
  "clientId": "a3f1c2d4-0000-0000-0000-000000000010"
}

Response 201 Created:

{
  "id": "tg1a2b3c4-0000-0000-0000-000000000001",
  "collectionRuleId": "cr1a2b3c4-0000-0000-0000-000000000001",
  "targetType": "CLIENT",
  "contractId": null,
  "clientId": "a3f1c2d4-0000-0000-0000-000000000010",
  "assignedBy": "d290f1ee-6c54-4b01-90e6-d701748f0851",
  "assignedAt": "2025-03-20T09:00:00Z",
  "createdAt": "2025-03-20T09:00:00Z"
}

Erros específicos:

Status	Código	Descrição
`409 Conflict`	`CONTRACT_ALREADY_TARGETED`	O contrato já está vinculado a outra régua.
`422 Unprocessable Entity`	`TARGET_COMPANY_MISMATCH`	O contrato ou cliente não pertence à empresa da régua.

`GET /v2/companies/:companyId/portfolio/collection-rules/:collectionRuleId/targets`

Lista os contratos e clientes vinculados à régua.

Permissão requerida: collection_rule:read

Query params:

Parâmetro	Tipo	Obrigatório	Descrição
`targetType`	Enum	Não	Filtrar por `CONTRACT` ou `CLIENT`.
`page`	Integer	Não	Número da página. Default: `1`.
`pageSize`	Integer	Não	Itens por página. Default: `20`. Máximo: `100`.

Response 200 OK:

{
  "data": [
    {
      "id": "tg1a2b3c4-0000-0000-0000-000000000001",
      "collectionRuleId": "cr1a2b3c4-0000-0000-0000-000000000001",
      "targetType": "CLIENT",
      "contractId": null,
      "clientId": "a3f1c2d4-0000-0000-0000-000000000010",
      "assignedBy": "d290f1ee-6c54-4b01-90e6-d701748f0851",
      "assignedAt": "2025-03-20T09:00:00Z",
      "createdAt": "2025-03-20T09:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "pageSize": 20,
    "nextPage": false
  }
}

`DELETE /v2/companies/:companyId/portfolio/collection-rules/:collectionRuleId/targets/:targetId`

Remove o vínculo de um contrato ou cliente com a régua.

Permissão requerida: collection_rule:update

Response 204 No Content

Erros específicos:

Status	Código	Descrição
`404 Not Found`	`COLLECTION_RULE_TARGET_NOT_FOUND`	Vínculo não encontrado ou não pertence à régua informada.

`GET /v2/companies/:companyId/portfolio/collection-rules/:collectionRuleId/executions`

Lista o histórico de execuções de uma régua com filtros por título, contrato e resultado.

Permissão requerida: collection_rule:read

Query params:

Parâmetro	Tipo	Obrigatório	Descrição
`receivableId`	UUID	Não	Filtrar execuções de um título específico.
`contractId`	UUID	Não	Filtrar execuções de um contrato específico.
`status`	Enum	Não	Filtrar por resultado: `SUCCESS`, `FAILED`.
`page`	Integer	Não	Número da página. Default: `1`.
`pageSize`	Integer	Não	Itens por página. Default: `20`. Máximo: `100`.

Response 200 OK:

{
  "data": [
    {
      "id": "ex1a2b3c4-0000-0000-0000-000000000001",
      "collectionStepId": "cs1a2b3c4-0000-0000-0000-000000000002",
      "collectionRuleId": "cr1a2b3c4-0000-0000-0000-000000000001",
      "receivableId": "r1a2b3c4-0000-0000-0000-000000000001",
      "contractId": "b9d3f1aa-22cc-4e72-b430-1e45a3d6e001",
      "companyId": "a1b2c3d4-0000-0000-0000-000000000001",
      "executedAt": "2025-03-17T08:00:00Z",
      "status": "SUCCESS",
      "failureReason": null,
      "resultRef": "act1a2b3c4-0000-0000-0000-000000000001",
      "createdAt": "2025-03-17T08:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "pageSize": 20,
    "nextPage": false
  }
}

6. Roadmap — Tipos de Ação Futuros

Status: Modelados mas não implementados na v1. Etapas configuradas com estes tipos serão registradas como SKIPPED no log de execução até que a implementação ocorra.

Tipo	Descrição	Dependências
`EMAIL`	Envio automático de e-mail ao devedor com template configurável.	Módulo de templates de e-mail, serviço de envio (ex: SendGrid).
`SMS`	Envio automático de SMS ao devedor.	Integração com gateway de SMS.
`CALL`	Criação de tarefa de ligação telefônica atribuída a um usuário.	Módulo de Atividades (já disponível como `ACTIVITY`).
`NEGATIVATION`	Negativação automática do devedor em bureau de crédito (Serasa/SPC).	Integração com bureaus de crédito, fluxo de notificação prévia obrigatória (5 dias).
`PROTEST`	Envio do título a protesto em cartório.	Integração com sistema de protesto, fluxo de notificação prévia.

Regras da régua por empresa

Réguas de Cobrança — Regras de Negócio#

1. Conceito#

2. Estruturas de Dados#

2.1. CollectionRule#

2.2. CollectionStep#

2.3. actionConfig por tipo de ação#

ACTIVITY (v1 — implementado)#

EMAIL (roadmap)#

SMS (roadmap)#

CALL (roadmap)#

NEGATIVATION (roadmap)#

PROTEST (roadmap)#

2.4. CollectionRuleTarget (Vínculo da Régua)#

2.5. CollectionStepExecution (Log de Execução)#

3. Regras de Negócio#

RN-RULE-001: Criação livre de réguas#

RN-RULE-002: Nome único por empresa#

RN-RULE-003: Atribuição ao contrato#

RN-RULE-004: Etapas ordenadas e únicas#

RN-RULE-005: Execução sequencial com intervalo de dias#

RN-RULE-006: Condição de elegibilidade por título#

RN-RULE-007: Etapa ignorada por pagamento#

RN-RULE-008: Gatilho DAYS_BEFORE_DUE#

RN-RULE-009: Gatilho ON_DUE_DATE#

RN-RULE-010: Gatilho DAYS_AFTER_DUE#

RN-RULE-011: Gatilho STATUS_CHANGE#

RN-RULE-013: Ações de roadmap não executáveis na v1#

RN-RULE-016: Vínculo por contrato#

RN-RULE-017: Vínculo por cliente#

RN-RULE-018: Precedência de vínculo#

RN-RULE-019: Unicidade de vínculo por contrato#

RN-RULE-014: Desativação de régua em uso#

RN-RULE-015: Exclusão lógica#

4. Padrão de Erros#

Códigos de erro específicos de réguas#

5. Endpoints#

POST /v2/companies/:companyId/portfolio/collection-rules#

GET /v2/companies/:companyId/portfolio/collection-rules#

GET /v2/companies/:companyId/portfolio/collection-rules/:collectionRuleId#

PATCH /v2/companies/:companyId/portfolio/collection-rules/:collectionRuleId#

PATCH /v2/companies/:companyId/portfolio/collection-rules/:collectionRuleId/status#

POST /v2/companies/:companyId/portfolio/collection-rules/:collectionRuleId/steps#

PATCH /v2/companies/:companyId/portfolio/collection-rules/:collectionRuleId/steps/:stepId#

DELETE /v2/companies/:companyId/portfolio/collection-rules/:collectionRuleId/steps/:stepId#

POST /v2/companies/:companyId/portfolio/collection-rules/:collectionRuleId/targets#

GET /v2/companies/:companyId/portfolio/collection-rules/:collectionRuleId/targets#

DELETE /v2/companies/:companyId/portfolio/collection-rules/:collectionRuleId/targets/:targetId#

GET /v2/companies/:companyId/portfolio/collection-rules/:collectionRuleId/executions#

6. Roadmap — Tipos de Ação Futuros#

Réguas de Cobrança — Regras de Negócio

1. Conceito

2. Estruturas de Dados

2.1. CollectionRule

2.2. CollectionStep

2.3. actionConfig por tipo de ação

`ACTIVITY` (v1 — implementado)

`EMAIL` (roadmap)

`SMS` (roadmap)

`CALL` (roadmap)

`NEGATIVATION` (roadmap)

`PROTEST` (roadmap)

2.4. CollectionRuleTarget (Vínculo da Régua)

2.5. CollectionStepExecution (Log de Execução)

3. Regras de Negócio

RN-RULE-001: Criação livre de réguas

RN-RULE-002: Nome único por empresa

RN-RULE-003: Atribuição ao contrato

RN-RULE-004: Etapas ordenadas e únicas

RN-RULE-005: Execução sequencial com intervalo de dias

RN-RULE-006: Condição de elegibilidade por título

RN-RULE-007: Etapa ignorada por pagamento

RN-RULE-008: Gatilho DAYS_BEFORE_DUE

RN-RULE-009: Gatilho ON_DUE_DATE

RN-RULE-010: Gatilho DAYS_AFTER_DUE

RN-RULE-011: Gatilho STATUS_CHANGE

RN-RULE-013: Ações de roadmap não executáveis na v1

RN-RULE-016: Vínculo por contrato

RN-RULE-017: Vínculo por cliente

RN-RULE-018: Precedência de vínculo

RN-RULE-019: Unicidade de vínculo por contrato

RN-RULE-014: Desativação de régua em uso

RN-RULE-015: Exclusão lógica

4. Padrão de Erros

Códigos de erro específicos de réguas

5. Endpoints

`POST /v2/companies/:companyId/portfolio/collection-rules`

`GET /v2/companies/:companyId/portfolio/collection-rules`

`GET /v2/companies/:companyId/portfolio/collection-rules/:collectionRuleId`

`PATCH /v2/companies/:companyId/portfolio/collection-rules/:collectionRuleId`

`PATCH /v2/companies/:companyId/portfolio/collection-rules/:collectionRuleId/status`

`POST /v2/companies/:companyId/portfolio/collection-rules/:collectionRuleId/steps`

`PATCH /v2/companies/:companyId/portfolio/collection-rules/:collectionRuleId/steps/:stepId`

`DELETE /v2/companies/:companyId/portfolio/collection-rules/:collectionRuleId/steps/:stepId`

`POST /v2/companies/:companyId/portfolio/collection-rules/:collectionRuleId/targets`

`GET /v2/companies/:companyId/portfolio/collection-rules/:collectionRuleId/targets`

`DELETE /v2/companies/:companyId/portfolio/collection-rules/:collectionRuleId/targets/:targetId`

`GET /v2/companies/:companyId/portfolio/collection-rules/:collectionRuleId/executions`

6. Roadmap — Tipos de Ação Futuros