Smart: Receita de NF Emitidas

Endpoints da WebApiAlcance para o CRUD de receitas de notas fiscais emitidas consumido pelo produto Smart. Cada registro representa a nota fiscal (lote) emitida por uma empresa, com a composição da receita bruta (consultas, exames, outros) e os tributos retidos até o valor líquido. Os endpoints cobrem listagem com filtro por CNPJ e paginação, consulta por ID, criação, atualização 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.

Campos monetários saem como string

Os campos monetários deste domínio são Decimal no schema (não float), para preservar a precisão do valor gravado no banco. O Pydantic serializa Decimal como string em JSON: por exemplo, "bruto": "3000.00", não "bruto": 3000.0. Faça a conversão explícita (Number(...)/parseFloat) no consumidor.

Base path

/api/v1/smart-receita-nf-emitidas

Escopos necessários

smart_receita_nf_emitidas:read - listagem e consulta por ID
smart_receita_nf_emitidas:write - criação, atualização e exclusão

O escopo é derivado do prefixo público da rota: /smart-receita-nf-emitidas vira o recurso smart_receita_nf_emitidas (hífen → underscore), e o método HTTP define a ação (read para GET, write para POST/PUT/PATCH/DELETE).

Endpoints

`GET /smart-receita-nf-emitidas/`

Lista as receitas de notas fiscais emitidas, com filtro opcional por CNPJ e paginação. Lista vazia é um estado válido - o retorno normal é 200 OK com data: [], não um erro.

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`cnpj`	`str`	query	não	Filtra os registros pelo CNPJ informado.
`limit`	`int`	query	não	Itens por página. Entre 1 e 500. Padrão `100`.
`offset`	`int`	query	não	Deslocamento de paginação. Padrão `0`.

Request

Sem corpo de requisição.

Response 200 OK

{
  "status": "success",
  "message": "Receitas de notas fiscais emitidas recuperadas com sucesso",
  "data": [
    {
      "id": 3301,
      "cnpj": "12345678000199",
      "cfg_emp": "HOSP01",
      "gcc_cod": "01",
      "gcc_descr": "RECEITA MEDICA",
      "emp_raz_soc": "ACME SERVICOS MEDICOS LTDA",
      "emp_cgc": "12345678000199",
      "nfl_serie": "1",
      "nfl_num": 8890,
      "nfl_dt_emissao": "2026-01-10T00:00:00",
      "consultas": "1200.00",
      "exames": "1500.00",
      "outros": "300.00",
      "bruto": "3000.00",
      "juros": "0.00",
      "desconto": "50.00",
      "iss": "150.00",
      "csll": "30.00",
      "pis": "19.50",
      "cofins": "90.00",
      "irrf": "45.00",
      "outros_imp": "0.00",
      "liquido": "2615.50",
      "ind_diferenca": 0,
      "data_hora_criacao": "2026-01-15T10:00:00"
    }
  ]
}

Escopo: smart_receita_nf_emitidas:read

`GET /smart-receita-nf-emitidas/{smart_receita_nf_id}`

Busca uma receita de nota fiscal emitida pelo ID.

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`smart_receita_nf_id`	`int`	path	sim	ID da receita de nota fiscal emitida.

Request

Sem corpo de requisição.

Response 200 OK

{
  "status": "success",
  "message": "Receita de nota fiscal emitida recuperada com sucesso",
  "data": {
    "id": 3301,
    "cnpj": "12345678000199",
    "bruto": "3000.00",
    "liquido": "2615.50",
    "...": "demais campos como em SmartReceitaNfEmitidasRead"
  }
}

Quando o ID não existe, retorna 404 Not Found com {"message": "Receita de nota fiscal emitida não encontrada."}. Escopo: smart_receita_nf_emitidas:read

`POST /smart-receita-nf-emitidas/`

Cria uma nova receita de nota fiscal emitida.

Parâmetros

Este endpoint não recebe parâmetros de rota ou query. O corpo é o schema SmartReceitaNfEmitidasCreate.

Request

{
  "cnpj": "12.345.678/0001-99",
  "cfg_emp": "HOSP01",
  "gcc_cod": "01",
  "gcc_descr": "RECEITA MEDICA",
  "emp_raz_soc": "ACME SERVICOS MEDICOS LTDA",
  "emp_cgc": "12345678000199",
  "nfl_serie": "1",
  "nfl_num": 8890,
  "nfl_dt_emissao": "2026-01-10T00:00:00",
  "consultas": 1200.00,
  "exames": 1500.00,
  "outros": 300.00,
  "bruto": 3000.00,
  "juros": 0.00,
  "desconto": 50.00,
  "iss": 150.00,
  "csll": 30.00,
  "pis": 19.50,
  "cofins": 90.00,
  "irrf": 45.00,
  "outros_imp": 0.00,
  "liquido": 2615.50,
  "ind_diferenca": 0
}

Response 201 Created

{
  "status": "success",
  "message": "Receita de nota fiscal emitida criada com sucesso",
  "data": {
    "id": 3301,
    "cnpj": "12345678000199",
    "bruto": "3000.00",
    "...": "demais campos como em SmartReceitaNfEmitidasRead"
  }
}

Em falha inesperada ao persistir, retorna 500 Internal Server Error com {"message": "Não foi possível criar a receita de nota fiscal emitida."}. Escopo: smart_receita_nf_emitidas:write

`PUT /smart-receita-nf-emitidas/{smart_receita_nf_id}`

Atualiza uma receita de nota fiscal emitida existente. O cnpj não é editável por este endpoint - o schema de atualização não o inclui.

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`smart_receita_nf_id`	`int`	path	sim	ID da receita de nota fiscal emitida.

O corpo é o schema SmartReceitaNfEmitidasUpdate, com todos os campos opcionais.

Request

{
  "desconto": 75.00,
  "liquido": 2590.50
}

Response 200 OK

{
  "status": "success",
  "message": "Receita de nota fiscal emitida atualizada com sucesso",
  "data": {
    "id": 3301,
    "cnpj": "12345678000199",
    "desconto": "75.00",
    "liquido": "2590.50",
    "...": "demais campos como em SmartReceitaNfEmitidasRead"
  }
}

Quando o ID não existe, retorna 404 Not Found com {"message": "Receita de nota fiscal emitida não encontrada."}. Escopo: smart_receita_nf_emitidas:write

`DELETE /smart-receita-nf-emitidas/{smart_receita_nf_id}`

Remove uma receita de nota fiscal emitida.

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`smart_receita_nf_id`	`int`	path	sim	ID da receita de nota fiscal emitida.

Request

Sem corpo de requisição.

Response 200 OK

{
  "status": "success",
  "message": "Receita de nota fiscal emitida removida com sucesso",
  "data": null
}

Quando o ID não existe, retorna 404 Not Found com {"message": "Receita de nota fiscal emitida não encontrada."}. Escopo: smart_receita_nf_emitidas:write

Schemas

`SmartReceitaNfEmitidasCreate`

Corpo do POST /smart-receita-nf-emitidas/. Todos os campos são opcionais no schema (nenhum é obrigatório para o Pydantic aceitar o payload), mas cnpj é a chave prática de identificação do cliente. Os campos monetários são Decimal.

Campo	Tipo	Observações
`cnpj`	`str`	Máx. 30 caracteres.
`cfg_emp`	`str`	Máx. 300 caracteres. Código/config da empresa de origem.
`gcc_cod`	`str`	Máx. 20 caracteres. Código do grupo/centro de custo.
`gcc_descr`	`str`	Máx. 300 caracteres. Descrição do grupo/centro de custo.
`emp_raz_soc`	`str`	Máx. 300 caracteres. Razão social da empresa.
`emp_cgc`	`str`	Máx. 30 caracteres. CNPJ da empresa emissora.
`nfl_serie`	`str`	Máx. 20 caracteres. Série da nota fiscal (lote).
`nfl_num`	`int`	Número da nota fiscal (lote).
`nfl_dt_emissao`	`datetime`	Data/hora de emissão da nota.
`consultas`	`Decimal`	Valor referente a consultas.
`exames`	`Decimal`	Valor referente a exames.
`outros`	`Decimal`	Valor referente a outros itens.
`bruto`	`Decimal`	Valor bruto total da nota.
`juros`	`Decimal`	Valor de juros.
`desconto`	`Decimal`	Valor do desconto aplicado.
`iss`	`Decimal`	Valor de ISS retido.
`csll`	`Decimal`	Valor de CSLL retido.
`pis`	`Decimal`	Valor de PIS retido.
`cofins`	`Decimal`	Valor de COFINS retido.
`irrf`	`Decimal`	Valor de IRRF retido.
`outros_imp`	`Decimal`	Valor de outros impostos retidos.
`liquido`	`Decimal`	Valor líquido (bruto menos descontos e tributos).
`ind_diferenca`	`int`	Indicador de diferença/divergência de conferência.

`SmartReceitaNfEmitidasUpdate`

Corpo do PUT /smart-receita-nf-emitidas/{smart_receita_nf_id}. Mesmos campos de SmartReceitaNfEmitidasCreate, exceto cnpj - trocar o CNPJ dono do registro não é permitido por este endpoint. Todos os campos são opcionais.

`SmartReceitaNfEmitidasRead`

Retornado nas listagens e nas respostas de criação/atualização. Estende SmartReceitaNfEmitidasCreate com:

Campo	Tipo	Notas
`id`	`int`	Identificador do registro.
`data_hora_criacao`	`datetime`	Data/hora de criação do registro.

Notas

Toda resposta segue o envelope { status: "success", message, data }.
Os campos monetários (consultas, exames, outros, bruto, juros, desconto, iss, csll, pis, cofins, irrf, outros_imp, liquido) são Decimal e trafegam como string em JSON, tanto na entrada (aceita número ou string) quanto na saída (sempre string).
Erros de negócio manualmente sinalizados pela rota (404 Not Found, 500 Internal Server Error) seguem o formato { "message": "..." } - não usam o campo detail.
Erros de validação de schema (tipo/formato inválido no payload) seguem o padrão do FastAPI: 422 Unprocessable Entity com { "detail": [...] }.
GET /smart-receita-nf-emitidas/ sempre retorna 200 OK; lista vazia (data: []) é estado normal, não um erro.
O filtro ?cnpj= aceita o CNPJ com ou sem máscara; internamente é normalizado antes da consulta.