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.

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 "file=@bank_statement_january.csv" \
 -F "format=csv"

Referência da API: Enviar arquivo

Resposta

{
  "job_id": "job_imp_789xyz",
  "status": "QUEUED",
  "context_id": "ctx_abc123",
  "source_id": "src_bank456",
  "file_name": "bank_statement_january.csv",
  "file_size_bytes": 15420,
  "created_at": "2024-01-20T10:30:00Z"
}

Verificar status da importação

cURL

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

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

Resposta (Processando)

{
  "job_id": "job_imp_789xyz",
  "status": "PROCESSING",
  "progress": {
    "total_rows": 1250,
    "processed_rows": 800,
    "valid_rows": 795,
    "invalid_rows": 5,
    "duplicate_rows": 12
  },
  "started_at": "2024-01-20T10:30:05Z"
}

Resposta (Concluído)

{
  "job_id": "job_imp_789xyz",
  "status": "COMPLETED",
  "summary": {
    "total_rows": 1250,
    "imported": 1233,
    "duplicates_skipped": 12,
    "validation_errors": 5
  },
  "errors": [
    {
      "row": 45,
      "field": "amount",
      "error": "Invalid decimal format"
    },
    {
      "row": 89,
      "field": "date",
      "error": "Date before minimum allowed"
    },
    {
      "row": 234,
      "field": "currency",
      "error": "Unknown currency code: XXX"
    }
  ],
  "started_at": "2024-01-20T10:30:05Z",
  "completed_at": "2024-01-20T10:30:45Z"
}

Valores de status do job de importação

Status	Descrição
`QUEUED`	Job recebido, aguardando para iniciar
`PROCESSING`	Arquivo está sendo analisado e validado
`COMPLETED`	Importação finalizada com sucesso
`FAILED`	Importação falhou (verifique os erros)
`CANCELLED`	Importação foi cancelada

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 calculando um hash dos campos-chave:

transaction_id
source_id
amount
currency
date

Se uma transação com o mesmo hash já existir no sistema, ela é marcada como duplicata.

Opções de tratamento de duplicatas

Opção	Comportamento
`skip` (padrão)	Linhas duplicadas são ignoradas, dados existentes permanecem inalterados
`replace`	Linhas duplicadas substituem as transações existentes
`error`	Importação falha se duplicatas forem encontradas

Configure o comportamento de tratamento de duplicatas através das configurações de contexto ou fonte.

Visualizando detalhes de duplicatas

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

{
  "summary": {
    "total_rows": 1000,
    "imported": 950,
    "duplicates_skipped": 50,
    "validation_errors": 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?context_id={contextId}&status=PROCESSING" \
 -H "Authorization: Bearer $TOKEN"

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 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 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.

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

Introduction

Primeiros passos

Configurações

Reconciliação diária

Integrações

Referência

Enviando arquivos

Formatos suportados

Requisitos de estrutura do arquivo

Campos obrigatórios

Campos opcionais

Exemplos de formato

CSV

JSON

XML

Upload via API

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

Melhores práticas

Próximos passos

Revisando Correspondências

Mapeamento de Campos

Introduction

Primeiros passos

Configurações

Reconciliação diária

Integrações

Referência

​Formatos suportados

​Requisitos de estrutura do arquivo

​Campos obrigatórios

​Campos opcionais

​Exemplos de formato

​CSV

​JSON

​XML

​Upload via API

​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

​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

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

Melhores práticas

Próximos passos