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

NF-e de entrada: conferir e lançar

Compara a nota com o pedido, vincula linhas a produtos e lança a nota no estoque e nas contas a pagar.

Conferir nota

Compara, produto a produto, o que foi pedido com o que veio na nota: quantidade e custo unitário, apontando divergências e itens que só existem de um lado. Sem pedido vinculado devolve linked: false e lines vazio.

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

Compara a nota com o pedido de compra

Parâmetros de caminho

iduuidobrigatório
Id (UUID) da nota.

Exemplo de requisição: Conferir nota

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

Resposta: Conferir nota

200Conferência
json
{
  "invoice_id": "5534915e-925c-45af-888a-4957b6fa54ff",
  "purchase_order_id": "047a8f24-473b-4638-bc0e-2c159c1fcca2",
  "linked": true,
  "has_divergence": true,
  "lines": [
    {
      "product_id": "94e6917e-8733-4ddc-b446-ed85977117e8",
      "product_name": "Camiseta Básica Preta M",
      "ordered_qty": 20,
      "invoice_qty": 18,
      "ordered_cost_cents": 4990,
      "invoice_cost_cents": 4990,
      "qty_diverges": true,
      "cost_diverges": false,
      "only_in_invoice": false,
      "only_in_order": false
    }
  ]
}

Campos da resposta

invoice_iduuid
Nota.
purchase_order_iduuid
Pedido vinculado. Vazio se não há.
linkedboolean
Se há pedido vinculado.
has_divergenceboolean
true se alguma linha diverge.
linesarray

Uma linha por produto.

product_iduuid
Produto.
product_namestring
Nome.
ordered_qtyinteger
Quantidade pedida.
invoice_qtyinteger
Quantidade na nota, já convertida em unidades de estoque.
ordered_cost_centsinteger
Custo unitário do pedido.
invoice_cost_centsinteger
Custo unitário da nota.
qty_divergesboolean
Quantidades diferentes.
cost_divergesboolean
Custos diferentes.
only_in_invoiceboolean
Veio na nota e não estava no pedido.
only_in_orderboolean
Estava no pedido e não veio na nota.

Erros: Conferir nota

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"}

Vincular pedido

Associa a nota a um pedido de compra do seller para a conferência. Mande purchase_order_id vazio para desvincular. Só notas ainda não lançadas podem mudar. A resposta já é a conferência.

PUT/api/v1/vendor/erp/notas-entrada/{id}/purchase-orderSeller

Vincula a nota a um pedido de compra

Parâmetros de caminho

iduuidobrigatório
Id (UUID) da nota.

Corpo da requisição

purchase_order_iduuid
Pedido a vincular. Vazio ou ausente desvincula.

Exemplo de requisição: Vincular pedido

bash
curl -X PUT "$BASE_URL/api/v1/vendor/erp/notas-entrada/3f6c1c1e-8d0b-4a55-9a52-1d6f6a4a7b10/purchase-order" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "purchase_order_id": "047a8f24-473b-4638-bc0e-2c159c1fcca2"
}'

Resposta: Vincular pedido

200Conferência após o vínculo
json
{
  "invoice_id": "5534915e-925c-45af-888a-4957b6fa54ff",
  "purchase_order_id": "047a8f24-473b-4638-bc0e-2c159c1fcca2",
  "linked": true,
  "has_divergence": true,
  "lines": [
    {
      "product_id": "94e6917e-8733-4ddc-b446-ed85977117e8",
      "product_name": "Camiseta Básica Preta M",
      "ordered_qty": 20,
      "invoice_qty": 18,
      "ordered_cost_cents": 4990,
      "invoice_cost_cents": 4990,
      "qty_diverges": true,
      "cost_diverges": false,
      "only_in_invoice": false,
      "only_in_order": false
    }
  ]
}

Campos da resposta

...object
Mesmos campos da rota Conferir nota.

Erros: Vincular pedido

StatusQuandoCorpo
400A nota já foi lançada ou cancelada.{"error":"vendorerp: cannot edit a posted or cancelled invoice"}
400O pedido está cancelado.{"error":"vendorerp: não é possível conferir contra uma OC cancelada"}
404A nota ou o pedido não existe.{"error":"purchase order 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"}

Vincular linha

Liga uma linha da nota a um produto do seller (ou a ignora). É o passo que resolve as linhas unmatched. Quando não resta nenhuma linha sem vínculo, a nota passa de pending_match para matched e pode ser lançada.

PUT/api/v1/vendor/erp/notas-entrada/{id}/items/{itemId}/matchSeller

Vincula uma linha a um produto

Parâmetros de caminho

iduuidobrigatório
Id da nota.
itemIduuidobrigatório
Id da linha (items[].id).

Corpo da requisição

product_iduuid
Produto do seller. Obrigatório, a menos que match_status seja ignored.
variation_iduuid
Variação do produto, se houver.
conversion_factorstring
Fator de conversão como texto decimal (por exemplo 12 quando a nota vem em caixas de 12). Padrão 1.
match_statusstring
ignored
Envie ignored para descartar a linha (ela não entra no estoque).

Exemplo de requisição: Vincular linha

bash
curl -X PUT "$BASE_URL/api/v1/vendor/erp/notas-entrada/3f6c1c1e-8d0b-4a55-9a52-1d6f6a4a7b10/items/8c5e2d3a-41b7-4f0a-9d6e-7a2b1c0d9e11/match" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "product_id": "94e6917e-8733-4ddc-b446-ed85977117e8",
  "conversion_factor": "12"
}'

Resposta: Vincular linha

200Nota atualizada
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: Vincular linha

StatusQuandoCorpo
400Corpo não é um JSON válido.{"error":"invalid request body","detail":"invalid character 'b' looking for beginning of object key string"}
400Sem product_id e sem match_status: ignored.{"error":"vendorerp: product_id required to match"}
400A nota já foi lançada ou cancelada.{"error":"vendorerp: cannot edit a posted or cancelled invoice"}
400A linha não pertence a esta nota.{"error":"vendorerp: item not in this invoice"}
404A nota ou o produto não existe, ou o produto não é do seller.{"error":"product 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"}

Lançar nota

Efetiva a compra: para cada linha não ignorada soma as unidades ao depósito e atualiza o custo médio; e cria uma conta a pagar por parcela (duplicatas) da nota, ou uma única conta no total quando a nota não tem parcelas. Tudo numa transação: se algo falha, nada é lançado. Só funciona uma vez por nota.

POST/api/v1/vendor/erp/notas-entrada/{id}/postSeller

Lança a nota no estoque e no financeiro

Parâmetros de caminho

iduuidobrigatório
Id (UUID) da nota.

Corpo da requisição

warehouse_iduuidobrigatório
Depósito ativo do seller que recebe as unidades.

Exemplo de requisição: Lançar nota

bash
curl -X POST "$BASE_URL/api/v1/vendor/erp/notas-entrada/3f6c1c1e-8d0b-4a55-9a52-1d6f6a4a7b10/post" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "warehouse_id": "8204b8b8-e7e2-4b96-bba8-5a937fe001c8"
}'

Resposta: Lançar nota

200Nota lançada
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": "posted",
    "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"
  },
  "payables": [
    {
      "id": "5f585c3c-68a2-4f88-b76c-e2465ab041d4",
      "description": "NF-e 35261011222333000181550010000487651876543249 dup 001",
      "amount_cents": 52400,
      "due_date": "2026-11-06",
      "status": "open"
    }
  ]
}

Campos da resposta

invoiceobject
A nota, agora posted.
payablesarray
Contas a pagar criadas. Mesmos campos de Contas a pagar.

Erros: Lançar nota

StatusQuandoCorpo
400warehouse_id em branco.{"error":"vendorerp: warehouse_id required to post"}
400A nota já foi lançada.{"error":"vendorerp: invoice already posted"}
400Ainda há linha unmatched (a nota não está matched).{"error":"vendorerp: invoice must be fully matched before posting"}
400Uma linha sem produto vinculado.{"error":"vendorerp: line 2 is not matched"}
400quantity vezes conversion_factor não dá inteiro.{"error":"vendorerp: line 1 quantity does not convert to whole units"}
400O depósito está inativo.{"error":"warehouse is inactive"}
404A nota ou o depósito não existe.{"error":"warehouse 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"}
Receber a OC e lançar a nota somam estoque duas vezes

As duas rotas dão entrada no estoque. Para a mesma compra, use uma delas: receba o pedido ou lance a nota. Vincular a nota ao pedido é só para conferência e não evita a dupla entrada.

Veja também

  • Importar e consultar notas
  • Contas a pagar
Anterior
NF-e de entrada: importar e consultar
Próxima
ERP financeiro do seller
Nesta página
  • Conferir nota
  • Exemplo de requisição: Conferir nota
  • Resposta: Conferir nota
  • Erros: Conferir nota
  • Vincular pedido
  • Exemplo de requisição: Vincular pedido
  • Resposta: Vincular pedido
  • Erros: Vincular pedido
  • Vincular linha
  • Exemplo de requisição: Vincular linha
  • Resposta: Vincular linha
  • Erros: Vincular linha
  • Lançar nota
  • Exemplo de requisição: Lançar nota
  • Resposta: Lançar nota
  • Erros: Lançar nota
  • Veja também