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:

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.

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 (.csv/.json/.xml). O upload retorna 202 Accepted com o job criado.

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 pela chave de deduplicação da linha dentro de uma fonte:

source_id
external_id (o identificador de transação do sistema de origem)

Se uma linha repetir essa chave — dentro do mesmo upload ou em relação a dados já persistidos — ela é tratada como duplicata.

Opções de tratamento de duplicatas

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

Política	Comportamento
`KEEP_FIRST` (padrão)	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`
`FLAG_AS_EXCEPTION`	Descarta a repetição e gera uma exceção `DUPLICATE_TRANSACTION` na transação sobrevivente (subconjunto reportado como `flaggedDuplicateRows`)

Quando a chave está ausente, KEEP_FIRST é aplicado.

Visualizando detalhes de duplicatas

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

{
  "totalRows": 1000,
  "persistedRows": 950,
  "droppedDuplicateRows": 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

# 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"

Aguardar todas as importações

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

# List imports for context
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.

# Check CSV is valid
head -5 transactions.csv

# Check encoding
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 muito grandes (>50MB), considere dividir em partes menores por intervalo de datas. Isso melhora a confiabilidade 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.

# Example: Daily upload 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