{
  "openapi": "3.1.0",
  "info": {
    "title": "ZipFinder API",
    "version": "1.0.0",
    "description": "API para consulta de CEP, consulta de CNPJ, validacao de enderecos, geocodificacao, estados, cidades e status operacional."
  },
  "servers": [
    {
      "url": "https://api.zipfinder.com.br/api",
      "description": "Producao"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    }
  ],
  "paths": {
    "/health": {
      "get": {
        "summary": "Health check da API",
        "description": "Retorna o status geral da API. Este endpoint nao exige autenticacao.",
        "operationId": "getHealth",
        "security": [],
        "responses": {
          "200": {
            "description": "API operacional.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HealthResponse"
                },
                "examples": {
                  "ok": {
                    "value": {
                      "status": "ok",
                      "timestamp": "2026-05-20T17:45:52.392Z"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/postal-codes/{postalCode}": {
      "get": {
        "summary": "Consulta de CEP",
        "description": "Consulta dados de endereco a partir de um CEP brasileiro. A geolocalizacao pode ser aproximada porque este endpoint nao recebe numero do endereco.",
        "operationId": "getPostalCode",
        "parameters": [
          {
            "name": "postalCode",
            "in": "path",
            "required": true,
            "description": "CEP brasileiro com ou sem mascara.",
            "schema": {
              "type": "string",
              "examples": ["04134020"]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Endereco encontrado.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PostalCodeResponse"
                },
                "examples": {
                  "saoPaulo": {
                    "value": {
                      "IsoAlpha2Country": "BR",
                      "IsoAlpha3Country": "BRA",
                      "ZipCode": "04134-020",
                      "Street": "Rua das Uvaias",
                      "TypeStreet": "Rua",
                      "NameStreet": "das Uvaias",
                      "Neighborhood": "Saude",
                      "City": "Sao Paulo",
                      "State": "SP",
                      "IbgeCode": "3550308",
                      "Latitude": -23.615189,
                      "Longitude": -46.633281,
                      "Source": "Correios do Brasil",
                      "LastUpdated": "2026-04-22T19:10:42.000Z"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/InvalidFormat"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "422": {
            "$ref": "#/components/responses/UnprocessableEntity"
          },
          "429": {
            "$ref": "#/components/responses/RateLimitExceeded"
          },
          "500": {
            "$ref": "#/components/responses/InternalServerError"
          }
        }
      }
    },
    "/v1/postal-codes/{postalCode}/details": {
      "get": {
        "summary": "Detalhe por CEP e numero",
        "description": "Consulta dados de endereco com maior precisao geografica a partir de CEP e numero.",
        "operationId": "getPostalCodeDetails",
        "parameters": [
          {
            "name": "postalCode",
            "in": "path",
            "required": true,
            "description": "CEP brasileiro com ou sem mascara.",
            "schema": {
              "type": "string",
              "examples": ["69309630"]
            }
          },
          {
            "name": "number",
            "in": "query",
            "required": true,
            "description": "Numero do endereco.",
            "schema": {
              "type": "string",
              "examples": ["503"]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Endereco detalhado encontrado.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PostalCodeDetailsResponse"
                },
                "examples": {
                  "boaVista": {
                    "value": {
                      "ZipCode": "69309-630",
                      "Number": "503",
                      "Street": "Rua Professor Agnelo Bitencourt",
                      "TypeStreet": "Rua",
                      "NameStreet": "Professor Agnelo Bitencourt",
                      "Neighborhood": "Centro",
                      "City": "Boa Vista",
                      "State": "RR",
                      "IbgeCode": "1400100",
                      "Latitude": 2.823509,
                      "Longitude": -60.675833,
                      "Confidence": 0.9821,
                      "Source": "IBGE",
                      "LastUpdated": "2026-04-22T19:10:42.000Z"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/InvalidFormat"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "422": {
            "$ref": "#/components/responses/UnprocessableEntity"
          },
          "429": {
            "$ref": "#/components/responses/RateLimitExceeded"
          },
          "500": {
            "$ref": "#/components/responses/InternalServerError"
          }
        }
      }
    },
    "/v1/companies/{cnpj}": {
      "get": {
        "summary": "Consulta de CNPJ",
        "description": "Consulta os dados cadastrais e de enderecamento de uma empresa a partir de um CNPJ brasileiro com 14 digitos.",
        "operationId": "getCompanyByCnpj",
        "parameters": [
          {
            "name": "cnpj",
            "in": "path",
            "required": true,
            "description": "CNPJ brasileiro com ou sem mascara.",
            "schema": {
              "type": "string",
              "examples": ["22685030000111"]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Empresa encontrada.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CompanyCnpjLookupResponse"
                },
                "examples": {
                  "example": {
                    "value": {
                      "Exists": true,
                      "Cnpj": "22685030000111",
                      "LegalName": "ZIPFINDER TECNOLOGIA LTDA",
                      "TradeName": "ZIPFINDER",
                      "Address": {
                        "Street": "Rua Exemplo",
                        "Number": "123",
                        "Complement": null,
                        "Neighborhood": "Centro",
                        "City": "Sao Paulo",
                        "State": "SP",
                        "ZipCode": "01001000",
                        "CountryCode": "BR"
                      },
                      "Phone": "1130000000",
                      "Email": "contato@zipfinder.com.br",
                      "Latitude": -23.55052,
                      "Longitude": -46.633308,
                      "GeoSource": "ibge",
                      "GeoConfidence": 0.98,
                      "GeoLastUpdated": "2026-05-21T00:00:00.000Z",
                      "Source": "provider",
                      "Stale": false,
                      "LastUpdated": "2026-05-21T00:00:00.000Z"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/InvalidFormat"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "Plano nao habilitado para consulta de CNPJ.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimitExceeded"
          },
          "500": {
            "$ref": "#/components/responses/InternalServerError"
          },
          "502": {
            "description": "Falha ao consultar o provedor de CNPJ.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/v1/countries/{countryCode}/states": {
      "get": {
        "summary": "Listagem de estados",
        "description": "Lista os estados disponiveis para um pais informado pelo codigo ISO alpha-3.",
        "operationId": "listStates",
        "parameters": [
          {
            "name": "countryCode",
            "in": "path",
            "required": true,
            "description": "Codigo ISO alpha-3 do pais.",
            "schema": {
              "type": "string",
              "examples": ["BRA"]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Estados encontrados.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StatesResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/InvalidFormat"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimitExceeded"
          },
          "500": {
            "$ref": "#/components/responses/InternalServerError"
          }
        }
      }
    },
    "/v1/countries/{countryCode}/states/{state}/cities": {
      "get": {
        "summary": "Listagem de cidades",
        "description": "Lista cidades de um estado dentro de um pais.",
        "operationId": "listCities",
        "parameters": [
          {
            "name": "countryCode",
            "in": "path",
            "required": true,
            "description": "Codigo ISO alpha-3 do pais.",
            "schema": {
              "type": "string",
              "examples": ["BRA"]
            }
          },
          {
            "name": "state",
            "in": "path",
            "required": true,
            "description": "Sigla do estado.",
            "schema": {
              "type": "string",
              "examples": ["SP"]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Cidades encontradas.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CitiesResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/InvalidFormat"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimitExceeded"
          },
          "500": {
            "$ref": "#/components/responses/InternalServerError"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "x-api-key",
        "description": "Chave de API no padrao zfp_..."
      }
    },
    "schemas": {
      "HealthResponse": {
        "type": "object",
        "required": ["status", "timestamp"],
        "properties": {
          "status": {
            "type": "string",
            "examples": ["ok"]
          },
          "timestamp": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "Country": {
        "type": "object",
        "properties": {
          "IsoAlpha2": {
            "type": "string"
          },
          "IsoAlpha3": {
            "type": "string"
          },
          "Name": {
            "type": "string"
          }
        }
      },
      "State": {
        "type": "object",
        "properties": {
          "Code": {
            "type": "string"
          },
          "Name": {
            "type": "string"
          }
        }
      },
      "PostalCodeResponse": {
        "type": "object",
        "properties": {
          "IsoAlpha2Country": {
            "type": "string"
          },
          "IsoAlpha3Country": {
            "type": "string"
          },
          "ZipCode": {
            "type": "string"
          },
          "Street": {
            "type": "string"
          },
          "TypeStreet": {
            "type": "string"
          },
          "NameStreet": {
            "type": "string"
          },
          "Neighborhood": {
            "type": "string"
          },
          "City": {
            "type": "string"
          },
          "State": {
            "type": "string"
          },
          "IbgeCode": {
            "type": "string"
          },
          "Latitude": {
            "type": "number"
          },
          "Longitude": {
            "type": "number"
          },
          "Source": {
            "type": "string"
          },
          "LastUpdated": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "PostalCodeDetailsResponse": {
        "allOf": [
          {
            "$ref": "#/components/schemas/PostalCodeResponse"
          },
          {
            "type": "object",
            "properties": {
              "Number": {
                "type": "string"
              },
              "Confidence": {
                "type": "number"
              }
            }
          }
        ]
      },
      "CompanyCnpjLookupResponse": {
        "type": "object",
        "required": ["Exists", "Cnpj", "Address", "Source", "Stale"],
        "properties": {
          "Exists": {
            "type": "boolean"
          },
          "Cnpj": {
            "type": "string"
          },
          "LegalName": {
            "type": ["string", "null"]
          },
          "TradeName": {
            "type": ["string", "null"]
          },
          "Address": {
            "type": "object",
            "properties": {
              "Street": { "type": ["string", "null"] },
              "Number": { "type": ["string", "null"] },
              "Complement": { "type": ["string", "null"] },
              "Neighborhood": { "type": ["string", "null"] },
              "City": { "type": ["string", "null"] },
              "State": { "type": ["string", "null"] },
              "ZipCode": { "type": ["string", "null"] },
              "CountryCode": { "type": ["string", "null"] }
            }
          },
          "Phone": {
            "type": ["string", "null"]
          },
          "Email": {
            "type": ["string", "null"]
          },
          "Latitude": {
            "type": ["number", "null"]
          },
          "Longitude": {
            "type": ["number", "null"]
          },
          "GeoSource": {
            "type": ["string", "null"]
          },
          "GeoConfidence": {
            "type": ["number", "null"]
          },
          "GeoLastUpdated": {
            "type": ["string", "null"],
            "format": "date-time"
          },
          "Source": {
            "type": "string"
          },
          "Stale": {
            "type": "boolean"
          },
          "LastUpdated": {
            "type": ["string", "null"],
            "format": "date-time"
          }
        }
      },
      "StatesResponse": {
        "type": "object",
        "properties": {
          "Country": {
            "$ref": "#/components/schemas/Country"
          },
          "States": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/State"
            }
          }
        }
      },
      "CitiesResponse": {
        "type": "object",
        "properties": {
          "Country": {
            "$ref": "#/components/schemas/Country"
          },
          "State": {
            "$ref": "#/components/schemas/State"
          },
          "Cities": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        }
      }
    },
    "responses": {
      "InvalidFormat": {
        "description": "Parametros com formato invalido.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      },
      "Unauthorized": {
        "description": "Chave de API ausente ou invalida.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      },
      "NotFound": {
        "description": "Recurso nao localizado.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      },
      "UnprocessableEntity": {
        "description": "Parametros validos, mas sem resultado processavel.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      },
      "RateLimitExceeded": {
        "description": "Limite mensal do plano excedido.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      },
      "InternalServerError": {
        "description": "Falha inesperada no servidor.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      }
    }
  }
}