openapi: 3.2.0
info:
  title: AGENTUM Business Counterparty Verification API
  version: 0.1.0
  description: 'Agente comercial da AGENTUM: inteligência empresarial e verificação de contraparte, pagas por chamada via x402 (USDC, Base mainnet). Rotas HTTP diretas — o serviço também fala A2A (POST /) para agentes que preferem esse protocolo, ver /.well-known/agent-card.json.'
  x-guidance: Use GET /preflight?q=<CNPJ|LEI|nome> pra verificação de contraparte de uma empresa (brasileira ou não) antes de fechar negócio — devolve um veredito consolidado (band/confidence/flags), nunca um score inventado. Use GET /company-intelligence?cnpj=<14 dígitos> pra inteligência de CNPJ brasileiro cruzada com bases de integridade pública (TCU, CEIS, CNEP, CVM). Use GET /company?cnpj=<14 dígitos> pra cadastro básico (razão social, situação, endereço) sem a checagem de integridade. Todas exigem pagamento x402 em USDC na rede Base (eip155:8453), carteira 0x7D1EDdfBd167787251fed83b250ABBeA1cf59a6F.
  contact:
    email: agentumcomercial@carmozinog.com
servers:
- url: https://business.agentum.lat
tags:
- name: Counterparty Verification
paths:
  /preflight:
    get:
      operationId: preflight
      summary: Verificação de contraparte (CNPJ, LEI ou nome de empresa)
      description: 'Roteador que aceita um CNPJ brasileiro (14 dígitos), um código LEI (20 caracteres) ou um nome de empresa, e devolve um veredito consolidado de contraparte: entidade identificada, banda de risco (clear/flagged/insufficient_data), confiança na cobertura de dado, e os achados componentes com fonte e status individual. Nunca fabrica um score — band/flags são derivados deterministicamente de fatos verificados em fontes públicas oficiais.'
      tags:
      - Counterparty Verification
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.150000'
        protocols:
        - x402: {}
      parameters:
      - name: q
        in: query
        required: true
        schema:
          type: string
          description: CNPJ brasileiro (14 dígitos, com ou sem máscara), código LEI (20 caracteres) ou nome de empresa
        example: '68964713000109'
      responses:
        '200':
          description: Veredito consolidado de contraparte
          content:
            application/json:
              schema:
                type: object
                properties:
                  query:
                    type: object
                    properties:
                      type:
                        type: string
                        enum:
                        - cnpj
                        - lei
                        - name
                      value:
                        type: string
                  entity:
                    type: object
                    properties:
                      name:
                        type: string
                      jurisdiction:
                        type: string
                      identifier:
                        type: object
                        properties:
                          type:
                            type: string
                          value:
                            type: string
                      status:
                        type: string
                  band:
                    type: string
                    enum:
                    - clear
                    - flagged
                    - insufficient_data
                  confidence:
                    type: string
                    enum:
                    - high
                    - medium
                    - low
                  flags:
                    type: array
                    items:
                      type: object
                      properties:
                        code:
                          type: string
                        source:
                          type: string
                        fact:
                          type: string
                  components:
                    type: array
                    items:
                      type: object
                      properties:
                        source:
                          type: string
                        status:
                          type: string
                          enum:
                          - verified
                          - not_found_in_checked_sources
                          - unavailable
                          - not_applicable
                          - conflicting
                        fact:
                          type: string
                        observedAt:
                          type: string
                  sources:
                    type: array
                    items:
                      type: object
                      properties:
                        name:
                          type: string
                        reference:
                          type:
                          - string
                          - 'null'
                  coverage:
                    type: object
                  as_of:
                    type: string
                  version:
                    type: string
                  disclaimer:
                    type: string
              example:
                query:
                  type: cnpj
                  value: '68964713000109'
                entity:
                  name: AGENTUM LTDA
                  jurisdiction: BR
                  identifier:
                    type: cnpj
                    value: '68964713000109'
                  status: ATIVA
                band: clear
                confidence: high
                flags: []
                components:
                - source: TCU - Inidôneos e Suspensos
                  status: not_found_in_checked_sources
                  fact: Nenhum registro encontrado
                  observedAt: '2026-09-11T12:00:00.000Z'
                sources:
                - name: TCU - Inidôneos e Suspensos
                  reference: null
                coverage:
                  sourcesApplicable:
                  - TCU
                  sourcesCheckedSuccessfully:
                  - TCU
                  sourcesUnavailable: []
                as_of: '2026-09-11T12:00:00.000Z'
                version: '1.0'
                disclaimer: Informação factual agregada de fontes públicas oficiais. Não é pontuação de risco, aconselhamento jurídico/financeiro, nem garantia de idoneidade — decisão final é de quem consulta.
        '400':
          description: Query inválida (não é CNPJ, LEI nem nome utilizável)
        '404':
          description: Nenhuma empresa encontrada pra esse LEI/nome
        '402':
          description: Payment Required