Atendimento: Obrigação-Modelo

Endpoints da WebApiAlcance para gerenciar os vínculos obrigação-modelo - a associação entre uma obrigação (pelo nome e departamento) e um modelo de mensagem usado no atendimento. Cada vínculo define qual modelo de mensagem deve ser aplicado a uma determinada obrigação. Cobrem criação, listagem (com filtro opcional por modelo 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/obrigacao-modelo

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

Escopos necessários

obrigacao_modelo:read - listagem e detalhamento por ID
obrigacao_modelo:write - criação, atualização e exclusão

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

Endpoints

`POST /obrigacao-modelo/`

Cria um novo vínculo entre uma obrigação e um modelo de mensagem.

Parâmetros

Este endpoint não recebe parâmetros de rota ou query - os dados vão no corpo da requisição (ObrigacaoModeloCreate): obrigacao_nome (obrigatório), departamento (obrigatório) e modelo_id (obrigatório).

Request

{
  "obrigacao_nome": "DAS - Simples Nacional",
  "departamento": "Fiscal",
  "modelo_id": 7
}

Response 201 Created

{
  "success": true,
  "message": "Vínculo criado com sucesso",
  "data": {
    "id": 42,
    "obrigacao_nome": "DAS - Simples Nacional",
    "departamento": "Fiscal",
    "modelo_id": 7,
    "legacy_uuid": null,
    "data_hora_criacao": "2026-07-03T09:15:00-03:00"
  }
}

Em caso de dados inválidos, retorna 422 Unprocessable Entity com detail descrevendo o erro.

Escopo: obrigacao_modelo:write

`GET /obrigacao-modelo/`

Lista os vínculos obrigação-modelo cadastrados. Aceita filtro opcional por modelo e paginação. Lista vazia é um estado válido - sempre retorna 200 OK, inclusive com data: [] e a mensagem "Nenhum vínculo encontrado.".

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`modelo_id`	`int`	query	não	Filtra os vínculos por modelo de mensagem.
`limit`	`int`	query	não	Limite de itens por página. Default `100` (`1`-`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": "Vínculos recuperados com sucesso",
  "data": [
    {
      "id": 42,
      "obrigacao_nome": "DAS - Simples Nacional",
      "departamento": "Fiscal",
      "modelo_id": 7,
      "legacy_uuid": null,
      "data_hora_criacao": "2026-07-03T09:15:00-03:00"
    }
  ]
}

Escopo: obrigacao_modelo:read

`GET /obrigacao-modelo/{vinculo_id}`

Detalha um vínculo pelo ID inteiro. Quando não encontrado, retorna 404 Not Found com detail descrevendo o erro.

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`vinculo_id`	`int`	path	sim	ID interno do vínculo

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Vínculo recuperado com sucesso",
  "data": {
    "id": 42,
    "obrigacao_nome": "DAS - Simples Nacional",
    "departamento": "Fiscal",
    "modelo_id": 7,
    "legacy_uuid": null,
    "data_hora_criacao": "2026-07-03T09:15:00-03:00"
  }
}

Escopo: obrigacao_modelo:read

`PUT /obrigacao-modelo/{vinculo_id}`

Atualiza um vínculo existente. O body é um ObrigacaoModeloUpdate com campos parciais - somente o que vier preenchido é alterado.

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`vinculo_id`	`int`	path	sim	ID do vínculo

Request (ObrigacaoModeloUpdate - todos os campos opcionais)

{
  "departamento": "Contábil",
  "modelo_id": 9
}

Response 200 OK

{
  "success": true,
  "message": "Vínculo atualizado com sucesso",
  "data": {
    "id": 42,
    "obrigacao_nome": "DAS - Simples Nacional",
    "departamento": "Contábil",
    "modelo_id": 9,
    "legacy_uuid": null,
    "data_hora_criacao": "2026-07-03T09:15:00-03:00"
  }
}

Quando não encontrado, retorna 404 Not Found; para outros dados inválidos, 422 Unprocessable Entity.

Escopo: obrigacao_modelo:write

`DELETE /obrigacao-modelo/{vinculo_id}`

Remove um vínculo obrigação-modelo pelo ID. Quando não encontrado, retorna 404 Not Found.

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`vinculo_id`	`int`	path	sim	ID do vínculo

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Vínculo removido com sucesso",
  "data": null
}

Escopo: obrigacao_modelo:write

Schemas

`ObrigacaoModeloCreate`

Campo	Tipo	Obrigatório	Observações
`obrigacao_nome`	`str`	sim	Nome da obrigação. Máx. 255 caracteres.
`departamento`	`str`	sim	Departamento responsável pela obrigação. Máx. 200 caracteres.
`modelo_id`	`int`	sim	ID do modelo de mensagem associado à obrigação.

`ObrigacaoModeloUpdate`

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

Campo	Tipo	Observações
`obrigacao_nome`	`str`	Novo nome da obrigação. Máx. 255 caracteres.
`departamento`	`str`	Novo departamento. Máx. 200 caracteres.
`modelo_id`	`int`	Reassocia o vínculo a outro modelo de mensagem.

`ObrigacaoModeloRead`

Campo	Tipo	Notas
`id`	`int`	Identificador do vínculo.
`obrigacao_nome`	`str`	Nome da obrigação.
`departamento`	`str`	Departamento responsável.
`modelo_id`	`int`	Modelo de mensagem associado.
`legacy_uuid`	`str \| null`	UUID de origem legada, quando aplicável.
`data_hora_criacao`	`datetime`	Timestamp de criação do vínculo.

Notas

Toda resposta segue o envelope { success, message, data } (ou { success: false, message, details } em erro).
GET /obrigacao-modelo/ retorna sempre 200 OK, inclusive quando não há vínculos - nesse caso data: [] e message: "Nenhum vínculo encontrado.".
O filtro modelo_id e a paginação (limit/offset) aplicam-se apenas ao GET /obrigacao-modelo/.
Cada vínculo associa uma obrigação a um modelo de mensagem; o modelo_id referencia o modelo usado no atendimento.