> ## 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. # Simular uma regra de correspondência contra um contexto (execução seca somente leitura) > Pré-visualiza como uma única regra — uma regra configurada existente (ruleId) OU uma regra candidata inline (rule) — corresponderia às transações não correspondidas de um contexto, SEM comprometer nada. Retorna o número de grupos 1:1 que a regra formaria, uma amostra limitada de pares que corresponderiam (cada um com uma pontuação de confiança, uma justificativa por componente (o "porquê") e chaves compostas correspondidas), e as contagens de não correspondidos por lado. Alimenta a pré-visualização "esta regra realmente vai corresponder?" da autoria de regras. Escopo: pontuado pelo engine de regras determinístico sobre valores brutos de transação; NÃO aplica normalização de taxa em tempo de execução nem a faixa de variância FX, e pré-visualiza apenas agrupamento 1:1 par a par (sem alocação 1:N/N:M). Nada é persistido; o tenant é tomado do JWT, nunca do corpo. ## OpenAPI ````yaml pt/openapi/v3-current/matcher.yaml post /v1/matching/simulate 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/simulate: post: tags: - Matching summary: >- Simular uma regra de correspondência contra um contexto (execução seca somente leitura) description: >- Pré-visualiza como uma única regra — uma regra configurada existente (ruleId) OU uma regra candidata inline (rule) — corresponderia às transações não correspondidas de um contexto, SEM comprometer nada. Retorna o número de grupos 1:1 que a regra formaria, uma amostra limitada de pares que corresponderiam (cada um com uma pontuação de confiança, uma justificativa por componente (o "porquê") e chaves compostas correspondidas), e as contagens de não correspondidos por lado. Alimenta a pré-visualização "esta regra realmente vai corresponder?" da autoria de regras. Escopo: pontuado pelo engine de regras determinístico sobre valores brutos de transação; NÃO aplica normalização de taxa em tempo de execução nem a faixa de variância FX, e pré-visualiza apenas agrupamento 1:1 par a par (sem alocação 1:N/N:M). Nada é persistido; o tenant é tomado do JWT, nunca do corpo. operationId: simulateMatchRule requestBody: content: application/json: schema: $ref: '#/components/schemas/SimulateMatchRequest' required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/SimulateMatchResponse' description: OK default: content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Erro security: - BearerAuth: [] components: schemas: SimulateMatchRequest: additionalProperties: false properties: contextId: description: ID do contexto contra cujas transações a regra é simulada format: uuid type: string rule: $ref: '#/components/schemas/SimulateRuleDefinition' description: >- Regra candidata inline para pré-visualizar. Forneça esta OU ruleId, não ambos. ruleId: description: >- Identificador de uma regra configurada existente a pré-visualizar. Forneça esta OU rule, não ambas. format: uuid type: string sampleLimit: default: 25 description: Número máximo de pares que corresponderiam a retornar na amostra format: int64 maximum: 200 minimum: 1 type: integer required: - contextId type: object SimulateMatchResponse: additionalProperties: false properties: matchedGroups: description: Número de grupos 1:1 que a regra formaria no contexto examples: - 12 format: int64 minimum: 0 type: integer ruleId: description: >- Identificador da regra pré-visualizada. Vazio para uma regra candidata inline (não persistida). examples: - 550e8400-e29b-41d4-a716-446655440000 type: string ruleType: description: Estratégia da regra pré-visualizada examples: - EXACT type: string sample: description: >- Amostra limitada de pares que corresponderiam (maior pontuação primeiro) items: $ref: '#/components/schemas/SimulateMatchPairResponse' maxItems: 200 type: - array - 'null' sampleTruncated: description: Se matchedGroups excede o comprimento da amostra retornada examples: - false type: boolean unmatchedLeft: description: Transações do lado esquerdo que permaneceriam sem correspondência examples: - 3 format: int64 minimum: 0 type: integer unmatchedRight: description: Transações do lado direito que permaneceriam sem correspondência examples: - 5 format: int64 minimum: 0 type: integer required: - ruleType - matchedGroups - unmatchedLeft - unmatchedRight - sampleTruncated - sample 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 SimulateRuleDefinition: additionalProperties: false properties: config: additionalProperties: {} description: >- Configuração de regra, mesmo formato que a config de uma regra de correspondência armazenada (ex.: matchAmount, matchCurrency, configurações de tolerância) type: object type: description: Estratégia de regra da regra candidata inline examples: - EXACT type: string required: - type - config type: object SimulateMatchPairResponse: additionalProperties: false properties: amountDelta: description: right.amount - left.amount como uma string decimal com sinal examples: - '0.00' type: string dateDeltaDays: description: Diferença de dias inteiros com sinal (right - left) em dias UTC examples: - 0 format: int64 type: integer left: $ref: '#/components/schemas/CandidateTransactionView' description: >- Transação do pool esquerdo (o lado esquerdo da regra) que o par agruparia right: $ref: '#/components/schemas/CandidateTransactionView' description: >- Transação do pool direito (o lado direito da regra) que o par agruparia score: description: Pontuação de confiança do engine para este par (0..100) examples: - 90 format: int64 maximum: 100 minimum: 0 type: integer why: $ref: '#/components/schemas/CandidateWhy' description: Justificativa por componente para a pontuação required: - left - right - 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}")' ````