Dabra Eleitoral API

openapi: 3.2.0
info:
  title: Dabra Eleitoral API
  version: v1
  description: 'API pública Dabra — consulta de dados. Toda conta tem uma chave de teste (`dabra_test_...`) que devolve o exemplo de cada endpoint a custo zero, marcado com o header X-Example: true — a validação de parâmetros é a mesma da produção.'
servers:
- url: https://app.dabradata.com
security:
- ApiKeyAuth: []
tags:
- name: Eleitoral
paths:
  /api/v1/consulta/tse-situacao:
    get:
      summary: Situação Eleitoral (TSE)
      description: Consulta a situação eleitoral de um eleitor junto à Justiça Eleitoral, retornando se o título está regular e se a biometria foi coletada.
      operationId: tse-situacao
      tags:
      - Eleitoral
      parameters:
      - name: cpf
        in: query
        required: true
        description: CPF do cidadão (11 dígitos, com ou sem máscara). Único parâmetro.
        schema:
          type: string
          format: cpf
        example: SEU_CPF
      responses:
        '200':
          description: Sucesso
          content:
            application/json:
              schema:
                type: object
              example:
                status: string
                isRegular: boolean
                identificacao: string
                biometriaColetada: boolean
        '400':
          $ref: '#/components/responses/Error400'
        '401':
          $ref: '#/components/responses/Error401'
        '402':
          $ref: '#/components/responses/Error402'
        '404':
          $ref: '#/components/responses/Error404'
        '429':
          $ref: '#/components/responses/Error429'
        '500':
          $ref: '#/components/responses/Error500'
  /api/v1/consulta/tse-titulo:
    get:
      summary: Título de Eleitor e Local de Votação
      description: 'Consulta a situação do título de eleitor e o local de votação de um cidadão a partir do CPF. Retorna a identificação do eleitor (nome e número de inscrição), a situação da regularidade eleitoral, se a biometria foi coletada, e o domicílio eleitoral completo: UF, município, zona, seção, bairro, logradouro e número. Informar nome da mãe e data de nascimento eleva a taxa de correspondência e desambigua homônimos.'
      operationId: tse-titulo
      tags:
      - Eleitoral
      parameters:
      - name: cpf
        in: query
        required: true
        description: CPF do cidadão (11 dígitos, com ou sem máscara). Obrigatório.
        schema:
          type: string
          format: cpf
        example: SEU_CPF
      - name: nome_mae
        in: query
        required: true
        description: Nome completo da mãe. Obrigatório — a base oficial exige nome da mãe e data de nascimento.
        schema:
          type: string
      - name: data_nascimento
        in: query
        required: true
        description: Data de nascimento (DD/MM/AAAA). Obrigatório — a base oficial exige nome da mãe e data de nascimento.
        schema:
          type: string
        example: 01/01/1990
      responses:
        '200':
          description: Sucesso
          content:
            application/json:
              schema:
                type: object
              example:
                status: string
                identificacao:
                  eleitor: string
                  inscricao: string
                biometriaColetada: null
                domicilioEleitoral:
                  uf: string
                  zona: number
                  local: string
                  secao: number
                  bairro: string
                  numero: string
                  municipio: string
                  logradouro: string
                  proximaEleicao: null
        '400':
          $ref: '#/components/responses/Error400'
        '401':
          $ref: '#/components/responses/Error401'
        '402':
          $ref: '#/components/responses/Error402'
        '404':
          $ref: '#/components/responses/Error404'
        '429':
          $ref: '#/components/responses/Error429'
        '500':
          $ref: '#/components/responses/Error500'
components:
  schemas:
    Error:
      type: object
      required:
      - error
      properties:
        error:
          type: object
          required:
          - code
          - message
          properties:
            code:
              type: string
            message:
              type: string
  responses:
    Error402:
      description: Saldo insuficiente
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Error401:
      description: Não autenticado
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Error400:
      description: Parâmetros inválidos
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Error429:
      description: Limite de requisições excedido
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Error404:
      description: Recurso não encontrado
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Error500:
      description: Erro interno
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key