NFS-e/Repasse: Referências Fiscais

Endpoints da WebApiAlcance para as referências fiscais do produto NFS-e/Repasse - os catálogos globais que alimentam os selects e as competências fiscais do emissor: CNAE, Sub-CNAE, CTISS, NBS, indicador de operação e classificação tributária. São dados de catálogo (sem dono nem tenant), servidos por um CRUD genérico parametrizado pelo tipo no path ({tipo}). Cobrem criação, listagem com filtros e paginação, detalhamento por ID, atualização e exclusão.

Base path

/api/v1/nfse-repasse/referencias-fiscais

Cada operação usa o segmento {tipo} para selecionar o catálogo. Valores válidos de {tipo}: cnae, sub-cnae, ctiss, nbs, indicador-operacao, classificacao-tributaria.

Escopos necessários

• nfse_repasse:read - listagem (com filtros) e detalhamento por ID
• nfse_repasse:write - criação, atualização e exclusão

O escopo é derivado do primeiro segmento da rota: /nfse-repasse/... vira o recurso nfse_repasse (hífen → underscore), e o método HTTP define a ação (read para GET, write para POST/PUT/DELETE). Como o produto compartilha esse primeiro segmento, o par nfse_repasse:read / nfse_repasse:write é comum a todos os recursos NFS-e/Repasse.

Endpoints

POST /nfse-repasse/referencias-fiscais/{tipo}

Cria uma nova referência fiscal do tipo indicado no path. Exige perfil administrador. Código duplicado retorna 409 Conflict (mensagem canônica "já existe").

Parâmetros

O corpo é um RefCreate: codigo e descricao (obrigatórios); ativo, ordenacao, municipio_codigo e uuid_legado (opcionais). O municipio_codigo só é persistido para ctiss (ignorado nos demais tipos).

Request

{
  "codigo": "8630-5/03",
  "descricao": "Atividade médica ambulatorial restrita a consultas",
  "ativo": true,
  "ordenacao": 10
}

Response 201 Created

{
  "success": true,
  "message": "Referência fiscal criada com sucesso!",
  "data": {
    "id": 1,
    "codigo": "8630-5/03",
    "descricao": "Atividade médica ambulatorial restrita a consultas",
    "ativo": true,
    "ordenacao": 10,
    "municipio_codigo": null,
    "uuid_legado": null,
    "created_at": "2026-07-03T12:00:00Z",
    "updated_at": "2026-07-03T12:00:00Z"
  }
}

Escopo: nfse_repasse:write

GET /nfse-repasse/referencias-fiscais/{tipo}

Lista as referências de um tipo (catálogo global), com filtros opcionais e paginação. Lista vazia é um estado válido - retorna 200 OK com data: [].

Parâmetros

Exemplo: GET /api/v1/nfse-repasse/referencias-fiscais/cnae?ativo=true&busca=consulta&page=1&per_page=50.

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Referências fiscais recuperadas com sucesso!",
  "data": [
    {
      "id": 1,
      "codigo": "8630-5/03",
      "descricao": "Atividade médica ambulatorial restrita a consultas",
      "ativo": true,
      "ordenacao": 10,
      "municipio_codigo": null,
      "uuid_legado": null,
      "created_at": "2026-07-03T12:00:00Z",
      "updated_at": "2026-07-03T12:00:00Z"
    }
  ]
}

Escopo: nfse_repasse:read

GET /nfse-repasse/referencias-fiscais/{tipo}/{ref_id}

Detalha uma referência pelo ID inteiro, dentro do tipo indicado. Quando não encontrado, retorna 404 Not Found.

Parâmetros

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Referência fiscal encontrada!",
  "data": {
    "id": 1,
    "codigo": "8630-5/03",
    "descricao": "Atividade médica ambulatorial restrita a consultas",
    "ativo": true,
    "ordenacao": 10,
    "municipio_codigo": null,
    "uuid_legado": null,
    "created_at": "2026-07-03T12:00:00Z",
    "updated_at": "2026-07-03T12:00:00Z"
  }
}

Escopo: nfse_repasse:read

PUT /nfse-repasse/referencias-fiscais/{tipo}/{ref_id}

Atualiza uma referência existente. Exige perfil administrador. O corpo é um RefUpdate com campos parciais - somente o que vier preenchido é alterado. id, uuid_legado, created_at e updated_at são imutáveis.

Parâmetros

O corpo é um RefUpdate (todos os campos opcionais): codigo, descricao, ativo, ordenacao e/ou municipio_codigo.

Request

{
  "descricao": "Atividade médica ambulatorial - consultas",
  "ativo": false
}

Response 200 OK

{
  "success": true,
  "message": "Referência fiscal atualizada!",
  "data": {
    "id": 1,
    "codigo": "8630-5/03",
    "descricao": "Atividade médica ambulatorial - consultas",
    "ativo": false,
    "ordenacao": 10,
    "municipio_codigo": null,
    "uuid_legado": null,
    "created_at": "2026-07-03T12:00:00Z",
    "updated_at": "2026-07-03T13:20:00Z"
  }
}

Escopo: nfse_repasse:write

DELETE /nfse-repasse/referencias-fiscais/{tipo}/{ref_id}

Remove uma referência fiscal pelo ID, dentro do tipo indicado. Exige perfil administrador.

Parâmetros

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Referência fiscal removida!",
  "data": null
}

Escopo: nfse_repasse:write

Schemas

RefCreate

RefUpdate

Todos os campos são opcionais; apenas os enviados são atualizados. id, uuid_legado, created_at e updated_at não aparecem aqui (bloqueio de mass-assignment).

RefRead

Notas

• Toda resposta segue o envelope { success, message, data } (ou { success: false, message, details } em erro).
• Os seis tipos (cnae, sub-cnae, ctiss, nbs, indicador-operacao, classificacao-tributaria) compartilham a mesma forma de dados e são atendidos pelo mesmo CRUD genérico - muda apenas o segmento {tipo} do path.
• As referências são dados globais de catálogo: não têm dono nem tenant.
• Como {tipo} é um enum de valores fechados, o FastAPI não confunde a coleção (/{tipo}) com o item (/{tipo}/{ref_id}); ainda assim, as rotas são declaradas na ordem coleção → item por consistência.
• municipio_codigo faz parte do schema comum, mas só é persistido na tabela CTISS (ignorado nos demais tipos).
• uuid_legado é metadado de migração: aceito no Create para correlação com a origem, mas imutável depois (não aparece no Update).