Adiantamento Fornecedor

Endpoints da WebApiAlcance para o controle de adiantamentos a fornecedores - registros de pagamentos antecipados a credores, importados do Klingo ERP. Cobrem criação, listagem geral com filtros e paginação, listagem por CNPJ do cliente, detalhamento por ID, atualização parcial 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/adiantamento-fornecedor

Escopos necessários

adiantamento_fornecedor:read - listagem, listagem por CNPJ e detalhamento
adiantamento_fornecedor:write - criação, atualização e exclusão

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

Endpoints

`POST /adiantamento-fornecedor/`

Cria um novo registro de adiantamento de fornecedor. Os dados são originados do Klingo ERP e importados na WebApi.

Parâmetros

Este endpoint não recebe parâmetros de rota ou query - os dados vão no corpo da requisição (AdiantamentoFornecedorCreate). Todos os campos são opcionais.

Request

{
  "cnpj_cliente": "12345678000199",
  "cfg_emp": "ALCANCE MATRIZ",
  "cpg_serie": "1",
  "cpg_num": "1050",
  "bcp_dthr": "2026-06-01T00:00:00",
  "consumo": "150.00",
  "adiantamento": "500.00",
  "cpg_credor": "FORNECEDOR EXEMPLO LTDA",
  "tipo": "ADIANTAMENTO",
  "saldo": "350.00",
  "grupo": "A",
  "valor_usado_individual": "150.00"
}

Response 201 Created

{
  "success": true,
  "message": "Adiantamento de fornecedor criado com sucesso",
  "data": {
    "id": 42,
    "cnpj_cliente": "12345678000199",
    "cfg_emp": "ALCANCE MATRIZ",
    "cpg_serie": "1",
    "cpg_num": "1050",
    "bcp_dthr": "2026-06-01T00:00:00",
    "consumo": "150.00",
    "adiantamento": "500.00",
    "cpg_credor": "FORNECEDOR EXEMPLO LTDA",
    "tipo": "ADIANTAMENTO",
    "saldo": "350.00",
    "grupo": "A",
    "valor_usado_individual": "150.00",
    "data_upload": "2026-06-02T09:30:00"
  }
}

Dados inválidos retornam 422 Unprocessable Entity. Escopo: adiantamento_fornecedor:write

`GET /adiantamento-fornecedor/`

Lista os adiantamentos de fornecedores cadastrados, com filtros opcionais e paginação. Lista vazia é um estado válido - sempre retorna 200 OK, inclusive com data: [] e a mensagem "Nenhum adiantamento de fornecedor encontrado.".

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`cnpj_cliente`	`str`	query	não	Filtra por CNPJ do cliente.
`tipo`	`str`	query	não	Filtra por tipo.
`grupo`	`str`	query	não	Filtra por grupo.
`limit`	`int`	query	não	Itens por página. Default `100`, faixa `1..500`.
`offset`	`int`	query	não	Offset de paginação. Default `0`, mínimo `0`.

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Adiantamentos de fornecedor recuperados com sucesso",
  "data": [
    {
      "id": 42,
      "cnpj_cliente": "12345678000199",
      "cfg_emp": "ALCANCE MATRIZ",
      "cpg_serie": "1",
      "cpg_num": "1050",
      "bcp_dthr": "2026-06-01T00:00:00",
      "consumo": "150.00",
      "adiantamento": "500.00",
      "cpg_credor": "FORNECEDOR EXEMPLO LTDA",
      "tipo": "ADIANTAMENTO",
      "saldo": "350.00",
      "grupo": "A",
      "valor_usado_individual": "150.00",
      "data_upload": "2026-06-02T09:30:00"
    }
  ]
}

Escopo: adiantamento_fornecedor:read

`GET /adiantamento-fornecedor/cliente/{cnpj_cliente}`

Lista todos os adiantamentos de um cliente específico pelo CNPJ, com paginação. Quando o cliente não tem adiantamentos, retorna 200 OK com data: [].

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`cnpj_cliente`	`str`	path	sim	CNPJ do cliente.
`limit`	`int`	query	não	Itens por página. Default `100`, faixa `1..500`.
`offset`	`int`	query	não	Offset de paginação. Default `0`, mínimo `0`.

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Adiantamentos de fornecedor recuperados com sucesso",
  "data": [
    {
      "id": 42,
      "cnpj_cliente": "12345678000199",
      "cfg_emp": "ALCANCE MATRIZ",
      "cpg_serie": "1",
      "cpg_num": "1050",
      "bcp_dthr": "2026-06-01T00:00:00",
      "consumo": "150.00",
      "adiantamento": "500.00",
      "cpg_credor": "FORNECEDOR EXEMPLO LTDA",
      "tipo": "ADIANTAMENTO",
      "saldo": "350.00",
      "grupo": "A",
      "valor_usado_individual": "150.00",
      "data_upload": "2026-06-02T09:30:00"
    }
  ]
}

Escopo: adiantamento_fornecedor:read

`GET /adiantamento-fornecedor/{adiantamento_id}`

Detalha um adiantamento pelo ID inteiro. Quando não encontrado, retorna 404 Not Found.

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`adiantamento_id`	`int`	path	sim	ID interno do registro

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Adiantamento de fornecedor recuperado com sucesso",
  "data": {
    "id": 42,
    "cnpj_cliente": "12345678000199",
    "cfg_emp": "ALCANCE MATRIZ",
    "cpg_serie": "1",
    "cpg_num": "1050",
    "bcp_dthr": "2026-06-01T00:00:00",
    "consumo": "150.00",
    "adiantamento": "500.00",
    "cpg_credor": "FORNECEDOR EXEMPLO LTDA",
    "tipo": "ADIANTAMENTO",
    "saldo": "350.00",
    "grupo": "A",
    "valor_usado_individual": "150.00",
    "data_upload": "2026-06-02T09:30:00"
  }
}

Escopo: adiantamento_fornecedor:read

`PUT /adiantamento-fornecedor/{adiantamento_id}`

Atualiza um adiantamento existente. O body é um AdiantamentoFornecedorUpdate com campos parciais - somente o que vier preenchido é alterado. O campo cnpj_cliente não pode ser alterado por este endpoint (proteção contra mass-assignment).

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`adiantamento_id`	`int`	path	sim	ID do registro

Request (AdiantamentoFornecedorUpdate - todos os campos opcionais)

{
  "consumo": "300.00",
  "saldo": "200.00",
  "valor_usado_individual": "300.00"
}

Response 200 OK

{
  "success": true,
  "message": "Adiantamento de fornecedor atualizado com sucesso",
  "data": {
    "id": 42,
    "cnpj_cliente": "12345678000199",
    "cfg_emp": "ALCANCE MATRIZ",
    "cpg_serie": "1",
    "cpg_num": "1050",
    "bcp_dthr": "2026-06-01T00:00:00",
    "consumo": "300.00",
    "adiantamento": "500.00",
    "cpg_credor": "FORNECEDOR EXEMPLO LTDA",
    "tipo": "ADIANTAMENTO",
    "saldo": "200.00",
    "grupo": "A",
    "valor_usado_individual": "300.00",
    "data_upload": "2026-06-02T09:30:00"
  }
}

Quando não encontrado, retorna 404 Not Found; dados inválidos retornam 422 Unprocessable Entity. Escopo: adiantamento_fornecedor:write

`DELETE /adiantamento-fornecedor/{adiantamento_id}`

Remove um adiantamento de fornecedor pelo ID. Quando não encontrado, retorna 404 Not Found.

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`adiantamento_id`	`int`	path	sim	ID do registro

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Adiantamento de fornecedor removido com sucesso",
  "data": null
}

Escopo: adiantamento_fornecedor:write

Schemas

`AdiantamentoFornecedorCreate`

Herda todos os campos de AdiantamentoFornecedorBase. Todos os campos são opcionais.

Campo	Tipo	Obrigatório	Observações
`cnpj_cliente`	`str`	não	CNPJ do cliente. Máx. 30 caracteres.
`cfg_emp`	`str`	não	Configuração/empresa. Máx. 300 caracteres.
`cpg_serie`	`str`	não	Série do título a pagar. Máx. 30 caracteres.
`cpg_num`	`str`	não	Número do título a pagar. Máx. 30 caracteres.
`bcp_dthr`	`datetime`	não	Data/hora do baixa/comprovante de pagamento.
`consumo`	`str`	não	Valor consumido. Máx. 30 caracteres.
`adiantamento`	`str`	não	Valor do adiantamento. Máx. 30 caracteres.
`cpg_credor`	`str`	não	Nome do credor/fornecedor. Máx. 300 caracteres.
`tipo`	`str`	não	Tipo do lançamento. Máx. 30 caracteres.
`saldo`	`str`	não	Saldo remanescente. Máx. 10 caracteres.
`grupo`	`str`	não	Grupo. Máx. 10 caracteres.
`valor_usado_individual`	`str`	não	Valor usado individual. Máx. 30 caracteres.

`AdiantamentoFornecedorUpdate`

Todos os campos são opcionais; apenas os enviados são atualizados. O campo cnpj_cliente foi removido deste schema para evitar mass-assignment (troca de dono do registro via PUT); alterar o CNPJ exige um fluxo dedicado (delete + create).

Campo	Tipo	Observações
`cfg_emp`	`str`	Configuração/empresa. Máx. 300 caracteres.
`cpg_serie`	`str`	Série do título a pagar. Máx. 30 caracteres.
`cpg_num`	`str`	Número do título a pagar. Máx. 30 caracteres.
`bcp_dthr`	`datetime`	Data/hora do baixa/comprovante de pagamento.
`consumo`	`str`	Valor consumido. Máx. 30 caracteres.
`adiantamento`	`str`	Valor do adiantamento. Máx. 30 caracteres.
`cpg_credor`	`str`	Nome do credor/fornecedor. Máx. 300 caracteres.
`tipo`	`str`	Tipo do lançamento. Máx. 30 caracteres.
`saldo`	`str`	Saldo remanescente. Máx. 10 caracteres.
`grupo`	`str`	Grupo. Máx. 10 caracteres.
`valor_usado_individual`	`str`	Valor usado individual. Máx. 30 caracteres.

`AdiantamentoFornecedorRead`

Estende AdiantamentoFornecedorBase com os campos gerados pelo servidor.

Campo	Tipo	Notas
`id`	`int`	Identificador interno do registro.
`cnpj_cliente`	`str`	CNPJ do cliente.
`cfg_emp`	`str`	Configuração/empresa.
`cpg_serie`	`str`	Série do título a pagar.
`cpg_num`	`str`	Número do título a pagar.
`bcp_dthr`	`datetime`	Data/hora do baixa/comprovante de pagamento.
`consumo`	`str`	Valor consumido.
`adiantamento`	`str`	Valor do adiantamento.
`cpg_credor`	`str`	Nome do credor/fornecedor.
`tipo`	`str`	Tipo do lançamento.
`saldo`	`str`	Saldo remanescente.
`grupo`	`str`	Grupo.
`valor_usado_individual`	`str`	Valor usado individual.
`data_upload`	`datetime`	Data/hora de importação do registro na WebApi.

Notas

Toda resposta segue o envelope { success, message, data } (ou { success: false, message, details } em erro). Códigos HTTP refletem semântica REST padrão.
Os dados de adiantamento são originados do Klingo ERP e importados na WebApi; o campo data_upload registra o momento da importação.
Valores monetários (consumo, adiantamento, saldo, valor_usado_individual) trafegam como string, preservando a formatação de origem.
GET /adiantamento-fornecedor/cliente/{cnpj_cliente} é declarado antes da rota dinâmica GET /adiantamento-fornecedor/{adiantamento_id}, então cliente é resolvido como segmento estático (e não interpretado como um adiantamento_id).
O campo cnpj_cliente é imutável via PUT: para reatribuir um adiantamento a outro cliente, exclua o registro e crie um novo.