Compliance API - Documentação para Backend

Base URL

{API_BASE_URL}/compliance-flows

Modelos de Dados

ComplianceFlow

json

{
  "id": "string (UUID)",
  "name": "string",
  "description": "string | null",
  "status": "draft | active | archived",
  "steps": [ComplianceStep],
  "attachedProviders": [AttachedProvider],
  "providersCount": "number",
  "createdAt": "ISO 8601 datetime",
  "updatedAt": "ISO 8601 datetime"
}

ComplianceStep

json

{
  "id": "string (UUID)",
  "title": "string",
  "order": "number (1-based)",
  "stepType": "documents | platformData",
  "schedule": {
    "frequency": "weekly | biweekly | monthly | quarterly | custom",
    "dayStart": "number (1-31)",
    "dayEnd": "number (1-31)",
    "monthStart": "number (1-12) | null",
    "monthEnd": "number (1-12) | null"
  },
  "documents": [ComplianceDocumentRequirement],
  "platformDataTypes": ["string"],
  "validators": [ComplianceValidator],
  "dependsOnPrevious": "boolean",
  "includeImmediateLeadership": "boolean",
  "onlyImmediateLeadershipRequired": "boolean",
  "allValidatorsRequired": "boolean"
}

stepType: Define o tipo da etapa.
documents: Prestador deve enviar documentos obrigatórios (campo documents preenchido, platformDataTypes vazio)
platformData: Prestador compartilha acesso a dados da plataforma (campo platformDataTypes preenchido, documents vazio)
platformDataTypes aceita: hours, activeContracts

ComplianceDocumentRequirement

json

{
  "id": "string (UUID)",
  "name": "string",
  "description": "string | null",
  "required": "boolean",
  "formats": ["string"]
}

formats aceita: .pdf, .png, .jpg, .jpeg, .doc, .docx, .xls, .xlsx

ComplianceValidator

json

{
  "id": "string (UUID)",
  "userId": "string (UUID - referência ao User)",
  "name": "string",
  "avatar": "string (URL) | null"
}

AttachedProvider

json

{
  "id": "string (UUID)",
  "providerId": "string (UUID)",
  "name": "string",
  "document": "string (CNPJ formatado)",
  "contractId": "string (UUID)",
  "contractName": "string",
  "attachedAt": "ISO 8601 datetime"
}

AvailableProvider

json

{
  "id": "string (UUID - provider company ID)",
  "name": "string",
  "document": "string (CNPJ)",
  "contractId": "string (UUID)",
  "contractName": "string",
  "avatar": "string (URL) | null"
}

Endpoints

1. Listar Fluxos de Compliance

GET /compliance-flows

Query Parameters:

Param	Tipo	Obrigatório	Descrição
`search`	string	Não	Busca por nome (case-insensitive)
`status`	string	Não	Filtro por status (draft/active/archived/all)

Response: 200 OK

json

{
  "data": [ComplianceFlow],
  "total": "number"
}

Notas:

Ordenar por updatedAt DESC
status=all ou omitido retorna todos
A busca é por name com ILIKE/case-insensitive

2. Obter Fluxo por ID

GET /compliance-flows/:id

Path Parameters:

Param	Tipo	Descrição
`id`	string	UUID do fluxo

Response: 200 OK

json

{
  "data": ComplianceFlow
}

Response: 404 Not Found. Fluxo não encontrado

3. Criar Fluxo de Compliance

POST /compliance-flows

Request Body:

json

{
  "name": "string (obrigatório)",
  "description": "string | null",
  "steps": [
    {
      "title": "string (obrigatório)",
      "order": "number",
      "stepType": "documents | platformData (obrigatório)",
      "schedule": {
        "frequency": "string (obrigatório)",
        "dayStart": "number (obrigatório)",
        "dayEnd": "number (obrigatório)",
        "monthStart": "number | null",
        "monthEnd": "number | null"
      },
      "documents": [
        {
          "name": "string (obrigatório)",
          "description": "string | null",
          "required": "boolean",
          "formats": ["string"]
        }
      ],
      "platformDataTypes": ["string"],
      "validators": [
        {
          "userId": "string (UUID do user, obrigatório)",
          "name": "string",
          "avatar": "string | null"
        }
      ],
      "dependsOnPrevious": "boolean (default: false)",
      "includeImmediateLeadership": "boolean (default: false)",
      "onlyImmediateLeadershipRequired": "boolean (default: false)",
      "allValidatorsRequired": "boolean (default: false)"
    }
  ]
}

Notas:

O backend gera os IDs para o fluxo, steps, documents e validators
status inicial é sempre draft
attachedProviders inicializa vazio
order dos steps deve ser recalculado sequencialmente (1, 2, 3...)
Validar que dayStart e dayEnd estão entre 1 e 31
Validar que frequency é um valor válido
Validar que stepType é documents ou platformData
Quando stepType = documents: documents pode ter itens, platformDataTypes deve ser []
Quando stepType = platformData: platformDataTypes pode ter itens, documents deve ser []
Valores válidos para platformDataTypes: hours, activeContracts

Response: 201 Created

json

{
  "data": ComplianceFlow
}

4. Atualizar Fluxo de Compliance

PUT /compliance-flows/:id

Path Parameters:

Param	Tipo	Descrição
`id`	string	UUID do fluxo

Request Body (todos opcionais):

json

{
  "name": "string",
  "description": "string | null",
  "status": "draft | active | archived",
  "steps": [ComplianceStep]
}

Notas:

Quando steps é enviado, substitui TODAS as etapas (full replace)
Steps com id existente são atualizados; sem id são criados (backend gera)
Steps que existiam mas não estão no array são removidos
order é recalculado sequencialmente
Atualiza updatedAt
Reordenação: Quando steps contém apenas [{ "id": "...", "order": N }] (sem demais campos), o backend deve apenas atualizar a ordem dos steps existentes sem modificar seus dados

Response: 200 OK

json

{
  "data": ComplianceFlow
}

Response: 404 Not Found. Fluxo não encontrado

5. Excluir Fluxo de Compliance

DELETE /compliance-flows/:id

Path Parameters:

Param	Tipo	Descrição
`id`	string	UUID do fluxo

Notas:

Remove o fluxo e todas as associações (steps, providers)
Considerar soft delete se necessário

Response: 204 No Content

Response: 404 Not Found. Fluxo não encontrado

6. Anexar Prestadores ao Fluxo

POST /compliance-flows/:id/providers

Path Parameters:

Param	Tipo	Descrição
`id`	string	UUID do fluxo

Request Body:

json

{
  "providerIds": ["string (UUID)"]
}

Notas:

providerIds é lista de IDs de empresas prestadoras com contratos ativos
Ignorar IDs já anexados (idempotente)
Para cada provider, buscar o contrato ativo e popular contractId e contractName
Atualizar providersCount e updatedAt

Response: 200 OK

json

{
  "data": ComplianceFlow
}

Response: 404 Not Found. Fluxo não encontrado

7. Remover Prestador do Fluxo

DELETE /compliance-flows/:flowId/providers/:providerId

Path Parameters:

Param	Tipo	Descrição
`flowId`	string	UUID do fluxo
`providerId`	string	UUID do provider (empresa)

Notas:

Remove o vínculo do prestador com o fluxo
Atualizar providersCount e updatedAt

Response: 204 No Content

Response: 404 Not Found. Fluxo ou prestador não encontrado

8. Listar Prestadores Disponíveis

GET /compliance-flows/:id/available-providers

Path Parameters:

Param	Tipo	Descrição
`id`	string	UUID do fluxo

Query Parameters:

Param	Tipo	Obrigatório	Descrição
`search`	string	Não	Busca por nome ou CNPJ

Notas:

Retorna prestadores com contratos ativos da empresa do tomador
Exclui prestadores já anexados ao fluxo
Busca case-insensitive por nome e documento

Response: 200 OK

json

{
  "data": [AvailableProvider],
  "total": "number"
}

9. Anexar Fluxos de Compliance em Lote

POST /providers/compliance-flows

Cria múltiplas associações prestador → fluxo de compliance em uma única chamada. Permite atribuir o mesmo fluxo para vários prestadores ou fluxos diferentes por prestador em uma única requisição.

Request Body:

json

{
  "attachments": [
    {
      "providerId": "string (UUID)",
      "complianceFlowId": "string (UUID)"
    }
  ]
}

Notas:

attachments não pode ser vazio
Cada providerId deve ser um prestador com contrato ativo no tomador autenticado
Cada complianceFlowId deve existir e estar com status active no tomador
Pares providerId + complianceFlowId já existentes são ignorados silenciosamente (idempotente)
Operação não é transacional por par: validações acontecem antes de qualquer insert; se os dados são válidos, apenas os pares realmente novos são criados

Response: 201 Created

json

{
  "data": [ProviderComplianceFlow]
}

Retorna todos os ProviderComplianceFlow correspondentes aos pares enviados (incluindo os que já existiam antes da chamada), para que o cliente possa atualizar seu estado sem nova leitura.

Erros:

404 Not Found com mensagem Prestadores não encontrados: <ids> se algum provider não existir/estiver ativo para o tomador
404 Not Found com mensagem Fluxos de compliance não encontrados ou inativos: <ids> se algum fluxo não estiver disponível
400 Bad Request se attachments estiver vazio ou os UUIDs forem inválidos

Regras de Negócio

Permissões: Apenas usuários com role borrower podem acessar esses endpoints
Escopo: Todos os endpoints são escopados pela empresa do tomador (via header X-Company-Id ou JWT)
Validadores: São users da empresa do tomador (role borrower ou user), não prestadores
Prestadores disponíveis: Apenas prestadores com pelo menos um contrato ativo com o tomador
Frequências de schedule:
- weekly: Repete toda semana (dayStart = dia da semana 1-7, ou dia do mês)
- biweekly: Repete a cada 2 semanas
- monthly: Repete todo mês nos dias indicados
- quarterly: Repete a cada trimestre (monthStart/monthEnd definem quais meses)
- custom: Configuração livre com monthStart/monthEnd
Dependência entre etapas: Quando dependsOnPrevious = true, o prestador só pode enviar documentos desta etapa após a etapa anterior estar aprovada/completa
Status transitions: draft → active → archived (uma vez arquivado, não volta)
Tipo da etapa: Cada step tem um stepType que define seu comportamento:
- documents: Etapa de envio de documentos. O prestador faz upload de arquivos nos formatos aceitos
- platformData: Etapa de compartilhamento de dados. O prestador concede acesso de leitura aos dados selecionados (ex: horas trabalhadas, contratos ativos)
Validação de liderança:
- includeImmediateLeadership: Inclui a liderança imediata do prestador como validador
- onlyImmediateLeadershipRequired: Apenas a liderança imediata é obrigatória (requer includeImmediateLeadership = true)
- allValidatorsRequired: Todos os validadores são obrigatórios (quando true, força onlyImmediateLeadershipRequired = true)

Headers Necessários

Authorization: Bearer {token}
X-Company-Id: {companyId}
Content-Type: application/json

Códigos de Erro

Código	Descrição
400	Validação falhou (campos obrigatórios)
401	Não autenticado
403	Sem permissão (role incorreto)
404	Recurso não encontrado
422	Dados inválidos
500	Erro interno do servidor

Compliance API - Documentação para Backend ​

Base URL ​

Modelos de Dados ​

ComplianceFlow ​

ComplianceStep ​

ComplianceDocumentRequirement ​

ComplianceValidator ​

AttachedProvider ​

AvailableProvider ​

Endpoints ​

1. Listar Fluxos de Compliance ​

2. Obter Fluxo por ID ​

3. Criar Fluxo de Compliance ​

4. Atualizar Fluxo de Compliance ​

5. Excluir Fluxo de Compliance ​

6. Anexar Prestadores ao Fluxo ​

7. Remover Prestador do Fluxo ​

8. Listar Prestadores Disponíveis ​

9. Anexar Fluxos de Compliance em Lote ​

Regras de Negócio ​

Headers Necessários ​

Códigos de Erro ​

Compliance API - Documentação para Backend

Base URL

Modelos de Dados

ComplianceFlow

ComplianceStep

ComplianceDocumentRequirement

ComplianceValidator

AttachedProvider

AvailableProvider

Endpoints

1. Listar Fluxos de Compliance

2. Obter Fluxo por ID

3. Criar Fluxo de Compliance

4. Atualizar Fluxo de Compliance

5. Excluir Fluxo de Compliance

6. Anexar Prestadores ao Fluxo

7. Remover Prestador do Fluxo

8. Listar Prestadores Disponíveis

9. Anexar Fluxos de Compliance em Lote

Regras de Negócio

Headers Necessários

Códigos de Erro