ATENDESMART

Documentação Técnica: API de Integração de Produtos

1. Visão Geral

Esta API foi desenvolvida para atuar como uma ponte de comunicação direta com o ecossistema Atendesmart, permitindo que sistemas externos realizem a consulta e recuperação programática de informações de produtos de forma segura, escalável e eficiente.

O objetivo central deste produto é possibilitar a sincronização de dados entre a base central do Atendesmart e outras plataformas (como E-commerces, ERPs de terceiros ou BI), garantindo que as informações cadastrais, fiscais e de estoque estejam sempre atualizadas sem a necessidade de intervenção manual.

Características Principais:

  • Acesso em Tempo Real: Consulta direta ao banco de dados para obtenção de informações atualizadas.
  • Filtro Incremental: Suporte à filtragem por data de modificação, permitindo sincronizações otimizadas (apenas o que mudou).
  • Estrutura Robusta: Retorno de dados detalhados, abrangendo desde a identificação básica (códigos de barras) até classificações fiscais complexas (NCM, CEST, impostos).
  • Escalabilidade: Implementação de paginação nativa para garantir a performance mesmo em catálogos com grandes volumes de itens.

Especificações Técnicas de Conexão:

  • Protocolo: HTTPS (TLS para garantir a criptografia dos dados em trânsito).
  • Método: POST (utilizado para envio seguro de credenciais e parâmetros no corpo da requisição).
  • Formato de Saída: JSON (padrão universal de fácil leitura por máquinas e humanos).
  • Endpoint: https://www.atendesmart2.com.br/sistema/comanda/api/produtos.php

Por que usar esta API?

Ao integrar-se a este endpoint, o desenvolvedor garante que sua aplicação externa tenha acesso à mesma inteligência de dados utilizada no sistema web Atendesmart, eliminando a duplicidade de cadastros e reduzindo erros operacionais em processos de venda e logística.

2. Autenticação e Segurança

O acesso à API requer autenticação via corpo da requisição (POST). É obrigatório o envio das credenciais da empresa para validar a conexão dinâmica com o banco de dados.

3. Parâmetros de Entrada

Os parâmetros devem ser enviados no corpo da requisição:

ParâmetroTipoObrigatórioDescrição
usuariostringSimNome de usuário para acesso.
senhastringSimSenha correspondente ao usuário.
paginacao_atualintegerNãoNúmero da página (Padrão: 1).
data_atualizacaotimestampNãoFiltro no formato YYYY-MM-DD HH:MM:SS.

4. Estrutura da Resposta

A API retorna um objeto JSON contendo metadados de controle e o array de produtos.

Metadados do Retorno

  • result: Indica se a operação foi bem-sucedida (boolean).
  • total: Total global de registros encontrados no banco.
  • total_registros: Quantidade de registros retornados na página atual.
  • total_paginacao: Quantidade total de páginas disponíveis.
  • paginacao_atual: Índice da página consultada.
  • data_atualizacao: Reflete o filtro de data aplicado.
  • dados: Array contendo os objetos de produtos.

Campos do Produto

Cada item no array dados inclui:

  • Identificação: id, nome_completo, nome_reduzido, codigo_barra.
  • Classificação: ncm, cest, grupo, subgrupo, fabricante.
  • Valores: custo, margem_lucro, preco.
  • Logística: unidades, dimensões, pesos.
  • Fiscal/Status: impostos (ICMS, PIS, COFINS, IPI, IBPT), CFOP e status.

5. Exemplo de Resposta (JSON)

JSON

{
    "result": true,
    "total": 8,
    "total_registros": 8,
    "data_atualizacao": "2023-04-20 00:00:00",
    "total_paginacao": 1,
    "paginacao_atual": 1,
    "dados": [
        {
            "id": "2",
            "nome_completo": "MACACAO",
            "nome_reduzido": "MACACAO",
            "ncm": "62092000",
            "cest": null,
            "codigo_barra": "10002",
            "custo": "6.0000000000",
            "margem_lucro": "166.670",
            "preco": "16.0000000000",
            "grupo": "",
            "subgrupo": "",
            "id_unidade_estoque": "1",
            "nome_unidade_estoque": "UNIDADE",
            "sigla_unidade_estoque": "UN",
            "id_unidade_compra": "1",
            "nome_unidade_compra": "UNIDADE",
            "sigla_unidade_compra": "UN",
            "quantidade_embalagem": "1.000",
            "id_fabricante": "0",
            "nome_fabricante": "",
            "altura": "0.00000",
            "largura": "0.00000",
            "comprimento": "0.00000",
            "peso_liquido": "0.000000",
            "peso_bruto": "0.000000",
            "icms_base_calculo_percentual": null,
            "icms_aliquota": null,
            "icms_cst": "",
            "pis_aliquota": null,
            "pis_cst": "",
            "cofins_aliquota": null,
            "cofins_cst": "",
            "ipi_aliquota": null,
            "ibpt_aliquota_federal_nacional": "13.450",
            "ibpt_aliquota_federal_importado": "32.000",
            "ibpt_aliquota_estadual": "18.000",
            "ibpt_aliquota_municipal": "0.000",
            "ibpt_chave": "9oi3aC",
            "ibpt_fonte": "IBPT",
            "cfop_codigo": null,
            "cfop_nome": "",
            "cfop_descricao": "",
            "status": "1",
            "variantes": [
                {
                    "id": "37",
                    "nome": "RN-16",
                    "codigo": "1000201",
                    "preco": "16.0000000000"
                }
            ]
        },

6. Paginação e Limites

  • A API retorna 50 registros por página.
  • O campo total_paginacao é calculado automaticamente pelo sistema.

7. Tratamento de Erros e Validações

A API realiza as seguintes validações antes do processamento:

  1. Usuário/Senha: Retorna erro se não informados ou se inválidos.
  2. Data: Retorna erro se o formato for inválido.
  3. Empresa: Retorna erro caso a empresa não seja localizada.
  4. Banco de Dados: Erros internos retornam mensagens detalhadas.

8. Exemplo de Consumo (PHP)

PHP

<?php
$url = 'https://www.atendesmart2.com.br/sistema/comanda/api/produtos.php';

$content = http_build_query(array(
    'usuario'          => 'xxx',
    'senha'            => 'xxx',
    'paginacao_atual'  => 1,
    'data_atualizacao' => '2025-01-01 00:00:00'
));

$context = stream_context_create(array(
    'http' => array(
        'method'  => 'POST',
        'header'  => "Content-type: application/x-www-form-urlencoded\r\n",
        'content' => $content,
    )
));

$dados = file_get_contents($url, false, $context);
echo $dados;
?>

9. Considerações Técnicas

  • Tecnologia: Utiliza banco de dados MySQL com conexão dinâmica por empresa.
  • Integração: Por utilizar JSON, a API é compatível com qualquer linguagem de programação.

Adicionalmente, recomendamos como boa prática que, a cada nova requisição, seja utilizada como parâmetro de consulta a data/hora da última sincronização realizada (data de corte da requisição anterior). Dessa forma, evita-se o reprocessamento de registros já integrados no mesmo dia, otimizando a performance e garantindo maior eficiência no consumo da API.

Essa abordagem também contribui para:

  • Redução de volume de dados trafegados;
  • Melhor controle incremental das atualizações;
  • Minimização de inconsistências em integrações contínuas.

Share this content:

Related Posts