ATENDESMART

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

Endpoint: clientes.php

1. Visão Geral

Esta documentação descreve o funcionamento do endpoint clientes.php, responsável pela disponibilização de dados cadastrais de clientes através de integração via API REST.

O endpoint permite a consulta de:

  • Dados cadastrais principais e informações complementares;
  • Endereços e contatos vinculados;
  • Dados para sincronização incremental.

Funcionamento Interno: A API realiza a autenticação da empresa integradora através de uma base centralizada e, após validação, conecta-se automaticamente à base de dados correspondente da empresa autenticada.

Objetivo Principal: Permitir integrações com ERP, E-commerce, Marketplaces, CRM, Sistemas Fiscais, Aplicativos Mobile, Plataformas de Fidelidade e Middlewares.

2. Características da API

CaracterísticaDetalhe
Método HTTPPOST
ProtocoloHTTPS (Recomendado)
Formato de RespostaJSON
CharsetEntrada: ISO-8859-1
AutenticaçãoUsuário e Senha
PaginaçãoSim (Limite: 50 registros/página)
SincronizaçãoIncremental disponível

3. Escopo da Integração

Desenvolvida para disponibilização de dados cadastrais de forma genérica e padronizada.

Possibilidades:

  • Consulta incremental por data de cadastro e atualização;
  • Consulta individual por cliente;
  • Carga completa da base via paginação;
  • Estrutura relacional com múltiplos endereços e contatos.

Compatibilidade: PHP, Java, .NET, Node.js, Python, Aplicações Mobile e Ferramentas ETL.

4. Autenticação e Segurança

O acesso é controlado via corpo da requisição (body). Após a validação na base central, o sistema identifica:

  1. Empresa
  2. Banco de dados
  3. Permissões de integração

Campos Obrigatórios:

  • usuario
  • senha

5. Recomendações de Segurança

  • Utilização exclusiva via HTTPS;
  • Armazenamento seguro das credenciais;
  • Controle de acesso por IP quando aplicável;
  • Utilização de timeout de integração;
  • Tratamento de tentativas de reconexão e validação de retorno.

6. Parâmetros da Requisição (POST)

  • usuario: Identificador da integração.
  • senha: Senha da integração.
  • data_cadastro: Filtra clientes cadastrados a partir desta data.
  • data_atualizacao: Filtra clientes alterados a partir desta data.
  • id_cliente: Filtra um ID específico.
  • paginacao_atual: Índice da página desejada.

7. Regras de Funcionamento dos Filtros

  • data_cadastro: Formato esperado AAAA-MM-DD HH:MM:SS.
  • data_atualizacao: Utilizado para sincronização incremental.
  • id_cliente: Corresponde ao campo código do cliente no banco.
  • paginacao_atual: Controle numérico de navegação.

8. Exemplo de Requisição

JSON

{
  “usuario”: “empresa_exemplo”,
  “senha”: “senha_secreta_123”,
  “data_cadastro”: “2024-01-01 00:00:00”,
  “paginacao_atual”: 1
}

9. Estrutura da Resposta

O JSON de retorno contém os seguintes metadados:

  • result: Status da operação.
  • total: Total de registros encontrados.
  • total_registros: Registros na página atual.
  • total_paginacao: Quantidade total de páginas disponíveis.
  • paginacao_atual: Página retornada.
  • dados: Array contendo os objetos de clientes.

JSON
{
“result”: true,
“total”: 2,
“total_registros”: 2,
“data_atualizacao”: “”,
“total_paginacao”: 1,
“paginacao_atual”: 1,
“dados”: [
{
“id”: “18”,
“data_aniversario”: “1899-12-30 00:00:00”,
“rg”: null,
“cliente_nome”: “Deise Bandeira”,
“cliente_documento”: “28668110896”,
“cliente_nome_usual”: “Deise Bandeira”,
“codigo”: “”,
“cadastrado_em”: “2024-03-05”,
“inscricao_estadual”: null,
“inscricao_municipal”: null,
“valor_limite”: “0.00”,
“desconto_percentual”: “0.00”,
“comissao_percentual”: “0.00”,
“status”: “1”,
“valor_saldo”: “0.00”,
“observacao”: “”,
“cnae”: null,
“enderecos”: ,
“contatos”:
},
{
“id”: “19”,
“data_aniversario”: “1899-12-30 00:00:00”,
“rg”: “”,
“cliente_nome”: “Raony Gomes”,
“cliente_documento”: “”,
“cliente_nome_usual”: “Raony Gomes”,
“codigo”: “”,
“cadastrado_em”: “2024-03-05”,
“inscricao_estadual”: “”,
“inscricao_municipal”: “”,
“valor_limite”: “700.00”,
“desconto_percentual”: “0.00”,
“comissao_percentual”: “0.00”,
“status”: “1”,
“valor_saldo”: “0.00”,
“observacao”: “”,
“cnae”: “”,
“enderecos”: ,
“contatos”:
}
]

10. Estrutura dos Dados do Cliente

Campos principais retornados no objeto cliente:

  • id, codigo, status
  • cliente_nome, cliente_documento, cliente_nome_usual
  • cadastrado_em, valor_limite, desconto_percentual, comissao_percentual
  • observacao
  • enderecos (Array), contatos (Array)

11. Estrutura de Endereços

O array enderecos detalha:

  • Logradouro, número, complemento e bairro.
  • Cidade, estado, CEP e país.
  • Tipo do endereço (ex: Cobrança, Entrega).

12. Estrutura de Contatos

O array contatos detalha:

  • Telefone e Celular.
  • E-mail.
  • Identificação de contato principal.
  • Observações específicas.

13. Tratamento de Paginação

Para grandes volumes de dados, siga o fluxo:

  1. Consulte a primeira página (paginacao_atual: 1).
  2. Valide o campo total_paginacao.
  3. Itere em um laço de repetição até atingir a última página disponível.

14. Estratégia Recomendada de Sincronização

  • Carga Inicial: Realizar a leitura completa utilizando a paginação, sem aplicar filtros de data.
  • Atualizações Futuras: Utilizar o parâmetro data_atualizacao enviando o timestamp da última sincronização bem-sucedida.

15. Recomendações de Integração

  • Manter Logs de integração para auditoria.
  • Configurar Timeout adequado para evitar processos travados.
  • Prever o Reprocessamento automático em caso de falhas momentâneas.
  • Tratar cenários de indisponibilidade de rede de forma resiliente.

Share this content:

Related Posts