> ## 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. # Propor um mapeamento de mapa-de-campo/dialeto apenas em configuração para uma amostra de origem > Inspeciona uma amostra representativa de um arquivo de origem e retorna uma proposta de mapeamento/dialeto APENAS EM CONFIGURAÇÃO (sugestões de coluna→chave-canônica, dialeto, confiança e justificativa por campo). É CONSULTIVA e sem efeitos colaterais: produzir uma proposta NÃO PERSISTE NADA. O operador revisa a proposta e a confirma pelo caminho EXISTENTE de declaração de mapa de campo. O tenant é resolvido do JWT e o contexto/origem do path — nunca do corpo. A resposta nunca carrega valores parseados, valores monetários ou transações. ## OpenAPI ````yaml pt/openapi/v3-current/matcher.yaml post /v1/imports/contexts/{contextId}/sources/{sourceId}/mapping-proposal 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/imports/contexts/{contextId}/sources/{sourceId}/mapping-proposal: post: tags: - Ingestion summary: >- Propor um mapeamento de mapa-de-campo/dialeto apenas em configuração para uma amostra de origem description: >- Inspeciona uma amostra representativa de um arquivo de origem e retorna uma proposta de mapeamento/dialeto APENAS EM CONFIGURAÇÃO (sugestões de coluna→chave-canônica, dialeto, confiança e justificativa por campo). É CONSULTIVA e sem efeitos colaterais: produzir uma proposta NÃO PERSISTE NADA. O operador revisa a proposta e a confirma pelo caminho EXISTENTE de declaração de mapa de campo. O tenant é resolvido do JWT e o contexto/origem do path — nunca do corpo. A resposta nunca carrega valores parseados, valores monetários ou transações. operationId: proposeMapping parameters: - description: Context ID in: path name: contextId required: true schema: description: ID do contexto format: uuid type: string - description: Source ID in: path name: sourceId required: true schema: description: ID da origem format: uuid type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/ProposeMappingRequest' required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/MappingProposalResponse' description: OK default: content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Erro security: - BearerAuth: [] components: schemas: ProposeMappingRequest: additionalProperties: false properties: format: description: Dica de formato de arquivo declarado enum: - csv - json - xml - camt053 examples: - csv type: string hints: additionalProperties: type: string description: >- Dicas de operador não secretas opcionais (ex.: locale=pt-BR, has_header=true) type: object sample: description: Amostra representativa de arquivo de origem examples: - | id;value;ccy;posted_at A1;10,50;BRL;2025-06-01 minLength: 1 type: string required: - sample type: object MappingProposalResponse: additionalProperties: false properties: dialect: $ref: '#/components/schemas/DialectResponse' description: >- Dialeto de origem proposto; null quando o advisor não tem sugestão de dialeto fields: description: Detalhamento por campo que embasa o mapeamento proposto items: $ref: '#/components/schemas/FieldProposalResponse' type: - array - 'null' mapping: additionalProperties: {} description: >- Mapa de campo canônico proposto (chave canônica -> coluna de origem); null quando o advisor não pôde propor um mapeamento type: object required: - fields 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 DialectResponse: additionalProperties: false properties: dateStyle: description: >- Convenção de data detectada: iso (YYYY-MM-DD), iso_offset (RFC 3339 com offset), dmy (DD/MM/YYYY) ou mdy (MM/DD/YYYY) examples: - iso type: string decimalStyle: description: >- Convenção decimal de valor detectada: ponto (1234.56) ou vírgula (1234,56) examples: - comma type: string delimiter: description: >- Separador de campo CSV detectado: vírgula, ponto e vírgula, tab ou pipe examples: - semicolon type: string encoding: description: >- Codificação de caracteres do arquivo detectada: utf-8, utf-8-sig (UTF-8 com BOM), cp1252 (Windows Latin-1) ou iso-8859-1 examples: - utf-8 type: string required: - encoding - delimiter - decimalStyle - dateStyle type: object FieldProposalResponse: additionalProperties: false properties: canonicalKey: description: Chave canônica de mapa de campo que a proposta visa examples: - amount type: string confidence: description: >- Confiança do advisor neste mapeamento, de 0.0 (nenhuma) a 1.0 (certa) examples: - 0.92 format: double maximum: 1 minimum: 0 type: number rationale: description: Explicação curta e legível por humanos para a sugestão examples: - numeric column with comma decimal type: string sourceColumn: description: Coluna de origem proposta que alimenta a chave canônica examples: - value type: string required: - canonicalKey - sourceColumn - confidence - rationale 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 securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: JWT description: 'Autenticação por Bearer token (formato: "Bearer {token}")' ````