Upload transaction file

curl --request POST \
  --url https://matcher.sandbox.lerian.net/v1/imports/contexts/{contextId}/sources/{sourceId}/upload \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: multipart/form-data' \
  --form file=@example-file \
  --form 'format=<string>'

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://matcher.sandbox.lerian.net/v1/imports/contexts/{contextId}/sources/{sourceId}/upload"

	payload := strings.NewReader("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"format\"\r\n\r\n<string>\r\n-----011000010111000001101001--")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "multipart/form-data")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

const form = new FormData();
form.append('file', '<string>');
form.append('format', '<string>');

const options = {method: 'POST', headers: {Authorization: 'Bearer <token>'}};

options.body = form;

fetch('https://matcher.sandbox.lerian.net/v1/imports/contexts/{contextId}/sources/{sourceId}/upload', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://matcher.sandbox.lerian.net/v1/imports/contexts/{contextId}/sources/{sourceId}/upload"

files = { "file": ("example-file", open("example-file", "rb")) }
payload = { "format": "<string>" }
headers = {"Authorization": "Bearer <token>"}

response = requests.post(url, data=payload, files=files, headers=headers)

print(response.text)

{
  "completedWithErrors": true,
  "contextId": "550e8400-e29b-41d4-a716-446655440000",
  "createdAt": "2025-01-15T10:30:00Z",
  "droppedDuplicateRows": 60,
  "failureRatePercent": 100,
  "flaggedDuplicateRows": 15,
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "persistedRows": 940,
  "reviewRows": 9,
  "sourceId": "550e8400-e29b-41d4-a716-446655440000",
  "status": "PROCESSING",
  "completedAt": "2025-01-15T10:35:00Z",
  "diagnosis": "file appears semicolon-delimited but the source declares comma; declare delimiter semicolon in the source dialect",
  "droppedDuplicateReason": "Rows repeated the duplicate key this source deduplicates on and were kept out of the import. This source flags duplicates, so each repeat whose original was found was attached to that original as a duplicate exception in the exceptions queue. Repeats of the same original share one exception, so the queue holds one item per repeated row, not one per repeat. The rest found no imported row to attach to (another import of this source may still have been in progress), so no exception was raised for them and they are not in the queue: re-upload those rows once every import of this source has finished. If unexpected, review the source's duplicate key and the fields it names (a coarse or truncated mapping collapses distinct rows onto one key).",
  "failedRows": 5,
  "fileName": "transactions_2024.csv",
  "startedAt": "2025-01-15T10:30:00Z",
  "totalRows": 1000
}

POST

imports

contexts

{contextId}

sources

{sourceId}

upload

Upload transaction file

curl --request POST \
  --url https://matcher.sandbox.lerian.net/v1/imports/contexts/{contextId}/sources/{sourceId}/upload \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: multipart/form-data' \
  --form file=@example-file \
  --form 'format=<string>'

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://matcher.sandbox.lerian.net/v1/imports/contexts/{contextId}/sources/{sourceId}/upload"

	payload := strings.NewReader("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"format\"\r\n\r\n<string>\r\n-----011000010111000001101001--")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "multipart/form-data")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

const form = new FormData();
form.append('file', '<string>');
form.append('format', '<string>');

const options = {method: 'POST', headers: {Authorization: 'Bearer <token>'}};

options.body = form;

fetch('https://matcher.sandbox.lerian.net/v1/imports/contexts/{contextId}/sources/{sourceId}/upload', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://matcher.sandbox.lerian.net/v1/imports/contexts/{contextId}/sources/{sourceId}/upload"

files = { "file": ("example-file", open("example-file", "rb")) }
payload = { "format": "<string>" }
headers = {"Authorization": "Bearer <token>"}

response = requests.post(url, data=payload, files=files, headers=headers)

print(response.text)

{
  "completedWithErrors": true,
  "contextId": "550e8400-e29b-41d4-a716-446655440000",
  "createdAt": "2025-01-15T10:30:00Z",
  "droppedDuplicateRows": 60,
  "failureRatePercent": 100,
  "flaggedDuplicateRows": 15,
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "persistedRows": 940,
  "reviewRows": 9,
  "sourceId": "550e8400-e29b-41d4-a716-446655440000",
  "status": "PROCESSING",
  "completedAt": "2025-01-15T10:35:00Z",
  "diagnosis": "file appears semicolon-delimited but the source declares comma; declare delimiter semicolon in the source dialect",
  "droppedDuplicateReason": "Rows repeated the duplicate key this source deduplicates on and were kept out of the import. This source flags duplicates, so each repeat whose original was found was attached to that original as a duplicate exception in the exceptions queue. Repeats of the same original share one exception, so the queue holds one item per repeated row, not one per repeat. The rest found no imported row to attach to (another import of this source may still have been in progress), so no exception was raised for them and they are not in the queue: re-upload those rows once every import of this source has finished. If unexpected, review the source's duplicate key and the fields it names (a coarse or truncated mapping collapses distinct rows onto one key).",
  "failedRows": 5,
  "fileName": "transactions_2024.csv",
  "startedAt": "2025-01-15T10:30:00Z",
  "totalRows": 1000
}

Autorizações

Authorization

string

header

obrigatório

Bearer token authentication (format: "Bearer {token}")

Cabeçalhos

X-Request-Id

string

A unique identifier for tracing the request across services.

X-Idempotency

string

Optional idempotency key for safe retries. Matcher reads the key only from this header, and only when you send one. A request that carries a key only in X-Idempotency-Key or Idempotency-Key is refused with 400 (MTCH-0015), and nothing is processed. If the same key is sent again and the original request was already processed, the stored response is returned with X-Idempotency-Replayed: true. A malformed key returns 400, a key whose first request is still in progress returns 409, and an idempotency storage failure returns 500. These refusals are problem documents.

Parâmetros de caminho

contextId

string<uuid>

obrigatório

The unique identifier of the reconciliation context. Context ID

sourceId

string<uuid>

obrigatório

The unique identifier of the reconciliation source. Source ID

Corpo

multipart/form-data

file

obrigatório

Transaction file (CSV, JSON, XML, or camt.053)

format

string

Canonical file-format key. Legacy flat keys (csv, json, xml, camt053) and namespaced keys (e.g. xx/delimited/generic, br/acquirer_csv/mercadopago) are accepted; discover the full set via GET /v1/imports/formats. Send before the file part. When omitted, inferred from the .csv/.json file extension.

Resposta

Indicates that the request was accepted for processing.

completedWithErrors

boolean

obrigatório

True when the job COMPLETED but at least one row failed — distinguishes a partially-failed import from a clean one

Exemplo:

true

contextId

string<uuid>

obrigatório

Reconciliation context this job belongs to

Exemplo:

"550e8400-e29b-41d4-a716-446655440000"

createdAt

string<date-time>

obrigatório

Creation timestamp (RFC 3339)

Exemplo:

"2025-01-15T10:30:00Z"

droppedDuplicateRows

integer<int64>

obrigatório

Number of rows kept out of the import as duplicates (rows repeating the source's duplicate key within the upload or already persisted); see flaggedDuplicateRows for how many were also raised as exceptions

Intervalo obrigatório: x >= 0

Exemplo:

60

failureRatePercent

integer<int64>

obrigatório

Percentage of rows that failed, ceiling-rounded so any failure registers as at least 1%; 0 when no rows failed

Intervalo obrigatório: 0 <= x <= 100

Exemplo:

100

flaggedDuplicateRows

integer<int64>

obrigatório

Number of dropped duplicate ROWS raised as DUPLICATE_TRANSACTION exceptions on the transaction they repeated, under the FLAG_AS_EXCEPTION duplicate policy — the default (subset of droppedDuplicateRows). Not a queue-item count: repeats of the same transaction share one exception, which carries how many times it was repeated

Intervalo obrigatório: x >= 0

Exemplo:

15

string<uuid>

obrigatório

Unique identifier for the job

Exemplo:

"550e8400-e29b-41d4-a716-446655440000"

persistedRows

integer<int64>

obrigatório

Number of transactions actually persisted by this job (additive diagnostics field; see also droppedDuplicateRows)

Intervalo obrigatório: x >= 0

Exemplo:

940

reviewRows

integer<int64>

obrigatório

Number of rows imported with status PENDING_REVIEW under the blank_external_id=NEEDS_REVIEW source policy — successful imports awaiting operator review, never counted as failures

Intervalo obrigatório: x >= 0

Exemplo:

9

sourceId

string<uuid>

obrigatório

Source this job ingests data into

Exemplo:

"550e8400-e29b-41d4-a716-446655440000"

status

enum<string>

obrigatório

Job lifecycle status: QUEUED (awaiting a worker), PROCESSING (parsing/normalizing rows), COMPLETED (finished), FAILED (aborted wholesale)

Opções disponíveis:

QUEUED,

PROCESSING,

COMPLETED,

FAILED

Exemplo:

"PROCESSING"

completedAt

string<date-time>

When the job completed (RFC 3339); null until completed

Exemplo:

"2025-01-15T10:35:00Z"

diagnosis

string

Safe one-line diagnosis of anything the parser found worth reporting about the file (dialect mismatch, degraded settlement re-join, zero-detail file), the rate-policy message for policy-FAILED jobs, or a generic safe message for other FAILED jobs. Present on COMPLETED jobs too, including ones with zero failed rows; empty when there is nothing to report — internal error detail is never surfaced here

Exemplo:

"file appears semicolon-delimited but the source declares comma; declare delimiter semicolon in the source dialect"

droppedDuplicateReason

string

Display-only explanation of why droppedDuplicateRows rows were kept out of the import: names the source's duplicate key as the identity that collided, says the repeats were attached as exceptions to the rows they repeated when the job flagged any (repeats of one row share one exception, so the queue holds one item per repeated row), and names the repeats that raised nothing when fewer were flagged than dropped, so the count does not read as silent data loss and the customer is sent to the configuration that decides it. Empty unless droppedDuplicateRows > 0

Exemplo:

"Rows repeated the duplicate key this source deduplicates on and were kept out of the import. This source flags duplicates, so each repeat whose original was found was attached to that original as a duplicate exception in the exceptions queue. Repeats of the same original share one exception, so the queue holds one item per repeated row, not one per repeat. The rest found no imported row to attach to (another import of this source may still have been in progress), so no exception was raised for them and they are not in the queue: re-upload those rows once every import of this source has finished. If unexpected, review the source's duplicate key and the fields it names (a coarse or truncated mapping collapses distinct rows onto one key)."

failedRows

integer<int64>

Number of rows that failed parsing or normalization

Intervalo obrigatório: x >= 0

Exemplo:

5

fileName

string

Original uploaded file name

Exemplo:

"transactions_2024.csv"

startedAt

string<date-time>

When the job started (RFC 3339); null for QUEUED jobs

Exemplo:

"2025-01-15T10:30:00Z"

totalRows

integer<int64>

Total number of data rows detected in the file

Intervalo obrigatório: x >= 0

Exemplo:

1000

Primeiros passos

API de Contextos de Configuração

API de Regras de Correspondência

API de Fontes de Dados

API de Mapeamento de Campos

API de Tabelas de Tarifas

API de Configuração de Regras de Tarifas

API de Agendamentos

Fluxo de exceções

Ações em massa

Comentários

Credenciais de callback

API de Disputas

API de Jobs de Exportação

API de Governança

Jobs de ingestão

Layouts e formatos

Revisões de extração

Extração de documentos

Execuções de correspondência

Correspondência manual e ajustes

Candidatos e itens em aberto

Sugestões de regras

Painel e métricas

Relatórios

Exportações

Status da descoberta

Conexões de descoberta

Extrações

Conexões de agregadores

Webhooks de agregadores

Tratamento de erros

Eventos

Upload transaction file

Autorizações

Cabeçalhos

Parâmetros de caminho

Corpo

Resposta