openapi: 3.0.3
info:
  title: CPFHub.io API
  version: 1.0.0
  description: |
    Official OpenAPI specification for the CPFHub.io API.
    Retrieve identity data (name, gender, date of birth) from a Brazilian CPF number.
    All requests require an API key sent in the `x-api-key` header.
    Sign up at https://app.cpfhub.io to generate your key.
  contact:
    name: CPFHub Support
    url: https://cpfhub.io
    email: support@cpfhub.io
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
  termsOfService: https://cpfhub.io/termos-de-uso

servers:
  - url: https://api.cpfhub.io
    description: Production

tags:
  - name: CPF
    description: Brazilian CPF identity lookup operations

security:
  - ApiKeyAuth: []

paths:
  /cpf/{cpf}:
    get:
      tags:
        - CPF
      summary: Retrieve identity data from CPF
      operationId: getPersonByCpf
      description: |
        Retrieve structured identity data (name, gender, date of birth) from a Brazilian CPF number.
        **Note:** CPFs not found in the database do not consume credits.
        Only requests that return data are counted toward your plan quota.
      parameters:
        - $ref: '#/components/parameters/Cpf'
        - in: header
          name: Accept
          required: false
          schema:
            type: string
            default: application/json
          example: application/json
      responses:
        '200':
          description: Successful lookup. Identity data returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CpfResponse'
        '400':
          description: Bad Request — Malformed CPF or missing parameter.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                success: false
                data: null
                error:
                  message: "CPF inválido"
        '401':
          description: Unauthorized — Missing or invalid API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                success: false
                data: null
                error:
                  message: "Chave de API inválida ou ausente"
        '404':
          description: Not Found — CPF not found in the database.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                success: false
                data: null
                error:
                  message: "CPF não encontrado"
        '429':
          description: |
            Too Many Requests — Rate limit exceeded.
            Response headers include rate limit details and reset time.
            Rate limits by plan:
            - Free: 1 request every 2 seconds
            - Pro: 1 request per second
            - Enterprise: custom
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                success: false
                data: null
                error:
                  message: "Limite de requisições excedido"
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                success: false
                data: null
                error:
                  message: "Erro interno do servidor"
        '503':
          description: Service Unavailable — Service temporarily unavailable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                success: false
                data: null
                error:
                  message: "Serviço temporariamente indisponível"

components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: API key generated at https://app.cpfhub.io

  parameters:
    Cpf:
      in: path
      name: cpf
      required: true
      description: |
        Brazilian CPF number. Accepts formatted (`XXX.XXX.XXX-XX`) or digits only (`XXXXXXXXXXX`).
      schema:
        type: string
        pattern: '^\d{3}\.?\d{3}\.?\d{3}-?\d{2}$'
      example: "123.456.789-00"

  schemas:
    CpfResponse:
      type: object
      required:
        - success
        - data
      properties:
        success:
          type: boolean
          description: Indicates whether the lookup was successful.
          example: true
        data:
          $ref: '#/components/schemas/CpfData'

    CpfData:
      type: object
      properties:
        cpf:
          type: string
          description: The queried CPF number (digits only).
          example: "12345678900"
        name:
          type: string
          description: Full name of the person.
          example: "Fulano de Tal"
        nameUpper:
          type: string
          description: Full name in uppercase.
          example: "FULANO DE TAL"
        gender:
          type: string
          description: Gender (M = male, F = female).
          enum:
            - M
            - F
          example: "M"
        birthDate:
          type: string
          description: Date of birth in DD/MM/YYYY format.
          example: "15/06/1990"
        day:
          type: integer
          description: Day of birth.
          minimum: 1
          maximum: 31
          example: 15
        month:
          type: integer
          description: Month of birth.
          minimum: 1
          maximum: 12
          example: 6
        year:
          type: integer
          description: Year of birth.
          example: 1990

    ErrorResponse:
      type: object
      required:
        - success
        - data
        - error
      properties:
        success:
          type: boolean
          description: Always false for error responses.
          example: false
        data:
          nullable: true
          description: Always null for error responses.
          example: null
        error:
          type: object
          required:
            - message
          properties:
            message:
              type: string
              description: Descriptive error message returned by the API (in Brazilian Portuguese).
              example: "CPF inválido"
