> ## 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. # Enviando arquivos > Importe dados de transações para o Matcher a partir de arquivos CSV, JSON ou XML usando a estrutura de campos suportada e as regras de ingestão. 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** ```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 campos 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 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 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. ```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: [Preview file](/pt/reference/matcher/preview-upload) ### Upload de arquivo único ```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 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](/pt/reference/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 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: [Get import status](/pt/reference/matcher/retrieve-ingestion-job) #### Resposta (Processando) ```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ído) ```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 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 Verifica se o arquivo é um CSV, JSON ou XML válido com estrutura correta. Verifica se os campos obrigatórios estão presentes e correspondem ao mapeamento de campos configurado. Valida se os valores são decimais válidos, datas são interpretáveis, moedas são códigos ISO válidos. 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: ```json theme={null} { "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 ```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" ``` ### Aguardar todas as importações Antes de executar a conciliação, certifique-se de que todas as importações estejam concluídas: ```bash theme={null} # 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. ```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: [Search transactions](/pt/reference/matcher/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 *** Verifique o formato e codificação do arquivo localmente antes de enviar. Isso detecta erros óbvios mais rapidamente. ```bash theme={null} # Check CSV is valid head -5 transactions.csv # Check encoding file transactions.csv ``` Padronize no 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 de transação únicos do sistema de origem. Isso permite a detecção adequada de duplicatas e trilhas de auditoria. Decida uma convenção (negativo para débitos, positivo para créditos) e aplique-a consistentemente. Documente isso no seu mapeamento de campos. Para arquivos muito grandes (>50MB), considere dividir em partes menores por intervalo de datas. Isso melhora a confiabilidade e permite novas tentativas parciais. Para reconciliação recorrente, automatize o envio de arquivos 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 *** Aprenda como interpretar resultados de correspondência e pontuações de confiança. Configure como os campos de origem mapeiam para o schema do Matcher.