> ## Documentation Index > Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt > Use this file to discover all available pages before exploring further. # Upload de arquivos > Importe dados de transações para o Matcher a partir de CSV, JSON, XML ou formatos bancários como camt.053. Pré-visualize a detecção de colunas e depois envie os arquivos para uma fonte. 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](https://docs.lerian.studio/pt/products/matcher/imports/matcher-import-formats.md) 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](#debit-and-credit-column). | 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}`: ```json theme={null} "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** ```csv theme={null} 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** ```json theme={null} [ { "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 theme={null} BANK-2024-001 1500.00 USD 2024-01-15 Invoice #1234 credit BANK-2024-002 250.00 USD 2024-01-15 Service fee debit ``` ## 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. ```bash cURL theme={null} 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 ```json theme={null} { "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" } ``` > [!TIP] > > Referência da API: [Pré-visualizar arquivo](https://docs.lerian.studio/pt/reference/products/matcher/preview-upload.md) ### Upload de um único arquivo ```bash cURL theme={null} 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" ``` > [!NOTE] > > 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`. > [!NOTE] > > 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`). > [!TIP] > > Referência da API: [Enviar arquivo](https://docs.lerian.studio/pt/reference/products/matcher/upload-transaction-file.md) #### Resposta ```json theme={null} { "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 ```bash cURL theme={null} curl -X GET https://api.matcher.example.com/v1/imports/contexts/{contextId}/jobs/{jobId} \ -H "Authorization: Bearer $TOKEN" ``` > [!TIP] > > Referência da API: [Obter status da importação](https://docs.lerian.studio/pt/reference/products/matcher/retrieve-ingestion-job.md) #### Resposta (em processamento) ```json theme={null} { "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) ```json theme={null} { "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" } ``` > [!NOTE] > > 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 **1. Validação de formato** Verifica se o arquivo é um CSV, JSON ou XML válido com a estrutura correta. **2. Validação de schema** Confere se os campos obrigatórios estão presentes e batem com o mapa de campos configurado. **3. 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: ```json theme={null} { "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 ```bash theme={null} # 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. ```bash theme={null} # 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. ```bash cURL theme={null} 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 ```json theme={null} { "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 } ``` > [!TIP] > > Referência da API: [Buscar transações](https://docs.lerian.studio/pt/reference/products/matcher/search-transactions.md) 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 *** > [accordion] 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. > > ```bash theme={null} > # Check CSV is valid > head -5 transactions.csv > > # Check encoding > file transactions.csv > ``` > [accordion] 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. > [accordion] 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. > [accordion] 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. > [accordion] 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. > [accordion] Configure uploads automatizados > > Para conciliação recorrente, automatize os uploads de arquivo usando jobs agendados. > > ```bash theme={null} > # Example: Daily upload via cron > 0 6 * * * /scripts/upload_bank_statement.sh > ``` ## Próximos passos *** > [card] [Revisão de correspondências](https://docs.lerian.studio/pt/products/matcher/daily-reconciliation/matcher-reviewing-matches.md) > > Veja como interpretar os resultados de correspondência e as pontuações de confiança. > [card] [Mapeamento de campos](https://docs.lerian.studio/pt/products/matcher/configuration/matcher-field-mapping.md) > > Configure como os campos da fonte mapeiam para o schema do Matcher. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.