Consultar a frota de um transportador (ANTT)

{
  "tags": [
    "Consultas"
  ],
  "summary": "Consultar a frota de um transportador (ANTT)",
  "operationId": "consultarFrota",
  "description": "Verifica, para uma lista de placas, se cada uma pertence à frota de um transportador no\nRNTRC (ANTT). A resposta traz, por placa, `pertence` (`true`/`false`, ou `null` quando a\nANTT não deu situação conclusiva).\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## Modo simulado em homologação\n\nEsta consulta **não tem provedor contratado** por trás: em homologação a resposta é\ngerada pela FleetPay, é determinística e **não tem efeito regulatório** — o dado não vem\nda ANTT e não reflete a frota real do transportador. Cada item de `frota` carrega\n`verificacao: \"simulada\"`, marcando a natureza da verificação por placa — e o campo é\nopcional por natureza: item **sem** `verificacao` é verificação real.\n\nO contrato de request e response já é o definitivo: integre agora. Quando o provedor real\nentrar, o comportamento deixa de ser simulado **sem mudança de contrato**.\n\n\n### O par `documento` + `rntrc` precisa conferir\n\nOs dois parâmetros são uma pergunta só: *\"a situação DESTE registro DESTE\ntransportador\"*. Um RNTRC que não seja o daquele CPF/CNPJ não descreve transportador\nnenhum, e a resposta é **`400` com `rntrc_nao_confere`** — nunca um `200` sobre o\ncadastro que por acaso foi encontrado.\n\nÉ `400` e não `503` porque a consulta rodou e concluiu: não houve indisponibilidade. E\nnão é `404` porque o que está errado é a **combinação** dos dois parâmetros, não um\nrecurso ausente no endereço.\n\nAs sentinelas abaixo são **isentas** dessa checagem — elas existem justamente para não\nserem o RNTRC de ninguém.\n\nRepare que a recusa do par é **diferente** de `pertence: null`. `null` é uma placa\ninconclusiva dentro de uma frota que existe; o `400` é a ausência de transportador\nsobre o qual responder — por isso ele não vem por placa, e sim no lugar da resposta\ninteira.\n\n### Sentinelas de teste\n\nEm modo simulado, estas placas respondem sempre a mesma coisa — use-as para exercitar o\ncaminho de erro da sua integração:\n\n| Placa | Resposta |\n|---|---|\n| `ZZZ0X00` | Placa fora da frota do transportador — `pertence: false` |\n| `ZZZ9X99` | Situação inconclusiva na ANTT — `pertence: null` |\n| qualquer outra placa válida | Resposta de sucesso |\n",
  "parameters": [
    {
      "name": "documento",
      "in": "query",
      "required": true,
      "schema": {
        "type": "string",
        "pattern": "^([0-9]{11}|[0-9]{14})$"
      },
      "description": "CPF (11 dígitos) ou CNPJ (14 dígitos) do transportador consultado, somente dígitos."
    },
    {
      "name": "rntrc",
      "in": "query",
      "required": true,
      "schema": {
        "type": "string",
        "pattern": "^[0-9]{8,9}$"
      },
      "description": "RNTRC do transportador consultado, com 8 ou 9 dígitos."
    },
    {
      "name": "placas",
      "in": "query",
      "required": true,
      "style": "form",
      "explode": true,
      "schema": {
        "type": "array",
        "minItems": 1,
        "maxItems": 20,
        "items": {
          "type": "string",
          "pattern": "^[A-Za-z]{3}[0-9][A-Za-z0-9][0-9]{2}$"
        }
      },
      "description": "Placas a verificar (1 a 20). Envie `placas[]=ABC1D23&placas[]=XYZ4E56`.\n\nEm homologação, `ZZZ0X00` devolve `pertence: false` e `ZZZ9X99` devolve\n`pertence: null`; qualquer outra placa válida devolve sucesso.\n"
    }
  ],
  "responses": {
    "200": {
      "description": "Situação de cada placa na frota do transportador.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "data": {
                "type": "object",
                "properties": {
                  "documento": {
                    "type": "string"
                  },
                  "rntrc": {
                    "type": "string"
                  },
                  "frota": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "placa": {
                          "type": "string"
                        },
                        "pertence": {
                          "type": "boolean",
                          "nullable": true
                        },
                        "verificacao": {
                          "type": "string",
                          "description": "Natureza da verificação desta placa. Em homologação vem\n`simulada`: a situação não foi apurada na ANTT, foi gerada em\nmodo simulado e não tem efeito regulatório.\n\nO marcador viaja **dentro de cada item**, e não no envelope da\nresposta, para sobreviver a ingestões que guardam só a lista de\nplacas e descartam o envelope.\n\n**Trate o campo como opcional.** Ele só existe enquanto a\nverificação é simulada: item **sem** `verificacao` é verificação\nreal. Um parser que exija o campo quebra na virada para o\nprovedor real — leia por presença, não por obrigatoriedade.\n"
                        }
                      }
                    }
                  }
                }
              },
              "environment": {
                "$ref": "#/components/schemas/Environment"
              }
            }
          }
        }
      }
    },
    "400": {
      "description": "`rntrc_nao_confere` — o RNTRC informado não é o registro deste CPF/CNPJ, então não\nhá frota sobre a qual responder.\n`validacao` — alguma placa está fora do formato Mercosul, ou falta parâmetro.\n",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Erro"
          }
        }
      }
    },
    "401": {
      "$ref": "#/components/responses/Erro401"
    },
    "403": {
      "$ref": "#/components/responses/Erro403"
    },
    "422": {
      "description": "A empresa autenticada ainda não concluiu o cadastro fiscal (`empresa_nao_habilitada`).",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Erro"
          }
        }
      }
    },
    "503": {
      "description": "A consulta está temporariamente indisponível (`consulta_indisponivel`). Aguarde e tente de novo.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Erro"
          }
        }
      }
    }
  },
  "method": "GET",
  "path": "/consultas/frota"
}