VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Referência completa/ERP Compras

NF-e de entrada: importar e consultar

Importa o XML da nota do fornecedor, lista as notas e consulta uma nota com suas linhas.

Listar notas de entrada

Uma NF-e de entrada é a nota fiscal eletrônica que o fornecedor emitiu contra o seller. Importá-la evita digitar a compra: a plataforma lê os itens, tenta casar com os seus produtos e, ao lançar, dá entrada no estoque e cria as contas a pagar. A listagem não traz as linhas.

GET/api/v1/vendor/erp/notas-entradaSeller

Lista as NF-e de entrada

Parâmetros de consulta

statusstring
pending_matchmatchedpostedcancelled
Estado da nota.
sourcestring
uploadsefaz
Origem.
pageintegerpadrão: 1
Página, a partir de 1. Valor inválido ou menor que 1 volta para 1.
per_pageintegerpadrão: 50
Itens por página, de 1 a 200. Fora dessa faixa vale o padrão.

Exemplo de requisição: Listar notas de entrada

bash
curl "$BASE_URL/api/v1/vendor/erp/notas-entrada?status=pending_match" \
  -H "Authorization: Bearer $TOKEN"

Resposta: Listar notas de entrada

200Notas retornadas
json
{
  "invoices": [
    {
      "id": "5534915e-925c-45af-888a-4957b6fa54ff",
      "access_key": "35261011222333000181550010000487651876543249",
      "number": "48765",
      "series": "1",
      "supplier_cnpj": "11222333000181",
      "supplier_name": "Distribuidora Aurora Ltda",
      "supplier_id": null,
      "purchase_order_id": null,
      "warehouse_id": null,
      "issue_date": "2026-10-09",
      "total_products_cents": 99800,
      "freight_cents": 5000,
      "discount_cents": 0,
      "total_invoice_cents": 104800,
      "source": "upload",
      "status": "matched",
      "duplicatas": [
        {
          "number": "001",
          "due_date": "2026-11-06",
          "amount_cents": 52400
        },
        {
          "number": "002",
          "due_date": "2026-12-06",
          "amount_cents": 52400
        }
      ],
      "created_at": "2026-10-11T14:30:00Z"
    }
  ],
  "total": 1
}

Campos da resposta

invoicesarray

Notas da página.

iduuid
Id da nota no sistema.
access_keystring
Chave de acesso da NF-e, 44 dígitos.
numberstring
Número.
seriesstring
Série.
supplier_cnpjstring
CNPJ do emitente, só dígitos.
supplier_namestring
Nome do emitente.
supplier_iduuid
Sempre null nas notas do seller.
purchase_order_iduuid
Pedido de compra vinculado. null se não vinculado.
warehouse_iduuid
Sempre null: o depósito é escolhido no lançamento.
issue_datestring
Data de emissão YYYY-MM-DD. null se ausente no XML.
total_products_centsinteger
Total dos produtos.
freight_centsinteger
Frete.
discount_centsinteger
Desconto.
total_invoice_centsinteger
Total da nota.
sourcestring
uploadsefaz
Origem da nota.
statusstring
pending_matchmatchedpostedcancelled
Estado da nota.
duplicatasarray

Parcelas de cobrança do XML. Pode vir null na listagem.

numberstring
Número da parcela.
due_datestring
Vencimento YYYY-MM-DD.
amount_centsinteger
Valor em centavos.
itemsarray

Linhas. Só no detalhe e nas ações.

iduuid
Id da linha.
line_numberinteger
Número da linha na nota.
supplier_codestring
Código do produto no fornecedor (cProd).
eanstring
Código de barras (GTIN).
descriptionstring
Descrição na nota.
ncmstring
NCM fiscal.
cfopstring
CFOP da operação.
unitstring
Unidade da nota (UN, CX...).
quantitystring
Quantidade da nota como texto decimal com 4 casas.
conversion_factorstring
Quantas unidades de estoque há em cada unidade da nota (padrão 1.0000). O estoque recebe quantity vezes este fator, que precisa dar inteiro.
unit_value_centsinteger
Valor unitário em centavos.
item_total_centsinteger
Total da linha em centavos.
landed_unit_cost_centsinteger
Custo unitário aterrissado (com rateio de frete etc.). null se não calculado.
product_iduuid
Produto do seller vinculado. null enquanto não casado.
variation_iduuid
Variação do produto, se houver.
match_statusstring
automanualunmatchedignored
Situação do vínculo.
product_namestring
Nome do produto vinculado.
created_atdatetime
Quando foi importada.
totalinteger
Total que atende ao filtro.

Erros: Listar notas de entrada

StatusQuandoCorpo
401Cabeçalho Authorization ausente, token inválido, expirado ou revogado.{"error":"missing authorization header"}
403O token não é de um usuário seller (por exemplo, é de administrador).{"error":"insufficient permissions"}
403O usuário não está vinculado a um seller, ou o cadastro do seller ainda está em análise (vendor_pending_review).{"error":"no vendor account associated with this user"}

Consultar nota de entrada

GET/api/v1/vendor/erp/notas-entrada/{id}Seller

Consulta uma NF-e de entrada

Parâmetros de caminho

iduuidobrigatório
Id (UUID) da nota.

Exemplo de requisição: Consultar nota de entrada

bash
curl "$BASE_URL/api/v1/vendor/erp/notas-entrada/3f6c1c1e-8d0b-4a55-9a52-1d6f6a4a7b10" \
  -H "Authorization: Bearer $TOKEN"

Resposta: Consultar nota de entrada

200Nota com linhas
json
{
  "id": "5534915e-925c-45af-888a-4957b6fa54ff",
  "access_key": "35261011222333000181550010000487651876543249",
  "number": "48765",
  "series": "1",
  "supplier_cnpj": "11222333000181",
  "supplier_name": "Distribuidora Aurora Ltda",
  "supplier_id": null,
  "purchase_order_id": null,
  "warehouse_id": null,
  "issue_date": "2026-10-09",
  "total_products_cents": 99800,
  "freight_cents": 5000,
  "discount_cents": 0,
  "total_invoice_cents": 104800,
  "source": "upload",
  "status": "matched",
  "duplicatas": [
    {
      "number": "001",
      "due_date": "2026-11-06",
      "amount_cents": 52400
    },
    {
      "number": "002",
      "due_date": "2026-12-06",
      "amount_cents": 52400
    }
  ],
  "items": [
    {
      "id": "816501df-beb7-4b95-89d5-e75efd42400d",
      "line_number": 1,
      "supplier_code": "CAM-PRE-M",
      "ean": "7891234567895",
      "description": "Camiseta Básica Preta M",
      "ncm": "61091000",
      "cfop": "5102",
      "unit": "UN",
      "quantity": "20.0000",
      "conversion_factor": "1.0000",
      "unit_value_cents": 4990,
      "item_total_cents": 99800,
      "landed_unit_cost_cents": 5240,
      "product_id": "94e6917e-8733-4ddc-b446-ed85977117e8",
      "variation_id": null,
      "match_status": "auto",
      "product_name": "Camiseta Básica Preta M"
    }
  ],
  "created_at": "2026-10-11T14:30:00Z"
}

Campos da resposta

iduuid
Id da nota no sistema.
access_keystring
Chave de acesso da NF-e, 44 dígitos.
numberstring
Número.
seriesstring
Série.
supplier_cnpjstring
CNPJ do emitente, só dígitos.
supplier_namestring
Nome do emitente.
supplier_iduuid
Sempre null nas notas do seller.
purchase_order_iduuid
Pedido de compra vinculado. null se não vinculado.
warehouse_iduuid
Sempre null: o depósito é escolhido no lançamento.
issue_datestring
Data de emissão YYYY-MM-DD. null se ausente no XML.
total_products_centsinteger
Total dos produtos.
freight_centsinteger
Frete.
discount_centsinteger
Desconto.
total_invoice_centsinteger
Total da nota.
sourcestring
uploadsefaz
Origem da nota.
statusstring
pending_matchmatchedpostedcancelled
Estado da nota.
duplicatasarray

Parcelas de cobrança do XML. Pode vir null na listagem.

numberstring
Número da parcela.
due_datestring
Vencimento YYYY-MM-DD.
amount_centsinteger
Valor em centavos.
itemsarray

Linhas. Só no detalhe e nas ações.

iduuid
Id da linha.
line_numberinteger
Número da linha na nota.
supplier_codestring
Código do produto no fornecedor (cProd).
eanstring
Código de barras (GTIN).
descriptionstring
Descrição na nota.
ncmstring
NCM fiscal.
cfopstring
CFOP da operação.
unitstring
Unidade da nota (UN, CX...).
quantitystring
Quantidade da nota como texto decimal com 4 casas.
conversion_factorstring
Quantas unidades de estoque há em cada unidade da nota (padrão 1.0000). O estoque recebe quantity vezes este fator, que precisa dar inteiro.
unit_value_centsinteger
Valor unitário em centavos.
item_total_centsinteger
Total da linha em centavos.
landed_unit_cost_centsinteger
Custo unitário aterrissado (com rateio de frete etc.). null se não calculado.
product_iduuid
Produto do seller vinculado. null enquanto não casado.
variation_iduuid
Variação do produto, se houver.
match_statusstring
automanualunmatchedignored
Situação do vínculo.
product_namestring
Nome do produto vinculado.
created_atdatetime
Quando foi importada.

Erros: Consultar nota de entrada

StatusQuandoCorpo
404A nota não existe ou é de outro seller.{"error":"inbound invoice not found"}
401Cabeçalho Authorization ausente, token inválido, expirado ou revogado.{"error":"missing authorization header"}
403O token não é de um usuário seller (por exemplo, é de administrador).{"error":"insufficient permissions"}
403O usuário não está vinculado a um seller, ou o cadastro do seller ainda está em análise (vendor_pending_review).{"error":"no vendor account associated with this user"}

Importar XML

Envia o arquivo XML da NF-e (versão 4.00, com ou sem o envelope nfeProc) como multipart/form-data, no campo file, até 16 MB. A importação é idempotente pela chave de acesso: reenviar a mesma nota do mesmo seller devolve a nota já existente, também com 201. A importação não mexe em estoque nem cria contas; isso só acontece ao lançar.

POST/api/v1/vendor/erp/notas-entrada/import-xmlSeller

Importa o XML de uma NF-e

Corpo da requisição

filefileobrigatório
Arquivo XML da NF-e.

Exemplo de requisição: Importar XML

bash
curl -X POST "$BASE_URL/api/v1/vendor/erp/notas-entrada/import-xml" \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@nfe-48765.xml;type=application/xml"

Resposta: Importar XML

201Nota importada
json
{
  "invoice": {
    "id": "5534915e-925c-45af-888a-4957b6fa54ff",
    "access_key": "35261011222333000181550010000487651876543249",
    "number": "48765",
    "series": "1",
    "supplier_cnpj": "11222333000181",
    "supplier_name": "Distribuidora Aurora Ltda",
    "supplier_id": null,
    "purchase_order_id": null,
    "warehouse_id": null,
    "issue_date": "2026-10-09",
    "total_products_cents": 99800,
    "freight_cents": 5000,
    "discount_cents": 0,
    "total_invoice_cents": 104800,
    "source": "upload",
    "status": "matched",
    "duplicatas": [
      {
        "number": "001",
        "due_date": "2026-11-06",
        "amount_cents": 52400
      },
      {
        "number": "002",
        "due_date": "2026-12-06",
        "amount_cents": 52400
      }
    ],
    "items": [
      {
        "id": "816501df-beb7-4b95-89d5-e75efd42400d",
        "line_number": 1,
        "supplier_code": "CAM-PRE-M",
        "ean": "7891234567895",
        "description": "Camiseta Básica Preta M",
        "ncm": "61091000",
        "cfop": "5102",
        "unit": "UN",
        "quantity": "20.0000",
        "conversion_factor": "1.0000",
        "unit_value_cents": 4990,
        "item_total_cents": 99800,
        "landed_unit_cost_cents": 5240,
        "product_id": "94e6917e-8733-4ddc-b446-ed85977117e8",
        "variation_id": null,
        "match_status": "auto",
        "product_name": "Camiseta Básica Preta M"
      }
    ],
    "created_at": "2026-10-11T14:30:00Z"
  },
  "items_matched": 1,
  "items_unmatched": 0
}

Campos da resposta

invoiceobject
A nota, com as linhas. Mesmos campos de Consultar nota.
items_matchedinteger
Linhas já vinculadas a um produto do seller.
items_unmatchedinteger
Linhas que ainda precisam de vínculo manual.

Erros: Importar XML

StatusQuandoCorpo
400Não veio multipart/form-data válido.{"error":"invalid multipart form"}
400Falta o campo file.{"error":"missing file field"}
400O XML é inválido ou a chave de acesso não tem 44 dígitos.{"error":"procurement: validation: invalid NF-e XML: ..."}
400A chave de acesso já foi importada por outro seller ou pelo administrador.{"error":"vendorerp: NF-e já importada em outro escopo"}
401Cabeçalho Authorization ausente, token inválido, expirado ou revogado.{"error":"missing authorization header"}
403O token não é de um usuário seller (por exemplo, é de administrador).{"error":"insufficient permissions"}
403O usuário não está vinculado a um seller, ou o cadastro do seller ainda está em análise (vendor_pending_review).{"error":"no vendor account associated with this user"}
O fornecedor é criado na importação

Se o CNPJ do emitente não existe entre os seus fornecedores, a importação cria um com os dados da nota.

Casamento automático

Cada linha é casada primeiro pelo código de barras (ean igual ao barcode do produto), depois pelo supplier_code igual ao SKU, só com produtos ativos do seller e só quando o resultado é único.

Veja também

  • Conferir, vincular e lançar
  • Fornecedores
Anterior
Cotações: ofertas e conversão
Próxima
NF-e de entrada: conferir e lançar
Nesta página
  • Listar notas de entrada
  • Exemplo de requisição: Listar notas de entrada
  • Resposta: Listar notas de entrada
  • Erros: Listar notas de entrada
  • Consultar nota de entrada
  • Exemplo de requisição: Consultar nota de entrada
  • Resposta: Consultar nota de entrada
  • Erros: Consultar nota de entrada
  • Importar XML
  • Exemplo de requisição: Importar XML
  • Resposta: Importar XML
  • Erros: Importar XML
  • Veja também