Consultar o veículo no operador de pedágio

{
  "tags": [
    "Consultas"
  ],
  "summary": "Consultar o veículo no operador de pedágio",
  "operationId": "consultarVeiculoPedagio",
  "description": "O que a **operadora informada** sabe sobre uma placa: se o veículo **carrega tag** e\nse dá para **emitir Vale-Pedágio** para ele.\n\n## O contrato é multi-operadora\n\n`operadora` é obrigatória, e as quatro aceitas são as quatro emissoras de tag do\nmercado:\n\n| `operadora` | | Disponível hoje |\n|---|---|---|\n| `sem_parar` | Sem Parar | **Sim** |\n| `conectcar` | ConectCar | ainda não |\n| `veloe` | Veloe | ainda não |\n| `move_mais` | Move Mais | ainda não |\n\nOperadora real ainda não atendida responde `422` com `operadora_indisponivel` — código\n**diferente** do `400` de operadora inexistente, e a distinção importa: um pede\naguardar a operadora entrar, o outro pede corrigir a chamada. Quando uma nova operadora\nfor atendida, nada muda na sua integração: o campo e o código de erro já existem.\n\n**Pré-requisito da empresa que consulta:** ter o cadastro fiscal concluído — com o\ncertificado digital A1 enviado em Configurações. Sem isso a resposta é `422` com\n`empresa_nao_habilitada`.\n\nExige o escopo `consultas` habilitado no painel.\n\n## As duas perguntas são independentes\n\nEsta é a parte que uma integração costuma errar, e o contrato as mantém em campos\nseparados de propósito:\n\n| | `tem_tag` | `habilitado_vale_pedagio` |\n|---|---|---|\n| via automática | `true` | `true` |\n| **sem tag, mas pode rodar** | `false` | `true` |\n| **com tag, bloqueado pelo operador** | `true` | `false` |\n\nAs duas linhas do meio são o ponto. O **Vale-Pedágio tradicional não exige tag** — um\nveículo sem tag continua podendo receber vale. E um veículo com tag pode estar\nbloqueado pelo operador por outro motivo.\n\nSe você colapsar os dois campos num só, sua integração vai **recusar frete que podia\nrodar**.\n\n## `tem_tag` é resposta, não inferência\n\nNão deduza a ausência de tag de `identificador_tag` vir nulo. `tem_tag` é a resposta;\n`identificador_tag` é o código, e só acompanha quem tem tag.\n\n## `404` é diferente de \"sem tag\"\n\nPlaca que o operador não conhece responde `404 veiculo_nao_encontrado` — e isso pede\numa providência diferente de um veículo cadastrado sem tag:\n\n| Resposta | O que fazer |\n|---|---|\n| `404` | cadastrar o veículo no operador de pedágio |\n| `200` com `tem_tag: false` | emitir o Vale-Pedágio tradicional |\n\n## Modo simulado em homologação\n\nEsta consulta **não tem operadora contratada** por trás: em homologação a resposta é\ngerada pela FleetPay, é determinística e **não reflete o cadastro real de nenhum\nveículo**. Cada resposta carrega `verificacao: \"simulada\"` — o campo viaja dentro do\ndado, e não só no envelope, porque um `tem_tag` gravado na sua base precisa carregar\nconsigo que nenhuma consulta real aconteceu.\n\nO contrato de request e response já é o definitivo: integre agora.\n\n### Só os veículos da massa de teste respondem\n\nPlaca fora da massa responde `404` — **não existe resposta genérica**. Ela existiu por\num dia e saiu: qualquer placa digitada recebia uma tag fabricada com cara de real, e um\n`tem_tag: true` gravado na sua base não carrega aviso de que a placa nem existia.\n\n| Placa | Estado |\n|---|---|\n| `TJD2D33` | com tag, habilitado — a via automática |\n| `AKS1I02` | **sem tag**, e ainda assim habilitado — o vale tradicional não exige tag |\n| `FTO0C61` | com tag, **não habilitado** — tag não autoriza por si |\n| qualquer outra placa | `404 veiculo_nao_encontrado` |\n",
  "parameters": [
    {
      "name": "placa",
      "in": "query",
      "required": true,
      "schema": {
        "type": "string",
        "pattern": "^[A-Za-z]{3}[0-9][A-Za-z0-9][0-9]{2}$"
      },
      "description": "Placa antiga (`ABC1234`) ou Mercosul (`ABC1D23`), sem separador.\n"
    },
    {
      "name": "operadora",
      "in": "query",
      "required": true,
      "schema": {
        "type": "string",
        "enum": [
          "sem_parar",
          "conectcar",
          "veloe",
          "move_mais"
        ]
      },
      "description": "A operadora de tag consultada. Hoje só `sem_parar` está disponível; as demais\nrespondem `422 operadora_indisponivel` até serem atendidas.\n"
    }
  ],
  "responses": {
    "200": {
      "description": "O que o operador tem para a placa.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/RespostaVeiculoPedagio"
          }
        }
      }
    },
    "400": {
      "description": "`validacao` — a placa está fora do formato aceito, ou não foi informada.\n",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Erro"
          }
        }
      }
    },
    "401": {
      "$ref": "#/components/responses/Erro401"
    },
    "403": {
      "$ref": "#/components/responses/Erro403"
    },
    "404": {
      "description": "`veiculo_nao_encontrado` — a placa não está cadastrada nesta operadora. **Não** é\na mesma coisa que um veículo cadastrado sem tag: um pede cadastrar o veículo na\noperadora, o outro pede emitir o vale tradicional.\n",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Erro"
          }
        }
      }
    },
    "422": {
      "description": "`operadora_indisponivel` — a operadora existe, mas ainda não é atendida; a\nmensagem diz quais estão disponíveis. **Aguarde**, não corrija a chamada.\n`empresa_nao_habilitada` — a empresa autenticada ainda não concluiu o cadastro\nfiscal.\n",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Erro"
          }
        }
      }
    },
    "503": {
      "description": "`consulta_indisponivel` — não foi possível consultar o operador.\n\n**Nunca trate isto como \"o veículo não tem tag\".** Guardar ausência de tag porque a\nconsulta falhou faria você parar de oferecer a via automática a um caminhão que a tem.\n",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Erro"
          }
        }
      }
    }
  },
  "method": "GET",
  "path": "/consultas/veiculo-pedagio"
}