README

SDK oficial PHP para a API de integração do Emitefy - emissão de NFe/NFC-e via API REST, para e-commerces, ERPs e outros SaaS que integram emissão fiscal em seus próprios sistemas.

Instalação

composer require emitefy/sdk-php

Requer PHP 8.2+.

Autenticação

Gere um token de integração no painel Emitefy (Configurações → Tokens)

um token de sessão do painel não funciona aqui. Veja Autenticação.

use Emitefy\Sdk\Client;

$client = new Client(token: 'SEU_TOKEN_DE_INTEGRACAO');

Emitindo uma nota fiscal

$nota = $client->emitir([
    'tipo' => 'nfce', // opcional - "nfe" (padrão) | "nfce"
    'empresa_id' => 'b1e6c1b0-...',
    'natureza_operacao' => 'Venda no varejo',
    'forma_pagamento' => 'pix', // obrigatório só para tipo "nfce"
    'itens' => [
        [
            'codigo' => 'SKU001',
            'descricao' => 'Produto de exemplo',
            'ncm' => '84713012',
            'cfop' => '5102',
            'unidade' => 'UN',
            'quantidade' => 1,
            'valor_unitario' => 99.90,
            'icms' => ['situacao_tributaria' => '102'],
        ],
    ],
], idempotencyKey: 'um-uuid-gerado-pelo-seu-sistema');

// $nota['status'] === 'processando' - a transmissão à SEFAZ é assíncrona.
// Acompanhe via webhook ou consultando de novo mais tarde:
$nota = $client->consultar($nota['id']);

Payload completo (destinatário, endereço, múltiplos itens) documentado em Emissão de Notas Fiscais.

O parâmetro opcional idempotencyKey evita emitir a mesma nota duas vezes se uma chamada anterior tiver dado timeout do seu lado sem confirmação - reenviar a mesma chave com o mesmo payload devolve a nota já criada.

Consultando, cancelando e corrigindo

$client->consultar($id);
$client->consultarPorChaveAcesso($chaveDeAcesso); // 44 caracteres

$client->cancelar($id, 'Cliente desistiu da compra antes da entrega.');
$client->cartaCorrecao($id, 'Correção do CFOP do item 1, sem impacto no valor.');

Cancelamento e Carta de Correção só são aceitos para notas autorizada e são assíncronos - o resultado final chega por webhook ou numa nova chamada a consultar().

Baixando XML, DANFE e DANFCE

file_put_contents('nota.xml', $client->baixarXml($id));
file_put_contents('danfe.pdf', $client->baixarDanfe($id));   // NFe
file_put_contents('danfce.pdf', $client->baixarDanfce($id)); // NFC-e

Só disponíveis para uma nota já autorizada.

Tratamento de erros

Toda falha da API vira uma exceção tipada, todas estendendo Emitefy\Sdk\Exceptions\EmitefyApiException (statusCode, type, errors, rawBody):

Exceção	Quando
`EmitefyValidationException`	422 - payload inválido ou regra de negócio recusada
`EmitefyAuthException`	401/403 - token inválido ou bloqueado pelo Firewall de IP
`EmitefyNotFoundException`	404 - `empresa_id`/nota inexistente
`EmitefyRateLimitException`	429 - limite de requisições excedido (`retryAfterSeconds`)
`EmitefyServerException`	5xx - falha inesperada do Emitefy
`EmitefyConnectionException`	Falha de rede antes de qualquer resposta chegar

use Emitefy\Sdk\Exceptions\EmitefyValidationException;

try {
    $client->emitir($payload);
} catch (EmitefyValidationException $e) {
    // $e->errors: ['destinatario.documento' => ['O campo documento é obrigatório.']]
}

Verificando webhooks

use Emitefy\Sdk\Webhooks\WebhookVerifier;

$rawBody = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_EMITEFY_SIGNATURE'] ?? '';

$payload = WebhookVerifier::verifyAndDecode($rawBody, $signature, $webhookSecret);
// lança Emitefy\Sdk\Exceptions\EmitefyWebhookSignatureException se a assinatura não conferir

match ($payload['evento']) {
    'nota.autorizada' => /* ... */,
    'nota.rejeitada' => /* ... */,
    default => null,
};

O segredo do webhook é exibido uma única vez no painel, ao configurar a URL de callback de uma Empresa Emitente (Empresas → editar → aba Webhooks). Catálogo completo de eventos em Emitefy\Sdk\Webhooks\WebhookEvent e em Webhooks.

Testando contra outro ambiente

$client = new Client(token: '...', baseUrl: 'http://localhost:8000');

Desenvolvimento

composer install
composer test

emitefy / sdk-php

Maintainers

Package info

Statistics

Security