Developers • API Pública v1-alpha

Documentação de integração do Bravelo ERP

Base inicial da API pública partner-facing, com foco no estágio real do produto: onboarding, fiscal (naturezas/configuração) e integração inicial com Mercado Livre.

Escopo enxutoContratos primeiroSem overengineering
Abrir OpenAPI YAMLVer changelog da APIEntrar no ERP

Escopo desta fase

Documentação e contrato primeiro. A superfície pública permanece pequena enquanto o produto consolida onboarding, fiscal e conexão inicial com Mercado Livre.

Dentro do escopo

  • Onboarding inicial
  • Configuração fiscal / naturezas de operação
  • Conexão inicial com Mercado Livre
  • Padrões de auth, erros, versionamento e changelog
  • OpenAPI + docs de integração no frontend

Fora do escopo (agora)

  • API pública completa de pedidos/produtos/estoque
  • Portal avançado de parceiros
  • SDKs oficiais
  • Webhooks outbound de plataforma
  • Sandbox completo

Endpoints publicados no spec alpha

Namespaces já registrados no backend, ainda indisponíveis para integração.

GET/api/public/v1/company/{cnpj}indisponível (501)

Namespace reservado; a consulta ainda não está disponível e falha explicitamente.

POST/api/public/v1/nfeindisponível (501)

Namespace reservado; nenhuma NF-e é criada enquanto o contrato final não estiver implementado.

GET/api/public/v1/nfe/{id}indisponível (501)

Namespace reservado; a consulta ainda não está disponível e falha explicitamente.

Quickstart (alpha)

A autenticação final da API pública será OAuth 2.0 + PKCE. Enquanto a camada pública ainda está em consolidação, use o spec somente como referência de planejamento; as operações respondem HTTP 501.

1. Abra o spec OpenAPI

O arquivo YAML é a fonte de verdade inicial do contrato público e será usado para renderização futura no portal.

/developers/openapi/v1-alpha

2. Padronize tratamento de erro

Consuma code como chave de tratamento e registre request_id para suporte/observabilidade.

INVALID_CNPJ • request_id • X-Request-Id

3. Acompanhe o changelog

Mudanças de contrato e depreciações serão registradas no changelog da API pública.

/developers/changelog/api-publica

Preview do OpenAPI (YAML)

Visualização rápida do spec. O portal completo (renderizador OpenAPI) entra na próxima etapa.

openapi: 3.0.3
info:
  title: Bravelo ERP API Publica
  version: 1.0.0-alpha.1
  description: |
    Especificacao inicial da API publica partner-facing do Bravelo ERP.

    Escopo atual (v1-alpha):
    - onboarding inicial (em preparacao para exposicao publica)
    - fiscal / naturezas de operacao (em preparacao para exposicao publica)
    - integracao inicial com Mercado Livre (em preparacao para fachada publica)

    Nesta primeira versao do spec, os namespaces planejados em `/api/public/v1`
    estao documentados. Enquanto a implementacao real e a autenticacao nao forem
    entregues, todas as operacoes reservadas falham explicitamente com HTTP 501.

    Autenticacao alvo da API publica: OAuth 2.0 (Authorization Code + PKCE), conforme decisoes de arquitetura.
    O runtime atual ainda esta em fase de transicao para esse modelo.
  contact:
    name: Bravelo ERP
servers:
  - url: https://api.bravelo.com.br
    description: Producao (target)
  - url: http://localhost:8080
    description: Desenvolvimento local (backend)
tags:
  - name: Empresa
    description: Endpoints de empresa para API publica (alpha; escopo enxuto)
  - name: Fiscal
    description: Endpoints fiscais partner-facing planejados para a v1-alpha
externalDocs:
  description: Changelog da API Publica
  url: https://www.bravelo.com.br/developers/changelog/api-publica
paths:
  /api/public/v1/company/{cnpj}:
    get:
      tags:
        - Empresa
      summary: Consultar empresa por CNPJ (reservado)
      description: |
        Namespace reservado da API publica. O runtime valida o formato do CNPJ,
        mas nao realiza a consulta e responde 501.

        Observacao importante:
        - auth publica final sera OAuth 2.0 + PKCE
        - enquanto indisponivel, o runtime ainda nao exige Bearer token
      operationId: getPublicCompanyByCNPJ
      security: []
      parameters:
        - name: cnpj
          in: path
          required: true
          description: CNPJ com 14 digitos numericos.
          schema:
            type: string
            pattern: '^\d{14}$'
            example: '12345678000199'
        - $ref: '#/components/parameters/XRequestId'
      responses:
        '501':
          description: Endpoint ainda não implementado.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicErrorResponse'
              examples:
                unavailable:
                  value:
                    code: NOT_IMPLEMENTED
                    message: Endpoint público ainda não disponível
                    request_id: 8bb8d1d3-b4e9-4f59-9608-1fdf7ee6f060
        '400':
          description: CNPJ invalido.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicErrorResponse'
              examples:
                invalidCnpj:
                  value:
                    code: INVALID_CNPJ
                    message: CNPJ deve conter 14 dígitos numéricos
                    details:
                      field: cnpj
                    request_id: 8bb8d1d3-b4e9-4f59-9608-1fdf7ee6f060
  /api/public/v1/nfe:
    post:
      tags:
        - Fiscal
      summary: Criar NF-e (reservado)
      description: |
        Namespace reservado para futura criacao de NF-e partner-facing.
        Nesta fase a operacao nao cria recursos e responde 501.
      operationId: createPublicNFeReserved
      security: []
      parameters:
        - $ref: '#/components/parameters/XRequestId'
      responses:
        '501':
          description: Endpoint ainda não implementado.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicErrorResponse'
              examples:
                unavailable:
                  value:
                    code: NOT_IMPLEMENTED
                    message: Endpoint público ainda não disponível
                    request_id: 8bb8d1d3-b4e9-4f59-9608-1fdf7ee6f060
  /api/public/v1/nfe/{id}:
    get:
      tags:
        - Fiscal
      summary: Consultar NF-e (reservado)
      description: |
        Namespace reservado para futura consulta de NF-e partner-facing.
        Nesta fase a operacao responde 501.
      operationId: getPublicNFeReserved
      security: []
      parameters:
        - name: id
          in: path
          required: true
          description: Identificador planejado da NF-e no contrato publico.
          schema:
            type: string
            example: 'nfe_123'
        - $ref: '#/components/parameters/XRequestId'
      responses:
        '501':
          description: Endpoint ainda não implementado.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicErrorResponse'
              examples:
                unavailable:
                  value:
                    code: NOT_IMPLEMENTED
                    message: Endpoint público ainda não disponível
                    request_id: 8bb8d1d3-b4e9-4f59-9608-1fdf7ee6f060
components:
  securitySchemes:
    OAuth2Auth:
      type: oauth2
      description: |
        Esquema alvo da API publica (planejado/arquitetado). A implementacao completa sera entregue nas MTs de OAuth.
        Fluxo principal: Authorization Code + PKCE para apps de terceiros.
      flows:
        authorizationCode:
          authorizationUrl: https://api.bravelo.com.br/oauth/authorize
          tokenUrl: https://api.bravelo.com.br/oauth/token
          scopes:
            company:read: Leitura de dados de empresa expostos na API publica
            fiscal:read: Leitura de configuracoes fiscais e naturezas
            fiscal:write: Alteracao de configuracoes fiscais suportadas pela API publica
            marketplace:ml:read: Leitura de status de integracao Mercado Livre
            marketplace:ml:write: Operacoes de conexao/desconexao Mercado Livre
  parameters:
    XRequestId:
      name: X-Request-Id
      in: header
      required: false
      description: |
        Identificador de correlacao opcional enviado pelo cliente.
        Quando enviado, a API publica deve ecoar esse valor em respostas de erro.
      schema:
        type: string
        example: req-abc-123
  headers:
    XRequestId:
      description: Identificador de correlacao da requisicao.
      schema:
        type: string
        example: 8bb8d1d3-b4e9-4f59-9608-1fdf7ee6f060
  schemas:
    PublicErrorResponse:
      type: object
      required:
        - code
        - message
        - request_id
      properties:
        code:
          type: string
          example: INVALID_CNPJ
        message:
          type: string
          example: CNPJ deve conter 14 dígitos numéricos
        details:
          description: Contexto adicional estruturado (opcional).
          nullable: true
        request_id:
          type: string
          example: 8bb8d1d3-b4e9-4f59-9608-1fdf7ee6f060