Smart: Divergência Contábeis (Fornecedor)

Endpoints da WebApiAlcance para as divergências contábeis de fornecedor exportadas do produto Smart. Cada registro compara o valor pago a um fornecedor (ipg_valor) com o valor efetivamente contabilizado (valor_contabilizado) para o mesmo documento, com os nomes de campo preservando a nomenclatura da planilha de origem. É um CRUD simples: listagem paginada com filtro opcional por CNPJ, busca 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-divergencia-contabeis-fornecedor

Escopos necessários

smart_divergencia_contabeis_fornecedor:read - listagem e busca por ID
smart_divergencia_contabeis_fornecedor:write - criação, atualização e exclusão

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

Endpoints

`GET /smart-divergencia-contabeis-fornecedor/`

Lista as divergências contábeis de fornecedor, com filtro opcional por CNPJ e paginação.

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`cnpj`	`string`	query	não	Filtra por CNPJ do cliente.
`limit`	`int`	query	não	Itens por página. `1..500`. Default `100`.
`offset`	`int`	query	não	Offset de paginação. `>= 0`. Default `0`.

Request

Sem corpo de requisição.

Response 200 OK

{
  "status": "success",
  "message": "Divergências contábeis de fornecedor recuperadas com sucesso",
  "data": [
    {
      "id": 701,
      "cnpj": "12345678000199",
      "cfg_emp": "01 - HOSPITAL EXEMPLO",
      "cpg_serie": "1",
      "cpg_num": 5521,
      "ipg_valor": 8000.0,
      "data_emissao": "2026-04-01T00:00:00",
      "cpg_credor": "FORNECEDOR EXEMPLO LTDA",
      "ind": "PART",
      "gcc_descr": "FORNECEDORES DIVERSOS",
      "bcp_dthr": "2026-04-05T10:00:00",
      "valor_contabilizado": 7950.0,
      "data_contabil": "2026-04-05T00:00:00",
      "indicador": "AV",
      "data_hora_criacao": "2026-04-06T08:00:00"
    }
  ]
}

Se nenhum registro casar com o filtro, data volta [] com 200 OK e message: "Nenhuma divergência contábil de fornecedor encontrada.".

Escopo: smart_divergencia_contabeis_fornecedor:read

`GET /smart-divergencia-contabeis-fornecedor/{smart_divergencia_id}`

Busca uma divergência contábil de fornecedor pelo ID.

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`smart_divergencia_id`	`int`	path	sim	ID da divergência contábil de fornecedor.

Request

Sem corpo de requisição.

Response 200 OK

{
  "status": "success",
  "message": "Divergência contábil de fornecedor recuperada com sucesso",
  "data": {
    "id": 701,
    "cnpj": "12345678000199",
    "cfg_emp": "01 - HOSPITAL EXEMPLO",
    "cpg_serie": "1",
    "cpg_num": 5521,
    "ipg_valor": 8000.0,
    "data_emissao": "2026-04-01T00:00:00",
    "cpg_credor": "FORNECEDOR EXEMPLO LTDA",
    "ind": "PART",
    "gcc_descr": "FORNECEDORES DIVERSOS",
    "bcp_dthr": "2026-04-05T10:00:00",
    "valor_contabilizado": 7950.0,
    "data_contabil": "2026-04-05T00:00:00",
    "indicador": "AV",
    "data_hora_criacao": "2026-04-06T08:00:00"
  }
}

Quando o ID não existe, responde {"message": "Divergência contábil de fornecedor não encontrada."} com 404 Not Found.

Escopo: smart_divergencia_contabeis_fornecedor:read

`POST /smart-divergencia-contabeis-fornecedor/`

Cria uma nova divergência contábil de fornecedor.

Parâmetros

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

Request

{
  "cnpj": "12345678000199",
  "cfg_emp": "01 - HOSPITAL EXEMPLO",
  "cpg_serie": "1",
  "cpg_num": 5521,
  "ipg_valor": 8000.0,
  "data_emissao": "2026-04-01T00:00:00",
  "cpg_credor": "FORNECEDOR EXEMPLO LTDA",
  "ind": "PART",
  "gcc_descr": "FORNECEDORES DIVERSOS",
  "bcp_dthr": "2026-04-05T10:00:00",
  "valor_contabilizado": 7950.0,
  "data_contabil": "2026-04-05T00:00:00",
  "indicador": "AV"
}

Response 201 Created

{
  "status": "success",
  "message": "Divergência contábil de fornecedor criada com sucesso",
  "data": {
    "id": 701,
    "cnpj": "12345678000199",
    "cfg_emp": "01 - HOSPITAL EXEMPLO",
    "cpg_serie": "1",
    "cpg_num": 5521,
    "ipg_valor": 8000.0,
    "data_emissao": "2026-04-01T00:00:00",
    "cpg_credor": "FORNECEDOR EXEMPLO LTDA",
    "ind": "PART",
    "gcc_descr": "FORNECEDORES DIVERSOS",
    "bcp_dthr": "2026-04-05T10:00:00",
    "valor_contabilizado": 7950.0,
    "data_contabil": "2026-04-05T00:00:00",
    "indicador": "AV",
    "data_hora_criacao": "2026-04-06T08:00:00"
  }
}

Escopo: smart_divergencia_contabeis_fornecedor:write

`PUT /smart-divergencia-contabeis-fornecedor/{smart_divergencia_id}`

Atualiza uma divergência contábil de fornecedor (update parcial - cnpj não pode ser alterado por esta rota).

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`smart_divergencia_id`	`int`	path	sim	ID da divergência contábil de fornecedor.

O corpo é um SmartDivergenciaContabeisFornecedorUpdate.

Request

{ "valor_contabilizado": 8000.0 }

Response 200 OK

{
  "status": "success",
  "message": "Divergência contábil de fornecedor atualizada com sucesso",
  "data": {
    "id": 701,
    "cnpj": "12345678000199",
    "cfg_emp": "01 - HOSPITAL EXEMPLO",
    "cpg_serie": "1",
    "cpg_num": 5521,
    "ipg_valor": 8000.0,
    "data_emissao": "2026-04-01T00:00:00",
    "cpg_credor": "FORNECEDOR EXEMPLO LTDA",
    "ind": "PART",
    "gcc_descr": "FORNECEDORES DIVERSOS",
    "bcp_dthr": "2026-04-05T10:00:00",
    "valor_contabilizado": 8000.0,
    "data_contabil": "2026-04-05T00:00:00",
    "indicador": "AV",
    "data_hora_criacao": "2026-04-06T08:00:00"
  }
}

Quando o ID não existe, responde {"message": "Divergência contábil de fornecedor não encontrada."} com 404 Not Found.

Escopo: smart_divergencia_contabeis_fornecedor:write

`DELETE /smart-divergencia-contabeis-fornecedor/{smart_divergencia_id}`

Remove uma divergência contábil de fornecedor.

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`smart_divergencia_id`	`int`	path	sim	ID da divergência contábil de fornecedor.

Request

Sem corpo de requisição.

Response 200 OK

{
  "status": "success",
  "message": "Divergência contábil de fornecedor removida com sucesso",
  "data": null
}

Quando o ID não existe, responde {"message": "Divergência contábil de fornecedor não encontrada."} com 404 Not Found.

Escopo: smart_divergencia_contabeis_fornecedor:write

Schemas

`SmartDivergenciaContabeisFornecedorCreate`

Corpo do POST. Todos os campos são opcionais no envio (schema não exige nenhum obrigatório).

Campo	Tipo	Observações
`cnpj`	`string`	Máx. 30 caracteres. CNPJ/CPF do cliente.
`cfg_emp`	`string`	Máx. 300 caracteres. Identificação da empresa na origem.
`cpg_serie`	`string`	Máx. 20 caracteres. Série do documento de pagamento.
`cpg_num`	`int`	Número do documento de pagamento.
`ipg_valor`	`float`	Valor da parcela paga ao fornecedor.
`data_emissao`	`datetime`	Data de emissão do documento.
`cpg_credor`	`string`	Máx. 300 caracteres. Nome do fornecedor/credor.
`ind`	`string`	Máx. 100 caracteres. Indicador/classificador de origem.
`gcc_descr`	`string`	Máx. 300 caracteres. Descrição do grupo/conta contábil de origem.
`bcp_dthr`	`datetime`	Data/hora do lançamento contábil comparado.
`valor_contabilizado`	`float`	Valor efetivamente contabilizado para o documento.
`data_contabil`	`datetime`	Data da contabilização.
`indicador`	`string`	Máx. 100 caracteres. Indicador adicional de origem.

`SmartDivergenciaContabeisFornecedorUpdate`

Corpo do PUT. Mesmos campos de SmartDivergenciaContabeisFornecedorCreate, exceto cnpj (o dono do registro não pode ser trocado por update).

`SmartDivergenciaContabeisFornecedorRead`

Retorno de leitura. Estende SmartDivergenciaContabeisFornecedorCreate com id e data_hora_criacao.

Campo	Tipo	Observações
`id`	`int`	Identificador do registro.
`data_hora_criacao`	`datetime`	Data/hora de criação do registro.
(demais campos)	-	Todos os campos de `SmartDivergenciaContabeisFornecedorCreate`.

Notas

Sucesso segue o envelope { status: "success", message, data }. Erros levantados como HTTPException (404, 500) respondem { message } com o código HTTP correspondente.
ipg_valor e valor_contabilizado são armazenados como DECIMAL(15,2) no banco, mas o schema os expõe como float; o valor trafega como número JSON de ponto flutuante.
?cnpj= vazio ou sem dígitos é tratado como "sem filtro" (não gera WHERE cnpj = '').
GET /smart-divergencia-contabeis-fornecedor/ sempre retorna 200 OK; lista vazia é estado normal.