Smart: Receita de Faturamento

Endpoints da WebApiAlcance para o CRUD de receitas de faturamento consumido pelo produto Smart. Cada registro representa uma nota fiscal de serviço (NFS-e) faturada a um convênio, com o valor bruto, descontos e a composição entre medicamentos, serviços e outros itens. 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.

Base path

/api/v1/smart-receita-faturamento

Escopos necessários

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

O escopo é derivado do prefixo público da rota: /smart-receita-faturamento vira o recurso smart_receita_faturamento (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-faturamento/`

Lista as receitas de faturamento, 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 faturamento recuperadas com sucesso",
  "data": [
    {
      "id": 901,
      "cnpj": "12345678000199",
      "cfg_emp": "HOSP01",
      "cnv_cod": "UNI01",
      "cnv_nome": "UNIMED REGIONAL",
      "nfs_serie": "1",
      "nfs_numero": 4521,
      "nfs_tipo": "NFSE",
      "nfs_valor": 3200.0,
      "desconto": 50.0,
      "nfs_dt_emis": "2026-01-10T00:00:00",
      "v_vlr_honorario": 2100.0,
      "indicador_1": "N",
      "indicador_2": null,
      "medicamentos": 600.0,
      "servicos": 2500.0,
      "outros": 100.0,
      "desconto_externo": 0.0,
      "data_hora_criacao": "2026-01-15T10:00:00"
    }
  ]
}

Escopo: smart_receita_faturamento:read

`GET /smart-receita-faturamento/{smart_receita_id}`

Busca uma receita de faturamento pelo ID.

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`smart_receita_id`	`int`	path	sim	ID da receita de faturamento.

Request

Sem corpo de requisição.

Response 200 OK

{
  "status": "success",
  "message": "Receita de faturamento recuperada com sucesso",
  "data": {
    "id": 901,
    "cnpj": "12345678000199",
    "cfg_emp": "HOSP01",
    "cnv_cod": "UNI01",
    "cnv_nome": "UNIMED REGIONAL",
    "nfs_serie": "1",
    "nfs_numero": 4521,
    "nfs_tipo": "NFSE",
    "nfs_valor": 3200.0,
    "desconto": 50.0,
    "nfs_dt_emis": "2026-01-10T00:00:00",
    "v_vlr_honorario": 2100.0,
    "indicador_1": "N",
    "indicador_2": null,
    "medicamentos": 600.0,
    "servicos": 2500.0,
    "outros": 100.0,
    "desconto_externo": 0.0,
    "data_hora_criacao": "2026-01-15T10:00:00"
  }
}

Quando o ID não existe, retorna 404 Not Found com {"message": "Receita de faturamento não encontrada."}. Escopo: smart_receita_faturamento:read

`POST /smart-receita-faturamento/`

Cria uma nova receita de faturamento.

Parâmetros

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

Request

{
  "cnpj": "12.345.678/0001-99",
  "cfg_emp": "HOSP01",
  "cnv_cod": "UNI01",
  "cnv_nome": "UNIMED REGIONAL",
  "nfs_serie": "1",
  "nfs_numero": 4521,
  "nfs_tipo": "NFSE",
  "nfs_valor": 3200.0,
  "desconto": 50.0,
  "nfs_dt_emis": "2026-01-10T00:00:00",
  "v_vlr_honorario": 2100.0,
  "indicador_1": "N",
  "medicamentos": 600.0,
  "servicos": 2500.0,
  "outros": 100.0,
  "desconto_externo": 0.0
}

Response 201 Created

{
  "status": "success",
  "message": "Receita de faturamento criada com sucesso",
  "data": {
    "id": 901,
    "cnpj": "12345678000199",
    "...": "demais campos como em SmartReceitaFaturamentoRead"
  }
}

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

`PUT /smart-receita-faturamento/{smart_receita_id}`

Atualiza uma receita de faturamento 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_id`	`int`	path	sim	ID da receita de faturamento.

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

Request

{
  "nfs_valor": 3250.0,
  "desconto": 75.0
}

Response 200 OK

{
  "status": "success",
  "message": "Receita de faturamento atualizada com sucesso",
  "data": {
    "id": 901,
    "cnpj": "12345678000199",
    "nfs_valor": 3250.0,
    "desconto": 75.0,
    "...": "demais campos como em SmartReceitaFaturamentoRead"
  }
}

Quando o ID não existe, retorna 404 Not Found com {"message": "Receita de faturamento não encontrada."}. Escopo: smart_receita_faturamento:write

`DELETE /smart-receita-faturamento/{smart_receita_id}`

Remove uma receita de faturamento.

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`smart_receita_id`	`int`	path	sim	ID da receita de faturamento.

Request

Sem corpo de requisição.

Response 200 OK

{
  "status": "success",
  "message": "Receita de faturamento removida com sucesso",
  "data": null
}

Quando o ID não existe, retorna 404 Not Found com {"message": "Receita de faturamento não encontrada."}. Escopo: smart_receita_faturamento:write

Schemas

`SmartReceitaFaturamentoCreate`

Corpo do POST /smart-receita-faturamento/. 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.

Campo	Tipo	Observações
`cnpj`	`str`	Máx. 30 caracteres.
`cfg_emp`	`str`	Máx. 300 caracteres. Código/config da empresa de origem.
`cnv_cod`	`str`	Máx. 20 caracteres. Código do convênio.
`cnv_nome`	`str`	Máx. 300 caracteres. Nome do convênio.
`nfs_serie`	`str`	Máx. 20 caracteres. Série da NFS-e.
`nfs_numero`	`int`	Número da NFS-e.
`nfs_tipo`	`str`	Máx. 20 caracteres. Tipo da NFS-e.
`nfs_valor`	`float`	Valor total da NFS-e.
`desconto`	`float`	Valor do desconto aplicado.
`nfs_dt_emis`	`datetime`	Data/hora de emissão da NFS-e.
`v_vlr_honorario`	`float`	Valor de honorário associado à nota.
`indicador_1`	`str`	Máx. 100 caracteres. Indicador auxiliar de classificação.
`indicador_2`	`str`	Máx. 100 caracteres. Segundo indicador auxiliar.
`medicamentos`	`float`	Parcela do valor referente a medicamentos.
`servicos`	`float`	Parcela do valor referente a serviços.
`outros`	`float`	Parcela do valor referente a outros itens.
`desconto_externo`	`float`	Desconto aplicado por fonte externa (convênio).

`SmartReceitaFaturamentoUpdate`

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

`SmartReceitaFaturamentoRead`

Retornado nas listagens e nas respostas de criação/atualização. Estende SmartReceitaFaturamentoCreate 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 }.
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-faturamento/ 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.