Conferir a chave PIX de um agregado

{
  "tags": [
    "Agregados"
  ],
  "summary": "Conferir a chave PIX de um agregado",
  "operationId": "conferirChavePixDoAgregado",
  "description": "**A chave PIX que este agregado me passou é a mesma que consta com vocês?**\n\nVocê manda o par (documento, chave) e recebe sim/não. É a conferência que vale a pena\nfazer **antes** de o dinheiro sair — principalmente quando a chave chegou por e-mail,\nWhatsApp ou num cadastro que alguém digitou.\n\n**O caso que este endpoint existe para pegar é `situacao: \"chave_de_outro_titular\"`:** a\nchave é real, está na sua base, e está cadastrada para **outro** agregado seu. É a\nassinatura da troca de chave — o golpe em que o pagamento sai certinho para a conta\nerrada. Um `if (chave === chaveQueTenhoNoERP)` do seu lado não pega isso.\n\n| `situacao` | O que fazer |\n|---|---|\n| `vinculada` | Segue o pagamento. |\n| `chave_de_outro_titular` | **Pare.** Confirme com o favorecido por um canal que você já usava antes. |\n| `nao_cadastrada` | Olhe `documento_possui_chave` antes de decidir (abaixo). |\n\n> ### Isto NÃO é uma consulta ao DICT do Bacen\n>\n> A resposta é sobre **o que está cadastrado na FleetPay**, não sobre a titularidade da\n> chave no arranjo de pagamentos. `vinculada: false` quer dizer \"não é a chave que consta\n> aqui\" — **nunca** \"esta chave não é dessa pessoa\". Tratar o `false` como prova de fraude\n> barra pagamento legítimo de agregado que simplesmente nunca cadastrou chave externa com\n> a gente. É para isso que existe o `documento_possui_chave`: com `false`, a FleetPay não\n> tem chave nenhuma dessa pessoa e não há divergência a apontar; com `true`, a pessoa tem\n> chave cadastrada e ela é **outra**.\n\n**O que sai daqui:** sim/não sobre o par que você mesmo mandou. Nem a chave de terceiro,\nnem o dono dela — em `chave_de_outro_titular` o `titular` vai `null` de propósito, para a\nconferência não virar um diretório reverso chave → pessoa.\n\nA chave pode ser mandada como você a tem, com ou sem máscara: comparamos CPF, CNPJ e\ntelefone por dígitos (o `+55` é opcional) e e-mail/chave aleatória sem diferenciar caixa.\n\n**Documento que não é seu agregado responde `404`, não `403`** — mesma regra do\n`GET /agregados/{documento}`, para o endpoint não virar oráculo de enumeração de CPF/CNPJ.\n",
  "parameters": [
    {
      "name": "documento",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string"
      },
      "description": "CPF (11 dígitos) ou CNPJ (14 dígitos) do agregado. Aceita com ou sem pontuação."
    },
    {
      "name": "chave",
      "in": "query",
      "required": true,
      "schema": {
        "type": "string",
        "maxLength": 77
      },
      "description": "A chave PIX a conferir: CPF, CNPJ, e-mail, telefone (`+55DDDNÚMERO`) ou chave aleatória (UUID)."
    }
  ],
  "responses": {
    "200": {
      "description": "O resultado da conferência",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/RespostaConferenciaChavePix"
          }
        }
      }
    },
    "400": {
      "$ref": "#/components/responses/Erro400"
    },
    "401": {
      "$ref": "#/components/responses/Erro401"
    },
    "403": {
      "$ref": "#/components/responses/Erro403"
    },
    "404": {
      "description": "Nenhum agregado com este documento está vinculado à sua empresa.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Erro"
          }
        }
      }
    },
    "429": {
      "$ref": "#/components/responses/Erro429"
    },
    "500": {
      "$ref": "#/components/responses/Erro500"
    }
  },
  "method": "GET",
  "path": "/agregados/{documento}/chave-pix"
}