openapi: 3.1.0
info:
  title: Brazilayer — Brazilian Company Data (CNPJ)
  version: 0.1.0
  description: |
    Official registration data for all Brazilian companies, from the Receita Federal
    (Brazilian IRS) public CNPJ registry, updated monthly. Paid endpoints use the x402
    payment protocol (USDC on Base): calling without payment returns HTTP 402 with a
    `payment-required` header describing price and pay-to address; pay and retry.
    Response keys are in Portuguese, mirroring official Brazilian legal terms.
    Free sample at GET /v1/cnpj/amostra. Terms: /termos (Portuguese).
  contact:
    email: andre.fonseca@coppead.ufrj.br
servers:
  - url: https://api.brazilayer.com
  - url: http://159.195.38.228
paths:
  /v1/health:
    get:
      summary: Service status and data reference month (free)
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  status: { type: string, enum: [ok, degradado] }
                  servico: { type: string }
                  base_referencia:
                    type: [string, 'null']
                    description: Reference month (YYYY-MM) of the loaded registry
  /v1/cnpj/amostra:
    get:
      summary: Free full sample (format of /v1/empresa/{cnpj}/completo) for one fixed CNPJ
      responses:
        '200':
          description: Sample company bundle with `amostra: true`
          content:
            application/json:
              schema: { $ref: '#/components/schemas/EmpresaCompleta' }
  /v1/cnpj/empresa/{cnpj}:
    get:
      summary: Company registration data ($0.005 via x402)
      parameters: [ { $ref: '#/components/parameters/cnpj' } ]
      responses:
        '200':
          description: Registration card
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Empresa' }
        '402': { $ref: '#/components/responses/PagamentoExigido' }
        '400': { $ref: '#/components/responses/Erro' }
        '404': { $ref: '#/components/responses/Erro' }
  /v1/cnpj/empresa/{cnpj}/socios:
    get:
      summary: Partners/shareholders of a company ($0.005 via x402)
      parameters: [ { $ref: '#/components/parameters/cnpj' } ]
      responses:
        '200':
          description: Partners list
          content:
            application/json:
              schema:
                type: object
                properties:
                  cnpj: { type: string }
                  total: { type: integer }
                  socios:
                    type: array
                    items: { $ref: '#/components/schemas/Socio' }
                  fonte: { $ref: '#/components/schemas/Fonte' }
        '402': { $ref: '#/components/responses/PagamentoExigido' }
        '400': { $ref: '#/components/responses/Erro' }
        '404': { $ref: '#/components/responses/Erro' }
  /v1/cnpj/empresa/{cnpj}/completo:
    get:
      summary: 'Bundle: registration + partners + branches ($0.01 via x402)'
      parameters: [ { $ref: '#/components/parameters/cnpj' } ]
      responses:
        '200':
          description: Full company profile
          content:
            application/json:
              schema: { $ref: '#/components/schemas/EmpresaCompleta' }
        '402': { $ref: '#/components/responses/PagamentoExigido' }
        '400': { $ref: '#/components/responses/Erro' }
        '404': { $ref: '#/components/responses/Erro' }
  /v1/cnpj/busca:
    get:
      summary: Search companies ($0.01 via x402). At least one filter required.
      parameters:
        - { name: nome, in: query, schema: { type: string }, description: Full-text on legal and trade names (Portuguese, accent-insensitive) }
        - { name: uf, in: query, schema: { type: string, pattern: '^[A-Za-z]{2}$' }, description: 2-letter state code }
        - { name: municipio, in: query, schema: { type: string, pattern: '^\d{4}$' }, description: 4-digit RFB city code }
        - { name: cnae, in: query, schema: { type: string, pattern: '^\d{7}$' }, description: 7-digit CNAE activity code }
        - { name: porte, in: query, schema: { type: string, enum: [micro_empresa, pequeno_porte, demais, nao_informado] } }
        - { name: situacao, in: query, schema: { type: string, enum: [ativa, baixada, suspensa, inapta, nula], default: ativa } }
        - { name: pagina, in: query, schema: { type: integer, default: 1 } }
        - { name: por_pagina, in: query, schema: { type: integer, default: 20, maximum: 50 } }
      responses:
        '200':
          description: Paginated results; total capped at "10000+"
          content:
            application/json:
              schema:
                type: object
                properties:
                  total:
                    oneOf: [ { type: integer }, { type: string, const: '10000+' } ]
                  pagina: { type: integer }
                  resultados:
                    type: array
                    items:
                      type: object
                      properties:
                        cnpj: { type: string }
                        razao_social: { type: [string, 'null'] }
                        nome_fantasia: { type: [string, 'null'] }
                        uf: { type: [string, 'null'] }
                        municipio: { type: [string, 'null'] }
                        cnae_principal: { type: [string, 'null'] }
                        situacao: { type: [string, 'null'] }
                  fonte: { $ref: '#/components/schemas/Fonte' }
        '402': { $ref: '#/components/responses/PagamentoExigido' }
        '400': { $ref: '#/components/responses/Erro' }
  /v1/cnpj/socio/busca:
    get:
      summary: 'Reverse lookup: companies where a person/entity is partner ($0.02 via x402)'
      parameters:
        - { name: nome, in: query, required: true, schema: { type: string, minLength: 3 }, description: Person or entity name (full-text, accent-insensitive) }
        - { name: pagina, in: query, schema: { type: integer, default: 1 } }
        - { name: por_pagina, in: query, schema: { type: integer, default: 20, maximum: 50 } }
      responses:
        '200':
          description: Paginated results
          content:
            application/json:
              schema:
                type: object
                properties:
                  total:
                    oneOf: [ { type: integer }, { type: string, const: '10000+' } ]
                  pagina: { type: integer }
                  resultados:
                    type: array
                    items:
                      type: object
                      properties:
                        nome_socio: { type: [string, 'null'] }
                        cnpj: { type: string, description: 8-digit CNPJ root of the company }
                        razao_social: { type: [string, 'null'] }
                        qualificacao: { $ref: '#/components/schemas/CodigoDescricao' }
                        data_entrada: { type: [string, 'null'], format: date }
                  fonte: { $ref: '#/components/schemas/Fonte' }
        '402': { $ref: '#/components/responses/PagamentoExigido' }
        '400': { $ref: '#/components/responses/Erro' }
components:
  parameters:
    cnpj:
      name: cnpj
      in: path
      required: true
      schema: { type: string }
      description: Brazilian company tax ID, 14 digits, with or without punctuation
  responses:
    Erro:
      description: 'Error envelope: { erro: { codigo, mensagem } }'
      content:
        application/json:
          schema:
            type: object
            properties:
              erro:
                type: object
                properties:
                  codigo: { type: string }
                  mensagem: { type: string }
    PagamentoExigido:
      description: |
        x402 payment required. The `payment-required` response header carries base64
        JSON with accepted payment options (scheme "exact", USDC on Base, amount in
        6-decimal units, payTo address). Sign an EIP-3009 authorization and retry with
        the `payment-signature` header. x402 client libraries automate this.
  schemas:
    Fonte:
      type: object
      description: Data source and reference month
      properties:
        base: { type: string, const: RFB/CNPJ }
        referencia: { type: [string, 'null'], description: YYYY-MM }
    CodigoDescricao:
      type: object
      properties:
        codigo: { type: [string, 'null'] }
        descricao: { type: [string, 'null'] }
    Socio:
      type: object
      properties:
        nome: { type: [string, 'null'] }
        tipo: { type: [string, 'null'], enum: [pessoa_fisica, pessoa_juridica, estrangeiro, null] }
        documento_mascarado: { type: [string, 'null'], description: CPF comes pre-masked from the government source }
        qualificacao: { $ref: '#/components/schemas/CodigoDescricao' }
        data_entrada: { type: [string, 'null'], format: date }
        faixa_etaria: { type: [string, 'null'], description: 'age bracket, e.g. 41-50' }
        representante_legal: { type: [string, 'null'] }
    Empresa:
      type: object
      properties:
        cnpj: { type: string, description: 14 digits }
        razao_social: { type: [string, 'null'], description: legal name }
        nome_fantasia: { type: [string, 'null'], description: trade name }
        matriz_filial: { type: [string, 'null'], enum: [matriz, filial, null] }
        situacao_cadastral:
          type: object
          description: 'registration status (Ativa = active, Baixada = closed)'
          properties:
            codigo: { type: [string, 'null'] }
            descricao: { type: [string, 'null'] }
            data: { type: [string, 'null'], format: date }
            motivo: { type: [string, 'null'] }
        data_inicio_atividade: { type: [string, 'null'], format: date }
        natureza_juridica: { $ref: '#/components/schemas/CodigoDescricao' }
        porte: { type: [string, 'null'], enum: [micro_empresa, empresa_pequeno_porte, demais, nao_informado, null] }
        capital_social: { type: [number, 'null'] }
        cnae_principal: { $ref: '#/components/schemas/CodigoDescricao' }
        cnae_secundarios:
          type: array
          items: { $ref: '#/components/schemas/CodigoDescricao' }
        endereco:
          type: object
          properties:
            logradouro: { type: [string, 'null'] }
            numero: { type: [string, 'null'] }
            complemento: { type: [string, 'null'] }
            bairro: { type: [string, 'null'] }
            municipio: { type: [string, 'null'] }
            uf: { type: [string, 'null'] }
            cep: { type: [string, 'null'] }
        contato:
          type: object
          properties:
            email: { type: [string, 'null'] }
            telefone: { type: [string, 'null'] }
        simples:
          type: object
          description: Simples/MEI small-business tax regime flags
          properties:
            optante: { type: boolean }
            mei: { type: boolean }
        fonte: { $ref: '#/components/schemas/Fonte' }
    EmpresaCompleta:
      allOf:
        - $ref: '#/components/schemas/Empresa'
        - type: object
          properties:
            socios:
              type: array
              items: { $ref: '#/components/schemas/Socio' }
            total_socios: { type: integer }
            filiais:
              type: array
              items:
                type: object
                properties:
                  cnpj: { type: string }
                  uf: { type: [string, 'null'] }
                  municipio: { type: [string, 'null'] }
                  situacao: { type: [string, 'null'] }
