> ## Documentation Index
> Fetch the complete documentation index at: https://docs.3xpay.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Abrir Disputa de MED

> Cria o registro inicial da contestação a partir do UUID da transação contestada. Após esta chamada, o status fica em `WAITING_CONTENT` aguardando o upload da evidência via PATCH.

Cria o registro inicial da contestação para uma transação em estado de MED. Após esta chamada o status fica em `WAITING_CONTENT` aguardando o upload da evidência via `PATCH /med-contest/exposes/{medId}`.

<Note>
  O `id` retornado nesta resposta é o **medId** usado nos endpoints subsequentes (detalhe e envio de evidência).
</Note>

<Info>
  **Importante:** o `transaction_id` aqui é o **UUID** recebido no webhook de infração (com `transactionStatus = "MED"`), **não** o ID numérico interno.
</Info>


## OpenAPI

````yaml POST /med-contest/exposes
openapi: 3.0.1
info:
  title: 3X Pay Gateway
  description: >-
    Para autenticar as rotas dessa API são necessario ter em mãos a
    **api_secret** e **api_key** da sua conta. Este podem ser encontrados dentro
    do painel https://app.3xpay.co acessando a página de Configurações e
    clicando na opção de Credencias de API.
  version: 1.0.0
servers:
  - url: https://gateway.3xpay.co
security:
  - apiKeyAuth: []
    apiSecretAuth: []
tags:
  - name: Transações
    description: Operações relacionadas a transações financeiras
  - name: Webhooks
    description: Notificações de eventos da API
  - name: Balance
    description: Operações relacionadas ao saldo da conta
  - name: Sub-accounts
    description: Operações relacionadas a subcontas BaaS
  - name: MED Contest
    description: >-
      Endpoints server-to-server para responder a solicitações de MED (Mecanismo
      Especial de Devolução do Pix)
paths:
  /med-contest/exposes:
    post:
      tags:
        - MED Contest
      summary: Abrir disputa de MED
      description: >-
        Cria o registro inicial da contestação a partir do UUID da transação
        contestada. Após esta chamada, o status fica em `WAITING_CONTENT`
        aguardando o upload da evidência via PATCH.
      operationId: createMedContest
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateMedContestRequest'
      responses:
        '201':
          description: Disputa criada com sucesso
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MedContestRecord'
        '400':
          description: Erro de validação ou disputa já existente
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                invalidUuid:
                  summary: transaction_id inválido
                  value:
                    error: 400
                    message: transaction_id deve ser um UUID válido.
                alreadyExists:
                  summary: Disputa já existente para a transação
                  value:
                    error: 400
                    message: >-
                      Já existe uma disputa de MED para esta transação. Use GET
                      /med-contest/exposes/:medId para recuperar o registro
                      existente.
        '404':
          description: Transação não encontrada
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                notFound:
                  summary: Transação não pertence à conta autenticada
                  value:
                    error: 404
                    message: Transação não encontrada para sua conta.
components:
  schemas:
    CreateMedContestRequest:
      type: object
      required:
        - transaction_id
      properties:
        transaction_id:
          type: string
          format: uuid
          description: >-
            UUID da transação contestada, recebido no webhook IN com
            `transactionStatus = MED`.
          example: 01a51b3e-e17d-45eb-b8a2-e2392b6b1b28
    MedContestRecord:
      type: object
      description: >-
        Registro da disputa de MED. O campo `id` é o `medId` usado nos demais
        endpoints.
      properties:
        id:
          type: integer
          description: ID numérico da disputa (medId).
          example: 1024
        transactionId:
          type: integer
          description: ID interno da transação relacionada.
          example: 50231
        status:
          $ref: '#/components/schemas/MedContestStatus'
        content:
          type: string
          nullable: true
          description: >-
            URL do arquivo de evidência armazenado. `null` enquanto a evidência
            não foi enviada.
          example: https://s3.../comprovante.pdf
        description:
          type: string
          nullable: true
          description: Descrição/texto da defesa enviada com a evidência.
          example: Comprovante de pagamento original.
        external_med_id:
          type: string
          nullable: true
          description: ID da disputa no PSP upstream (preenchido após o envio).
          example: dispute_8f3a...
        processor_name:
          type: string
          nullable: true
          description: Nome do PSP upstream que recebeu a defesa.
          example: woovi
        retry_count:
          type: integer
          description: Quantidade de tentativas de envio.
          example: 0
        last_error:
          type: string
          nullable: true
          description: Mensagem do último erro de transporte, se houver.
        created_at:
          type: string
          format: date-time
          example: '2026-05-12T10:30:00.000Z'
        updated_at:
          type: string
          format: date-time
          example: '2026-05-12T10:30:00.000Z'
    Error:
      required:
        - error
        - message
      type: object
      properties:
        error:
          type: integer
          format: int32
        message:
          type: string
    MedContestStatus:
      type: string
      description: Status do registro de disputa.
      enum:
        - WAITING_CONTENT
        - REQUESTED
        - DEFENSE_SUBMITTED
        - DEFENSE_FAILED
        - APPROVED
        - REJECTED
        - REFUNDED
        - CANCELLED
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: api_key
    apiSecretAuth:
      type: apiKey
      in: header
      name: api_secret

````