Smart: Recebimento de Convênio

Endpoints da WebApiAlcance para o CRUD de recebimentos de convênio consumido pelo produto Smart. Cada registro representa um lançamento de recebimento vinculado a uma nota fiscal de serviço (NFS-e) e a uma mensalidade de convênio médico, com os tributos retidos na operação (PIS, IRRF, ISS, COFINS, CSLL). 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-recebimento-convenio

Escopos necessários

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

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

Endpoints

`GET /smart-recebimento-convenio/`

Lista os recebimentos de convênio, 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": "Recebimentos de convênio recuperados com sucesso",
  "data": [
    {
      "id": 501,
      "cnpj": "12345678000199",
      "cfg_emp": "HOSP01",
      "nfs_serie": "1",
      "nfs_numero": 4521,
      "nfs_tipo": "NFSE",
      "mns_serie": 3,
      "mns_num": 8890,
      "mns_vlr": 1250.5,
      "ano_nfe": 2026,
      "pis": 8.13,
      "irrf": 15.0,
      "iss": 31.25,
      "cofins": 37.5,
      "csll": 12.5,
      "outros": 0.0,
      "convenio": "UNIMED REGIONAL",
      "cnv_cod": "UNI01",
      "v_nfl_emissao": "2026-01-10T00:00:00",
      "v_nfx_numero": "4521",
      "v_nfl_valor": 1250.5,
      "gcc_descr": "CONVENIOS MEDICOS",
      "indicador": "N",
      "indicador_2": null,
      "tipo": "RECEBIMENTO",
      "valor_tipo": 1250.5,
      "smm_tpcod": "01",
      "nfe_reapresentacao": null,
      "mns_tipo": "MENSAL",
      "data_hora_criacao": "2026-01-15T10:00:00"
    }
  ]
}

Escopo: smart_recebimento_convenio:read

`GET /smart-recebimento-convenio/{smart_recebimento_id}`

Busca um recebimento de convênio pelo ID.

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`smart_recebimento_id`	`int`	path	sim	ID do recebimento de convênio.

Request

Sem corpo de requisição.

Response 200 OK

{
  "status": "success",
  "message": "Recebimento de convênio recuperado com sucesso",
  "data": {
    "id": 501,
    "cnpj": "12345678000199",
    "cfg_emp": "HOSP01",
    "nfs_serie": "1",
    "nfs_numero": 4521,
    "nfs_tipo": "NFSE",
    "mns_serie": 3,
    "mns_num": 8890,
    "mns_vlr": 1250.5,
    "ano_nfe": 2026,
    "pis": 8.13,
    "irrf": 15.0,
    "iss": 31.25,
    "cofins": 37.5,
    "csll": 12.5,
    "outros": 0.0,
    "convenio": "UNIMED REGIONAL",
    "cnv_cod": "UNI01",
    "v_nfl_emissao": "2026-01-10T00:00:00",
    "v_nfx_numero": "4521",
    "v_nfl_valor": 1250.5,
    "gcc_descr": "CONVENIOS MEDICOS",
    "indicador": "N",
    "indicador_2": null,
    "tipo": "RECEBIMENTO",
    "valor_tipo": 1250.5,
    "smm_tpcod": "01",
    "nfe_reapresentacao": null,
    "mns_tipo": "MENSAL",
    "data_hora_criacao": "2026-01-15T10:00:00"
  }
}

Quando o ID não existe, retorna 404 Not Found com {"message": "Recebimento de convênio não encontrado."}. Escopo: smart_recebimento_convenio:read

`POST /smart-recebimento-convenio/`

Cria um novo recebimento de convênio.

Parâmetros

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

Request

{
  "cnpj": "12.345.678/0001-99",
  "cfg_emp": "HOSP01",
  "nfs_serie": "1",
  "nfs_numero": 4521,
  "nfs_tipo": "NFSE",
  "mns_serie": 3,
  "mns_num": 8890,
  "mns_vlr": 1250.5,
  "ano_nfe": 2026,
  "pis": 8.13,
  "irrf": 15.0,
  "iss": 31.25,
  "cofins": 37.5,
  "csll": 12.5,
  "outros": 0.0,
  "convenio": "UNIMED REGIONAL",
  "cnv_cod": "UNI01",
  "v_nfl_emissao": "2026-01-10T00:00:00",
  "v_nfx_numero": "4521",
  "v_nfl_valor": 1250.5,
  "gcc_descr": "CONVENIOS MEDICOS",
  "indicador": "N",
  "tipo": "RECEBIMENTO",
  "valor_tipo": 1250.5,
  "smm_tpcod": "01",
  "mns_tipo": "MENSAL"
}

Response 201 Created

{
  "status": "success",
  "message": "Recebimento de convênio criado com sucesso",
  "data": {
    "id": 501,
    "cnpj": "12345678000199",
    "...": "demais campos como em SmartRecebimentoConvenioRead"
  }
}

Em falha inesperada ao persistir, retorna 500 Internal Server Error com {"message": "Não foi possível criar o recebimento de convênio."}. Escopo: smart_recebimento_convenio:write

`PUT /smart-recebimento-convenio/{smart_recebimento_id}`

Atualiza um recebimento de convênio 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_recebimento_id`	`int`	path	sim	ID do recebimento de convênio.

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

Request

{
  "mns_vlr": 1300.0,
  "outros": 25.0
}

Response 200 OK

{
  "status": "success",
  "message": "Recebimento de convênio atualizado com sucesso",
  "data": {
    "id": 501,
    "cnpj": "12345678000199",
    "mns_vlr": 1300.0,
    "outros": 25.0,
    "...": "demais campos como em SmartRecebimentoConvenioRead"
  }
}

Quando o ID não existe, retorna 404 Not Found com {"message": "Recebimento de convênio não encontrado."}. Escopo: smart_recebimento_convenio:write

`DELETE /smart-recebimento-convenio/{smart_recebimento_id}`

Remove um recebimento de convênio.

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`smart_recebimento_id`	`int`	path	sim	ID do recebimento de convênio.

Request

Sem corpo de requisição.

Response 200 OK

{
  "status": "success",
  "message": "Recebimento de convênio removido com sucesso",
  "data": null
}

Quando o ID não existe, retorna 404 Not Found com {"message": "Recebimento de convênio não encontrado."}. Escopo: smart_recebimento_convenio:write

Schemas

`SmartRecebimentoConvenioCreate`

Corpo do POST /smart-recebimento-convenio/. 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.
`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.
`mns_serie`	`int`	Série da mensalidade.
`mns_num`	`int`	Número da mensalidade.
`mns_vlr`	`float`	Valor da mensalidade.
`ano_nfe`	`int`	Ano de referência da NF-e.
`pis`	`float`	Valor de PIS retido.
`irrf`	`float`	Valor de IRRF retido.
`iss`	`float`	Valor de ISS retido.
`cofins`	`float`	Valor de COFINS retido.
`csll`	`float`	Valor de CSLL retido.
`outros`	`float`	Outros valores/descontos.
`convenio`	`str`	Máx. 300 caracteres. Nome do convênio.
`cnv_cod`	`str`	Máx. 20 caracteres. Código do convênio.
`v_nfl_emissao`	`datetime`	Data/hora de emissão da nota do lote.
`v_nfx_numero`	`str`	Máx. 20 caracteres. Número da nota (referência externa).
`v_nfl_valor`	`float`	Valor da nota fiscal do lote.
`gcc_descr`	`str`	Máx. 300 caracteres. Descrição do grupo/centro de custo.
`indicador`	`str`	Máx. 300 caracteres. Indicador auxiliar de classificação.
`indicador_2`	`str`	Máx. 300 caracteres. Segundo indicador auxiliar.
`tipo`	`str`	Máx. 100 caracteres. Tipo do registro/lançamento.
`valor_tipo`	`float`	Valor associado ao campo `tipo`.
`smm_tpcod`	`str`	Máx. 20 caracteres. Código do tipo de mensalidade.
`nfe_reapresentacao`	`str`	Máx. 20 caracteres. Indicador de reapresentação da NF-e.
`mns_tipo`	`str`	Máx. 20 caracteres. Tipo de mensalidade.

`SmartRecebimentoConvenioUpdate`

Corpo do PUT /smart-recebimento-convenio/{smart_recebimento_id}. Mesmos campos de SmartRecebimentoConvenioCreate, exceto cnpj - trocar o CNPJ dono do registro não é permitido por este endpoint. Todos os campos são opcionais.

`SmartRecebimentoConvenioRead`

Retornado nas listagens e nas respostas de criação/atualização. Estende SmartRecebimentoConvenioCreate 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-recebimento-convenio/ 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.