---
openapi: 3.0.3
info:
  title: CEP API
  description: Consultas gerais à base de CEP dos Correios.
  version: 1.0.1
servers:
- url: https://cep.api-hml.rota.sp.gov.br
  description: Homologação
security:
- IdpSP: []
tags:
- name: Consultar Endereço
- name: Obsoletas
paths:
  /cidades:
    get:
      tags:
      - Cidades
      summary: Consulta cidades por UF
      parameters:
      - name: uf
        in: query
        description: UF - Unidade Federativa
        required: true
        schema:
          type: string
      responses:
        "200":
          description: Consulta realizada com sucesso.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ConsultaCidadeResponse'
        "204":
          description: No Content.
        "400":
          $ref: '#/components/responses/ValidationError'
        "401":
          $ref: '#/components/responses/UnauthorizedError'
        "403":
          $ref: '#/components/responses/ForbiddenError'
        "500":
          $ref: '#/components/responses/InternalServerError'
  /paises:
    get:
      tags:
      - Países
      summary: Consulta país por nome
      parameters:
      - name: nome
        in: query
        description: Nome do país
        required: true
        schema:
          type: string
      responses:
        "200":
          description: Consulta realizada com sucesso.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ConsultaPaisResponse'
        "204":
          description: No Content.
        "400":
          $ref: '#/components/responses/ValidationError'
        "401":
          $ref: '#/components/responses/UnauthorizedError'
        "403":
          $ref: '#/components/responses/ForbiddenError'
        "500":
          $ref: '#/components/responses/InternalServerError'
  /v2/paises:
    get:
      tags:
      - Países
      summary: Consulta país por nome
      parameters:
      - name: nome
        in: query
        description: Nome do país
        required: true
        schema:
          type: string
      responses:
        "200":
          description: Consulta realizada com sucesso.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ConsultaPaisResponse'
        "204":
          description: No Content.
        "400":
          $ref: '#/components/responses/ValidationError'
        "401":
          $ref: '#/components/responses/UnauthorizedError'
        "403":
          $ref: '#/components/responses/ForbiddenError'
        "500":
          $ref: '#/components/responses/InternalServerError'
  /enderecos:
    get:
      tags:
      - Obsoletas
      summary: Consulta de Endereço
      description: Consulta de Endereço por CEP
      operationId: consultaEnderecoQuery
      parameters:
      - name: cep
        in: query
        description: Um CEP formato BR 99999999
        required: true
        schema:
          type: string
      responses:
        "202":
          description: Consulta realizada com sucesso.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ConsultaCepResponse'
        "204":
          description: No Content.
        "400":
          $ref: '#/components/responses/ValidationError'
        "401":
          $ref: '#/components/responses/UnauthorizedError'
        "403":
          $ref: '#/components/responses/ForbiddenError'
        "500":
          $ref: '#/components/responses/InternalServerError'
      deprecated: true
  /enderecos/{cep}:
    get:
      tags:
      - Obsoletas
      summary: Consulta de Endereço
      description: Consulta de Endereço por CEP
      operationId: consultaEnderecoPath
      parameters:
      - name: cep
        in: path
        description: Um CEP formato BR 99999999
        required: true
        schema:
          type: string
      responses:
        "202":
          description: Consulta realizada com sucesso.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ConsultaCepResponse'
        "204":
          description: No Content.
        "400":
          $ref: '#/components/responses/ValidationError'
        "401":
          $ref: '#/components/responses/UnauthorizedError'
        "403":
          $ref: '#/components/responses/ForbiddenError'
        "500":
          $ref: '#/components/responses/InternalServerError'
      deprecated: true
  /v2/enderecos:
    get:
      tags:
      - Obsoletas
      summary: Consulta de endereços
      description: Consulta de endereços
      operationId: consultaEnderecoQueryV2
      parameters:
      - name: cep
        in: query
        description: "Consulta os endereços com base em um CEP, que deve ser informado\
          \ no formato 99999999."
        required: true
        schema:
          type: string
      responses:
        "200":
          description: Consulta realizada com sucesso. É retornada uma coleção dos
            endereços encontrados.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ConsultaCepResponse'
        "204":
          description: Não foi encontrado nenhum endereço com os critérios informados.
        "400":
          $ref: '#/components/responses/ValidationError'
        "401":
          $ref: '#/components/responses/UnauthorizedError'
        "403":
          $ref: '#/components/responses/ForbiddenError'
        "500":
          $ref: '#/components/responses/InternalServerError'
      deprecated: true
  /v2/enderecos/{cep}:
    get:
      tags:
      - Obsoletas
      summary: Consulta de Endereço
      description: Consulta de Endereço por CEP
      operationId: consultaEnderecoPathV2
      parameters:
      - name: cep
        in: path
        description: Um CEP formato BR 99999999
        required: true
        schema:
          type: string
      responses:
        "200":
          description: Consulta realizada com sucesso.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ConsultaCepResponse'
        "204":
          description: No Content.
        "400":
          $ref: '#/components/responses/ValidationError'
        "401":
          $ref: '#/components/responses/UnauthorizedError'
        "403":
          $ref: '#/components/responses/ForbiddenError'
        "500":
          $ref: '#/components/responses/InternalServerError'
      deprecated: true
  /v3/enderecos:
    get:
      tags:
      - Consultar Endereço
      summary: Consulta de endereços
      description: Consulta de endereços
      parameters:
      - name: cep
        in: query
        description: "Consulta os endereços com base em um CEP, que deve ser informado\
          \ no formato 99999999."
        schema:
          type: string
          example: "50000001"
      - name: logradouro
        in: query
        description: Consulta os endereços com base em um logradouro.
        schema:
          type: string
          example: Av. Zero ou um
      - name: numero
        in: query
        description: Consulta os endereços com base em um numero.
        schema:
          type: integer
          example: 10
      - name: cidade
        in: query
        description: Consulta os endereços com base em uma cidade.
        schema:
          type: string
          example: São Paulo
      - name: uf
        in: query
        description: Consulta os endereços com base em uma Unidade Federativa (UF).
        schema:
          enum:
          - AC
          - AL
          - AM
          - AP
          - BA
          - CE
          - DF
          - ES
          - GO
          - MA
          - MG
          - MS
          - MT
          - PA
          - PB
          - PE
          - PI
          - PR
          - RJ
          - RN
          - RO
          - RR
          - RS
          - SC
          - SE
          - SP
          - TO
          type: string
          example: SP
      responses:
        "200":
          description: Consulta realizada com sucesso. É retornada uma coleção dos
            endereços encontrados.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ConsultaCepResponse'
        "204":
          description: Não foi encontrado nenhum endereço com os critérios informados.
        "400":
          $ref: '#/components/responses/ValidationError'
        "401":
          $ref: '#/components/responses/UnauthorizedError'
        "403":
          $ref: '#/components/responses/ForbiddenError'
        "500":
          $ref: '#/components/responses/InternalServerError'
components:
  schemas:
    ConsultaPaisResponse:
      title: País
      type: object
      properties:
        codPais:
          type: number
          example: 31
        pais:
          type: string
          example: Brasil
        paisEmIngles:
          type: string
          example: Brazil
        sigla:
          type: string
          example: BRA
    ConsultaCidadeResponse:
      title: Cidade
      type: object
      properties:
        cep:
          type: string
          example: "13579000"
        localidade:
          type: string
          example: Santa Eudóxia
        numeroIBGE:
          type: integer
          example: 354906
        municipio:
          type: string
          example: São Carlos
        uf:
          type: string
          example: SP
        tipoLocalidade:
          type: string
          example: Distrito
        codigoLocal:
          type: integer
          example: 9605
        codigoTipo:
          type: integer
          example: 117
        codigoLocalRel:
          type: integer
          example: 9643
    ConsultaCepResponse:
      title: Endereco
      type: object
      properties:
        cep:
          type: string
        bairro:
          type: string
        tipoLogradouro:
          type: string
        endereco:
          type: string
        complemento:
          type: string
        tipoLogradouroAbrev:
          type: string
        enderecoAbrev:
          type: string
        tipoLogradouroAbrevDNE:
          type: string
        localidade:
          type: string
        estado:
          type: string
        uf:
          type: string
        numeroIBGE:
          type: number
        logradouro:
          type: string
        cdTipoCEP:
          type: number
        tipoCEP:
          type: string
        municipio:
          type: string
        tipoLocalidade:
          type: string
        codigoMunicipio:
          type: number
        codigoLocalRel:
          type: number
        latitude:
          type: string
        longitude:
          type: string
        codigoDne:
          type: number
        tipoLogradouroDne:
          type: number
        codigoBairro:
          type: number
  responses:
    ValidationError:
      description: Erro de validação
      content:
        application/json:
          schema:
            type: object
            properties:
              status:
                enum:
                - "400"
                type: string
              trace:
                description: Trace ID
                type: string
              messages:
                type: array
                items:
                  description: Mensagens de erro
                  type: string
    UnauthorizedError:
      description: Access token é invalido ou expirado.
    ForbiddenError:
      description: "Access token é válido, porém não fornece acesso à operação."
    InternalServerError:
      description: Ocorreu um erro interno. Entre em contato com a equipe do ROTA
        para suporte.
  securitySchemes:
    IdpSP:
      type: http
      scheme: bearer
      bearerFormat: JWT
