> ## 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. # Listar candidatos a correspondência de uma transação > Retorna uma lista ranqueada de transações não correspondidas do lado oposto que o engine considera contrapartes plausíveis para a transação alvo, cada uma com uma pontuação de confiança, a regra que a impulsionou, uma justificativa por componente (o "porquê") e deltas de valor/data. Alimenta os seletores de candidatos de resolução-de-exceção e correspondência-manual. Escopo: propostas são pontuadas pelo engine de regras determinístico sobre valores brutos de transação e NÃO aplicam normalização de taxa em tempo de execução nem a faixa de variância FX; apenas contrapartes 1:1 par a par são retornadas. ## OpenAPI ````yaml pt/openapi/v3-current/matcher.yaml get /v1/matching/candidates openapi: 3.1.0 info: title: Matcher APIs description: >- Referência completa de API para o motor de conciliação Matcher, que fornece conciliação automática de transações entre o Midaz Ledger e sistemas externos. version: 4.1.0 license: name: Elastic License 2.0 url: https://www.elastic.co/licensing/elastic-license servers: - url: https://matcher.sandbox.lerian.net security: [] paths: /v1/matching/candidates: get: tags: - Matching summary: Listar candidatos a correspondência de uma transação description: >- Retorna uma lista ranqueada de transações não correspondidas do lado oposto que o engine considera contrapartes plausíveis para a transação alvo, cada uma com uma pontuação de confiança, a regra que a impulsionou, uma justificativa por componente (o "porquê") e deltas de valor/data. Alimenta os seletores de candidatos de resolução-de-exceção e correspondência-manual. Escopo: propostas são pontuadas pelo engine de regras determinístico sobre valores brutos de transação e NÃO aplicam normalização de taxa em tempo de execução nem a faixa de variância FX; apenas contrapartes 1:1 par a par são retornadas. operationId: listMatchCandidates parameters: - description: Context ID the transaction belongs to explode: false in: query name: contextId required: true schema: description: ID do contexto ao qual a transação pertence format: uuid type: string - description: >- Target transaction to find counterparts for. For an exception, resolve its transaction id first, then pass it here. explode: false in: query name: transactionId required: true schema: description: >- Transação alvo para a qual encontrar contrapartes. Para uma exceção, resolva primeiro seu ID de transação e então passe-o aqui. format: uuid type: string - description: Maximum number of ranked proposals to return explode: false in: query name: limit schema: default: 50 description: Número máximo de propostas ranqueadas a retornar format: int64 maximum: 200 minimum: 1 type: integer responses: '200': content: application/json: schema: $ref: '#/components/schemas/CandidateProposalsResponse' description: OK default: content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Erro security: - BearerAuth: [] components: schemas: CandidateProposalsResponse: additionalProperties: false properties: items: description: Propostas candidatas ranqueadas (maior pontuação primeiro) items: $ref: '#/components/schemas/CandidateProposalResponse' maxItems: 200 type: - array - 'null' targetTransactionId: description: A transação para a qual as contrapartes foram propostas examples: - 550e8400-e29b-41d4-a716-446655440000 type: string required: - targetTransactionId - items type: object Detail: additionalProperties: false properties: code: description: >- Código de erro de domínio estável e legível por máquina com escopo no serviço emissor (formato: -NNNN). examples: - ERR-0001 type: string detail: description: >- Uma explicação legível por humanos específica para esta ocorrência do problema. examples: - Property foo is required but is missing. type: string errors: description: Lista opcional de detalhes de erro individuais items: $ref: '#/components/schemas/ErrorDetail' type: - array - 'null' instance: description: >- Uma referência URI que identifica a ocorrência específica do problema. examples: - https://example.com/error-log/abc123 format: uri type: string status: description: Código de status HTTP examples: - 400 format: int64 type: integer title: description: >- Um resumo curto e legível por humanos do tipo do problema. Este valor não deve mudar entre ocorrências do erro. examples: - Bad Request type: string type: default: about:blank description: >- Uma referência URI para documentação legível por humanos sobre o erro. examples: - https://example.com/errors/example format: uri type: string type: object CandidateProposalResponse: additionalProperties: false properties: amountDelta: description: candidate.amount - target.amount como uma string decimal com sinal examples: - '0.00' type: string dateDeltaDays: description: >- Diferença de dias inteiros com sinal (candidate - target) em dias UTC examples: - 0 format: int64 type: integer ruleId: description: Identificador da regra que produziu a melhor pontuação para este par examples: - 550e8400-e29b-41d4-a716-446655440000 type: string ruleType: description: Estratégia da regra que produziu a melhor pontuação examples: - EXACT type: string score: description: Pontuação de confiança do engine para este par (0..100) examples: - 90 format: int64 maximum: 100 minimum: 0 type: integer transaction: $ref: '#/components/schemas/CandidateTransactionView' description: A transação de contraparte proposta why: $ref: '#/components/schemas/CandidateWhy' description: Justificativa por componente para a pontuação required: - transaction - ruleId - ruleType - score - why - amountDelta - dateDeltaDays type: object ErrorDetail: additionalProperties: false properties: location: description: 'Onde o erro ocorreu, ex.: ''body.items[3].tags'' ou ''path.thing-id''' type: string message: description: Texto da mensagem de erro type: string value: description: O valor na localização informada type: object CandidateTransactionView: additionalProperties: false properties: amount: description: Valor candidato como string decimal examples: - '100.50' type: string baseAmount: description: >- Valor candidato na moeda base, quando a transação foi convertida em FX examples: - '100.50' type: string currency: description: Código de moeda candidato ISO 4217 examples: - USD type: string date: description: Data da transação candidata (timestamp RFC 3339) examples: - '2025-01-15T10:30:00Z' type: string externalId: description: Referência/ID externo da transação candidata examples: - INV-1234 type: string id: description: ID da transação candidata (UUID) examples: - 550e8400-e29b-41d4-a716-446655440000 type: string sourceId: description: Origem à qual o candidato pertence (UUID) examples: - 550e8400-e29b-41d4-a716-446655440001 type: string required: - id - sourceId - amount - currency - date type: object CandidateWhy: additionalProperties: false properties: amountMatch: description: >- Se os valores são literalmente iguais no eixo de sinal da regra correspondida (não meramente dentro da tolerância) examples: - true type: boolean currencyMatch: description: Se os códigos de moeda são literalmente iguais e ambos não vazios examples: - true type: boolean dateMatch: description: >- Se ambas as transações caem no mesmo dia calendário UTC (não a janela DATE_LAG completa) examples: - true type: boolean matchedKeys: description: >- Concordância por chave para os campos de correspondência compostos configurados da regra correspondida (matchFields), em ordem de nome de campo. Vazio quando a regra correspondida não declara matchFields ativos. items: $ref: '#/components/schemas/CandidateMatchedKey' type: - array - 'null' referenceScore: description: Contribuição de similaridade de referência graduada de 0 a 1 examples: - 1 format: double maximum: 1 minimum: 0 type: number required: - amountMatch - currencyMatch - dateMatch - referenceScore type: object CandidateMatchedKey: additionalProperties: false properties: agreed: description: >- Se as duas transações concordam sobre esta chave sob o modo/tolerância configurado do campo — a própria decisão de gate por campo do engine examples: - true type: boolean field: description: >- Nome do campo de correspondência composto configurado (chave de metadados) examples: - payment_id type: string required: - field - agreed type: object securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: JWT description: 'Autenticação por Bearer token (formato: "Bearer {token}")' ````