ATENDESMART

Documentação Técnica: API de Vendas

Este documento descreve as especificações técnicas para integração e consumo da API de Vendas.

1. Visão Geral

A API de Vendas Atendesmart é uma interface de comunicação desenvolvida para fornecer conectividade direta entre sistemas externos e o ecossistema Atendesmart. Seu principal objetivo é permitir a extração e consulta de informações de vendas registradas no sistema web de forma automatizada e segura.

Através desta API, desenvolvedores e parceiros podem integrar dados transacionais em tempo real para alimentar dashboards de BI, sistemas de contabilidade, ERPs de terceiros ou ferramentas de gestão de estoque.

Principais Características:

  • Acesso Unificado: Permite a consulta detalhada de registros de vendas originados no sistema web Atendesmart.
  • Interoperabilidade: As requisições são realizadas via métodos padrão de mercado, garantindo que qualquer linguagem de programação moderna possa consumir os dados.
  • Segurança e Controle: O acesso é restrito a requisições autenticadas, garantindo a integridade e a privacidade das informações da empresa.
  • Estrutura de Dados: O retorno das informações ocorre em formato JSON, oferecendo uma estrutura hierárquica que inclui não apenas os dados da venda, mas também detalhes de itens (produtos) e formas de pagamento.

Esta API foi projetada para suportar desde consultas pontuais até sincronizações volumosas, oferecendo recursos nativos de paginação e filtros por data de emissão ou atualização para otimizar a performance do consumo.

2. Configuração do Endpoint

  • URL: https://www.atendesmart2.com.br/sistema/comanda/api/vendas.php
  • Método HTTP: POST
  • Formato de Dados: Requisição via parâmetros (query string) e resposta em JSON.

3. Parâmetros da Requisição

Abaixo estão os campos que devem ser enviados no corpo da requisição:

ParâmetroTipoObrigatoriedadeDescrição
usuariostringObrigatórioCredencial de acesso do usuário.
senhastringObrigatórioSenha de acesso associada.
paginacao_atualintOpcionalDefine a página de resultados (padrão: 1).
data_emissaotimestampOpcionalFiltro por data (formato: YYYY-MM-DD HH:MM:SS).
data_atualizacaotimestampOpcionalFiltro por data de atualização (YYYY-MM-DD HH:MM:SS).

4. Estrutura de Retorno (Sucesso)

Em caso de sucesso, a API retorna um objeto JSON com metadados de paginação e a lista de registros.

Campos do Objeto Principal:

  • result: Booleano indicando o sucesso da operação.
  • total: Total geral de registros encontrados no banco de dados.
  • total_registros: Quantidade de registros retornados na página atual.
  • total_paginacao: Número total de páginas disponíveis.
  • paginacao_atual: Índice da página atual.
  • dados: Array de objetos contendo os detalhes de cada venda.
    • Subitens: Incluem itens (produtos) e pagamentos (formas de pagamento).

Exemplo de JSON:

JSON

{
  "result": true,
  "total": 44,
  "total_registros": 44,
  "data_atualizacao": "",
  "total_paginacao": 1,
  "paginacao_atual": 1,
  "dados": [
    {
      "id": "35072",
      "data_emissao": "2026-03-26 08:21:45",
      "cliente_id": "24896",
      "cliente_nome": "CONSUMIDOR",
      "valor_cupom": "1089.00",
      "itens": [...],
      "pagamentos": [...]
    }
  ]
}

5. Tratamento de Erros

Se a requisição falhar, o campo result será false e uma mensagem explicativa será fornecida no campo msg.

Formato de Erro:

{"result": false, "msg": "Mensagem de erro"}

Erros Comuns:

  • Usuário ou senha inválidos.
  • Data informada em formato incorreto.
  • Empresa inválida ou sem permissão.

6. Exemplo de Implementação (PHP)

PHP

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

$params = array(
    'usuario'          => 'seu_usuario',
    'senha'            => 'sua_senha',
    'paginacao_atual'  => 1,
    'data_emissao'     => '2026-03-26 08:21:45'
);

$content = http_build_query($params);

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

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

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