README

Cliente da API do Gestor Integrado para PHP 8.1+: cadastros, vendas, compras, ordens de serviço, financeiro, estoque e notas fiscais. Sem dependências (usa o cURL do PHP).

Referência completa da API (campos de cada recurso, exemplos e respostas): https://gestorintegrado.com/desenvolvedores

Instalação

composer require ebitsistemas/gestor-sdk

Ou, sem o Packagist, aponte o repositories do seu composer.json para esta pasta (tipo path) ou para o repositório.

Primeiros passos

No sistema, crie um token em Configurações › Integrações › API do sistema (só leitura ou leitura e escrita). Ele aparece uma vez só: guarde como uma senha. O token age como o usuário que o criou.
O endereço da API é o mesmo para todas as empresas (https://hubintegrado.com, o padrão do SDK): o token já diz de qual empresa é.

use GestorIntegrado\Sdk\Cliente;

$cliente = new Cliente(getenv('GESTOR_TOKEN'));

echo $cliente->eu()['nome']; // o usuário dono do token

// Uma página (busca, pagina, por_pagina 10/25/50/100, ordem, direcao e os filtros do recurso)
$pagina = $cliente->produtos->listar(['busca' => 'arroz', 'por_pagina' => 25]);
foreach ($pagina as $produto) {
    echo $produto['nome'], PHP_EOL;
}
echo $pagina->total();

// Todos os registros, página por página, sob demanda
foreach ($cliente->parceiros->todos(['busca' => 'silva']) as $parceiro) { /* ... */ }

// Consultar, cadastrar, atualizar e remover
$venda = $cliente->vendas->consultar(15);
$unidade = $cliente->unidades->cadastrar(['sigla' => 'CX', 'nome' => 'Caixa']);
$cliente->unidades->atualizar($unidade['id'], ['sigla' => 'CX', 'nome' => 'Caixa com 12']);
$cliente->unidades->remover($unidade['id']);

// Ações próprias do recurso: {recurso}/{id}/{acao}
$cliente->vendas->acao('status', 15, ['status_id' => 3]);
$cliente->vendas->acao('notafiscal', 15);

// Recurso com hífen: camelCase (ordens-servico) ou pelo nome
$os = $cliente->ordensServico->listar();
$os = $cliente->recurso('ordens-servico')->listar();

// Qualquer endpoint (caminho sem /api/v1)
$painel = $cliente->get('dashboard');

// Arquivos (XML e PDF da nota, carta de correção): o conteúdo cru
file_put_contents('danfe.pdf', $cliente->baixar('notas-fiscais/nfe/10/pdf', ['formato' => 'danfe']));

Exemplos

Em exemplos/, com GESTOR_TOKEN no ambiente (php exemplos/<arquivo>.php):

Arquivo	O que faz
`parceiros.php`	Cadastra, atualiza, lista e remove um cliente
`produtos.php`	Cadastra, dá entrada no estoque, atualiza, lista e remove
`servicos.php`	Cadastra, atualiza, lista e remove
`vendas.php`	Cadastra uma venda e lista as do mês
`financeiro.php`	Lança uma conta a pagar, dá baixa, lista contas a receber e o calendário
`nfe.php`	Emite a NF-e de uma venda, espera a SEFAZ e baixa o XML e o DANFE
`listar-produtos.php`	O mais curto: percorrer todos os produtos ativos

Erros

Toda resposta de erro vira uma exceção com a mensagem em português, pronta para mostrar:

Classe	Status	Quando
`NaoAutenticado`	401	Token inválido, vencido ou revogado
`SemPermissao`	403	Sem permissão, token só de leitura gravando ou licença suspensa
`NaoEncontrado`	404	Registro não encontrado
`RegraDeNegocio`	409	A regra do negócio não deixou (ex.: remover algo em uso)
`Validacao`	422	Campos recusados: `$erro->erros()` traz campo => mensagens
`LimiteDeChamadas`	429	Muitas chamadas: `$erro->esperarSegundos()`
`ErroDeConexao`	—	Não chegou resposta (rede, DNS, tempo esgotado)

Todas estendem GestorIntegrado\Sdk\Erros\ErroDaApi (status(), erros(), resposta()).

use GestorIntegrado\Sdk\Erros\Validacao;

try {
    $cliente->unidades->cadastrar(['nome' => 'Caixa']);
} catch (Validacao $erro) {
    print_r($erro->erros()); // ['sigla' => ['O campo sigla é obrigatório.']]
}

Limites e novas tentativas

A API aceita até 120 chamadas por minuto por usuário. Ao receber 429, o SDK espera o Retry-After e tenta de novo (até 3 tentativas). Falha de rede só é repetida em consultas (GET), que não gravam nada.

$cliente = new Cliente($token, [
    'tempo_limite' => 30, // segundos por chamada
    'tentativas' => 3,
]);

Para usar outro cliente HTTP (ou nos testes), passe 'transporte' => new MeuTransporte (implementa GestorIntegrado\Sdk\Http\Transporte).

Recursos

O catálogo completo, com método e caminho de cada endpoint, está em recursos/endpoints.json.

Recurso	Propriedade	Básico	Ações próprias (`acao(...)`)
Parceiros (clientes e fornecedores)	`parceiros`	listar, consultar, cadastrar, atualizar, remover, opcoes	`opcoes/{lista}` GET, `historico` (com id) GET
Produtos e estoque	`produtos`	listar, consultar, cadastrar, atualizar, remover, opcoes	`opcoes/{lista}` GET, `insumos` GET, `estoque` (com id) POST, `historico` (com id) GET, `historico-precos` (com id) GET, `limite-extra` (com id) POST
Serviços	`servicos`	listar, consultar, cadastrar, atualizar, remover, opcoes	`historico` (com id) GET, `historico-precos` (com id) GET
Categorias	`categorias`	listar, consultar, cadastrar, atualizar, remover, opcoes	`mover` (com id) POST
Grupos	`grupos`	listar, consultar, cadastrar, atualizar, remover, opcoes	—
Unidades	`unidades`	listar, consultar, cadastrar, atualizar, remover	—
Variações	`variacoes`	listar, consultar, cadastrar, atualizar, remover, opcoes	—
Grupos de impressão	`gruposImpressao`	listar, consultar, cadastrar, atualizar, remover, opcoes	—
Vendas	`vendas`	listar, consultar, cadastrar, atualizar, opcoes	`opcoes/{lista}` GET, `kanban` GET, `frete` POST, `calcular` POST, `aprovar` (com id) POST, `status` (com id) POST, `comprovante-entrega` (com id) GET, `cupom` (com id) GET e mais 3
Compras	`compras`	listar, consultar, cadastrar, atualizar, opcoes	`opcoes/{lista}` GET, `kanban` GET, `calcular` POST, `aprovar` (com id) POST, `status` (com id) POST, `impressao` (com id) GET, `notafiscal` (com id) POST, `email` (com id) GET/POST
Ordens de serviço	`ordensServico`	listar, consultar, cadastrar, atualizar, opcoes	`opcoes/{lista}` GET, `kanban` GET, `equipamentos` GET, `agenda` GET, `indicadores` GET, `calcular` POST, `aprovar` (com id) POST, `nota-produto` (com id) GET/POST e mais 6
Descontos	`descontos`	listar, consultar, cadastrar, atualizar, remover, opcoes	`opcoes/{lista}` GET
Financeiro: faturamentos e parcelas	`faturamentos`	listar, consultar, cadastrar, atualizar, opcoes	`impressao` (com id) GET, `opcoes/{lista}` GET, `kanban` GET, `status` (com id) POST, `pagamentos/{pagamento}/baixas/{baixa}/estorno` (com id) POST, `email/{modelo}` (com id) GET/POST
Boletos e PIX	`boletos`	listar, opcoes	`pendentes` GET, `enviar` POST, `nao-enviar` POST, `reabrir` (com id) POST, `cancelar` (com id) POST, `consultar` (com id) POST
Contas bancárias	`contasBancarias`	listar, consultar, cadastrar, atualizar, remover, opcoes	—
Caixas	`caixas`	listar, consultar, cadastrar, atualizar, remover	—
Fechamentos de caixa	`fechamentosCaixa`	listar, consultar, opcoes	`fechar` (com id) POST
Calendário financeiro	`calendario`	listar	—
Indicadores financeiros	`indicadores`	—	`financeiro` GET
Notas fiscais (NF-e, NFC-e e NFS-e)	`notasFiscais`	listar, consultar	`{nota}/transmitir` (com id) POST, `{nota}/consultar` (com id) POST, `{nota}/cancelar` (com id) POST, `{nota}/corrigir` (com id) POST, `{nota}/xml` (com id) GET, `{nota}/pdf` (com id) GET, `{nota}/cce/{evento}` (com id) GET, `nfse/{nota}/email` GET/POST e mais 6
Notas recebidas	`notasRecebidas`	listar, consultar, opcoes	`importar` POST, `buscar-nfse` POST, `manifestar` (com id) POST, `itens/{item}/relacionar` (com id) POST, `compra` (com id) GET, `devolucao` (com id) GET, `xml` (com id) GET, `pdf` (com id) GET
Tributações	`tributacoes`	listar, consultar, cadastrar, atualizar, remover, opcoes	—
Operações fiscais	`operacoes`	listar, consultar, cadastrar, atualizar, remover, opcoes	—
Classificações fiscais	`classificacoes`	listar, consultar, atualizar, opcoes	`status` (com id) POST
Relatórios	`relatorios`	listar	`filtros` (com id) GET, `gerar` (com id) GET
Dashboard	`dashboard`	—	`dashboard` GET
Comanda	`comanda`	listar, consultar, cadastrar, atualizar, remover	`inicio` GET, `produtos/{produto}/imagem` GET, `clientes` GET, `vendas/{venda}/cobranca` GET/POST, `vendas/{venda}/cobranca/{parcela}/confirmar` POST, `vendas/{venda}/cobranca/cancelar-venda` POST, `vendas/ultima` GET, `vendas/{venda}/cupom` GET e mais 20
PDV (frente de caixa)	`pdv`	listar, consultar, cadastrar	`inicio` GET, `produtos` GET, `produtos/codigo/{codigo}` GET, `clientes` GET, `vendas/{venda}/cobranca` GET/POST, `vendas/{venda}/cobranca/{parcela}/confirmar` POST, `vendas/{venda}/cobranca/cancelar-venda` POST, `vendas/salvar` POST e mais 10
App do entregador	`entregador`	—	`entregas` GET, `posicao` POST, `entregas/{codigo}/posicao` POST, `entregas/{codigo}/{acao}` POST, `relatorio` GET, `rota/previa` POST, `rota/iniciar` POST
Autoatendimento (totem)	`autoatendimento`	consultar, cadastrar	`inicio` GET, `produtos/{produto}/imagem` GET, `pedidos/{venda}/cupom` GET, `pedidos/{venda}/cobranca` DELETE/GET/POST
Configurações	`configuracoes`	consultar, cadastrar, atualizar, remover	`notafiscal/emitente` POST, `notafiscal/backup` GET, `notafiscal/certificado` GET, `comanda/impressao` GET, `cardapio/geral` GET, `cardapio/layout` GET, `cardapio/layout/imagem` GET, `cardapio/horarios` GET e mais 4
Usuários	`usuarios`	listar, consultar, cadastrar, atualizar, remover	—
Cargos	`cargos`	listar, consultar, cadastrar, atualizar, remover, opcoes	—
Status	`status`	listar, consultar, cadastrar, atualizar, remover, opcoes	—
Formas de pagamento	`formasPagamento`	listar, consultar, cadastrar, atualizar, remover	—
Empresa	`empresa`	consultar, atualizar	`resumo` GET, `logo` GET
Integrações	`integracoes`	listar, consultar, atualizar	`situacao` GET, `frete/{provedor}` GET, `tray` DELETE/GET, `tray/conectar` POST, `tray/produtos` GET/POST, `tray/sincronizar` POST, `tray/pedidos` GET/PUT, `tray/pedidos/conferir` POST e mais 12
Anexos	`anexos`	listar, cadastrar, remover	`principal` (com id) PUT, `arquivo` (com id) GET
Auditoria	`auditoria`	listar, consultar, opcoes	—
Notificações	`notificacoes`	listar	`resumo` GET, `lidas` POST, `lida` (com id) POST
Consultas (CEP e CNPJ)	`consultas`	—	`cep/{cep}` GET, `cnpj/{cnpj}` GET
Ferramentas	`ferramentas`	—	`balanca` GET, `balanca/arquivo/{modelo}` GET, `etiquetas/produtos` GET
Ajuda	`ajuda`	—	`faq` GET, `perguntas` GET, `iris` POST
Usuário do token	`eu`	—	`eu` GET
Menu e permissões	`menu`	—	`menu` GET, `acessos` POST, `permissoes` GET
Cupons de desconto	`cupons`	listar, consultar, cadastrar, atualizar, remover	—
Contratos	`contratos`	listar, consultar, cadastrar, atualizar, remover, opcoes	`opcoes/{lista}` GET, `status` (com id) POST, `documento` (com id) GET, `assinatura` (com id) POST
Modelos de contrato	`contratosModelos`	listar, consultar, cadastrar, atualizar, remover	`gerar-com-ia` POST, `arquivo` (com id) GET
Assinaturas (contratos)	`assinaturas`	cadastrar, remover	`imagem` (com id) GET
Equipamentos (ordens de serviço)	`equipamentos`	listar, consultar, cadastrar, atualizar, remover, opcoes	`opcoes/{lista}` GET, `historico` (com id) GET
Pagamentos (recibos por e-mail)	`pagamentos`	—	`{modelo}/email` (com id) GET/POST
WhatsApp	`whatsapp`	—	`{id}` (com id) GET/POST
Íris (assistente)	`iris`	—	`mensagem` POST, `voz` GET/POST
Documentos legais	`documentosLegais`	—	`pdf` (com id) GET
Primeiro acesso	`primeiroAcesso`	consultar	`aceitar` POST, `configurar` POST

Testes

composer test   # ou: php tests/executar.php

Licença

MIT: veja LICENSE.

ebitsistemas / gestor-sdk

Package info

Security

Statistics