API atual/Referência completa/ERP Cobrança e conciliação

Conciliação: extratos e transações

Importa extratos OFX, lista as importações e as transações com sugestão de casamento.

Importar extrato

Conciliar é conferir o extrato do banco com os títulos do ERP. Aqui você envia o arquivo OFX (o formato de extrato exportado pelos bancos). A plataforma grava as transações novas, ignora as que já importou antes e tenta casar sozinha cada transação nova com um título. Aceita multipart/form-data (campos file e bank_account_id, arquivo até 16 MB) ou JSON com o conteúdo do arquivo.

POST/api/v1/vendor/erp/conciliacao/importSeller

Importa um extrato OFX

Corpo da requisição

bank_account_iduuidobrigatório

Conta bancária do seller dona do extrato.

file_namestring

Só no modo JSON: nome do arquivo, para o histórico.

contentstringobrigatório

Só no modo JSON: o texto do arquivo OFX. No modo multipart, o arquivo vai no campo file.

Exemplo de requisição: Importar extrato

bash

curl -X POST "$BASE_URL/api/v1/vendor/erp/conciliacao/import" \
  -H "Authorization: Bearer $TOKEN" \
  -F "bank_account_id=a1c3e5f7-2b4d-4f6a-8c0e-1d3f5a7b9c21" \
  -F "file=@extrato-outubro.ofx"

Resposta: Importar extrato

201Extrato importado

json

{
  "import_id": "3d4e5f60-7182-4930-a1b2-c3d4e5f60718",
  "tx_count": 42,
  "duplicate_count": 3,
  "matched_count": 11
}

Campos da resposta

import_iduuid

Id da importação.

tx_countinteger

Transações novas.

duplicate_countinteger

Transações já existentes, ignoradas.

matched_countinteger

Casadas automaticamente.

Erros: Importar extrato

Status	Quando	Corpo
400	Multipart ilegível.	`{"error":"invalid multipart form"}`
400	Multipart sem o campo `file`.	`{"error":"file is required"}`
400	Corpo não é um JSON válido.	`{"error":"invalid request body","detail":"invalid character 'b' looking for beginning of object key string"}`
400	`bank_account_id` em branco.	`{"error":"vendorerp: vendor_id and bank_account_id required"}`
400	O conteúdo não é um OFX válido. A tentativa fica no histórico como `failed`.	`{"error":"vendorerp: OFX inválido: ..."}`
404	A conta bancária não existe ou é de outro seller.	`{"error":"bank account not found"}`
401	Cabeçalho `Authorization` ausente, token inválido, expirado ou revogado.	`{"error":"missing authorization header"}`
403	O token não é de um usuário seller (por exemplo, é de administrador).	`{"error":"insufficient permissions"}`
403	O 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"}`

Listar importações

Devolve as 100 importações mais recentes, sem paginação.

GET/api/v1/vendor/erp/conciliacao/importsSeller

Lista as importações de extrato

Parâmetros de consulta

bank_account_iduuid

Só importações desta conta.

Exemplo de requisição: Listar importações

bash

curl "$BASE_URL/api/v1/vendor/erp/conciliacao/imports?bank_account_id=a1c3e5f7-2b4d-4f6a-8c0e-1d3f5a7b9c21" \
  -H "Authorization: Bearer $TOKEN"

Resposta: Listar importações

200Importações

json

{
  "imports": [
    {
      "id": "3d4e5f60-7182-4930-a1b2-c3d4e5f60718",
      "bank_account_id": "a1c3e5f7-2b4d-4f6a-8c0e-1d3f5a7b9c21",
      "file_name": "extrato-outubro.ofx",
      "tx_count": 42,
      "duplicate_count": 3,
      "matched_count": 11,
      "status": "done",
      "error": "",
      "created_at": "2026-10-11T14:30:00Z"
    }
  ],
  "total": 1
}

Campos da resposta

importsarray

Importações.

iduuid

Id da importação.

bank_account_iduuid

Conta bancária do extrato.

file_namestring

Nome do arquivo.

tx_countinteger

Transações novas gravadas.

duplicate_countinteger

Transações ignoradas por já existirem.

matched_countinteger

Transações casadas automaticamente.

statusstring

processingdonefailed

Situação.

errorstring

Motivo da falha, quando failed.

created_atdatetime

Quando foi importado.

totalinteger

Quantidade devolvida.

Erros: Listar importações

Status	Quando	Corpo
500	Um filtro de id não é um UUID válido (a plataforma devolve 500, não 400).	`{"error":"failed to list imports","detail":"o valor \"xyz\" não é um uuid válido. Envie o identificador completo, com os 36 caracteres e os hífens. Corrija o campo e reenvie."}`
401	Cabeçalho `Authorization` ausente, token inválido, expirado ou revogado.	`{"error":"missing authorization header"}`
403	O token não é de um usuário seller (por exemplo, é de administrador).	`{"error":"insufficient permissions"}`
403	O 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"}`

Listar transações

Mostra as transações importadas, da data de lançamento mais recente para a mais antiga. As pending já trazem suggestions, os títulos que combinam, para você escolher.

GET/api/v1/vendor/erp/conciliacao/transactionsSeller

Lista as transações do extrato

Parâmetros de consulta

bank_account_iduuid

Só desta conta.

statusstring

pendingmatchedignored

Situação. Valor desconhecido devolve lista vazia.

pageintegerpadrão: 1

Página, a partir de 1. Valor inválido ou menor que 1 volta para 1.

per_pageintegerpadrão: 25

Itens por página, de 1 a 200. Fora dessa faixa vale o padrão.

Exemplo de requisição: Listar transações

bash

curl "$BASE_URL/api/v1/vendor/erp/conciliacao/transactions?status=pending" \
  -H "Authorization: Bearer $TOKEN"

Resposta: Listar transações

200Transações

json

{
  "transactions": [
    {
      "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": [
        {
          "target_type": "receivable",
          "target_id": "cd8210a4-9275-4142-949f-b0f54e5a984c",
          "label": "Mercadinho Pinheiros",
          "amount_cents": 20000,
          "due_date": "2026-10-01"
        }
      ]
    }
  ],
  "total": 1
}

Campos da resposta

transactionsarray

Transações da página.

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.

totalinteger

Total que atende ao filtro.

Erros: Listar transações

Status	Quando	Corpo
500	Um filtro de id não é um UUID válido (a plataforma devolve 500, não 400).	`{"error":"failed to list transactions","detail":"o valor \"xyz\" não é um uuid válido. Envie o identificador completo, com os 36 caracteres e os hífens. Corrija o campo e reenvie."}`
401	Cabeçalho `Authorization` ausente, token inválido, expirado ou revogado.	`{"error":"missing authorization header"}`
403	O token não é de um usuário seller (por exemplo, é de administrador).	`{"error":"insufficient permissions"}`
403	O 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"}`

Veja também

API atual/Referência completa/ERP Cobrança e conciliação

Conciliação: extratos e transações

Importa extratos OFX, lista as importações e as transações com sugestão de casamento.

Importar extrato

POST/api/v1/vendor/erp/conciliacao/importSeller

Importa um extrato OFX

Corpo da requisição

bank_account_iduuidobrigatório

Conta bancária do seller dona do extrato.

file_namestring

Só no modo JSON: nome do arquivo, para o histórico.

contentstringobrigatório

Só no modo JSON: o texto do arquivo OFX. No modo multipart, o arquivo vai no campo file.

Exemplo de requisição: Importar extrato

bash

curl -X POST "$BASE_URL/api/v1/vendor/erp/conciliacao/import" \
  -H "Authorization: Bearer $TOKEN" \
  -F "bank_account_id=a1c3e5f7-2b4d-4f6a-8c0e-1d3f5a7b9c21" \
  -F "file=@extrato-outubro.ofx"

Resposta: Importar extrato

201Extrato importado

json

{
  "import_id": "3d4e5f60-7182-4930-a1b2-c3d4e5f60718",
  "tx_count": 42,
  "duplicate_count": 3,
  "matched_count": 11
}

Campos da resposta

import_iduuid

Id da importação.

tx_countinteger

Transações novas.

duplicate_countinteger

Transações já existentes, ignoradas.

matched_countinteger

Casadas automaticamente.

Erros: Importar extrato

Status	Quando	Corpo
400	Multipart ilegível.	`{"error":"invalid multipart form"}`
400	Multipart sem o campo `file`.	`{"error":"file is required"}`
400	Corpo não é um JSON válido.	`{"error":"invalid request body","detail":"invalid character 'b' looking for beginning of object key string"}`
400	`bank_account_id` em branco.	`{"error":"vendorerp: vendor_id and bank_account_id required"}`
400	O conteúdo não é um OFX válido. A tentativa fica no histórico como `failed`.	`{"error":"vendorerp: OFX inválido: ..."}`
404	A conta bancária não existe ou é de outro seller.	`{"error":"bank account not found"}`
401	Cabeçalho `Authorization` ausente, token inválido, expirado ou revogado.	`{"error":"missing authorization header"}`
403	O token não é de um usuário seller (por exemplo, é de administrador).	`{"error":"insufficient permissions"}`
403	O 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"}`

Listar importações

Devolve as 100 importações mais recentes, sem paginação.

GET/api/v1/vendor/erp/conciliacao/importsSeller

Lista as importações de extrato

Parâmetros de consulta

bank_account_iduuid

Só importações desta conta.

Exemplo de requisição: Listar importações

bash

curl "$BASE_URL/api/v1/vendor/erp/conciliacao/imports?bank_account_id=a1c3e5f7-2b4d-4f6a-8c0e-1d3f5a7b9c21" \
  -H "Authorization: Bearer $TOKEN"

Resposta: Listar importações

200Importações

json

{
  "imports": [
    {
      "id": "3d4e5f60-7182-4930-a1b2-c3d4e5f60718",
      "bank_account_id": "a1c3e5f7-2b4d-4f6a-8c0e-1d3f5a7b9c21",
      "file_name": "extrato-outubro.ofx",
      "tx_count": 42,
      "duplicate_count": 3,
      "matched_count": 11,
      "status": "done",
      "error": "",
      "created_at": "2026-10-11T14:30:00Z"
    }
  ],
  "total": 1
}

Campos da resposta

importsarray

Importações.

iduuid

Id da importação.

bank_account_iduuid

Conta bancária do extrato.

file_namestring

Nome do arquivo.

tx_countinteger

Transações novas gravadas.

duplicate_countinteger

Transações ignoradas por já existirem.

matched_countinteger

Transações casadas automaticamente.

statusstring

processingdonefailed

Situação.

errorstring

Motivo da falha, quando failed.

created_atdatetime

Quando foi importado.

totalinteger

Quantidade devolvida.

Erros: Listar importações

Status	Quando	Corpo
500	Um filtro de id não é um UUID válido (a plataforma devolve 500, não 400).	`{"error":"failed to list imports","detail":"o valor \"xyz\" não é um uuid válido. Envie o identificador completo, com os 36 caracteres e os hífens. Corrija o campo e reenvie."}`
401	Cabeçalho `Authorization` ausente, token inválido, expirado ou revogado.	`{"error":"missing authorization header"}`
403	O token não é de um usuário seller (por exemplo, é de administrador).	`{"error":"insufficient permissions"}`
403	O 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"}`

Listar transações

Mostra as transações importadas, da data de lançamento mais recente para a mais antiga. As pending já trazem suggestions, os títulos que combinam, para você escolher.

GET/api/v1/vendor/erp/conciliacao/transactionsSeller

Lista as transações do extrato

Parâmetros de consulta

bank_account_iduuid

Só desta conta.

statusstring

pendingmatchedignored

Situação. Valor desconhecido devolve lista vazia.

pageintegerpadrão: 1

Página, a partir de 1. Valor inválido ou menor que 1 volta para 1.

per_pageintegerpadrão: 25

Itens por página, de 1 a 200. Fora dessa faixa vale o padrão.

Exemplo de requisição: Listar transações

bash

curl "$BASE_URL/api/v1/vendor/erp/conciliacao/transactions?status=pending" \
  -H "Authorization: Bearer $TOKEN"

Resposta: Listar transações

200Transações

json

{
  "transactions": [
    {
      "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": [
        {
          "target_type": "receivable",
          "target_id": "cd8210a4-9275-4142-949f-b0f54e5a984c",
          "label": "Mercadinho Pinheiros",
          "amount_cents": 20000,
          "due_date": "2026-10-01"
        }
      ]
    }
  ],
  "total": 1
}

Campos da resposta

transactionsarray

Transações da página.

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.

totalinteger

Total que atende ao filtro.

Erros: Listar transações

Status	Quando	Corpo
500	Um filtro de id não é um UUID válido (a plataforma devolve 500, não 400).	`{"error":"failed to list transactions","detail":"o valor \"xyz\" não é um uuid válido. Envie o identificador completo, com os 36 caracteres e os hífens. Corrija o campo e reenvie."}`
401	Cabeçalho `Authorization` ausente, token inválido, expirado ou revogado.	`{"error":"missing authorization header"}`
403	O token não é de um usuário seller (por exemplo, é de administrador).	`{"error":"insufficient permissions"}`
403	O 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"}`