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
`external_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
`description`	String	Descrição em texto livre
`fee_amount`	Decimal	Tarifa cobrada na transação
`fee_currency`	String	Moeda da tarifa
`direction`	Object	Coluna que marca cada linha como débito ou crédito. Veja Coluna de débito e crédito.

O Matcher guarda as colunas não mapeadas como metadados da transação.

Coluna de débito e crédito

Alguns arquivos marcam cada linha como débito ou crédito em uma coluna separada. Para ler o sinal dessa coluna, mapeie a chave opcional direction para um objeto {column, debit, credit}:

"direction": { "column": "type", "debit": "debit", "credit": "credit" }

Uma linha de débito é importada com valor negativo, e uma linha de crédito é importada com valor positivo. Com direction mapeada, a coluna de valor deve vir sem sinal. Um valor com sinal, uma célula de direção vazia ou um valor de direção desconhecido rejeita a linha. O Matcher lê direction apenas em arquivos CSV, JSON e XML.

Exemplos de formato

CSV

Requisitos do CSV:

A primeira linha deve ser o cabeçalho das colunas
Codificação UTF-8 e delimitador vírgula por padrão (configuráveis)
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:

Um array de objetos ou um único objeto
Nomes de campo consistentes entre os objetos
Codificação UTF-8 por padrão (configurável)

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 bem formado
Elementos de registro chamados transaction, row, record, item ou entry
Codificação UTF-8 por padrão (configurável)

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 Matcher interpreta e armazena o arquivo inteiro dentro da requisição de upload. O upload retorna 202 Accepted com o job concluído. Quando a importação falha, o Matcher responde com um erro em vez do job. O Matcher lê uma chave de idempotência apenas do header X-Idempotency, e apenas quando você envia uma. Uma requisição que traz uma chave apenas em X-Idempotency-Key ou Idempotency-Key é recusada com 400 (MTCH-0015), e nada é processado. Uma resposta repetida traz o header X-Idempotency-Replayed.

O limite padrão de upload é 1 GiB. Ele conta todo o corpo da requisição, incluindo cada parte, header de parte e boundary, não apenas o arquivo.

O Matcher recusa um upload maior que o limite de upload com 413 (MTCH-0010). Ele recusa um upload que para de enviar dados por tempo demais com 408 (MTCH-0311).

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": "COMPLETED",
  "fileName": "bank_statement_january.csv",
  "totalRows": 1250,
  "persistedRows": 1250,
  "droppedDuplicateRows": 0,
  "flaggedDuplicateRows": 0,
  "reviewRows": 0,
  "failureRatePercent": 0,
  "completedWithErrors": false,
  "startedAt": "2024-01-20T10:30:00Z",
  "completedAt": "2024-01-20T10:30:45Z",
  "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",
  "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.

reviewRows conta as linhas com external_id vazio que o Matcher importa com status PENDING_REVIEW. Isso acontece quando a fonte define blank_external_id como NEEDS_REVIEW no seu config. Com o padrão, REJECT, um external_id vazio faz a linha falhar.

Valores de status do job de importação

Status	Descrição
`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.

Erros comuns de validação

Cada erro de linha traz o número da linha, o campo quando houver um e uma mensagem. Mensagens comuns:

Mensagem	Causa	Solução
`missing required field`	Um campo obrigatório está vazio na linha	Preencha o campo no arquivo de origem
`invalid decimal amount`	O valor não é um número válido	Procure símbolos de moeda ou separadores de milhar
`invalid date format`	A data não pode ser interpretada	Use o formato ISO 8601 (YYYY-MM-DD)
`invalid ISO 4217 currency code`	Código de moeda não reconhecido	Use códigos ISO 4217 (USD, EUR, BRL)

Tratamento de erros

Por padrão, o Matcher importa as linhas válidas mesmo se algumas linhas têm erros. Para fazer o job falhar quando as linhas com falha passam de um percentual, defina fail_on_error_rate_percent (de 1 a 99) no config da fonte.

Detecção de duplicatas

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

Como as duplicatas são detectadas

Por padrão, uma linha é duplicata quando repete o external_id de uma linha da mesma fonte, dentro do mesmo upload ou contra dados já persistidos. Para detectar duplicatas por outros campos, defina duplicate_key no config da fonte. O valor é uma lista ordenada de nomes do mapeamento de campos, como ["external_id", "amount"].

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 de `droppedDuplicateRows` é 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,
  "droppedDuplicateRows": 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 "format=csv" \
 -F "file=@bank_january.csv"

# Upload ledger export
curl -X POST "https://api.matcher.example.com/v1/imports/contexts/{contextId}/sources/{ledgerSourceId}/upload" \
 -H "Authorization: Bearer $TOKEN" \
 -F "format=csv" \
 -F "file=@ledger_january.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, a correspondência exata de external_id pelo parâmetro reference 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. Quando um arquivo marca débitos e créditos em uma coluna separada, mapeie essa coluna com a chave direction em vez disso.

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.

# 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

Console

Operações

Upload de arquivos

Formatos aceitos

Requisitos de estrutura do arquivo

Campos obrigatórios

Campos opcionais

Coluna de débito e crédito

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

​Coluna de débito e crédito

​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

Coluna de débito e crédito

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