Enviando arquivos

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

Formatos suportados

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

CSV: Valores separados por vírgula com cabeçalhos. Mais comum para exportações bancárias.
JSON: Array de objetos de transação. Melhor para integrações via 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 adquirentes) — 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 podem ser mapeados para o schema interno do Matcher.

Campos obrigatórios

Toda 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	Outra parte na transação
`type`	String	Tipo de transação (crédito, débito, etc.)
`metadata`	Object	Campos personalizados adicionais

Exemplos de formato

CSV

Requisitos do CSV:

A primeira linha deve ser cabeçalhos de colunas
Codificação UTF-8
Delimitador vírgula (configurável)
Campos com vírgulas ou quebras de linha devem estar entre aspas

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 campos 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 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 via API

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

Pré-visualizar antes do upload

Antes de enviar um arquivo para ingestão, você pode pré-visualizá-lo para verificar a detecção de colunas e os dados de amostra. Isso ajuda a identificar problemas de mapeamento de campos antecipadamente.

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: Preview file

Upload de arquivo único

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 o file chegar primeiro, o formato é inferido a partir da extensão do nome do arquivo apenas para .csv e .json; .xml nunca é inferido (é uma família de formatos — XML puro, camt.053 — então o campo format explícito é obrigatório; caso contrário o upload é rejeitado). O upload retorna 202 Accepted com o job criado.

O limite padrão de upload é de 1 GiB e se aplica à solicitação multipart inteira, incluindo todas as partes, cabeçalhos e delimitadores, não apenas ao arquivo. Você pode configurar ingestion.max_upload_bytes entre 1 MiB e 8 GiB.

Referência da API: Upload file

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 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: Get import status

Resposta (Processando)

{
  "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ído)

{
  "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 parse/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 contagem de totalErrors/truncated). Para um job totalmente FAILED, o diagnosis traz um motivo seguro de uma única linha.

Valores de status do job de importação

Status	Descrição
`QUEUED`	Job recebido, aguardando um worker
`PROCESSING`	O arquivo está sendo analisado e normalizado
`COMPLETED`	Importação finalizada (verifique `completedWithErrors` para falhas parciais)
`FAILED`	Importação abortada por completo (veja `diagnosis`)

Validação e tratamento de erros

O Matcher valida os arquivos enviados em múltiplas etapas.

Etapas de validação

Validação de formato

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

Validação de schema

Verifica se os campos obrigatórios estão presentes e correspondem ao mapeamento de campos configurado.

Validação de tipo de dados

Valida se os valores são decimais válidos, datas são interpretáveis, moedas são códigos ISO válidos.

Validação de regras de negócio

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

Erros de validação comuns

Erro	Causa	Solução
`INVALID_FORMAT`	Arquivo não pode ser analisado	Verifique a codificação e estrutura do arquivo
`MISSING_REQUIRED_FIELD`	Campo obrigatório não encontrado	Verifique a configuração de mapeamento de campos
`INVALID_AMOUNT`	Valor não é um número válido	Verifique símbolos de moeda ou vírgulas nos números
`INVALID_DATE`	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, linhas válidas são importadas mesmo se algumas linhas tiverem erros. Configure o comportamento de tratamento de erros através das configurações de contexto ou trate os erros após a conclusão da importação revisando a resposta de status do job.

Detecção de duplicatas

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

Como as duplicatas são detectadas

Duplicatas são identificadas por uma chave de deduplicação com escopo da fonte. 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 precisar de uma identidade composta. Todo campo selecionado deve estar mapeado. Fontes vinculadas a um agregador não podem declarar uma chave personalizada porque suas retrações são endereçadas por external_id. Se uma linha repetir essa chave — dentro do mesmo upload ou em relação a dados já persistidos — ela é tratada como duplicata. Alterar duplicate_key afeta apenas importações futuras; as linhas já importadas mantêm suas chaves existentes.

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 gera uma exceção `DUPLICATE_TRANSACTION` na transação sobrevivente (subconjunto reportado como `flaggedDuplicateRows`)
`KEEP_FIRST`	Mantém a primeira ocorrência e descarta silenciosamente as repetições, contadas em `droppedDuplicateRows`
`REJECT`	Transforma cada linha repetida em um erro de linha de ingestão, contado em `failedRows`

Quando a política está ausente, FLAG_AS_EXCEPTION é aplicado.

Visualizando detalhes de duplicatas

O resumo da importação mostra quantas duplicatas foram encontradas:

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

Uploads em lote

Para jobs de reconciliação grandes, você pode enviar múltiplos arquivos em sequência.

Enviar múltiplos arquivos

# Enviar extrato bancário
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"

# Enviar exportação do razão
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"

Aguardar todas as importações

Antes de executar a conciliação, certifique-se de que todas as importações estejam concluídas:

# Listar importações do contexto
curl -X GET "https://api.matcher.example.com/v1/imports/contexts/{contextId}/jobs" \
 -H "Authorization: Bearer $TOKEN"

Pesquisar transações importadas

Após importar arquivos, você pode pesquisar entre todas as transações de um contexto para verificar 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: Search transactions

Os filtros suportados incluem amount_min, amount_max, date_from, date_to, currency, source_id, status e busca de texto livre via parâmetro q.

Melhores práticas

Valide os arquivos antes do upload

Verifique o formato e codificação do arquivo localmente antes de enviar. Isso detecta erros óbvios mais rapidamente.

# Verificar se o CSV é válido
head -5 transactions.csv

# Verificar a codificação
file transactions.csv

Use formatos de data consistentes

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

Inclua IDs de transação

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

Trate valores negativos de forma consistente

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

Envie incrementalmente para arquivos grandes

Para arquivos maiores que 50 MB, considere dividi-los em partes 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 reconciliação recorrente, automatize o envio de arquivos usando jobs agendados ou webhooks dos sistemas de origem.

# Exemplo: upload diário via cron
0 6 * * * /scripts/upload_bank_statement.sh

Próximos passos

Revisando correspondências

Aprenda como interpretar resultados de correspondência e pontuações de confiança.

Mapeamento de campos

Configure como os campos de origem mapeiam para o schema do Matcher.

Visão geral

Guias

Matcher UI

Servidor MCP

Operações

Enviando arquivos

Formatos suportados

Requisitos de estrutura do arquivo

Campos obrigatórios

Campos opcionais

Exemplos de formato

CSV

JSON

XML

Upload via API

Pré-visualizar antes do upload

Resposta

Upload de arquivo único

Resposta

Verificar status da importação

Resposta (Processando)

Resposta (Concluído)

Valores de status do job de importação

Validação e tratamento de erros

Etapas de validação

Erros de validação comuns

Tratamento de erros

Detecção de duplicatas

Como as duplicatas são detectadas

Opções de tratamento de duplicatas

Visualizando detalhes de duplicatas

Uploads em lote

Enviar múltiplos arquivos

Aguardar todas as importações

Pesquisar transações importadas

Resposta

Melhores práticas

Próximos passos

Revisando correspondências

Mapeamento de campos

​Formatos suportados

​Requisitos de estrutura do arquivo

​Campos obrigatórios

​Campos opcionais

​Exemplos de formato

​CSV

​JSON

​XML

​Upload via API

​Pré-visualizar antes do upload

​Resposta

​Upload de arquivo único

​Resposta

​Verificar status da importação

​Resposta (Processando)

​Resposta (Concluído)

​Valores de status do job de importação

​Validação e tratamento de erros

​Etapas de validação

​Erros de validação comuns

​Tratamento de erros

​Detecção de duplicatas

​Como as duplicatas são detectadas

​Opções de tratamento de duplicatas

​Visualizando detalhes de duplicatas

​Uploads em lote

​Enviar múltiplos arquivos

​Aguardar todas as importações

​Pesquisar transações importadas

​Resposta

​Melhores práticas

​Próximos passos

Revisando correspondências

Mapeamento de campos

Formatos suportados

Requisitos de estrutura do arquivo

Campos obrigatórios

Campos opcionais

Exemplos de formato

CSV

JSON

XML

Upload via API

Pré-visualizar antes do upload

Resposta

Upload de arquivo único

Resposta

Verificar status da importação

Resposta (Processando)

Resposta (Concluído)

Valores de status do job de importação

Validação e tratamento de erros

Etapas de validação

Erros de validação comuns

Tratamento de erros

Detecção de duplicatas

Como as duplicatas são detectadas

Opções de tratamento de duplicatas

Visualizando detalhes de duplicatas

Uploads em lote

Enviar múltiplos arquivos

Aguardar todas as importações

Pesquisar transações importadas

Resposta

Melhores práticas

Próximos passos