NFS-e Importada

Endpoints da WebApiAlcance para gerenciar NFS-e importadas - notas fiscais de serviço trazidas de planilhas (XLSX) ou lançadas manualmente, com seus valores de serviços e retenções fiscais (PIS, COFINS, ISS, IRRF, CSLL, INSS). Cobrem criação individual, importação em lote idempotente (upsert), listagem por cliente e por usuário (com filtro de competência), busca por ID, atualização parcial, exclusão individual e exclusão em lote por competência (limpar e reimportar).

Base path

/api/v1/nfse-importada

Escopos necessários

• nfse_importada:read - listagem por cliente, listagem por usuário e busca por ID
• nfse_importada:write - criação individual, importação em lote, atualização, exclusão individual e exclusão em lote

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

Endpoints

POST /nfse-importada/

Cria uma NFS-e individual, usada para registro manual. O cliente dono da NFS-e é definido por id_customer, e o id_usuario_created vem do usuário autenticado (não é aceito no corpo).

Parâmetros

Este endpoint não recebe parâmetros de rota ou query - os dados vão no corpo da requisição (NfseImportadaCreate). Obrigatórios: id_customer, cnpj_prestador, numero_nfse, data_emissao, mes_apuracao.

Request

{
  "id_customer": 1,
  "cnpj_prestador": "12345678000199",
  "cnpj_tomador": "98765432000188",
  "numero_nfse": "2026-000123",
  "data_emissao": "2026-05-15",
  "mes_apuracao": "2026-05",
  "valor_servicos": "1500.00",
  "valor_pis": "9.75",
  "valor_cofins": "45.00",
  "valor_iss": "75.00",
  "valor_irrf": "22.50",
  "valor_csll": "15.00",
  "origem": "manual"
}

Response 201 Created

{
  "success": true,
  "message": "NFS-e criada com sucesso!",
  "data": {
    "id": 1,
    "id_customer": 1,
    "cnpj_prestador": "12345678000199",
    "cnpj_tomador": "98765432000188",
    "numero_nfse": "2026-000123",
    "data_emissao": "2026-05-15",
    "mes_apuracao": "2026-05",
    "valor_servicos": "1500.00",
    "valor_pis": "9.75",
    "valor_cofins": "45.00",
    "valor_iss": "75.00",
    "valor_irrf": "22.50",
    "valor_csll": "15.00",
    "valor_inss": "0.00",
    "origem": "manual",
    "dados_brutos": null,
    "id_usuario_created": 42,
    "created_at": "2026-05-16T10:00:00",
    "updated_at": "2026-05-16T10:00:00"
  }
}

Escopo: nfse_importada:write

POST /nfse-importada/bulk

Importação em lote idempotente (upsert). Recebe uma lista de NFS-e em JSON e faz upsert pela constraint UNIQUE (id_customer, cnpj_prestador, numero_nfse, data_emissao): inexistente cria (criadas++), existente idêntica ignora (ignoradas++) e existente com valores diferentes atualiza (atualizadas++). Erros individuais não abortam o lote - são reportados no array errors com o índice do item no payload.

Parâmetros

Este endpoint não recebe parâmetros de rota ou query - o corpo é um NfseImportadaBulkCreate, objeto com items (lista de NfseImportadaCreate, mínimo 1 e máximo 500 itens por chamada; limite defensivo contra DoS).

Request

{
  "items": [
    {
      "id_customer": 1,
      "cnpj_prestador": "12345678000199",
      "numero_nfse": "2026-000123",
      "data_emissao": "2026-05-15",
      "mes_apuracao": "2026-05",
      "valor_servicos": "1500.00"
    }
  ]
}

Response 200 OK

{
  "success": true,
  "message": "Importação processada.",
  "data": {
    "criadas": 12,
    "atualizadas": 3,
    "ignoradas": 5,
    "errors": [
      {
        "index": 7,
        "numero_nfse": "2026-000130",
        "motivo": "cnpj_prestador inválido (deve ter 14 dígitos)."
      }
    ]
  }
}

Escopo: nfse_importada:write

GET /nfse-importada/by-customer/{customer_id}

Lista as NFS-e de um cliente, com filtro opcional de competência e paginação. Lista vazia é um estado válido - retorna 200 OK com data: [] e a mensagem "Nenhuma NFS-e encontrada.".

Parâmetros

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "NFS-e recuperadas com sucesso!",
  "data": [
    {
      "id": 1,
      "id_customer": 1,
      "cnpj_prestador": "12345678000199",
      "cnpj_tomador": "98765432000188",
      "numero_nfse": "2026-000123",
      "data_emissao": "2026-05-15",
      "mes_apuracao": "2026-05",
      "valor_servicos": "1500.00",
      "valor_pis": "9.75",
      "valor_cofins": "45.00",
      "valor_iss": "75.00",
      "valor_irrf": "22.50",
      "valor_csll": "15.00",
      "valor_inss": "0.00",
      "origem": "import",
      "dados_brutos": null,
      "id_usuario_created": 42,
      "created_at": "2026-05-16T10:00:00",
      "updated_at": "2026-05-16T10:00:00"
    }
  ]
}

Escopo: nfse_importada:read

GET /nfse-importada/by-user

Lista todas as NFS-e do usuário autenticado (consolidação geral, multi-tenant), com filtro opcional de competência. Lista vazia retorna 200 OK com data: [] e a mensagem "Nenhuma NFS-e encontrada.".

Parâmetros

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "NFS-e recuperadas com sucesso!",
  "data": [
    {
      "id": 1,
      "id_customer": 1,
      "cnpj_prestador": "12345678000199",
      "cnpj_tomador": "98765432000188",
      "numero_nfse": "2026-000123",
      "data_emissao": "2026-05-15",
      "mes_apuracao": "2026-05",
      "valor_servicos": "1500.00",
      "valor_pis": "9.75",
      "valor_cofins": "45.00",
      "valor_iss": "75.00",
      "valor_irrf": "22.50",
      "valor_csll": "15.00",
      "valor_inss": "0.00",
      "origem": "import",
      "dados_brutos": null,
      "id_usuario_created": 42,
      "created_at": "2026-05-16T10:00:00",
      "updated_at": "2026-05-16T10:00:00"
    }
  ]
}

Escopo: nfse_importada:read

DELETE /nfse-importada/by-customer/{customer_id}/competencia/{mes_apuracao}

Exclusão em lote - remove todas as NFS-e de um cliente em uma competência. Usado quando o front quer "limpar e reimportar". O mes_apuracao no path deve seguir o formato YYYY-MM (validado na rota; formato inválido retorna 422).

Parâmetros

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "NFS-e removidas em lote.",
  "data": { "removidas": 17 }
}

Escopo: nfse_importada:write

GET /nfse-importada/{nfse_id}

Busca uma NFS-e importada pelo ID inteiro. Quando não encontrada, retorna 404 Not Found.

Parâmetros

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "NFS-e encontrada!",
  "data": {
    "id": 1,
    "id_customer": 1,
    "cnpj_prestador": "12345678000199",
    "cnpj_tomador": "98765432000188",
    "numero_nfse": "2026-000123",
    "data_emissao": "2026-05-15",
    "mes_apuracao": "2026-05",
    "valor_servicos": "1500.00",
    "valor_pis": "9.75",
    "valor_cofins": "45.00",
    "valor_iss": "75.00",
    "valor_irrf": "22.50",
    "valor_csll": "15.00",
    "valor_inss": "0.00",
    "origem": "manual",
    "dados_brutos": null,
    "id_usuario_created": 42,
    "created_at": "2026-05-16T10:00:00",
    "updated_at": "2026-05-16T10:00:00"
  }
}

Escopo: nfse_importada:read

PUT /nfse-importada/{nfse_id}

Atualiza uma NFS-e existente. O corpo é um NfseImportadaUpdate com campos parciais - somente o que vier preenchido é alterado. Campos imutáveis (id_customer, id_usuario_created, id, created_at, updated_at) não são aceitos aqui, para bloquear mass-assignment.

Parâmetros

Request (NfseImportadaUpdate - todos os campos opcionais)

{
  "valor_servicos": "1800.00",
  "valor_iss": "90.00"
}

Response 200 OK

{
  "success": true,
  "message": "NFS-e atualizada!",
  "data": {
    "id": 1,
    "id_customer": 1,
    "cnpj_prestador": "12345678000199",
    "cnpj_tomador": "98765432000188",
    "numero_nfse": "2026-000123",
    "data_emissao": "2026-05-15",
    "mes_apuracao": "2026-05",
    "valor_servicos": "1800.00",
    "valor_pis": "9.75",
    "valor_cofins": "45.00",
    "valor_iss": "90.00",
    "valor_irrf": "22.50",
    "valor_csll": "15.00",
    "valor_inss": "0.00",
    "origem": "manual",
    "dados_brutos": null,
    "id_usuario_created": 42,
    "created_at": "2026-05-16T10:00:00",
    "updated_at": "2026-05-16T11:42:00"
  }
}

Escopo: nfse_importada:write

DELETE /nfse-importada/{nfse_id}

Remove uma NFS-e importada pelo ID.

Parâmetros

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "NFS-e removida!",
  "data": null
}

Escopo: nfse_importada:write

Schemas

NfseImportadaBase / NfseImportadaCreate

Campos compartilhados entre criação e leitura. NfseImportadaCreate é idêntico ao NfseImportadaBase (também usado como item do bulk import). Valores monetários são Decimal (2 casas), nunca negativos.

NfseImportadaUpdate

Todos os campos são opcionais; apenas os enviados (exclude_unset) são atualizados. Não inclui id_customer nem campos gerenciados (bloqueio de mass-assignment). Mesmas regras de validação do Base (CNPJ com 14 dígitos, valores ≥ 0, origem ∈ manual, dados_brutos ≤ 16 KiB).

NfseImportadaRead

Estende o NfseImportadaBase com os campos gerenciados (server-side).

(mais todos os campos de NfseImportadaBase.)

NfseImportadaBulkCreate

Payload do endpoint POST /nfse-importada/bulk.

NfseImportadaBulkResult

Resultado consolidado do bulk import (retornado em data).

NfseImportadaBulkError

Detalhe de um item que falhou no bulk import.

Notas

• Toda resposta segue o envelope { success, message, data } (ou { success: false, message, details } em erro).
• Não há upload multipart nem task Celery neste domínio. O parsing do XLSX ocorre no cliente/front-end; a WebApi recebe as linhas já normalizadas em JSON via POST /nfse-importada/bulk, que é síncrono e idempotente.

• Chave de idempotência (UNIQUE): (id_customer, cnpj_prestador, numero_nfse, data_emissao). Por isso CNPJs são normalizados a 14 dígitos antes de qualquer validação - evita que dois formatos do mesmo CNPJ virem dois registros.
• Mapeamento de erros do service para HTTP: "não encontrada" → 404, "já existe" → 409, "acesso negado" → 403, demais → 422.
• Relaciona-se com Customers - id_customer referencia o cliente dono da NFS-e.