Upload de arquivos

Este guia mostra como importar dados de transações de fontes externas para o Matcher para conciliação.

Formatos aceitos

O Matcher aceita arquivos de transações em três formatos de uso geral:

CSV: valores separados por vírgula com cabeçalhos. O mais comum para exportações bancárias.
JSON: array de objetos de transação. Melhor para integrações de API.
XML: elementos estruturados. Comum em sistemas corporativos.

Além desses, o endpoint de upload também aceita formatos bancários especializados como camt053 e as chaves de descritor com namespace do catálogo de formatos (CNAB, layouts de adquirente). Veja Formatos de importação para o catálogo completo.

Requisitos de estrutura do arquivo

Cada arquivo deve conter registros de transações com campos que você possa mapear para o schema interno do Matcher.

Campos obrigatórios

Cada transação deve ter estes campos (ou equivalentes mapeáveis):

Campo	Tipo	Descrição
`transaction_id`	String	Identificador único dentro da fonte
`amount`	Decimal	Valor da transação (positivo ou negativo)
`currency`	String	Código de moeda ISO 4217
`date`	Date/DateTime	Data da transação

Campos opcionais

Campo	Tipo	Descrição
`reference`	String	Referência externa ou descrição
`counterparty`	String	A outra parte da transação
`type`	String	Tipo da transação (crédito, débito etc.)
`metadata`	Object	Campos personalizados adicionais

Exemplos de formato

CSV

Requisitos do CSV:

A primeira linha deve ser o cabeçalho das colunas
Codificação UTF-8
Delimitador vírgula (configurável)
Coloque entre aspas os campos que contêm vírgulas ou quebras de linha

Exemplo de código

 transaction_id,amount,currency,date,reference,type
 BANK-2024-001,1500.00,USD,2024-01-15,Invoice #1234,credit
 BANK-2024-002,-250.00,USD,2024-01-15,Service fee,debit
 BANK-2024-003,3200.50,USD,2024-01-16,Customer payment,credit
 BANK-2024-004,-89.99,USD,2024-01-16,Subscription,debit

JSON

Requisitos do JSON:

O elemento raiz deve ser um array
Nomes de campo consistentes entre os objetos
Codificação UTF-8

Exemplo de código

[
  {
    "transaction_id": "BANK-2024-001",
    "amount": 1500.0,
    "currency": "USD",
    "date": "2024-01-15",
    "reference": "Invoice #1234",
    "type": "credit"
  },
  {
    "transaction_id": "BANK-2024-002",
    "amount": -250.0,
    "currency": "USD",
    "date": "2024-01-15",
    "reference": "Service fee",
    "type": "debit"
  }
]

XML

Requisitos do XML:

XML válido com declaração
Elemento raiz contendo os elementos de transação
Codificação UTF-8

Exemplo de código

  <?xml version="1.0" encoding="UTF-8"?>
  <transactions>
    <transaction>
      <transaction_id>BANK-2024-001</transaction_id>
      <amount>1500.00</amount>
      <currency>USD</currency>
      <date>2024-01-15</date>
     <reference>Invoice #1234</reference>
      <type>credit</type>
    </transaction>
    <transaction>
      <transaction_id>BANK-2024-002</transaction_id>
      <amount>-250.00</amount>
      <currency>USD</currency>
      <date>2024-01-15</date>
      <reference>Service fee</reference>
      <type>debit</type>
      </transaction>
  </transactions>

Upload pela API

Use o endpoint de importação para enviar arquivos de transações.

Pré-visualize antes de enviar

Antes de confirmar um arquivo para ingestão, você pode pré-visualizá-lo para conferir a detecção de colunas e uma amostra dos dados. Isso ajuda a pegar problemas de mapeamento de campos cedo.

cURL

curl -X POST "https://api.matcher.example.com/v1/imports/contexts/{contextId}/sources/{sourceId}/preview" \
 -H "Authorization: Bearer $TOKEN" \
 -F "file=@bank_statement_january.csv" \
 -F "max_rows=5"

Resposta

{
  "columns": ["transaction_id", "amount", "currency", "date", "reference"],
  "sampleRows": [
    ["BANK-2024-001", "1500.00", "USD", "2024-01-15", "Invoice #1234"],
    ["BANK-2024-002", "-250.00", "USD", "2024-01-15", "Service fee"]
  ],
  "rowCount": 2,
  "format": "csv"
}

Referência da API: Pré-visualizar arquivo

Upload de um único arquivo

cURL

curl -X POST "https://api.matcher.example.com/v1/imports/contexts/{contextId}/sources/{sourceId}/upload" \
 -H "Authorization: Bearer $TOKEN" \
 -F "format=csv" \
 -F "file=@bank_statement_january.csv"

Envie o campo format antes da parte file. Se file chega primeiro, o Matcher infere o formato pela extensão do nome do arquivo apenas para .csv e .json. O Matcher nunca infere .xml, porque é uma família de formatos que cobre XML puro e camt.053. Envie o campo format explícito para XML. Sem ele, o Matcher rejeita o upload. O upload retorna 202 Accepted com o job criado.

O limite de upload é 1 GiB por padrão e vale para toda a requisição multipart, incluindo cada parte, header e boundary, não apenas o arquivo. Você pode configurar ingestion.max_upload_bytes de 1 MiB até 8 GiB.

Referência da API: Enviar arquivo

Resposta

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "contextId": "969a11cd-6b7d-4e71-b82b-0828e0603149",
  "sourceId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "QUEUED",
  "fileName": "bank_statement_january.csv",
  "totalRows": 0,
  "persistedRows": 0,
  "droppedDuplicateRows": 0,
  "failedRows": 0,
  "failureRatePercent": 0,
  "completedWithErrors": false,
  "createdAt": "2024-01-20T10:30:00Z"
}

Verificar o status da importação

cURL

curl -X GET https://api.matcher.example.com/v1/imports/contexts/{contextId}/jobs/{jobId} \
 -H "Authorization: Bearer $TOKEN"

Referência da API: Obter status da importação

Resposta (em processamento)

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "contextId": "969a11cd-6b7d-4e71-b82b-0828e0603149",
  "sourceId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "PROCESSING",
  "fileName": "bank_statement_january.csv",
  "totalRows": 1250,
  "startedAt": "2024-01-20T10:30:05Z"
}

Resposta (concluída)

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "contextId": "969a11cd-6b7d-4e71-b82b-0828e0603149",
  "sourceId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "COMPLETED",
  "completedWithErrors": true,
  "fileName": "bank_statement_january.csv",
  "totalRows": 1250,
  "persistedRows": 1233,
  "droppedDuplicateRows": 12,
  "failedRows": 5,
  "failureRatePercent": 1,
  "reviewRows": 0,
  "diagnosis": "",
  "startedAt": "2024-01-20T10:30:05Z",
  "completedAt": "2024-01-20T10:30:45Z"
}

Os erros de parsing/normalização por linha não ficam embutidos no job. Quando completedWithErrors é true (ou o job está FAILED), busque os detalhes em GET /v1/imports/contexts/{contextId}/jobs/{jobId}/errors (limitado a 100 linhas armazenadas, com a contagem em totalErrors/truncated). Para um job FAILED por inteiro, diagnosis traz um motivo seguro de uma linha.

Valores de status do job de importação

Status	Descrição
`QUEUED`	Job recebido, aguardando um worker
`PROCESSING`	O arquivo está sendo interpretado e normalizado
`COMPLETED`	Importação concluída (veja `completedWithErrors` para falhas parciais)
`FAILED`	Importação abortada por inteiro (veja `diagnosis`)

Validação e tratamento de erros

O Matcher valida os arquivos enviados em várias etapas.

Etapas de validação

Validação de formato

Verifica se o arquivo é um CSV, JSON ou XML válido com a estrutura correta.

Validação de schema

Confere se os campos obrigatórios estão presentes e batem com o mapa de campos configurado.

Validação de tipo de dado

Valida se os valores são decimais válidos, se as datas podem ser interpretadas e se as moedas são códigos ISO válidos.

Validação de regra de negócio

Aplica regras específicas do contexto, como intervalos de datas, limites de valor etc.

Erros comuns de validação

Erro	Causa	Solução
`INVALID_FORMAT`	O arquivo não pode ser interpretado	Verifique a codificação e a estrutura do arquivo
`MISSING_REQUIRED_FIELD`	Campo obrigatório não encontrado	Confira a configuração de mapeamento de campos
`INVALID_AMOUNT`	O valor não é um número válido	Procure símbolos de moeda ou vírgulas nos números
`INVALID_DATE`	A data não pode ser interpretada	Use o formato ISO 8601 (YYYY-MM-DD)
`UNKNOWN_CURRENCY`	Código de moeda não reconhecido	Use códigos ISO 4217 (USD, EUR, BRL)
`DATE_OUT_OF_RANGE`	Data antes/depois do intervalo permitido	Verifique os limites de data do contexto

Tratamento de erros

Por padrão, o Matcher importa as linhas válidas mesmo se algumas linhas têm erros. Configure o comportamento de tratamento de erros nas configurações do contexto ou trate os erros depois que a importação termina, revisando a resposta de status do job.

Detecção de duplicatas

O Matcher detecta e trata transações duplicadas automaticamente para evitar contagem em dobro.

Como as duplicatas são detectadas

Uma chave de deduplicação com escopo na fonte identifica as duplicatas. Por padrão, ela é o external_id da fonte. Defina duplicate_key no config da fonte como uma lista ordenada de campos mapeados (external_id, amount, currency, date, description, fee_amount ou fee_currency) quando você precisa de uma identidade composta. Você deve mapear cada campo selecionado. As fontes vinculadas a agregador não podem declarar uma chave personalizada, porque as retratações delas usam o external_id. Se uma linha repete essa chave (dentro do mesmo upload ou contra dados já persistidos), o Matcher a trata como duplicata. Uma mudança em duplicate_key afeta apenas as importações seguintes. As linhas importadas antes mantêm as chaves que já têm.

Opções de tratamento de duplicatas

Defina a chave duplicate_policy no config da fonte para controlar o tratamento:

Política	Comportamento
`FLAG_AS_EXCEPTION` (padrão)	Descarta a repetição e levanta uma exceção `DUPLICATE_TRANSACTION` na transação que permanece (o subconjunto é informado em `flaggedDuplicateRows`)
`KEEP_FIRST`	Mantém a primeira ocorrência e descarta as repetições em silêncio, contadas em `droppedDuplicateRows`
`REJECT`	Transforma cada linha repetida em um erro de linha na ingestão, contado em `failedRows`

Quando duplicate_policy está ausente, vale FLAG_AS_EXCEPTION.

Ver os detalhes das duplicatas

O resumo da importação mostra o número de duplicatas:

{
  "totalRows": 1000,
  "persistedRows": 950,
  "flaggedDuplicateRows": 50,
  "failedRows": 0,
  "failureRatePercent": 0
}

Uploads em lote

Para jobs grandes de conciliação, você pode enviar vários arquivos em sequência.

Enviar vários arquivos

# Upload bank statement
curl -X POST "https://api.matcher.example.com/v1/imports/contexts/{contextId}/sources/{bankSourceId}/upload" \
 -H "Authorization: Bearer $TOKEN" \
 -F "file=@bank_january.csv" \
 -F "format=csv"

# Upload ledger export
curl -X POST "https://api.matcher.example.com/v1/imports/contexts/{contextId}/sources/{ledgerSourceId}/upload" \
 -H "Authorization: Bearer $TOKEN" \
 -F "file=@ledger_january.csv" \
 -F "format=csv"

Aguarde todas as importações

Antes de rodar a correspondência, garanta que todas as importações terminaram:

# List imports for context
curl -X GET "https://api.matcher.example.com/v1/imports/contexts/{contextId}/jobs" \
 -H "Authorization: Bearer $TOKEN"

Buscar as transações enviadas

Depois de importar os arquivos, você pode buscar em todas as transações de um contexto para conferir a qualidade dos dados ou investigar registros específicos.

cURL

curl -X GET "https://api.matcher.example.com/v1/imports/contexts/{contextId}/transactions/search?q=Invoice&amount_min=1000&status=UNMATCHED" \
 -H "Authorization: Bearer $TOKEN"

Resposta

{
  "items": [
    {
      "id": "019c96a0-2a10-7dfe-b5c1-8a1b2c3d4e5f",
      "sourceId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "amount": "1500.00",
      "currency": "USD",
      "date": "2024-01-15T00:00:00Z",
      "description": "Invoice #1234",
      "status": "UNMATCHED"
    }
  ],
  "total": 1,
  "limit": 20,
  "offset": 0
}

Referência da API: Buscar transações

Os filtros aceitos incluem amount_min, amount_max, date_from, date_to, currency, source_id, status e a busca em texto livre pelo parâmetro q.

Boas práticas

Valide os arquivos antes do upload

Verifique o formato e a codificação do arquivo localmente antes de enviar. Isso pega erros óbvios mais rápido.

# Check CSV is valid
head -5 transactions.csv

# Check encoding
file transactions.csv

Use formatos de data consistentes

Padronize o formato ISO 8601 (YYYY-MM-DD ou YYYY-MM-DDTHH:MM:SSZ) em todas as fontes para evitar problemas de interpretação.

Inclua os IDs das transações

Sempre inclua IDs únicos de transação do sistema de origem. Isso permite uma detecção de duplicatas correta e trilhas de auditoria.

Trate os valores negativos de forma consistente

Defina uma convenção (negativo para débitos, positivo para créditos) e aplique-a de forma consistente. Documente isso no seu mapeamento de campos.

Envie de forma incremental para arquivos grandes

Para arquivos maiores que 50 MB, considere dividi-los em pedaços menores por intervalo de datas. Essa é uma recomendação de confiabilidade, não o limite de upload, e permite novas tentativas parciais.

Configure uploads automatizados

Para conciliação recorrente, automatize os uploads de arquivo usando jobs agendados ou webhooks dos sistemas de origem.

# Example: Daily upload via cron
0 6 * * * /scripts/upload_bank_statement.sh

Próximos passos

Revisão de correspondências

Veja como interpretar os resultados de correspondência e as pontuações de confiança.

Mapeamento de campos

Configure como os campos da fonte mapeiam para o schema do Matcher.

Visão geral

Guias

Matcher UI

Servidor MCP

Operações

Upload de arquivos

Formatos aceitos

Requisitos de estrutura do arquivo

Campos obrigatórios

Campos opcionais

Exemplos de formato

CSV

JSON

XML

Upload pela API

Pré-visualize antes de enviar

Resposta

Upload de um único arquivo

Resposta

Verificar o status da importação

Resposta (em processamento)

Resposta (concluída)

Valores de status do job de importação

Validação e tratamento de erros

Etapas de validação

Erros comuns de validação

Tratamento de erros

Detecção de duplicatas

Como as duplicatas são detectadas

Opções de tratamento de duplicatas

Ver os detalhes das duplicatas

Uploads em lote

Enviar vários arquivos

Aguarde todas as importações

Buscar as transações enviadas

Resposta

Boas práticas

Próximos passos

Revisão de correspondências

Mapeamento de campos

​Formatos aceitos

​Requisitos de estrutura do arquivo

​Campos obrigatórios

​Campos opcionais

​Exemplos de formato

​CSV

​JSON

​XML

​Upload pela API

​Pré-visualize antes de enviar

​Resposta

​Upload de um único arquivo

​Resposta

​Verificar o status da importação

​Resposta (em processamento)

​Resposta (concluída)

​Valores de status do job de importação

​Validação e tratamento de erros

​Etapas de validação

​Erros comuns de validação

​Tratamento de erros

​Detecção de duplicatas

​Como as duplicatas são detectadas

​Opções de tratamento de duplicatas

​Ver os detalhes das duplicatas

​Uploads em lote

​Enviar vários arquivos

​Aguarde todas as importações

​Buscar as transações enviadas

​Resposta

​Boas práticas

​Próximos passos

Revisão de correspondências

Mapeamento de campos

Formatos aceitos

Requisitos de estrutura do arquivo

Campos obrigatórios

Campos opcionais

Exemplos de formato

CSV

JSON

XML

Upload pela API

Pré-visualize antes de enviar

Resposta

Upload de um único arquivo

Resposta

Verificar o status da importação

Resposta (em processamento)

Resposta (concluída)

Valores de status do job de importação

Validação e tratamento de erros

Etapas de validação

Erros comuns de validação

Tratamento de erros

Detecção de duplicatas

Como as duplicatas são detectadas

Opções de tratamento de duplicatas

Ver os detalhes das duplicatas

Uploads em lote

Enviar vários arquivos

Aguarde todas as importações

Buscar as transações enviadas

Resposta

Boas práticas

Próximos passos