Notas fiscais de produto (NF-e)

$nfe->productInvoices cobre o ciclo de vida completo da NF-e (modelo 55) no host api.nfse.io, sob /v2: emissão, listagem por cursor, consulta, cancelamento, carta de correção (CC-e), inutilização e downloads.

A emissão segue o contrato 202 discriminado (assíncrona; conclusão via webhook): create() / createWithStateTax() devolvem ProductInvoicePending|ProductInvoiceIssued. Não há createAndWait() nem createBatch().

Prefira webhooks para NF-e

Diferente da NFS-e, productInvoices não tem getStatus(). A conclusão da emissão é orientada a webhook — configure um alvo em Webhooks. Se precisar de polling, use retrieve() e leia o campo de fluxo do DTO.

Métodos

Método	Descrição	Retorno
`create($companyId, $data)`	Emite a NF-e.	`ProductInvoicePending\|ProductInvoiceIssued`
`createWithStateTax($companyId, $stateTaxId, $data)`	Emite vinculada a uma inscrição estadual.	`ProductInvoicePending\|ProductInvoiceIssued`
`list($companyId, $options)`	Lista por cursor; `$options` obrigatório com `environment`.	`ListResponse`
`retrieve($companyId, $invoiceId)`	Consulta por id.	`ProductInvoice`
`cancel($companyId, $invoiceId, $reason = null)`	Cancela; `reason` opcional vai na query.	`ProductInvoice`
`listItems($companyId, $invoiceId)`	Lista os itens da nota.	`array` (arrays crus)
`listEvents($companyId, $invoiceId)`	Lista os eventos fiscais.	`array` (arrays crus)
`downloadPdf($companyId, $invoiceId)`	DANFE PDF.	`string` (bytes crus)
`downloadXml($companyId, $invoiceId)`	XML autorizado.	`string`
`downloadRejectionXml($companyId, $invoiceId)`	XML de rejeição.	`string`
`downloadEpecXml($companyId, $invoiceId)`	XML de contingência EPEC.	`string`
`sendCorrectionLetter($companyId, $invoiceId, $correction)`	Emite CC-e.	`array`
`downloadCorrectionLetterPdf($companyId, $invoiceId)`	PDF da CC-e.	`string`
`downloadCorrectionLetterXml($companyId, $invoiceId)`	XML da CC-e.	`string`
`disable($companyId, $invoiceId, $data)`	Inutiliza uma nota específica.	`array`
`disableRange($companyId, $data)`	Inutiliza uma faixa de numeração.	`array`

Emitir uma NF-e

use Nfe\Response\Pending;

$result = $nfe->productInvoices->create('55df4dc6b6cd9007e4f13ee8', [
    'buyer' => [
        'federalTaxNumber' => 11111111111111,
        'name'             => 'Cliente Exemplo LTDA',
    ],
    'items' => [
        ['code' => '001', 'description' => 'Produto X', 'quantity' => 1, 'unitAmount' => 99.9],
    ],
]);

if ($result instanceof Pending) {
    $result->invoiceId();   // acompanhe via webhook ou retrieve()
} else {
    $result->resource();    // Nfe\ProductInvoice
}

Para emitir vinculada a uma inscrição estadual específica (veja Inscrições estaduais):

$result = $nfe->productInvoices->createWithStateTax($companyId, $stateTaxId, $data);

Listar com `environment` obrigatório

A paginação é por cursor e o argumento $options é obrigatório — precisa conter environment (string "Production" ou "Test").

$pagina = $nfe->productInvoices->list($companyId, [
    'environment' => 'Production',
    'limit'       => 50,
]);

foreach ($pagina->data as $nf) {
    echo $nf->id, PHP_EOL;
}

// Próxima página:
$proxima = $nfe->productInvoices->list($companyId, [
    'environment'   => 'Production',
    'startingAfter' => $pagina->page->startingAfter,
    'limit'         => 50,
]);

environment é o ambiente da SEFAZ

Este environment (string) é um parâmetro real de ambiente da SEFAZ, separado da configuração produção/teste da conta (definida em app.nfe.io). O enum Nfe\Environment do cliente está reservado para uso futuro.

Baixar arquivos (bytes crus)

Todos os downloads devolvem a string de bytes — grave com file_put_contents():

file_put_contents('danfe.pdf', $nfe->productInvoices->downloadPdf($companyId, $invoiceId));
file_put_contents('nfe.xml', $nfe->productInvoices->downloadXml($companyId, $invoiceId));

Carta de correção (CC-e)

Um texto vazio ou só com espaços lança Nfe\Exception\InvalidRequestException antes de qualquer HTTP.

$nfe->productInvoices->sendCorrectionLetter(
    $companyId,
    $invoiceId,
    'Correção do endereço de entrega do destinatário',
);

file_put_contents(
    'cce.pdf',
    $nfe->productInvoices->downloadCorrectionLetterPdf($companyId, $invoiceId),
);

Cancelar e inutilizar

// Cancelamento (com justificativa opcional na query):
$nfe->productInvoices->cancel($companyId, $invoiceId, 'Pedido cancelado pelo cliente');

// Inutilizar uma nota específica:
$nfe->productInvoices->disable($companyId, $invoiceId, [
    'reason' => 'Numeração não utilizada',
]);

// Inutilizar uma faixa de numeração:
$nfe->productInvoices->disableRange($companyId, [
    'environment' => 'Production',
    'serie'       => 1,
    'state'       => 'SP',
    'beginNumber' => 100,
    'lastNumber'  => 110,
    'reason'      => 'Falha de impressão',
]);

Próximos passos

Notas de consumidor (NFC-e) — modelo 65.
Inscrições estaduais — pré-requisito para emitir NF-e.
Paginação — cursor vs. página.

Métodos​

Emitir uma NF-e​

Listar com environment obrigatório​

Baixar arquivos (bytes crus)​

Carta de correção (CC-e)​

Cancelar e inutilizar​

Próximos passos​

NFE.io