Pessoas físicas (naturalPeople)

$nfe->naturalPeople gerencia o cadastro de pessoas físicas (tomadores PF) vinculadas a uma empresa emissora. Escopo de empresa, família main (api.nfe.io /v1), chave principal. A API é idêntica à de pessoas jurídicas, com uma diferença de tipo importante.

Métodos

Método	Descrição	Retorno
list($companyId)	Lista as pessoas físicas da empresa.	ListResponse
create($companyId, $data)	Cadastra uma PF.	NaturalPerson
retrieve($companyId, $personId)	Consulta por id.	NaturalPerson
update($companyId, $personId, $data)	Atualiza.	NaturalPerson
delete($companyId, $personId)	Exclui.	void
createBatch($companyId, $batch)	Cadastra várias em sequência.	array
findByTaxNumber($companyId, $taxNumber)	Busca por CPF (client-side).	?NaturalPerson

Exemplos

Cadastrar uma pessoa física

$pessoa = $nfe->naturalPeople->create('55df4dc6b6cd9007e4f13ee8', [
    'federalTaxNumber' => '31119298000',   // string para PF
    'name'             => 'Maria da Silva',
    'email'            => 'maria@example.com',
]);

federalTaxNumber é string para PF

No DTO NaturalPerson, federalTaxNumber é ?string — diferente de LegalPerson/Company, onde é ?int. O SDK não valida nem coage no create; enviar o tipo errado pode causar rejeição ou perda de zeros à esquerda do CPF.

Lote, busca e exclusão

$nfe->naturalPeople->createBatch($companyId, [
    ['federalTaxNumber' => '31119298000', 'name' => 'Maria da Silva'],
    ['federalTaxNumber' => '19100000000', 'name' => 'João Souza'],
]); // sequencial, sem paralelismo

$pf = $nfe->naturalPeople->findByTaxNumber($companyId, '31119298000');

if ($pf !== null) {
    $nfe->naturalPeople->delete($companyId, $pf->id);   // void
}

Veja também

• Pessoas jurídicas — o equivalente PJ.
• Consulta de CPF — valide a situação cadastral na Receita.
• Notas de serviço — use a PF como borrower.