Documentação Técnica: API de Integração de Pedidos
Endpoint: pedidos.php
1. Visão Geral
Esta documentação descreve o funcionamento do endpoint para recuperação de dados de Pedidos, responsável pela disponibilização de informações detalhadas de vendas, incluindo dados do cliente, itens vinculados e informações de pagamento através de integração via API REST.
O endpoint permite a consulta de:
- Dados mestres do pedido (emissão, valores totais e numeração);
- Detalhes dos itens (produtos, quantidades, valores e impostos);
- Informações fiscais (Nota Fiscal, chave de acesso e protocolos);
- Dados para sincronização incremental e fluxo de pagamentos.
Funcionamento Interno: A API valida as credenciais na tabela de empresas do banco central. Se válido, as configurações do banco de dados específico da empresa são carregadas dinamicamente para realizar a consulta dos pedidos.
2. Características da API
| Característica | Detalhe |
| Método HTTP | POST |
| Content-Type | application/x-www-form-urlencoded ou multipart/form-data |
| Formato de Resposta | JSON |
| Charset | Saída com tratamento utf8_encode em campos de texto |
| Autenticação | Usuário e Senha (vinculados à empresa) |
| Paginação | Sim (Limite: 50 registros/página) |
| Sincronização | Incremental por data de atualização disponível |
3. Escopo da Integração
A API foi desenvolvida para permitir a extração padronizada de dados de vendas para sistemas externos.
Possibilidades:
- Consulta incremental por data de emissão ou atualização;
- Consulta individual por número de pedido ou nota fiscal;
- Leitura de dados fiscais completos (NCM, CFOP, CEST e impostos como ICMS, PIS, COFINS e IPI);
- Estrutura relacional com múltiplos itens e formas de pagamento.
Compatível com: ERPs, E-commerces, CRMs, Plataformas de Business Intelligence (BI) e Middlewares de integração.
4. Autenticação e Segurança
O acesso é controlado através de credenciais enviadas no corpo da requisição. O fluxo de validação identifica:
- Usuário e Senha: Validados em base centralizada.
- Conexão Dinâmica: O sistema aponta para o banco de dados específico da empresa autenticada.
- Sessão: Configurações de acesso são carregadas em variáveis de sessão durante a execução.
Campos Obrigatórios:
usuariosenha
5. Recomendações de Segurança
- Atenção a Injeção: Como a API utiliza funções legadas e concatenação de variáveis, é fundamental validar os dados de entrada para prevenir ataques de SQL Injection;
- Utilização exclusiva via protocolo HTTPS para proteger as credenciais;
- Armazenamento seguro das senhas de integração em cofres de credenciais;
- Implementação de controle de tentativas de acesso inválidas.
6. Parâmetros da Requisição (POST)
usuario: Nome de usuário para autenticação (Obrigatório).senha: Senha para autenticação (Obrigatório).data_emissao: Filtra pedidos emitidos a partir da data informada.data_atualizacao: Filtra pedidos atualizados a partir da data informada.numero_pedido: Filtra por um número de pedido específico.numero_nf: Filtra por um número de nota fiscal específico.serie_nf: Filtra por uma série de nota fiscal específica.paginacao_atual: Índice da página de resultados (Padrão: 1).
7. Regras de Funcionamento dos Filtros
- Datas (
data_emissao/data_atualizacao): Devem seguir o formatoY-m-d H:i:s(Ex: 2024-05-01 08:00:00). numero_pedido: Filtro numérico direto sobre a identificação do pedido.paginacao_atual: Controla o deslocamento dos registros para volumes que excedam 50 itens.
8. Exemplo de Requisição
Abaixo, a representação lógica dos dados enviados via formulário POST:
JSON
{
"usuario": "seu_usuario_api",
"senha": "sua_senha_secreta",
"data_emissao": "2024-05-01 08:00:00",
"paginacao_atual": 1
}
9. Estrutura da Resposta
O JSON de retorno contém metadados de controle e a lista de pedidos:
result: Indica sucesso (true) ou falha (false).total: Quantidade total de pedidos encontrados no filtro.total_paginacao: Número total de páginas disponíveis.paginacao_atual: Página atual retornada.dados: Array contendo os objetos dos pedidos e seus subníveis.
JSON
{
"result": true,
"total": 1,
"total_registros": 1,
"data_atualizacao": "",
"total_paginacao": 1,
"paginacao_atual": 1,
"dados": [
{
"id": "22906",
"data_emissao": "2026-05-28 00:00:00",
"cliente_id": "0",
"cliente_nome": "",
"cliente_documento": NULL,
"valor_produtos": "281845.38",
"valor_seguro": "0.00",
"valor_descontos": "0.00",
"valor_acrescimos": "0.00",
"valor_pedido": "281845.38",
"valor_frete": "0.00",
"numero_do_pedido": "18273",
"data_entrega": "2026-05-28 06:06:39",
"numero_da_nota": "100911",
"chave_da_nota": "352605038705720001105500000000000001000229065",
"protocolo_da_nota": "135262065464913",
"protocolo_cancelamento_da_nota": null,
"peso_bruto_total": "6845.668274",
"peso_liquido_total": "6626.978000",
"informacoes_adicionais": "UNIDADE: 10.591 - CD SP CONGELADOS BARUERI/SP (OC 299.269.001)\nRUA JUSSARA, 1635 - JD SANTA CECILIA - BARUERI/SPBARUERI/SP \n",
"tipo": "Nota fiscal",
"itens": [
{
"id": "42500",
"produto": "COXAO DURO [CONGELADO]",
"codigo_barra": "789306",
"quantidade": "3605.90000",
"valor_unitario": "42.5300000000",
"valor_total": "153358.93",
"valor_descontos": "0.00",
"valor_acrescimos": null,
"ncm": "02013000",
"cfop_codigo": "5101",
"icms_cst": "020",
"icms_aliquota": "12.00",
"cofins_cst": "07",
"cofins_aliquota": "0.00",
"pis_cst": "07",
"pis_aliquota": "0.00",
"cest": "1708400",
"icms_valor": "10734.51",
"cofins_valor": "0.00",
"pis_valor": "0.00",
"ipi_cst": "53",
"ipi_aliquota": "0.00",
"ipi_valor": "0.00",
"icmsst_bc": "0.00",
"icmsst_aliquota": "0.00",
"icmsst_valor": "0.00",
"peso_bruto_total": "3724.894700",
"peso_liquido_total": "3605.900000",
"peso_bruto_unitario": "1.033000",
"peso_liquido_unitario": "1.000000",
"valor_frete": null,
"valor_seguro": null
},
{
"id": "42501",
"produto": "CUPIM [CONGELADO]",
"codigo_barra": "789058",
"quantidade": "3021.07800",
"valor_unitario": "42.5300000000",
"valor_total": "128486.45",
"valor_descontos": "0.00",
"valor_acrescimos": null,
"ncm": "02013000",
"cfop_codigo": "5101",
"icms_cst": "020",
"icms_aliquota": "12.00",
"cofins_cst": "07",
"cofins_aliquota": "0.00",
"pis_cst": "07",
"pis_aliquota": "0.00",
"cest": "1708400",
"icms_valor": "8993.54",
"cofins_valor": "0.00",
"pis_valor": "0.00",
"ipi_cst": "53",
"ipi_aliquota": "0.00",
"ipi_valor": "0.00",
"icmsst_bc": "0.00",
"icmsst_aliquota": "0.00",
"icmsst_valor": "0.00",
"peso_bruto_total": "3120.773574",
"peso_liquido_total": "3021.078000",
"peso_bruto_unitario": "1.033000",
"peso_liquido_unitario": "1.000000",
"valor_frete": null,
"valor_seguro": null
}
],
"pagamentos": [
{
"id": "32598",
"valor": "281845.38",
"numerario": "TED SDX",
"nome": ""
}
]
}
]
}
10. Estrutura dos Dados do Pedido
Campos principais retornados para cada pedido:
id,numero_do_pedido,data_emissao,data_entrega;cliente_nome,cliente_documento,cliente_id;- Valores Totais:
valor_pedido,valor_produtos,valor_frete,valor_seguro,valor_descontos,valor_acrescimos; - Dados Fiscais:
numero_da_nota,chave_da_nota,protocolo_da_nota; itens(Array),pagamentos(Array).
11. Estrutura de Itens
O array itens detalha cada produto do pedido:
id,produto,codigo_barra,quantidade;valor_unitario,valor_total,valor_descontos,valor_acrescimos;- Tributação:
ncm,cfop_codigo,cest, CSTs (ICMS, PIS, COFINS, IPI) e seus respectivos valores e alíquotas.
12. Estrutura de Pagamentos
O array pagamentos pode retornar as condições e formas de pagamento vinculadas ao pedido.
13. Tratamento de Paginação
Para grandes volumes de dados:
- Verifique o campo
total_paginacaona primeira resposta. - Itere pelas páginas subsequentes alterando o parâmetro
paginacao_atualaté atingir o limite de páginas informado pela API.
14. Estratégia Recomendada de Sincronização
- Sincronização Incremental: Utilize o campo
data_atualizacaopara buscar apenas os pedidos modificados desde a última integração bem-sucedida. - Filtro Fiscal: Utilize
numero_nfouserie_nfpara conciliar pedidos faturados com o sistema contábil.
15. Recomendações de Integração
- Tratamento de Erros: Monitore o campo
result. Em caso de falha, valide mensagens como “Usuário inválido”, “Empresa inválida” ou “Data inválida”. - Performance: Evite solicitações de carga completa (sem filtros) com frequência excessiva; prefira os filtros de data.
- Resiliência: Implemente tratamento de timeout e logs para registrar o ID do último pedido processado.
Share this content: