Atendimento: Catálogo de Obrigações

Endpoints da WebApiAlcance para gerenciar o catálogo de obrigações - o cadastro de referência das obrigações acessórias/fiscais tratadas pelo Atendimento (ex.: DAS, DCTFWeb, EFD-Contribuições), cada uma classificada por departamento e sinalizando se está sujeita a multa. Cobrem criação, listagem (com filtro por departamento e paginação), detalhamento por ID, atualização parcial e exclusão.

Todos os endpoints exigem autenticação. Veja Autenticação para o fluxo de API Key. O Swagger oficial está em api.contabilidadealcance.com.br/docs.

Base path

/api/v1/catalogo-obrigacoes

A URL completa em produção é https://api.contabilidadealcance.com.br/api/v1/catalogo-obrigacoes.

Escopos necessários

catalogo_obrigacoes:read - listagem e detalhamento
catalogo_obrigacoes:write - criação, atualização e exclusão

O escopo é derivado da rota: o prefixo /catalogo-obrigacoes vira o recurso catalogo_obrigacoes (hífen → underscore), e o método HTTP define a ação (read para GET, write para POST/PUT/DELETE).

Endpoints

`POST /catalogo-obrigacoes/`

Cria um novo item do catálogo de obrigações. Os dados vão no corpo da requisição (CatalogoObrigacaoCreate).

Parâmetros

Este endpoint não recebe parâmetros de rota ou query - os dados vão no corpo da requisição (CatalogoObrigacaoCreate): nome (obrigatório), departamento (obrigatório) e tem_multa (opcional, default false).

Request

{
  "nome": "DAS - Simples Nacional",
  "departamento": "Fiscal",
  "tem_multa": true
}

Response 201 Created

{
  "success": true,
  "message": "Item do catálogo criado com sucesso",
  "data": {
    "id": 42,
    "nome": "DAS - Simples Nacional",
    "departamento": "Fiscal",
    "tem_multa": true,
    "legacy_uuid": null,
    "data_hora_criacao": "2026-07-03T09:15:00-03:00"
  }
}

Erros de validação retornam 422 Unprocessable Entity com detail descrevendo o problema.

Escopo: catalogo_obrigacoes:write

`GET /catalogo-obrigacoes/`

Lista os itens do catálogo. Aceita filtro opcional por departamento e paginação por limit/offset. Lista vazia é um estado válido - retorna 200 OK com data: [] e a mensagem "Nenhum item de catálogo encontrado.".

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`departamento`	`str`	query	não	Filtra pelo departamento. Default: sem filtro.
`limit`	`int`	query	não	Limite de itens por página. Default `100` (entre `1` e `500`).
`offset`	`int`	query	não	Offset de paginação. Default `0` (mínimo `0`).

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Catálogo recuperado com sucesso",
  "data": [
    {
      "id": 42,
      "nome": "DAS - Simples Nacional",
      "departamento": "Fiscal",
      "tem_multa": true,
      "legacy_uuid": null,
      "data_hora_criacao": "2026-07-03T09:15:00-03:00"
    }
  ]
}

Escopo: catalogo_obrigacoes:read

`GET /catalogo-obrigacoes/{catalogo_id}`

Detalha um item do catálogo pelo ID inteiro. Quando não encontrado, retorna 404 Not Found com detail descrevendo o item inexistente.

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`catalogo_id`	`int`	path	sim	ID interno do item do catálogo.

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Item do catálogo recuperado com sucesso",
  "data": {
    "id": 42,
    "nome": "DAS - Simples Nacional",
    "departamento": "Fiscal",
    "tem_multa": true,
    "legacy_uuid": null,
    "data_hora_criacao": "2026-07-03T09:15:00-03:00"
  }
}

Escopo: catalogo_obrigacoes:read

`PUT /catalogo-obrigacoes/{catalogo_id}`

Atualiza um item existente. O body é um CatalogoObrigacaoUpdate com campos parciais - somente o que vier preenchido é alterado.

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`catalogo_id`	`int`	path	sim	ID do item do catálogo.

Request (CatalogoObrigacaoUpdate - todos os campos opcionais)

{
  "departamento": "Contábil",
  "tem_multa": false
}

Response 200 OK

{
  "success": true,
  "message": "Item do catálogo atualizado com sucesso",
  "data": {
    "id": 42,
    "nome": "DAS - Simples Nacional",
    "departamento": "Contábil",
    "tem_multa": false,
    "legacy_uuid": null,
    "data_hora_criacao": "2026-07-03T09:15:00-03:00"
  }
}

Item inexistente retorna 404 Not Found; erros de validação retornam 422 Unprocessable Entity.

Escopo: catalogo_obrigacoes:write

`DELETE /catalogo-obrigacoes/{catalogo_id}`

Remove um item do catálogo pelo ID.

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`catalogo_id`	`int`	path	sim	ID do item do catálogo.

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Item do catálogo removido com sucesso",
  "data": null
}

Item inexistente retorna 404 Not Found.

Escopo: catalogo_obrigacoes:write

Schemas

`CatalogoObrigacaoCreate`

Campo	Tipo	Obrigatório	Observações
`nome`	`str`	sim	Nome da obrigação. Máximo de 200 caracteres.
`departamento`	`str`	sim	Departamento responsável pela obrigação. Máximo de 200 caracteres.
`tem_multa`	`bool`	não	Indica se a obrigação está sujeita a multa. Default `false`.

`CatalogoObrigacaoUpdate`

Todos os campos são opcionais; apenas os enviados são atualizados.

Campo	Tipo	Observações
`nome`	`str`	Novo nome da obrigação. Máximo de 200 caracteres.
`departamento`	`str`	Novo departamento. Máximo de 200 caracteres.
`tem_multa`	`bool`	Nova sinalização de sujeição a multa.

`CatalogoObrigacaoRead`

Campo	Tipo	Notas
`id`	`int`	Identificador do item do catálogo.
`nome`	`str`	Nome da obrigação.
`departamento`	`str`	Departamento responsável.
`tem_multa`	`bool`	Indica se a obrigação está sujeita a multa.
`legacy_uuid`	`str \| null`	Identificador de origem em sistema legado, quando aplicável.
`data_hora_criacao`	`datetime`	Timestamp de criação do registro.

Notas

Toda resposta segue o envelope { success, message, data } (ou { success: false, message, details } em erro).
GET /catalogo-obrigacoes/{catalogo_id} e o DELETE retornam 404 Not Found para IDs inexistentes; o PUT retorna 404 quando o item não existe e 422 para violações de validação.
Na listagem, limit é restrito ao intervalo de 1 a 500 (default 100) e offset tem mínimo 0 (default 0); valores fora do intervalo são rejeitados com 422.