Developers • API Pública v1-alpha

Documentação de integração do Lompa 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

Apenas endpoints públicos já registrados no backend. Sem inventar recursos que ainda não existem.

GET/api/public/v1/company/{cnpj}placeholder alpha

Consulta pública placeholder para consolidar contrato de empresa por CNPJ e padrão de erro/request_id.

POST/api/public/v1/nfeplaceholder alpha

Placeholder de criação de NF-e para fixar namespace fiscal partner-facing (sem fluxo final implementado ainda).

GET/api/public/v1/nfe/{id}placeholder alpha

Placeholder de consulta de NF-e para evolução futura do contrato fiscal público.

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 como referência de contrato.

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: Lompa ERP API Publica
  version: 1.0.0-alpha.1
  description: |
    Especificacao inicial da API publica partner-facing do ERP Lompa.

    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, apenas os endpoints publicos atualmente registrados em `/api/public/v1`
    estao documentados. Alguns endpoints ainda sao placeholders e servem para consolidar contrato, DX e padroes.

    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: Lompa ERP
servers:
  - url: https://erp.lompa.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 (v1-alpha; placeholders iniciais)
externalDocs:
  description: Changelog da API Publica
  url: https://erp.lompa.com.br/developers/changelog/api-publica
paths:
  /api/public/v1/company/{cnpj}:
    get:
      tags:
        - Empresa
      summary: Consultar empresa por CNPJ (placeholder alpha)
      description: |
        Endpoint placeholder da API publica. Atualmente retorna resposta basica e valida CNPJ com 14 digitos.

        Observacao importante:
        - auth publica final sera OAuth 2.0 + PKCE
        - neste placeholder alpha, 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:
        '200':
          description: Resposta placeholder de consulta de empresa.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CompanyLookupPlaceholderResponse'
              examples:
                placeholder:
                  value:
                    cnpj: '12345678000199'
                    status: placeholder - consulta CNPJ será implementada
        '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 (placeholder alpha)
      description: |
        Endpoint placeholder para futura criacao de NF-e partner-facing.
        Nesta fase retorna apenas uma confirmacao placeholder para consolidar namespace e contrato.
      operationId: createPublicNFePlaceholder
      security: []
      parameters:
        - $ref: '#/components/parameters/XRequestId'
      responses:
        '201':
          description: Resposta placeholder de criacao de NF-e.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NFeCreatePlaceholderResponse'
              examples:
                created:
                  value:
                    message: NF-e creation placeholder
  /api/public/v1/nfe/{id}:
    get:
      tags:
        - Fiscal
      summary: Consultar NF-e (placeholder alpha)
      description: |
        Endpoint placeholder para futura consulta de NF-e partner-facing.
      operationId: getPublicNFePlaceholder
      security: []
      parameters:
        - name: id
          in: path
          required: true
          description: Identificador da NF-e no contrato publico (placeholder).
          schema:
            type: string
            example: 'nfe_123'
        - $ref: '#/components/parameters/XRequestId'
      responses:
        '200':
          description: Resposta placeholder de consulta de NF-e.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NFePlaceholderResponse'
              examples:
                placeholder:
                  value:
                    id: nfe_123
                    status: placeholder
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://erp.lompa.com.br/oauth/authorize
          tokenUrl: https://erp.lompa.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
    CompanyLookupPlaceholderResponse:
      type: object
      required:
        - cnpj
        - status
      properties:
        cnpj:
          type: string
          example: '12345678000199'
        status:
          type: string
          example: placeholder - consulta CNPJ será implementada
    NFeCreatePlaceholderResponse:
      type: object
      required:
        - message
      properties:
        message:
          type: string
          example: NF-e creation placeholder
    NFePlaceholderResponse:
      type: object
      required:
        - id
        - status
      properties:
        id:
          type: string
          example: nfe_123
        status:
          type: string
          example: placeholder