Manual Técnico do Serviço de API
API (Application Programming Interface) é um conjunto de regras e recursos que permite a comunicação e a troca de informações entre diferentes sistemas, aplicações ou serviços.
Por meio de uma API, um sistema pode solicitar, consultar, enviar, alterar ou excluir dados de outro sistema de forma padronizada, sem a necessidade de acessar diretamente sua estrutura interna.
Em sistemas corporativos, as APIs são utilizadas para realizar integrações entre aplicações, automatizando o compartilhamento de informações e permitindo que diferentes sistemas trabalhem de forma integrada.
Introdução
Este documento apresenta a documentação técnica do serviço de API do CoreBusiness, cujo objetivo é disponibilizar uma interface padronizada para integração entre aplicações externas e o sistema.
A API permite a comunicação entre diferentes sistemas por meio de serviços Web baseados no protocolo HTTP, utilizando estruturas de dados no formato JSON.
Este manual apresenta os endpoints disponibilizados para integração, contemplando:
• métodos HTTP;
• rotas dos serviços;
• parâmetros de entrada;
• estruturas das requisições;
• estruturas das respostas;
• regras de utilização;
• autenticação;
• códigos de retorno;
• exemplos de utilização.
O objetivo desta documentação é fornecer aos desenvolvedores e integradores as informações necessárias para realizar a integração com o CoreBusiness de forma adequada.
Os valores apresentados nos exemplos deste manual são meramente ilustrativos. IDs, CNPJ, CPF, SKU, produtos, empresas, tabelas de preço, operações fiscais, vendedores e demais informações devem ser substituídos pelos dados existentes no ambiente CoreBusiness utilizado pela integração.
Dados Gerais
A documentação interativa da API poderá ser acessada por meio da URL disponibilizada para cada ambiente do cliente:
https://urlDoCliente.com.br:5000/swagger/index.htmlO endereço poderá variar conforme o ambiente utilizado. O Swagger permite consultar os endpoints disponíveis, visualizar os modelos de requisição e resposta e realizar testes dos serviços, conforme as permissões disponíveis no ambiente.
Cabeçalho Accept-Language
Nas requisições realizadas para a API, deverá ser informado o cabeçalho: HTTP Accept-Language com o valor pt-BR.
Exemplo:
Accept-Language: pt-BRAutenticação
Os endpoints da API utilizam autenticação por meio do esquema Bearer Token.
O token deverá ser informado no cabeçalho HTTP Authorization.
Nome do cabeçalho:
• Authorization
Valor do cabeçalho:
• O valor do token será gerado pelo endpoint GerarToken.
Exemplo de token:
yJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJMTVNfVXNlciIsImp0aSI6ImU5OTNiMjViLThmYzgtNDNlYy05NmRlLTViYmJiZDMyM2ExOCIsImh0dHA6Ly9zY2hlbWFzLm1pY3Jvc29mdC5jb20vd3MvMjAwOC8wNi9pZGVudGl0eS9jbGFpbXMvcm9sZSI6IkxNU19BZG1pbmlzdHJhdG9yIiwiZXhwIjoxNzg0NTcxMjY5LCJpc3MiOiJodHRwczovL3NhbmRib3gtYXBpY3RlYm9zY2gubG95YWx0eWNvcnAuY29tLm14In0.lv_W6dPpHJesVJM39mih20IfneNNDamPuXt....
Tratamento de Erros
A API utiliza códigos de status HTTP para indicar o resultado das requisições.
Quando uma requisição não puder ser processada, o retorno deverá ser analisado para identificar a causa do problema.
HTTP 400 – Bad Request
Indica que a requisição enviada não pôde ser processada.
Entre as possíveis causas estão:
• Informações obrigatórias não preenchidas;
• Estrutura da requisição inválida;
• Dados incompatíveis com as regras do endpoint;
• Credenciais ou informações de acesso incorretas, quando aplicável.
A mensagem retornada pela API deverá ser utilizada para identificar a causa específica do erro.
Pedidos
O endpoint de Pedidos é responsável pela criação e cadastro de pedidos de venda no CoreBusiness. Por meio deste serviço é possível enviar informações referentes ao pedido, cliente, empresa, vendedor, forma de pagamento, operação fiscal, endereço de entrega e itens.
Principais regras• O cliente deverá ser identificado por meio das informações disponíveis no cadastro de pessoa.
• A empresa poderá ser identificada pelo ID ou pelo CNPJ, conforme o modelo disponibilizado pela API.
• Vendedor, forma de pagamento e operação fiscal utilizam identificadores cadastrados no CoreBusiness.
• O produto poderá ser identificado pelo ID ou pelo SKU.
• O valor unitário poderá ser informado quando a integração não utilizar o valor da tabela de preço.
• A tabela de preço deverá utilizar um identificador existente no ambiente.
• O endereço poderá utilizar um endereço já cadastrado ou as informações do endereço poderão ser enviadas conforme a estrutura do endpoint.
• Os parâmetros efetivarPedido e reservarItens permitem controlar o processamento do pedido.
• ignorarFaltaDeEstoqueNaEfetivacao é opcional.
1. Consultar ou obter os dados do cliente.
2. Identificar a empresa que realizará a operação.
3. Obter os identificadores de vendedor, forma de pagamento e operação fiscal.
4. Identificar os produtos que serão incluídos no pedido.
5. Montar o Request Body.
6. Enviar a requisição para: POST /api/COM/Pedidos
7. Validar o retorno da API.
8. Confirmar o processamento do pedido no CoreBusiness.
{
"cp": "string",
"nome": "string",
"enderecos": [
{
"id": 0 //se editar,
"codigoIBGE": "string",
"cep": "string",
"uf": "string",
"cidade": "string",
"bairro": "string",
"logradouro": "string",
"numero": "string",
"complemento": "string",
"finalidade": 0 //tabela de finalidade endereço no final do documento
}
],
"emails": [ //opcional
{
"email": "string",
"finalidade": {
"valor": 0, //tabela finalidade e-mail no final do documento
"descricao": "string"
}
}
],
"telefones": [
{
"id": 0, //se for atualizar o cadastro
"ddd": "string",
"numero": "string",
"finalidade": 0, //tabela de finalidade telefone no final do documento
"tipoTelefone": { //gerado pela Deltacon (opcional)
"id": 0,
"nome": "string"
}
}
],
"documentos": [
{
"tipo": 1, //tabela de tipo de documento da pessoa
"numero": "string",
"opcaoDoc": 0 //tabela opção de documentos da pessoa no final do documento
}
],
"sites": [ //opcional
{
"id": 0,
"enderecoSite": "string"
}
],
"cliente": {
"tipoConsumo": 0, //Tipo Consumo (apenas CNPJ), tabela no final do documento
},
"naoAtualizar": true //sempre que for cadastro novo
}
Emitir DFe
Endpoint responsável pela emissão de Documentos Fiscais eletrônicos (DFe) vinculados a um pedido.
Identificação do pedidoO pedido poderá ser identificado de duas formas:
• pelo id do pedido; ou
• pela combinação de numero, serie e empresa.
Quando o id do pedido for informado, os demais dados de identificação poderão não ser necessários, conforme o comportamento apresentado no Swagger.
1. Identificar o pedido que deverá ser faturado.
2. Obter o id do pedido ou os demais dados necessários para sua identificação.
3. Montar o Request Body.
4. Enviar a requisição para: POST /api/COM/Pedidos/EmitirDFe
5. Validar o retorno da API e acompanhar o processamento do documento fiscal.
|
Busca Produtos Paginados
O endpoint BuscaProdutosPaginado permite consultar os produtos cadastrados no CoreBusiness utilizando paginação e filtros.
A consulta pode ser realizada considerando:
• página;
• quantidade de registros;
• período de inserção ou atualização;
• empresa;
• situação do produto;
• carregamento dos arquivos relacionados ao produto.
Por se tratar de uma requisição GET, os filtros são informados como parâmetros da URL, e não como Request Body JSON.
|
Para consultas que não necessitam das imagens ou demais arquivos associados aos produtos, recomenda-se manter carregaBlobArquivos desabilitado, evitando respostas maiores e possível impacto no desempenho.
Novo Produto
O endpoint NovoProduto permite realizar o cadastro de um novo produto no CoreBusiness.
O serviço permite informar os dados principais do produto e informações complementares, como:
• SKU;
• código de barras;
• nome;
• unidade;
• características;
• conversões de unidade;
• categorias;
• afinidades (compatíveis, Alternativos, Seguros, Garantias, Aplicações, Relacionados, Tags e Observações);
• grupo;
• descrição;
• NCM;
• CEST;
• composição;
• preços;
• dimensões;
• promoções;
• códigos;
• integrações;
• informações relacionadas à produção.
Conforme o modelo apresentado no Swagger:
• Nome, SKU, NCM, Grupo, Unidade e Empresa são obrigatórios.
• Composição e Preços são opcionais.
• Quando for informada uma composição, deverão ser informados os objetos dos produtos correspondentes aos componentes.
• Os produtos utilizados na composição podem ser identificados por ID ou SKU, conforme o modelo.
• Quando forem informadas múltiplas categorias, deverá ser observada a estrutura aceita pelo endpoint.
• O campo codigoBarras, quando preenchido, será utilizado como código de barras do tipo EAN13, conforme indicado pelo Swagger.
Para o cadastro do produto temos alguns cadastros adicionais como por exemplo:
POST /api/GEM/Caracteristicas
POST /api/GEM/CaracteristicaOpcoes/ListarPorCaracteristica/{idCaracteristica}
POST /api/GEM/Produtos/ListaUnidades
POST /api/GEM/Categorias/Arvore
POST /api/GEM/GruposProduto/Arvore
{
"id": 0,
"sku": "string",
"codigoBarras": "string",
"nome": "string",
"un": "string",
"caracteristicas": [
{
"id": 0,
"caracteristica": "string",
"conteudo": "string"
}
],
"conversoresDeUnidades": [
{
"id": 0,
"descricao": "string",
"fatorConversao": 0,
"unidadeEntrada": "string",
"unidadeSaida": "string"
}
],
"categorias": [
{
"id": 0,
"nome": "string",
"pai": "string"
}
],
"categoria": "string",
"afinidades": [
{
"id": 0,
"produto": "string",
"afim": "string",
"tipo": {
"valor": 0,
"descricao": "string"
}
}
],
"grupo": "string",
"descricao": "string",
"descricaoDetalhada": "string",
"ncm": "string",
"empresa": {
"id": 0,
"cnpj": "string",
"nome": "string"
},
"cest": {
"id": 0,
"codigo": "string",
"descricao": "string"
},
"composicao": [
{
"id": 0,
"produto": "string",
"quantidade": 0,
"unidadeSigla": "string"
}
],
"fotoPrincipal": "string",
"ativo": true,
"precos": [
{
"id": 0,
"tabelaPreco": "string",
"valor": 0,
"un": "string"
}
],
"dimensoes": [
{
"id": 0,
"altura": 0,
"largura": 0,
"peso": 0,
"profundidade": 0,
"tipo": 0, // tabela tipo dimensões no final do documento
"un": "string"
}
],
"promocoes": [
{
"id": 0,
"valorDesconto": 0,
"porcentagemDesconto": 0,
"descontoMaximo": 0,
"inicio": "2026-08-11T12:19:20.456Z",
"fim": "2026-08-11T12:19:20.456Z",
"percentualComissao": 0,
"qtdMaxima": 0,
"qtdMinima": 0,
"qtdMaxParcelas": 0,
"tabelasVinculadas": [
{
"id": 0,
"descontoMaximo": 0,
"qtdMaxParcelas": 0,
"tabelaPreco": {
"id": 0,
"nome": "string",
"operacaoPercentual": "string",
"percentual": 0,
"tabelaOrigemID": 0,
"tipoOrigem": "string"
}
}
]
}
],
"codigos": [
{
"id": 0,
"tipo": 0,
"codigo": "string",
"unidade": "string",
"fornecedor": "string"
}
],
"integracoes": [
{
"id": 0,
"empresa": {
"id": 0,
"cnpj": "string",
"nome": "string"
},
"integracao": {
"valor": 0,
"descricao": "string"
},
"idIntegracao": "string",
"ultimaExportacao": "2026-08-11T12:19:20.456Z",
"exportar": true
}
],
"produzivel": true,
"criarReceita": true,
"custoPivo": 0
}
Quando o cadastro for realizado com sucesso, a API retorna o HTTP 200 – OK, juntamente com os dados do produto cadastrado, conforme o modelo de resposta disponibilizado pelo endpoint.
Os valores apresentados no exemplo são ilustrativos. IDs, SKU, NCM, empresa, tabela de preço, categorias e demais informações devem ser substituídos pelos dados existentes no ambiente CoreBusiness utilizado pela integração.
Atualizar Produto
O endpoint AtualizarProduto permite atualizar um produto já existente no CoreBusiness. A principal característica deste endpoint é que o produto deverá ser enviado com o objeto completo, conforme o modelo disponibilizado pela API.
Endpoint• O produto deverá existir previamente no CoreBusiness.
• O objeto do produto deverá ser carregado integralmente antes da atualização.
• Não é recomendado enviar somente os campos que serão alterados.
• Após carregar o produto, deverão ser alteradas somente as informações necessárias.
• O objeto completo deverá ser enviado novamente para o endpoint.
• O envio de um objeto incompleto poderá provocar alterações indevidas em informações do produto.
• O campo codigoBarras representa o primeiro código de barras vinculado ao produto, seguindo a ordem de tipo definida pelo sistema, iniciando pelo tipo EAN13.
Não utilize este endpoint enviando apenas os campos que deseja alterar. Primeiro obtenha o produto completo e, depois, envie o objeto completo com as alterações.
{
"id": 0,
"sku": "string",
"codigoBarras": "string",
"nome": "string",
"un": "string",
"caracteristicas": [
{
"id": 0,
"caracteristica": "string",
"conteudo": "string"
}
],
"conversoresDeUnidades": [
{
"id": 0,
"descricao": "string",
"fatorConversao": 0,
"unidadeEntrada": "string",
"unidadeSaida": "string"
}
],
"categorias": [
{
"id": 0,
"nome": "string",
"pai": "string"
}
],
"categoria": "string",
"afinidades": [
{
"id": 0,
"produto": "string",
"afim": "string",
"tipo": {
"valor": 0,
"descricao": "string"
}
}
],
"grupo": "string",
"descricao": "string",
"descricaoDetalhada": "string",
"ncm": "string",
"empresa": {
"id": 0,
"cnpj": "string",
"nome": "string"
},
"cest": {
"id": 0,
"codigo": "string",
"descricao": "string"
},
"composicao": [
{
"id": 0,
"produto": "string",
"quantidade": 0,
"unidadeSigla": "string"
}
],
"fotoPrincipal": "string",
"ativo": true,
"precos": [
{
"id": 0,
"tabelaPreco": "string",
"valor": 0,
"un": "string"
}
],
"dimensoes": [
{
"id": 0,
"altura": 0,
"largura": 0,
"peso": 0,
"profundidade": 0,
"tipo": 0,
"un": "string"
}
],
"promocoes": [
{
"id": 0,
"valorDesconto": 0,
"porcentagemDesconto": 0,
"descontoMaximo": 0,
"inicio": "2026-08-11T12:30:46.044Z",
"fim": "2026-08-11T12:30:46.044Z",
"percentualComissao": 0,
"qtdMaxima": 0,
"qtdMinima": 0,
"qtdMaxParcelas": 0,
"tabelasVinculadas": [
{
"id": 0,
"descontoMaximo": 0,
"qtdMaxParcelas": 0,
"tabelaPreco": {
"id": 0,
"nome": "string",
"operacaoPercentual": "string",
"percentual": 0,
"tabelaOrigemID": 0,
"tipoOrigem": "string"
}
}
]
}
],
"codigos": [
{
"id": 0,
"tipo": 0,
"codigo": "string",
"unidade": "string",
"fornecedor": "string"
}
],
"integracoes": [
{
"id": 0,
"empresa": {
"id": 0,
"cnpj": "string",
"nome": "string"
},
"integracao": {
"valor": 0,
"descricao": "string"
},
"idIntegracao": "string",
"ultimaExportacao": "2026-08-11T12:30:46.044Z",
"exportar": true
}
],
"produzivel": true,
"criarReceita": true,
"custoPivo": 0
}
- Consultar o produto utilizando: GET /api/GEM/Produtos/BuscaProdutosPaginado
- Obter o cadastro completo do produto.
- Alterar somente as informações necessárias.
- Manter as demais informações existentes no objeto.
- Enviar o objeto completo para: POST /api/GEM/Produtos/AtualizarProduto
- Validar o retorno da API.
- Confirmar a atualização do produto no CoreBusiness.
Este endpoint deve ser utilizado quando for necessário alterar informações de um produto já cadastrado, sempre enviando o cadastro completo do produto, evitando que informações não enviadas sejam alteradas ou removidas indevidamente.
Tabelas
0 – Undefined
1 – Residência ou Sede do Estabelecimento (uso geral)
2 – Envio de Correspondência
3 – Entrega de mercadorias, bens e serviços
4 – Cobrança
5 – Retirada de Mercadorias (Logística/Armazém Geral)
6 – Imóvel/Propriedade Rural
0 – Sem Entrega
1 – Remessa de mercadoria
2 – Entrega
3 – Entrega Futura
4 – Faturamento de Entrega Futura
5 – Execução de Serviço
6 – Entrega via Retirada
8 – Em Mãos
2 – Web Site de e-Commerce
4 – e-Mail ou outro contato eletrônico
9 – Skype
10 – WhatsApp
11 – Telegram
12 – Facebook
13 – Integração API
15 – Tela Mobile
17 – Integração Mercado Livre
18 – Integração Magento 2
19 – E-Commerce Shopee
0 – Não definida
1 – Envio de Documentos Fiscais Eletrônicos (DF-e)
2 – Marketing e Propaganda
3 – Confirmação
4 – Skype
5 – MSN
6 – Twitter
7 – Pedido de Compra/Cotação
8 – Cobrança
9 – CRM
10 – Exportação
11 – Notificações
12 – Envio apenas do XML da Nota
99 – Geral
0 – Não Informado
1 – Principal
2 – Fax
3 – Financeiro
4 – Compras
5 – Entrega
0 – Outros (documentos não definidos)
1 – C.P.F. – Cadastro de Pessoas Físicas
2 – C.N.P.J. – Cadastro Nacional de Pessoas Jurídicas
3 – RG – Carteira de Identidade ou Registro Geral
4 – C.T.P.S. – Carteira de Trabalho e Previdência Social
5 – C.N.H. – Carteira Nacional de Habilitação
6 – Passaporte – Identidade Internacional
7 – RNE – Registro Nacional de Estrangeiro
8 – OAB – Identificação da Ordem dos Advogados do Brasil
10 – CREA – Conselho Regional de Engenharia e Agronomia
11 – CRM – Conselho Regional de Medicina
12 – FGTS – Fundo de Garantia por Tempo de Serviço
13 – PIS – Programa de Integração Social
14 – PASEP – Programa de Formação do Patrimônio do Servidor Público
15 – Inscrição Estadual
16 – Inscrição Municipal
17 – Inscrição Estadual de Substituto Tributário
18 – Número de Registro ANP (Agência nacional de petróleo)
19 – Número de Inscrição na SUFRAMA
20 – Identificação de Estrangeiro para NF-e
21 – Alvará de Funcionamento
22 – Alvará Sanitário
23 – Inscrição Estadual – Contribuinte de outro Estado
24 – RSP – Registro Sumário de Produtor
25 – CPP – Cadastro de Produtor Primário
26 – RNTRC – Registro Nacional de Transportadores Rodoviários de Carga
27 – Declaração de Dispensa de Retenção
28 – CAEPF – Cadastro de Atividade Econômica da Pessoa Física
29 – CRC – Conselho Regional de Contabilidade
30 – Identificação Assinatura Manual
0 – Comportamento definido pelo CNAE
1 – Consumo – Consumidor Final
2 – Revenda
3 – Industrialização
4 – Governo
5 – Serviço
7 – Agropecuária
Tabela Opção de Documentos da Pessoa (Apenas para quem tem IE).
1 - Contribuinte ICMS
2 - Contribuinte ISENTO de Inscrição no cadastro de Contribuintes do ICMS
3 - Não Contribuinte, que pode ou não possuir Inscrição Estadual.
0 – Bruto
1 – Líquido
2 – Embalagem Especial