Dabra Receita Federal API

openapi: 3.2.0
info:
  title: Dabra Receita Federal 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: Receita Federal
paths:
  /api/v1/consulta/receita-federal-pf:
    get:
      summary: Receita Federal - Pessoa Física
      description: Consulta em tempo real a situação cadastral de uma pessoa física na Receita Federal, sem cache — cada consulta é feita ao vivo na fonte oficial. Retorna nome, data de nascimento, situação cadastral e um link de auditoria direto no site da própria Receita Federal para validar a autenticidade do comprovante.
      operationId: receita-federal-pf
      tags:
      - Receita Federal
      parameters:
      - name: cpf
        in: query
        required: true
        description: CPF (somente números, 11 dígitos)
        schema:
          type: string
          format: cpf
        example: SEU_CPF
      - name: comprovante
        in: query
        required: false
        description: Inclui o comprovante da consulta (link válido por 7 dias). Acréscimo de 25% sobre o preço da consulta, cobrado somente quando o comprovante é entregue.
        schema:
          type: boolean
        example: true
      responses:
        '200':
          description: Sucesso
          content:
            application/json:
              schema:
                type: object
                properties:
                  comprovante:
                    type: array
                    description: 'Comprovante da consulta: o documento emitido pela fonte, num link aberto para você guardar. Só vem quando você pede com o parâmetro `comprovante` (acréscimo de 25% sobre o preço da consulta, cobrado somente quando o comprovante é entregue). O link vale por 7 dias a partir da emissão e o arquivo pode levar alguns segundos para ficar disponível. Chave opcional: leia como ausente quando não vier.'
                    items:
                      type: string
                      format: uri
              example:
                anoObito: null
                numeroCPF: string
                nomeSocial: null
                dataEmissao: string
                possuiObito: boolean
                dataInscricao: string
                dataNascimento: string
                link_validacao: string
                nomePessoaFisica: string
                digitoVerificador: string
                situacaoCadastral: string
                codigoControleComprovante: string
                dataInscricaoAnterior1990: null
                comprovante:
                - https://arquivos.dabradata.com/comprovantes/cpv_01J8Z3K9X2
        '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/receita-federal-pj:
    get:
      summary: Receita Federal — Pessoa Jurídica
      description: 'Dados cadastrais, fiscais e societários de empresas a partir do CNPJ: situação cadastral, endereço, atividade econômica (CNAE), capital social, enquadramento tributário e Quadro de Sócios e Administradores (QSA). Dados oriundos da base cadastral oficial da Receita Federal. O documento de sócio pessoa física vem mascarado, conforme a divulgação pública da Receita Federal.'
      operationId: receita-federal-pj
      tags:
      - Receita Federal
      parameters:
      - name: cnpj
        in: query
        required: true
        description: CNPJ da empresa a consultar. Aceita com ou sem pontuação (somente dígitos ou formatado).
        schema:
          type: string
          format: cnpj
        example: SEU_CNPJ
      responses:
        '200':
          description: Sucesso
          content:
            application/json:
              schema:
                type: object
              example:
                uf: string
                cep: string
                qsa:
                - pais: null
                  nome_socio: string
                  codigo_pais: null
                  faixa_etaria: string
                  cnpj_cpf_do_socio: string
                  qualificacao_socio: string
                  codigo_faixa_etaria: number
                  data_entrada_sociedade: string
                  identificador_de_socio: number
                  cpf_representante_legal: string
                  nome_representante_legal: string
                  codigo_qualificacao_socio: number
                  qualificacao_representante_legal: string
                  codigo_qualificacao_representante_legal: number
                cnpj: string
                pais: null
                email: string
                porte: string
                bairro: string
                numero: string
                ddd_fax: string
                municipio: string
                logradouro: string
                cnae_fiscal: number
                codigo_pais: null
                complemento: string
                codigo_porte: number
                razao_social: string
                nome_fantasia: string
                capital_social: number
                ddd_telefone_1: string
                ddd_telefone_2: string
                opcao_pelo_mei: boolean
                codigo_municipio: number
                cnaes_secundarios:
                - codigo: number
                  descricao: string
                natureza_juridica: string
                regime_tributario: []
                situacao_especial: string
                opcao_pelo_simples: boolean
                situacao_cadastral: number
                data_opcao_pelo_mei: null
                data_exclusao_do_mei: null
                cnae_fiscal_descricao: string
                codigo_municipio_ibge: null
                data_inicio_atividade: string
                data_situacao_especial: null
                data_opcao_pelo_simples: string
                data_situacao_cadastral: string
                nome_cidade_no_exterior: string
                codigo_natureza_juridica: number
                data_exclusao_do_simples: null
                motivo_situacao_cadastral: number
                ente_federativo_responsavel: string
                identificador_matriz_filial: number
                qualificacao_do_responsavel: number
                descricao_situacao_cadastral: string
                descricao_tipo_de_logradouro: string
                descricao_motivo_situacao_cadastral: string
                descricao_identificador_matriz_filial: string
        '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/receita-federal-pj-live:
    get:
      summary: Receita Federal — Pessoa Jurídica (Tempo Real)
      description: 'Dados cadastrais de um CNPJ consultados AO VIVO na Receita Federal, sem cache: cada chamada vai à fonte oficial e devolve o carimbo de data e hora da consulta em `consultado_em`. Inclui situação cadastral, natureza jurídica, endereço, capital social, CNAEs e o Quadro de Sócios e Administradores (QSA) com nome e qualificação. Use quando o frescor do dado for mais importante que o tempo de resposta e o preço; para o mesmo conteúdo mais barato e mais rápido, com atualização mensal, use a consulta cadastral de CNPJ padrão.'
      operationId: receita-federal-pj-live
      tags:
      - Receita Federal
      parameters:
      - name: cnpj
        in: query
        required: true
        description: CNPJ da empresa a consultar. Aceita com ou sem máscara (00000000000000 ou 00.000.000/0000-00).
        schema:
          type: string
          format: cnpj
        example: SEU_CNPJ
      responses:
        '200':
          description: Sucesso
          content:
            application/json:
              schema:
                type: object
              example:
                uf: SP
                cep: '13010100'
                qsa:
                - nome: MARIA EXEMPLO DA SILVA
                  pais_origem: null
                  qualificacao: 49-Sócio-Administrador
                  nome_representante_legal: null
                  qualificacao_representante_legal: null
                - nome: JOSE EXEMPLO PEREIRA
                  pais_origem: null
                  qualificacao: 22-Sócio
                  nome_representante_legal: null
                  qualificacao_representante_legal: null
                cnpj: '99888777000100'
                email: contato@exemploalimentos.com.br
                porte: EPP
                bairro: CENTRO
                numero: '1200'
                telefone: (19) 3200-0000
                municipio: CAMPINAS
                logradouro: RUA EXEMPLO DAS FLORES
                complemento: LOJA 2
                razao_social: COMERCIO EXEMPLO DE ALIMENTOS LTDA
                consultado_em: '2026-08-05T14:32:14'
                data_abertura: '2011-04-18'
                matriz_filial: MATRIZ
                nome_fantasia: EXEMPLO ALIMENTOS
                capital_social: 450000.0
                cnaes_secundarios:
                - 56.11-2-03 - Lanchonetes, casas de chá, de sucos e similares
                - 10.91-1-02 - Fabricação de produtos de padaria e confeitaria
                natureza_juridica: Sociedade Empresária Limitada
                situacao_especial: null
                situacao_cadastral: ATIVA
                cnae_principal_codigo: 47.21-1-02
                data_situacao_especial: null
                data_situacao_cadastral: '2011-04-18'
                cnae_principal_descricao: Padaria e confeitaria com predominância de revenda
                codigo_natureza_juridica: '2062'
                ente_federativo_responsavel: null
                observacoes_situacao_cadastral: 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'
  /api/v1/consulta/restituicao-irpf:
    get:
      summary: Restituição do IRPF (Receita Federal)
      description: 'Consulta o andamento do pedido de restituição do Imposto de Renda Pessoa Física direto na fonte oficial da Receita Federal. Informe apenas o CPF: quando há restituição liberada, retorna a situação, o lote, a data de disponibilidade e o banco/agência do crédito.'
      operationId: restituicao-irpf
      tags:
      - Receita Federal
      parameters:
      - name: cpf
        in: query
        required: true
        description: CPF do contribuinte (11 dígitos). Aceita com ou sem pontuação; o dígito verificador é conferido.
        schema:
          type: string
          format: cpf
          pattern: ^[0-9]{11}$
      - name: exercicio
        in: query
        required: false
        description: 'Ano-exercício da declaração, com 4 dígitos (ex.: ''2025''). Sem ele, consultamos o exercício CORRENTE, que é o que a maioria dos consulentes quer.'
        schema:
          type: string
          pattern: ^(19|20)[0-9]{2}$
      - name: data_nascimento
        in: query
        required: false
        description: 'OPCIONAL (DD/MM/AAAA). Não é preciso informar: sem ela, a data é resolvida pelo próprio CPF. Se você já tem a data em cadastro, envie-a — pula uma etapa de enriquecimento e deixa a consulta mais rápida.'
        schema:
          type: string
          format: br_date
          pattern: ^[0-9]{2}/[0-9]{2}/[0-9]{4}$
      responses:
        '200':
          description: Sucesso
          content:
            application/json:
              schema:
                type: object
              example:
                status: string
                situacao: string
                exercicio: number
                observacoes: null
                restituicao:
                  lote: null
                  dataDisponibilidade: null
                  situacaoRestituicao: null
                cpfConsultado: string
                dadosBancarios:
                  banco: null
                  conta: null
                  agencia: null
                  chavePix: null
                tipoDeclaracao: null
                debitoAutomatico:
                  situacao: null
                existeDeclaracao: boolean
                nomeContribuinte: string
                emFilaRestituicao: boolean
                possuiRestituicao: boolean
                valorRestituicaoOriginal: null
                valorRestituicaoCorrigido: 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'
  /api/v1/consulta/simples-nacional:
    get:
      summary: Simples Nacional - Enquadramento
      description: Consulta a situação atual do contribuinte no Simples Nacional e SIMEI, indicando se é optante. Inclui histórico de períodos anteriores e eventos futuros previstos.
      operationId: simples-nacional
      tags:
      - Receita Federal
      parameters:
      - name: cnpj
        in: query
        required: true
        description: CNPJ (somente números, 14 dígitos)
        schema:
          type: string
          format: cnpj
        example: SEU_CNPJ
      responses:
        '200':
          description: Sucesso
          content:
            application/json:
              schema:
                type: object
              example:
                cnpj: string
                situacaoSIMEI: string
                enquadradoSIMEI: boolean
                nomeEmpresarial: string
                eventosFuturosSIMEI:
                - dataFim: null
                  dataInicio: null
                  detalhamento: string
                optanteSimplesNacional: boolean
                simeiPeriodosAnteriores:
                - dataFim: null
                  dataInicio: null
                  detalhamento: string
                situacaoSimplesNacional: string
                meiTransportadorAutonomo:
                - dataFim: null
                  dataInicio: null
                  detalhamento: string
                situacaoRegimeRegularCBS: string
                situacaoRegimeRegularIBS: string
                eventosFuturosSimplesNacional:
                - dataFim: null
                  dataInicio: null
                  detalhamento: string
                simplesNacionalPeriodosAnteriores:
                - dataFim: null
                  dataInicio: string
                  detalhamento: string
        '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