VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Referência completa/ERP Cobrança e conciliação

Conciliação: casar e ignorar

Casa uma transação do extrato com um título, desfaz o casamento ou ignora a transação.

Casar transação

Liga uma transação pending a uma conta a pagar ou a receber. O título precisa estar open e com exatamente o mesmo valor da transação (em módulo). O título é quitado (paid ou received, com a data de agora) e a transação vira matched, tudo numa transação de banco.

POST/api/v1/vendor/erp/conciliacao/transactions/{id}/matchSeller

Casa uma transação com um título

Parâmetros de caminho

iduuidobrigatório
Id (UUID) da transação.

Corpo da requisição

target_typestringobrigatório
payablereceivable
Tipo do título.
target_iduuidobrigatório
Id do título.

Exemplo de requisição: Casar transação

bash
curl -X POST "$BASE_URL/api/v1/vendor/erp/conciliacao/transactions/3f6c1c1e-8d0b-4a55-9a52-1d6f6a4a7b10/match" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "target_type": "receivable",
  "target_id": "cd8210a4-9275-4142-949f-b0f54e5a984c"
}'

Resposta: Casar transação

200Transação casada
json
{
  "id": "6a7b8c9d-0e1f-4203-9415-26374859a6b7",
  "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
  "bank_account_id": "a1c3e5f7-2b4d-4f6a-8c0e-1d3f5a7b9c21",
  "fitid": "202610090001",
  "posted_at": "2026-10-09",
  "amount_cents": 20000,
  "description": "PIX RECEBIDO MERCADINHO PINHEIROS",
  "status": "matched",
  "ignored_reason": "",
  "matched_at": "2026-10-11T14:30:00Z",
  "created_at": "2026-10-11T14:30:00Z",
  "suggestions": null
}

Campos da resposta

iduuid
Id da transação.
vendor_iduuid
Seller dono.
bank_account_iduuid
Conta bancária.
fitidstring
Identificador único da transação no extrato (FITID do OFX). Evita duplicar ao reimportar.
posted_atstring
Data do lançamento no banco YYYY-MM-DD.
amount_centsinteger
Valor com sinal: positivo é crédito (entrada), negativo é débito (saída).
descriptionstring
Descrição do banco.
statusstring
pendingmatchedignored
Situação.
ignored_reasonstring
Motivo, quando ignored.
matched_atdatetime
Quando foi casada. null se não.
created_atdatetime
Quando foi importada.
suggestionsarray

Só em transações pending da listagem: até 10 títulos candidatos.

target_typestring
payablereceivable
Tipo do título sugerido.
target_iduuid
Id do título.
labelstring
Cliente ou fornecedor, ou a descrição.
amount_centsinteger
Valor do título.
due_datestring
Vencimento.

Erros: Casar transação

StatusQuandoCorpo
400Corpo não é um JSON válido.{"error":"invalid request body","detail":"invalid character 'b' looking for beginning of object key string"}
400target_type inválido.{"error":"vendorerp: target_type must be payable|receivable"}
400target_id em branco.{"error":"vendorerp: target_id required"}
400A transação não está pending.{"error":"vendorerp: transaction is not pending"}
400O título não existe, não está open ou o valor difere.{"error":"vendorerp: título não encontrado, já liquidado ou com valor divergente do extrato"}
404A transação não existe ou é de outro seller.{"error":"bank transaction not found"}
401Cabeçalho Authorization ausente, token inválido, expirado ou revogado.{"error":"missing authorization header"}
403O token não é de um usuário seller (por exemplo, é de administrador).{"error":"insufficient permissions"}
403O usuário não está vinculado a um seller, ou o cadastro do seller ainda está em análise (vendor_pending_review).{"error":"no vendor account associated with this user"}
O sentido do dinheiro não é conferido

Casar um crédito com uma conta a pagar (ou um débito com uma conta a receber) é aceito se o valor bater. As sugestões respeitam o sentido; o casamento manual não.

O casamento não cria baixa

O título fica quitado, mas paid_amount_cents continua 0 e não há registro em baixas, então ele não entra nos saldos bancários nem na série diária de caixa.

Desfazer casamento

Volta a transação de matched para pending e reabre os títulos que ela havia quitado (estado open, sem data de quitação).

POST/api/v1/vendor/erp/conciliacao/transactions/{id}/unmatchSeller

Desfaz o casamento

Parâmetros de caminho

iduuidobrigatório
Id (UUID) da transação.

Exemplo de requisição: Desfazer casamento

bash
curl -X POST "$BASE_URL/api/v1/vendor/erp/conciliacao/transactions/3f6c1c1e-8d0b-4a55-9a52-1d6f6a4a7b10/unmatch" \
  -H "Authorization: Bearer $TOKEN"

Resposta: Desfazer casamento

200Casamento desfeito
json
{
  "id": "6a7b8c9d-0e1f-4203-9415-26374859a6b7",
  "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
  "bank_account_id": "a1c3e5f7-2b4d-4f6a-8c0e-1d3f5a7b9c21",
  "fitid": "202610090001",
  "posted_at": "2026-10-09",
  "amount_cents": 20000,
  "description": "PIX RECEBIDO MERCADINHO PINHEIROS",
  "status": "pending",
  "ignored_reason": "",
  "matched_at": null,
  "created_at": "2026-10-11T14:30:00Z",
  "suggestions": null
}

Campos da resposta

iduuid
Id da transação.
vendor_iduuid
Seller dono.
bank_account_iduuid
Conta bancária.
fitidstring
Identificador único da transação no extrato (FITID do OFX). Evita duplicar ao reimportar.
posted_atstring
Data do lançamento no banco YYYY-MM-DD.
amount_centsinteger
Valor com sinal: positivo é crédito (entrada), negativo é débito (saída).
descriptionstring
Descrição do banco.
statusstring
pendingmatchedignored
Situação.
ignored_reasonstring
Motivo, quando ignored.
matched_atdatetime
Quando foi casada. null se não.
created_atdatetime
Quando foi importada.
suggestionsarray

Só em transações pending da listagem: até 10 títulos candidatos.

target_typestring
payablereceivable
Tipo do título sugerido.
target_iduuid
Id do título.
labelstring
Cliente ou fornecedor, ou a descrição.
amount_centsinteger
Valor do título.
due_datestring
Vencimento.

Erros: Desfazer casamento

StatusQuandoCorpo
400A transação não está matched.{"error":"vendorerp: transaction is not matched"}
404A transação não existe ou é de outro seller.{"error":"bank transaction not found"}
401Cabeçalho Authorization ausente, token inválido, expirado ou revogado.{"error":"missing authorization header"}
403O token não é de um usuário seller (por exemplo, é de administrador).{"error":"insufficient permissions"}
403O usuário não está vinculado a um seller, ou o cadastro do seller ainda está em análise (vendor_pending_review).{"error":"no vendor account associated with this user"}

Ignorar transação

Marca uma transação pending como ignored, por exemplo uma tarifa que você não controla no ERP. O motivo é obrigatório. Não existe rota para reverter um ignored.

POST/api/v1/vendor/erp/conciliacao/transactions/{id}/ignoreSeller

Ignora uma transação

Parâmetros de caminho

iduuidobrigatório
Id (UUID) da transação.

Corpo da requisição

reasonstringobrigatório
Motivo, obrigatório.

Exemplo de requisição: Ignorar transação

bash
curl -X POST "$BASE_URL/api/v1/vendor/erp/conciliacao/transactions/3f6c1c1e-8d0b-4a55-9a52-1d6f6a4a7b10/ignore" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "reason": "Tarifa bancária"
}'

Resposta: Ignorar transação

200Transação ignorada
json
{
  "id": "6a7b8c9d-0e1f-4203-9415-26374859a6b7",
  "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
  "bank_account_id": "a1c3e5f7-2b4d-4f6a-8c0e-1d3f5a7b9c21",
  "fitid": "202610090001",
  "posted_at": "2026-10-09",
  "amount_cents": 20000,
  "description": "PIX RECEBIDO MERCADINHO PINHEIROS",
  "status": "ignored",
  "ignored_reason": "Tarifa bancária",
  "matched_at": null,
  "created_at": "2026-10-11T14:30:00Z",
  "suggestions": null
}

Campos da resposta

iduuid
Id da transação.
vendor_iduuid
Seller dono.
bank_account_iduuid
Conta bancária.
fitidstring
Identificador único da transação no extrato (FITID do OFX). Evita duplicar ao reimportar.
posted_atstring
Data do lançamento no banco YYYY-MM-DD.
amount_centsinteger
Valor com sinal: positivo é crédito (entrada), negativo é débito (saída).
descriptionstring
Descrição do banco.
statusstring
pendingmatchedignored
Situação.
ignored_reasonstring
Motivo, quando ignored.
matched_atdatetime
Quando foi casada. null se não.
created_atdatetime
Quando foi importada.
suggestionsarray

Só em transações pending da listagem: até 10 títulos candidatos.

target_typestring
payablereceivable
Tipo do título sugerido.
target_iduuid
Id do título.
labelstring
Cliente ou fornecedor, ou a descrição.
amount_centsinteger
Valor do título.
due_datestring
Vencimento.

Erros: Ignorar transação

StatusQuandoCorpo
400Corpo não é um JSON válido.{"error":"invalid request body","detail":"invalid character 'b' looking for beginning of object key string"}
400reason em branco.{"error":"vendorerp: reason required"}
400A transação não está pending.{"error":"vendorerp: transaction is not pending"}
404A transação não existe ou é de outro seller.{"error":"bank transaction not found"}
401Cabeçalho Authorization ausente, token inválido, expirado ou revogado.{"error":"missing authorization header"}
403O token não é de um usuário seller (por exemplo, é de administrador).{"error":"insufficient permissions"}
403O usuário não está vinculado a um seller, ou o cadastro do seller ainda está em análise (vendor_pending_review).{"error":"no vendor account associated with this user"}
Ciclo de uma transação

pending leva a matched (e volta com unmatch) ou a ignored (sem volta).

Veja também

  • Extratos e transações
Anterior
Conciliação: extratos e transações
Próxima
ERP de frente de caixa (PDV)
Nesta página
  • Casar transação
  • Exemplo de requisição: Casar transação
  • Resposta: Casar transação
  • Erros: Casar transação
  • Desfazer casamento
  • Exemplo de requisição: Desfazer casamento
  • Resposta: Desfazer casamento
  • Erros: Desfazer casamento
  • Ignorar transação
  • Exemplo de requisição: Ignorar transação
  • Resposta: Ignorar transação
  • Erros: Ignorar transação
  • Veja também