README

A url para realizar os testes na api da Omie é essa: https://app.omie.com.br/developer/

Biblioteca PHP para facilitar integração com a API da Omie.

Este projeto ainda está em construção, mas já tem uma base pronta para:

carregar configurações por .env
resolver configuração para Laravel e standalone
definir contratos de clientes seguindo SOLID
executar testes com Pest

Para quem é este projeto?

Para desenvolvedores iniciantes e intermediários que querem organizar uma integração com a Omie de forma simples e escalável.

Requisitos

Antes de começar, você precisa ter instalado:

PHP 8.4+ (recomendado)
Composer

Instalação

Entre na pasta do projeto.
Instale as dependências:

composer install

Configuração do ambiente (.env)

Este projeto lê variáveis de ambiente para montar a configuração.

Crie o arquivo .env na raiz do projeto (ou copie de .env.example).
Preencha os valores:

OMIE_API=https://app.omie.com.br/api/v1/
OMIE_APP_KEY=sua_chave_omie
OMIE_APP_SECRET=seu_segredo_omie

O que cada variável significa?

OMIE_API: URL base da API da Omie.
OMIE_APP_KEY: sua chave da aplicação na Omie.
OMIE_APP_SECRET: seu segredo da aplicação na Omie.

Uso com Laravel

O pacote suporta auto-discovery do provider via Composer.

Adicione as variáveis no .env da aplicação Laravel:

OMIE_API=https://app.omie.com.br/api/v1/
OMIE_APP_KEY=sua_chave_omie
OMIE_APP_SECRET=seu_segredo_omie
OMIE_TIMEOUT=30

Publique a configuração do pacote:

php artisan vendor:publish --tag=omie-config

Injete as interfaces diretamente no container do Laravel:

<?php

use Rafapaulino\Omiephpsdk\Clients\Contracts\ClientServiceInterface;

final class OmieClientController
{
    public function __construct(private ClientServiceInterface $clientService)
    {
    }
}

Arquivo de configuração publicado: config/omie.php.

Como obter as configurações no código

A classe Config resolve automaticamente a configuração:

em Laravel, lê config('omie')
em standalone, carrega .env e usa src/config.php

Arquivo: src/Config/Config.php

Exemplo:

<?php

use Rafapaulino\Omiephpsdk\Config\Config;

$config = Config::resolve();

print_r($config);

Saída esperada (exemplo):

Array
(
    [omie_api] => https://app.omie.com.br/api/v1/
    [omie_key] => sua_chave_omie
    [omie_secret] => seu_segredo_omie
    [timeout] => 30
)

ConfigSingleton continua disponível por retrocompatibilidade.

Estrutura de contratos (SOLID)

As interfaces de clientes foram separadas por responsabilidade (Interface Segregation Principle).

Pasta: src/Clients/Contracts

Interfaces disponíveis:

CreatesClientsInterface (createClient)
RetrievesClientsInterface (getClient)
UpdatesClientsInterface (updateClient)
DeletesClientsInterface (deleteClient)
ListsClientsInterface (listClients)
ClientServiceInterface (agrega todas as interfaces acima)

Isso permite implementar apenas o que sua classe realmente precisa.

Contratos de users:

ListsUsersInterface (listUsers)
UserServiceInterface (agrega as interfaces de users)

Contratos de vendedores:

CreatesSellersInterface (createSeller)
SellerServiceInterface (agrega as interfaces de vendedores)

Contratos de produtos:

ListsProductsInterface (listProducts)
ProductServiceInterface (agrega as interfaces de produtos)

Contratos de contas correntes:

ListsCurrentAccountsInterface (listCurrentAccounts)
CurrentAccountServiceInterface (agrega as interfaces de contas correntes)

Contratos de CFOP:

ListsCfopInterface (listCfop)
CfopServiceInterface (agrega as interfaces de CFOP)

Contratos de categorias:

ListsCategoriesInterface (listCategories)
CategoryServiceInterface (agrega as interfaces de categorias)

Contratos de formas de pagamento:

ListsPaymentMethodsInterface (listPaymentMethods)
PaymentMethodServiceInterface (agrega as interfaces de formas de pagamento)

Service de Clientes (`OmieClientService`)

A implementação atual do serviço de clientes está em src/Clients/OmieClientService.php.

Métodos já implementados:

createClient(array $payload): array
listClients(array $filters = []): array
getClient(int|string $clientId): array
updateClient(int|string $clientId, array $payload): array
deleteClient(int|string $clientId): array

Exemplo de uso

<?php

use Rafapaulino\Omiephpsdk\Clients\OmieClientService;

$service = new OmieClientService();

// Cria cliente (call: IncluirCliente)
$created = $service->createClient([
    'codigo_cliente_integracao' => 'CodigoInterno0001',
    'email' => 'primeiro@ccliente.com.br',
    'razao_social' => 'Primeiro Cliente  Ltda Me',
    'nome_fantasia' => 'Primeiro Cliente',
    'cnpj_cpf' => '59872959048',
]);

// Lista clientes (call: ListarClientes)
$clients = $service->listClients([
    'pagina' => 1,
    'registros_por_pagina' => 20,
]);

// Consulta um cliente por codigo_cliente_omie (call: ConsultarCliente)
$client = $service->getClient(11118162834);

// Atualiza cliente (call: AlterarCliente)
$updated = $service->updateClient('CodigoInterno0001', [
    'codigo_cliente_integracao' => 'CodigoInterno0001',
    'email' => 'primeiro@ccliente.com.br',
    'razao_social' => 'Primeiro Cliente  Ninja Ltda Me',
    'nome_fantasia' => 'Primeiro Cliente Ninja',
]);

// Exclui cliente (call: ExcluirCliente)
$deleted = $service->deleteClient(11118162834);

No updateClient, se o payload não incluir codigo_cliente_omie ou codigo_cliente_integracao, o método usa o valor de $clientId como codigo_cliente_integracao.

Filtros do `listClients`

Por padrão, o método envia:

pagina = 1
registros_por_pagina = 50
apenas_importado_api = 'N'

Você pode sobrescrever esses valores passando o array $filters.

Service de Users (`OmieUserService`)

A implementação atual do serviço de users está em src/Users/OmieUserService.php.

Métodos já implementados:

listUsers(array $filters = []): array

Exemplo de uso

<?php

use Rafapaulino\Omiephpsdk\Users\OmieUserService;

$service = new OmieUserService();

// Lista users (call: ListarUsuarios)
$users = $service->listUsers([
    'pagina' => 1,
    'registros_por_pagina' => 20,
]);

Filtros do `listUsers`

Por padrão, o método envia:

pagina = 1
registros_por_pagina = 20

Você pode sobrescrever esses valores passando o array $filters.

Service de Vendedores (`OmieSellerService`)

A implementação atual do serviço de vendedores está em src/Sellers/OmieSellerService.php.

Métodos já implementados:

createSeller(array $payload): array

Exemplo de uso

<?php

use Rafapaulino\Omiephpsdk\Sellers\OmieSellerService;

$service = new OmieSellerService();

// Cria vendedor (call: IncluirVendedor)
$seller = $service->createSeller([
    'codInt' => '123',
    'nome' => 'Joao Teste',
    'inativo' => 'N',
    'email' => 'teste@minhaempresa.com.br',
    'fatura_pedido' => 'S',
    'visualiza_pedido' => 'N',
    'comissao' => 10,
]);

Service de Produtos (`OmieProductService`)

A implementação atual do serviço de produtos está em src/Products/OmieProductService.php.

Métodos já implementados:

listProducts(array $filters = []): array

Exemplo de uso

<?php

use Rafapaulino\Omiephpsdk\Products\OmieProductService;

$service = new OmieProductService();

// Lista produtos (call: ListarProdutos)
$products = $service->listProducts([
    'pagina' => 1,
    'registros_por_pagina' => 50,
]);

Filtros do `listProducts`

Por padrão, o método envia:

pagina = 1
registros_por_pagina = 50
apenas_importado_api = 'N'
filtrar_apenas_omiepdv = 'N'

Você pode sobrescrever esses valores passando o array $filters.

Service de Contas Correntes (`OmieCurrentAccountService`)

A implementação atual do serviço de contas correntes está em src/CurrentAccount/OmieCurrentAccountService.php.

Métodos já implementados:

listCurrentAccounts(array $filters = []): array

Exemplo de uso

<?php

use Rafapaulino\Omiephpsdk\CurrentAccount\OmieCurrentAccountService;

$service = new OmieCurrentAccountService();

// Lista contas correntes (call: ListarContasCorrentes)
$accounts = $service->listCurrentAccounts([
    'pagina' => 1,
    'registros_por_pagina' => 100,
]);

Filtros do `listCurrentAccounts`

Por padrão, o método envia:

pagina = 1
registros_por_pagina = 100
apenas_importado_api = 'N'

Você pode sobrescrever esses valores passando o array $filters.

Service de CFOP (`OmieCfopService`)

A implementação atual do serviço de CFOP está em src/CFOP/OmieCfopService.php.

Métodos já implementados:

listCfop(array $filters = []): array

Exemplo de uso

<?php

use Rafapaulino\Omiephpsdk\CFOP\OmieCfopService;

$service = new OmieCfopService();

// Lista CFOP (call: ListarCFOP)
$cfops = $service->listCfop([
    'pagina' => 1,
    'registros_por_pagina' => 50,
]);

Filtros do `listCfop`

Por padrão, o método envia:

pagina = 1
registros_por_pagina = 50

Você pode sobrescrever esses valores passando o array $filters.

Service de Categorias (`OmieCategoryService`)

A implementação atual do serviço de categorias está em src/Categories/OmieCategoryService.php.

Métodos já implementados:

listCategories(array $filters = []): array

Exemplo de uso

<?php

use Rafapaulino\Omiephpsdk\Categories\OmieCategoryService;

$service = new OmieCategoryService();

// Lista categorias (call: ListarCategorias)
$categories = $service->listCategories([
    'pagina' => 1,
    'registros_por_pagina' => 50,
]);

Filtros do `listCategories`

Por padrão, o método envia:

pagina = 1
registros_por_pagina = 50

Você pode sobrescrever esses valores passando o array $filters.

Service de Formas de Pagamento (`OmiePaymentMethodService`)

A implementação atual do serviço de formas de pagamento está em src/PaymentMethods/OmiePaymentMethodService.php.

Métodos já implementados:

listPaymentMethods(array $filters = []): array

Exemplo de uso

<?php

use Rafapaulino\Omiephpsdk\PaymentMethods\OmiePaymentMethodService;

$service = new OmiePaymentMethodService();

// Lista formas de pagamento (call: ListarFormasPagVendas)
$paymentMethods = $service->listPaymentMethods([
    'pagina' => 1,
    'registros_por_pagina' => 50,
]);

Filtros do `listPaymentMethods`

Por padrão, o método envia:

pagina = 1
registros_por_pagina = 50

Você pode sobrescrever esses valores passando o array $filters.

Service de Etapas de Faturamento (`OmieBillingStepService`)

A implementação atual do serviço de etapas de faturamento está em src/BillingSteps/OmieBillingStepService.php.

Métodos já implementados:

listBillingSteps(array $filters = []): array

Exemplo de uso

<?php

use Rafapaulino\Omiephpsdk\BillingSteps\OmieBillingStepService;

$service = new OmieBillingStepService();

// Lista etapas de faturamento (call: ListarEtapasFaturamento)
$billingSteps = $service->listBillingSteps([
    'pagina' => 1,
    'registros_por_pagina' => 20,
]);

Filtros do `listBillingSteps`

Por padrão, o método envia:

pagina = 1
registros_por_pagina = 20

Você pode sobrescrever esses valores passando o array $filters.

Service de Ordens de Serviço (`OmieServiceOrderService`)

A implementação atual do serviço de ordens de serviço está em src/ServiceOrders/OmieServiceOrderService.php.

Métodos já implementados:

createServiceOrder(array $payload): array

Exemplo de uso

<?php

use Rafapaulino\Omiephpsdk\ServiceOrders\OmieServiceOrderService;

$service = new OmieServiceOrderService();

// Cria uma ordem de serviço
$os = $service->createServiceOrder([
    'Cabecalho' => [
        'cCodIntOS' => '12345',
        'cCodParc' => '999',
        'cEtapa' => '10',
        'dDtPrevisao' => '10/10/2030',
        'nCodCli' => 123456789,
        'nQtdeParc' => 1,
    ],
    // Outros itens do payload...
]);

Service de Serviços (`OmieServiceService`)

A implementação atual do serviço de serviços (cadastro de serviços) está em src/Services/OmieServiceService.php.

Métodos já implementados:

listServices(array $filters = []): array

Exemplo de uso

<?php

use Rafapaulino\Omiephpsdk\Services\OmieServiceService;

$service = new OmieServiceService();

// Lista serviços (call: ListarCadastroServico)
$services = $service->listServices([
    'nPagina' => 1,
    'nRegPorPagina' => 100,
]);

Filtros do `listServices`

Por padrão, o método envia:

nPagina = 1
nRegPorPagina = 100

Você pode sobrescrever esses valores passando o array $filters.

Service de Venda Simples (`OmieSimpleSaleService`)

A implementação atual do serviço de venda simples está em src/SimpleSale/OmieSimpleSaleService.php.

Métodos já implementados:

addOrder(array $payload): array
listOrders(array $filters = []): array
addObs(array $payload): array

Exemplo de uso

<?php

use Rafapaulino\Omiephpsdk\SimpleSale\OmieSimpleSaleService;

$service = new OmieSimpleSaleService();

// Cria um pedido de venda simples (call: AdicionarPedido)
$sale = $service->addOrder([
    'codigo_pedido_integracao' => '12345',
    'codigo_cliente' => 123456,
    'codigo_cenario_impostos' => 0,
    'codigo_categoria' => '1.01.01',
    'codigo_conta_corrente' => 123456,
    'itens' => [
        [
            'codigo_produto' => 654321,
            'quantidade' => 1,
            'valor_unitario' => 0,
            'cfop' => "1.102",
            'codigo_cenario_impostos_item' => 0,
        ],
    ],
]);

// Adiciona observação no pedido faturado (call: AlterarPedFaturado)
$saleObs = $service->addObs([
    'codigo_pedido' => $sale['codigo_pedido'],
    'obs_venda' => 'Comentário via API',
]);

// Lista pedidos (call: ListarPedidos)
$orders = $service->listOrders([
    'pagina' => 1,
    'registros_por_pagina' => 100,
]);

Filtros do `listOrders`

Por padrão, o método envia:

pagina = 1
registros_por_pagina = 100
apenas_importado_api = 'N'

Você pode sobrescrever esses valores passando o array $filters.

Testes com Pest

Os testes ficam na pasta tests.

Para rodar:

./vendor/bin/pest

No Windows (PowerShell), se php estiver configurado no PATH:

vendor\bin\pest.bat

Estado atual do projeto

Este SDK está em fase inicial. A parte de contratos e configuração já está pronta.

Próximos passos comuns:

criar implementação concreta para chamadas HTTP na API Omie
tratar erros e respostas da API
adicionar mais testes unitários e de integração

Licença

MIT

rafapaulino / omiephpsdk

Maintainers

Package info

Statistics

Security

README

Para quem é este projeto?

Requisitos

Instalação

Configuração do ambiente (.env)

O que cada variável significa?

Uso com Laravel

Como obter as configurações no código

Estrutura de contratos (SOLID)

Service de Clientes (OmieClientService)

Exemplo de uso

Filtros do listClients

Service de Users (OmieUserService)

Exemplo de uso

Filtros do listUsers

Service de Vendedores (OmieSellerService)

Exemplo de uso

Service de Produtos (OmieProductService)

Exemplo de uso

Filtros do listProducts

Service de Contas Correntes (OmieCurrentAccountService)

Exemplo de uso

Filtros do listCurrentAccounts

Service de CFOP (OmieCfopService)

Exemplo de uso

Filtros do listCfop

Service de Categorias (OmieCategoryService)

Exemplo de uso

Filtros do listCategories

Service de Formas de Pagamento (OmiePaymentMethodService)

Exemplo de uso

Filtros do listPaymentMethods

Service de Etapas de Faturamento (OmieBillingStepService)

Exemplo de uso

Filtros do listBillingSteps

Service de Ordens de Serviço (OmieServiceOrderService)

Exemplo de uso

Service de Serviços (OmieServiceService)

Exemplo de uso

Filtros do listServices

Service de Venda Simples (OmieSimpleSaleService)

Exemplo de uso

Filtros do listOrders

Testes com Pest

Estado atual do projeto

Licença

Service de Clientes (`OmieClientService`)

Filtros do `listClients`

Service de Users (`OmieUserService`)

Filtros do `listUsers`

Service de Vendedores (`OmieSellerService`)

Service de Produtos (`OmieProductService`)

Filtros do `listProducts`

Service de Contas Correntes (`OmieCurrentAccountService`)

Filtros do `listCurrentAccounts`

Service de CFOP (`OmieCfopService`)

Filtros do `listCfop`

Service de Categorias (`OmieCategoryService`)

Filtros do `listCategories`

Service de Formas de Pagamento (`OmiePaymentMethodService`)

Filtros do `listPaymentMethods`

Service de Etapas de Faturamento (`OmieBillingStepService`)

Filtros do `listBillingSteps`

Service de Ordens de Serviço (`OmieServiceOrderService`)

Service de Serviços (`OmieServiceService`)

Filtros do `listServices`

Service de Venda Simples (`OmieSimpleSaleService`)

Filtros do `listOrders`