> ## 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](/pt/products/matcher/imports/matcher-import-formats) 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 | | ---------------- | ------------- | ----------------------------------------- | | `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 | A outra parte da transação | | `type` | String | Tipo da transação (crédito, débito etc.) | | `metadata` | Object | Campos personalizados adicionais | ## Exemplos de formato *** ### CSV **Requisitos do CSV:** * A primeira linha deve ser o cabeçalho das colunas * Codificação UTF-8 * Delimitador vírgula (configurável) * 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:** * O elemento raiz deve ser um array * Nomes de campo consistentes entre os objetos * Codificação UTF-8 **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 válido com declaração * Elemento raiz contendo os elementos de transação * Codificação UTF-8 **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" } ``` Referência da API: [Pré-visualizar arquivo](/pt/reference/products/matcher/preview-upload) ### 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" ``` 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 upload retorna **202 Accepted** com o job criado. O limite de upload é **1 GiB** por padrão e vale para toda a requisição multipart, incluindo cada parte, header e boundary, não apenas o arquivo. Você pode configurar `ingestion.max_upload_bytes` de **1 MiB** até **8 GiB**. Referência da API: [Enviar arquivo](/pt/reference/products/matcher/upload-transaction-file) #### Resposta ```json theme={null} { "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 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" ``` Referência da API: [Obter status da importação](/pt/reference/products/matcher/retrieve-ingestion-job) #### 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", "totalRows": 1250, "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" } ``` 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. ### Valores de status do job de importação | Status | Descrição | | ------------ | ---------------------------------------------------------------------- | | `QUEUED` | Job recebido, aguardando um worker | | `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 Verifica se o arquivo é um CSV, JSON ou XML válido com a estrutura correta. Confere se os campos obrigatórios estão presentes e batem com o mapa de campos configurado. 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. Aplica regras específicas do contexto, como intervalos de datas, limites de valor etc. ### Erros comuns de validação | Erro | Causa | Solução | | ------------------------ | ---------------------------------------- | ------------------------------------------------- | | `INVALID_FORMAT` | O arquivo não pode ser interpretado | Verifique a codificação e a estrutura do arquivo | | `MISSING_REQUIRED_FIELD` | Campo obrigatório não encontrado | Confira a configuração de mapeamento de campos | | `INVALID_AMOUNT` | O valor não é um número válido | Procure símbolos de moeda ou vírgulas nos números | | `INVALID_DATE` | A 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, o Matcher importa as linhas válidas mesmo se algumas linhas têm erros. Configure o comportamento de tratamento de erros nas configurações do contexto ou trate os erros depois que a importação termina, revisando a resposta de status do job. ## Detecção de duplicatas *** O Matcher detecta e trata transações duplicadas automaticamente para evitar contagem em dobro. ### Como as duplicatas são detectadas Uma chave de deduplicação com escopo na fonte identifica as duplicatas. 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 você precisa de uma identidade composta. Você deve mapear cada campo selecionado. As fontes vinculadas a agregador não podem declarar uma chave personalizada, porque as retratações delas usam o `external_id`. Se uma linha repete essa chave (dentro do mesmo upload ou contra dados já persistidos), o Matcher a trata como duplicata. Uma mudança em `duplicate_key` afeta apenas as importações seguintes. As linhas importadas antes mantêm as chaves que já têm. ### 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 é 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, "flaggedDuplicateRows": 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 "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" ``` ### 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 } ``` Referência da API: [Buscar transações](/pt/reference/products/matcher/search-transactions) Os filtros aceitos incluem `amount_min`, `amount_max`, `date_from`, `date_to`, `currency`, `source_id`, `status` e a busca em texto livre pelo parâmetro `q`. ## Boas práticas *** 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 ``` Padronize o formato ISO 8601 (`YYYY-MM-DD` ou `YYYY-MM-DDTHH:MM:SSZ`) em todas as fontes para evitar problemas de interpretação. Sempre inclua IDs únicos de transação do sistema de origem. Isso permite uma detecção de duplicatas correta e trilhas de auditoria. Defina uma convenção (negativo para débitos, positivo para créditos) e aplique-a de forma consistente. Documente isso no seu mapeamento de campos. 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. Para conciliação recorrente, automatize os uploads de arquivo usando jobs agendados ou webhooks dos sistemas de origem. ```bash theme={null} # Example: Daily upload via cron 0 6 * * * /scripts/upload_bank_statement.sh ``` ## Próximos passos *** Veja como interpretar os resultados de correspondência e as pontuações de confiança. Configure como os campos da fonte mapeiam para o schema do Matcher.