Como Emitir NF-e com Pedido de Compra (xPed e nItemPed) via API: Guia para Fornecedores e Grandes Redes

Se a sua empresa, ERP ou plataforma de e-commerce fornece mercadorias para grandes redes de varejo (como Magazine Luiza, Carrefour, Grupo Pão de Açúcar, Mercado Livre Fulfillment), montadoras de veículos, redes hospitalares ou grandes distribuidoras, você certamente já viveu ou ouviu falar do pesadelo da doca de recebimento:

🛑 O Cenário do Bloqueio na Portaria:
A transportadora chega ao centro de distribuição (CD) do cliente com uma carga de alto valor. O conferente bipa a chave de acesso da NF-e no portal EDI (SAP Ariba, Neogrid ou similar) e o sistema trava. O motivo? A nota fiscal foi emitida sem o Número do Pedido de Compra (<xPed>) ou sem o Número do Item do Pedido (<nItemPed>) correspondente em cada produto.
Resultado imediato: A carga é recusada na portaria, o caminhão volta, sua empresa paga frete reverso, suporta custo de diária parada e tem o pagamento glosado até a emissão de uma nota de devolução e refaturamento.

Embora o preenchimento dessas tags não seja obrigatório para a validação matemática da SEFAZ perante o Fisco, ele é uma regra comercial mandatória e inegociável nas transações B2B corporativas.

Neste guia técnico, vamos explorar como as tags xPed e nItemPed funcionam no Manual de Orientação do Contribuinte (MOC 7.0) da SEFAZ, por que a maioria das APIs fiscais falha ao lidar com elas e como estruturar payloads limpos em JSON na Notaas com impressão automática no DANFE PDF.

🔍 O Que São xPed e nItemPed no XML da NF-e (MOC 7.0)?

Dentro da estrutura hierárquica do XML da NF-e (Modelo 55), cada mercadoria faturada é descrita sob a tag <det>, que contém os dados específicos do produto no grupo <prod>.

A SEFAZ disponibiliza dois campos alfanuméricos específicos para a rastreabilidade do processo de compras corporativo:

<det nItem="1">
  <prod>
    <cProd>SKU-10294</cProd>
    <cEAN>7891234567890</cEAN>
    <xProd>PARAFUSO SEXTAVADO ACO INOX 5/8 X 2 POL</xProd>
    <NCM>73181500</NCM>
    <CFOP>5102</CFOP>
    <uCom>UN</uCom>
    <qCom>1000.0000</qCom>
    <vUnCom>1.2500</vUnCom>
    <vProd>1250.00</vProd>
    <!-- Rastreabilidade B2B da Compra -->
    <xPed>PO-450912</xPed>
    <nItemPed>1</nItemPed>
  </prod>
  ...
</det>

1. Tag <xPed> (Número do Pedido de Compra)

• Finalidade: Identificador do contrato de fornecimento ou pedido de compras gerado pelo ERP do cliente comprador (ex: Purchase Order - PO do SAP, Totvs Protheus ou Oracle).
• Especificação Técnica SEFAZ: Tipo TString, tamanho mínimo de 1 e máximo de 15 caracteres alfanuméricos.
• Escopo: Pode ser preenchido item a item (quando um mesmo faturamento atende itens de diferentes ordens de compra) ou repetido em toda a nota.

2. Tag <nItemPed> (Número do Item no Pedido de Compra)

• Finalidade: A linha exata do item dentro do pedido de compras original do cliente. Se o cliente comprou 20 itens no pedido PO-450912, este campo indica se o produto em questão é o item 1, 2, 10 ou 20.
• Especificação Técnica SEFAZ: Tipo numérico inteiro de 1 a 6 dígitos (de 1 a 999999).
• Função no EDI: Permite que o sistema de recebimento do comprador dê baixa automática no estoque sem exigir intervenção humana para "adivinhar" a qual linha do pedido aquele SKU pertence.

⚠️ A Falha Comum das APIs Legadas: "Gambiarras" em Informações Adicionais

Muitas bibliotecas e APIs fiscais antigas não possuem os campos xPed e nItemPed modelados nos objetos dos itens. Diante dessa limitação, desenvolvedores costumam improvisar inserindo textos livres no campo de Informações Adicionais do Produto (<infAdProd>):

<!-- ❌ GAMBIARRA QUE GERA RECUSA NO CD: -->
<infAdProd>REF: PEDIDO DE COMPRA PO-450912 ITEM 1</infAdProd>

Por Que Essa Prática Causa Rejeição nas Grandes Redes?

1. Robôs de EDI e Portais XML: Sistemas como Mercado Livre Fulfillment, GPA e Ariba leem diretamente as tags estruturadas <xPed> e <nItemPed>. Se o campo XML estiver vazio, o leitor automático acusa divergência documental e bloqueia o agendamento da doca.
2. Conferência Cega por Coletores de Dados: Na barreira física do armazém, os operadores utilizam coletores WMS que cruzam o XML contra a ordem de recebimento. Textos jogados em infAdProd não são parseados pelo coletor.
3. Limite de Caracteres no DANFE: O excesso de texto em infAdProd pode poluir o documento auxiliar ou ser truncado dependendo do layout de impressão.

🚀 Como Emitir NF-e com xPed e nItemPed na Notaas

A engine da Notaas suporta nativamente a rastreabilidade de compras B2B através de propriedades limpas e intuitivas dentro de cada item da requisição.

Você não precisa se preocupar com namespaces XML, regras de schema XSD ou conversões manuais de string.

Exemplo de Payload REST JSON (POST /api/v1/emitir)

{
  "tipo": "nfe",
  "naturezaOperacao": "Venda de Mercadoria",
  "destinatario": {
    "cnpj": "00000000000191",
    "razaoSocial": "COMPRADOR VAREJISTA CORPORATIVO S.A.",
    "inscricaoEstadual": "123456789110",
    "endereco": {
      "logradouro": "Avenida das Nacoes",
      "numero": "1500",
      "bairro": "Distrito Industrial",
      "codigoMunicipio": "3550308",
      "uf": "SP",
      "cep": "01000000"
    }
  },
  "itens": [
    {
      "codigo": "SKU-9921",
      "descricao": "BOBINA DE ACO GALVANIZADO 0.50MM X 1200MM",
      "ncm": "72104910",
      "cfop": "5101",
      "unidade": "KG",
      "quantidade": 2500,
      "valorUnitario": 8.40,
      "tributacao": {
        "origem": "0",
        "cstIcms": "00",
        "aliquotaIcms": 18,
        "cstPis": "01",
        "aliquotaPis": 1.65,
        "cstCofins": "01",
        "aliquotaCofins": 7.60
      },
      // 🎯 Identificadores B2B de Pedido de Compra (Notaas v0.56.29):
      "pedidoCompra": "PO-884019",
      "itemPedido": 1
    },
    {
      "codigo": "SKU-9922",
      "descricao": "CHAPA DE ACO INOX 304 2.0MM X 1000MM X 2000MM",
      "ncm": "72193400",
      "cfop": "5101",
      "unidade": "UN",
      "quantidade": 50,
      "valorUnitario": 420.00,
      "tributacao": {
        "origem": "0",
        "cstIcms": "00",
        "aliquotaIcms": 18,
        "cstPis": "01",
        "aliquotaPis": 1.65,
        "cstCofins": "01",
        "aliquotaCofins": 7.60
      },
      // Item referente ao segundo registro do pedido do cliente:
      "pedidoCompra": "PO-884019",
      "itemPedido": 2
    }
  ],
  "pagamento": {
    "formas": [
      {
        "meio": "15",
        "valor": 42000.00
      }
    ]
  }
}

⚡ Fluxo de Processamento e Entrega da Nota:

• 1. Envio JSON: Sua aplicação dispara o payload acima via REST para a Notaas.
• 2. Sanitização & Mapeamento: A engine Notaas valida o limite alfanumérico (até 15 caracteres) e injeta as tags <xPed> e <nItemPed> no nó <prod> do XML.
• 3. Autorização SEFAZ: O XML é assinado com o certificado A1 da sua empresa e transmitido síncronamente para a SEFAZ autorizadora.
• 4. Renderização do DANFE PDF: A Notaas compila o DANFE oficial incluindo automaticamente no rodapé do item: PEDIDO: PO-884019 ITEM: 1.
• 5. Webhook com HMAC: Seu backend recebe a confirmação com as URLs públicas do XML autorizado e do PDF do DANFE em alta resolução.

📄 Como o Pedido de Compra Aparece no DANFE PDF?

Um dos maiores diferenciais da Notaas frente a geradores de DANFE legados (como utilitários Java ou scripts sem suporte visual) é a formatação dedicada no corpo do documento auxiliar:

┌────────────────────────────────────────────────────────────────────────────────────────┐
│ CÓDIGO  │ DESCRIÇÃO DO PRODUTO / SERVIÇO                     │ NCM/SH   │ CST │ CFOP │
├─────────┼────────────────────────────────────────────────────┼──────────┼─────┼──────┤
│ SKU-9921│ BOBINA DE ACO GALVANIZADO 0.50MM X 1200MM          │ 72104910 │ 000 │ 5101 │
│         │ PEDIDO: PO-884019 ITEM: 001                        │          │     │      │
├─────────┼────────────────────────────────────────────────────┼──────────┼─────┼──────┤
│ SKU-9922│ CHAPA DE ACO INOX 304 2.0MM X 1000MM X 2000MM      │ 72193400 │ 000 │ 5101 │
│         │ PEDIDO: PO-884019 ITEM: 002                        │          │     │      │
└────────────────────────────────────────────────────────────────────────────────────────┘

Ao imprimir o DANFE que acompanha a mercadoria no caminhão, o conferente físico da doca lê instantaneamente a vinculação do pedido sem precisar consultar planilhas externas, garantindo o despacho e recebimento em menos de 5 minutos.

🛠️ Exemplo de Implementação em TypeScript / Node.js

Se você utiliza Node.js, Nest.js ou Next.js no seu sistema de faturamento, veja como estruturar a emissão de maneira modular:

import axios from "axios";

interface ItemFaturamento {
  codigo: string;
  descricao: string;
  ncm: string;
  cfop: string;
  unidade: string;
  quantidade: number;
  valorUnitario: number;
  pedidoCompra?: string;
  itemPedido?: number;
}

export async function emitirNfeCorporativa(
  itensFaturados: ItemFaturamento[],
  cnpjDestinatario: string,
  apiKey: string
) {
  const url = "https://api.notaas.com.br/api/v1/emitir";

  const payload = {
    tipo: "nfe",
    naturezaOperacao: "Venda de Producao B2B",
    destinatario: {
      cnpj: cnpjDestinatario,
      razaoSocial: "REDE ATACADISTA E VAREJISTA LTDA"
    },
    itens: itensFaturados.map((item) => ({
      ...item,
      tributacao: {
        origem: "0",
        cstIcms: "00",
        aliquotaIcms: 18,
        cstPis: "01",
        aliquotaPis: 1.65,
        cstCofins: "01",
        aliquotaCofins: 7.60
      }
    })),
    pagamento: {
      formas: [{ meio: "15", valor: 15000.00 }]
    }
  };

  try {
    const { data } = await axios.post(url, payload, {
      headers: {
        Authorization: `Bearer ${apiKey}`,
        "Content-Type": "application/json"
      }
    });

    console.log("Nota Autorizada com Sucesso! Chave:", data.chaveAcesso);
    console.log("Link do DANFE PDF com Pedido de Compra:", data.danfeUrl);
    return data;
  } catch (error: any) {
    console.error("Falha na emissão da NF-e:", error.response?.data || error.message);
    throw error;
  }
}

📋 Checklist de Prontidão B2B para o Seu ERP

Antes de liberar a expedição de mercadorias para clientes corporativos, valide os seguintes pontos no seu pipeline de integração:

• Tamanho da String: Garanta que seu front-end ou integração limite o campo de pedido de compra a 15 caracteres (espaços a mais são higienizados pela Notaas).
• Item Numérico: O itemPedido deve ser um número inteiro positivo (ex: 1, 2, 15). Não envie letras ou caracteres especiais nesse nó.
• Agrupamento de Pedidos: A Notaas permite que diferentes itens da mesma nota fiscal apontem para pedidos de compra distintos (ex: Item 1 aponta para PO-100 e Item 2 aponta para PO-105), cenário muito frequente em entregas parciais de contratos guarda-chuva.
• Conexão com Logística (MDF-e): Se a sua entrega for interestadual e realizada com veículos da sua própria frota, lembre-se de que a legislação exige a emissão do MDF-e de Carga Própria vinculando as chaves de acesso emitidas. Veja nosso guia completo sobre API de CT-e e MDF-e para Transporte e Logística.

🏁 Conclusão e Próximos Passos

A automação de pedidos de compra no faturamento é o divisor de águas entre um ERP com suporte precário e uma solução enterprise de alta confiabilidade. Evitar recusas físicas em grandes redes poupa milhares de reais em logística reversa e protege o fluxo de caixa da sua empresa.

Com a Notaas, você tem:

• 50 notas fiscais gratuitas todo mês por CNPJ em produção real, sem exigência de cartão de crédito.
• Suporte nativo a xPed, nItemPed, cálculo de ICMS ST e devoluções sem complexidade XSD.
• DANFE e DACTE gerados em milissegundos localmente, eliminando a dependência de servidores lentos.

👉 Quer automatizar a emissão fiscal do seu sistema hoje mesmo?
Acesse a Documentação da API da Notaas ou crie sua conta gratuita em platform.notaas.com.br/sign-up.