Documentação da API

Guia de integração e uso da API RESTful do Omega Computer.

Introdução

A API do Omega Computer segue o padrão RESTful e utiliza JSON para comunicação. Todas as respostas são envelopadas em um formato padrão para facilitar o tratamento de erros e sucesso.

Base URL: https://app.omegacomputer.com.br/api
Abrir Swagger UI
Formato de Resposta (Envelope)
{
  "success": true,
  "data": { ... },     // Objeto de retorno em caso de sucesso
  "error": null        // Nulo se success == true
}
Formato de Erro
{
  "success": false,
  "data": null,
  "error": {
    "code": "AUTH_INVALID_CREDENTIALS",
    "message": "Usuário ou senha incorretos.",
    "details": null
  }
}

Autenticação

Utilizamos OAuth2 com JWT (JSON Web Tokens). Para acessar recursos protegidos, você deve enviar o token no cabeçalho da requisição.

Header Obrigatório
Authorization: Bearer {seu_token_aqui}
Obtendo o Token

Faça uma requisição POST para /api/auth/login com as credenciais.

POST /api/auth/login
Content-Type: application/json

{
  "login": "seu_usuario",
  "senha": "sua_senha"
}

Resposta:

{
  "success": true,
  "data": {
    "accessToken": "eyJhbGciOiJIUz...",
    "refreshToken": "7f8a9b0c...",
    "expiration": "2024-01-01T12:00:00",
    "razaoSocial": "EMPRESA EXEMPLO LTDA",
    "acessoContabil": true,
    "acessoFiscal": true,
    "acessoNfe": false,
    "acessoRecibo": true,
    "acessoSocial": false,
    "acessoCustom": false,
    "acessoAssinatura": false
  },
  "error": null
}

Autenticação (Escritório)

Para escritórios contábeis, utilize o endpoint específico abaixo. O token retornado deve ser usado da mesma forma (Bearer Token).

POST /api/auth/loginEscritorio
Corpo da Requisição
{
  "login": "00000000000000", // CNPJ do Escritório (Sem Máscara)
  "senha": "sua_senha"
}
Resposta
{
  "success": true,
  "data": {
    "accessToken": "eyJhbGciOiJIUz...",
    "refreshToken": "7f8a9b0c...",
    "expiration": "2024-01-01T12:00:00",
    "razaoSocial": "ESCRITÓRIO CONTÁBIL EXEMPLO",
    "acessoContabil": true,
    "acessoFiscal": true,
    "acessoNfe": true,
    "acessoRecibo": true,
    "acessoSocial": true,
    "acessoCustom": false,
    "acessoAssinatura": false
  },
  "error": null
}

Módulo Escritório

Endpoints dedicados para gestão de múltiplos clientes por um único escritório contábil.

Listar Empresas Vinculadas

Retorna a lista de empresas (clientes) sob responsabilidade do CNPJ do escritório logado.
A permissão de acesso é validada pelo vínculo CNPJ_RESPONSAVEL no cadastro do cliente.

GET /api/escritorio/{cnpjResponsavel}/empresas
Parâmetros:
  • cnpjResponsavel (path): CNPJ do escritório contábil (apenas números ou formatado).
Exemplo de Requisição: 
GET /api/escritorio/11222333000100/empresas
Authorization: Bearer {seu_token}
Exemplo de Resposta (200 OK): 
{
  "success": true,
  "data": [
    {
      "cnpj": "11222333000100",
      "razao_social": "CLIENTE EXEMPLO LTDA",
      "acesso_contabil": true,
      "acesso_fiscal": true,
      "acesso_nfe": true,
      "acesso_recibo": false,
      "acesso_social": true,
      "acesso_custom": false,
      "acesso_assinatura": false,
      "situacao_usuario": "1"
    }
  ],
  "error": null
}

Integrações

Endpoints que atuam como proxy para serviços externos de consulta de dados.

BrasilAPI
CNPJ

Consulta dados cadastrais na Receita Federal.

GET /api/brasil/cnpj/00000000000000
CEP

Busca endereço por CEP.

GET /api/brasil/cep/00000000
Invertexto (com IBGE)

Consulta dados normalizados e enriquecidos com código IBGE local.

CNPJ
GET /api/invertexto/cnpj/00000000000000

Utilitários

Endpoints auxiliares para operações do sistema.

Geografia
GET /api/Utils/GetMunicipiosByUf?uf={uf}
Retorna lista de municípios para uma UF (Sigla).
GET /api/Utils/GetIbgeCode?uf={uf}&municipio={nome}
Retorna o código IBGE do município.
Sistema
  • GET /api/Notificacoes/Checar - Verifica se há arquivos processados prontos para download.
  • POST /api/Theme/toggle - Alterna tema (Claro/Escuro).

Processamento de Arquivos

Fluxo assíncrono para upload e processamento de arquivos grandes.

1. Upload
POST /api/Upload/upload
Content-Type: multipart/form-data

Arquivo: (binary)
Cnpj: "00000000000000"
Modulo: 0 (Fiscal) | 1 (Nfe) | 2 (Rps) | 3 (Contabil) | 4 (Social) | 7 (Backup)
TipoImportacao: (opcional)
2. Resposta de Upload
{
  "protocolo": 123,
  "mensagem": "Importação iniciada em segundo plano."
}
3. Download

Após a conclusão (notificada via /api/Notificacoes/Checar), use o ID para baixar.

GET /Download/{id}

Códigos de Erro

Código Interno HTTP Descrição
AUTH_INVALID_CREDENTIALS 401 Login ou senha incorretos.
AUTH_ACCOUNT_DISABLED 403 Usuário inativo ou bloqueado no sistema.
AUTH_CLIENT_DISABLED 403 Empresa contratante suspensa ou inativa.
VAL_REQUIRED_FIELD 400 Falha de validação nos campos enviados.
SYS_INTERNAL_ERROR 500 Erro interno não tratado no servidor.

Principais Endpoints

Abaixo listamos os endpoints principais disponíveis nesta versão da API.

  • POST /api/auth/login - Realiza login e retorna tokens.
  • POST /api/auth/loginEscritorio - Autenticação de Escritórios.
  • POST /api/auth/refresh - Renova o Access Token usando Refresh Token.

Importação de NFe / CTe

Importa arquivos XML de Nota Fiscal Eletrônica (NFe) ou Conhecimento de Transporte (CTe).

POST /api/fiscal/importacao/nfe
Parâmetros (Form-Data):
  • arquivo (file): O arquivo XML (NFe modelo 55 ou CTe modelo 57).
  • cnpj (string): CNPJ da empresa (deve ser Emitente, Destinatário ou Transportador).
Importação de NFS-e Nacional

Importa arquivos XML no padrão nacional de Nota Fiscal de Serviço Eletrônica.

POST /api/fiscal/importacao/nfse-nacional
Parâmetros (Form-Data):
  • arquivo (file): O arquivo XML da NFS-e Nacional.
  • cnpj (string): CNPJ da empresa relacionada à nota.
Importação de Prefeitura (RPS/NFSe)

Importa arquivos de RPS ou NFSe baseados no código IBGE da prefeitura.
Suporta múltiplos formatos (XML, Excel, TXT) dependendo do IBGE informado.

POST /api/fiscal/importacao/prefeitura
Parâmetros (Form-Data):
  • arquivo (file): O arquivo a ser importado.
  • cnpj (string): CNPJ da empresa.
  • ibge (string): Código IBGE (7 dígitos) da prefeitura. Ex: 3518800 (Guarulhos).

  • GET /api/escritorio/{cnpjResponsavel}/empresas - Lista clientes vinculados.