Sincronização com ERP

Rotas de retorno do ERP para o pedido, para gravar a nota fiscal, o código do pedido no ERP e a confirmação de importação (orderSAP).

Muitas lojas usam a Venddor como vitrine e um ERP (Protheus, SAP, Bling, Totvs...) para faturar. O fluxo típico é: o ERP lê o pedido novo (Listar pedidos), cria a venda no sistema dele, fatura, e devolve à Venddor o número do pedido no ERP e a nota fiscal. Estas duas rotas são o retorno: elas existem só na API compatível com a Venddor 1.0 (/api/v1.0), com o contrato da Venddor 1.0, porque os conectores de ERP existentes foram escritos assim.

Além destas duas rotas, o ERP também pode gravar observações e rastreio no pedido (Alterar pedido) e mudar o status (Alterar o status). Os campos estruturados de nota fiscal abaixo só existem nestas rotas.

PUT/api/v1.0/extra_order_fields/{order_id}Admin

Gravar os dados da nota fiscal no pedido

Grava, no pedido, os dados que o ERP devolveu depois de faturar. Cada campo enviado e não vazio é guardado como um registro do pedido (visível em order_data, tipo payment). Enviar o mesmo campo de novo cria outro registro; a chamada não é idempotente, então não reenvie sem necessidade. Campos ausentes ou vazios são ignorados.

Se o pedido veio de um marketplace externo (Shopee, TikTok) e o corpo traz a chave da nota e o XML, a nota também é enviada ao marketplace.

Parâmetros de caminho

order_idstringobrigatório

Id do pedido (UUID, ou o decimal da rota /api/extra_order_fields/{order_id}). O número do pedido (PEDIDO-...) não é aceito aqui.

Corpo da requisição

codigo_pedido_erpstring

Código do pedido no ERP.

link_notastring

Link para visualizar a nota fiscal.

chave_notastring

Chave de acesso da NF-e (44 dígitos).

nota_fiscalstring

Número da nota fiscal.

xml_notastring

XML da NF-e (texto ou base64).

pdf_notastring

DANFE em PDF (link ou base64).

base64_xmlstring

XML da NF-e em base64. Para pedido de marketplace, é o campo usado no envio ao canal.

PUT/api/v1.0/orders_ext/{id}Admin

Gravar o número do pedido no ERP (orderSAP)

Registra o número do pedido no ERP (orderSAP) e marca o pedido como importado pelo ERP. Na primeira gravação de um orderSAP para o pedido, o pedido é movido para o status de letra U (importado pelo ERP) do cadastro da loja. Gravações seguintes só atualizam o número, sem mexer no status.

A letra U precisa existir (e estar ativa) no cadastro de status da loja; senão a chamada responde 409 e nada é gravado. Pedido com estorno pendente não aceita a mudança (a resposta é 500).

O orderSAP volta no detalhe do pedido (Consultar pedido).

Parâmetros de caminho

idstringobrigatório

Id do pedido (UUID, ou decimal em /api/orders_ext/{id}).

Corpo da requisição

orderSAPstringobrigatório

Número do pedido no ERP. Não pode ser vazio.

Exemplo de requisição

bash

# 1) Confirmar a importação e gravar o número do pedido no ERP
curl -X PUT "$BASE_URL/api/v1.0/orders_ext/$ORDER_ID" \
  -u "$EMAIL:$API_KEY" -H "Content-Type: application/json" \
  -d '{"orderSAP":"SAP-1001"}'

# 2) Depois de faturar, devolver a nota
curl -X PUT "$BASE_URL/api/v1.0/extra_order_fields/$ORDER_ID" \
  -u "$EMAIL:$API_KEY" -H "Content-Type: application/json" \
  -d '{
    "codigo_pedido_erp": "ERP-8841",
    "nota_fiscal": "123",
    "chave_nota": "35261011222333000181550010000001231000001234",
    "link_nota": "https://erp.exemplo.com.br/nf/123.pdf"
  }'

Resposta

200extra_order_fields: dados gravados

json

{ "order_id": "fdbcc184-7cdc-4cf9-aaf7-5a1f7b6370e2", "fields_saved": 4 }

200orders_ext: orderSAP gravado

json

{ "id": "fdbcc184-7cdc-4cf9-aaf7-5a1f7b6370e2", "success": true }

Campos da resposta

order_idstring

(extra_order_fields) Id do pedido.

fields_savedinteger

(extra_order_fields) Quantos campos não vazios foram gravados.

idstring

(orders_ext) Id do pedido, como foi enviado na URL.

successboolean

(orders_ext) true quando o orderSAP e (na primeira gravação) o status foram gravados.

Erros

Status	Quando	Corpo
400	Corpo que não é JSON	`{"message":"Invalid JSON body","status":400}`
400	(orders_ext) `orderSAP` vazio ou ausente	`{"message":"orderSAP is required","status":400}`
401	Sem credenciais ou chave inválida	`{"message":"Invalid credentials","status":401}`
403	Usuário não administrador	`{"message":"Forbidden: admin scope required","status":403}`
404	Pedido não encontrado (inclusive número de pedido no lugar do id)	`{"message":"Order not found","status":404}` (extra_order_fields) ou `{"message":"order not found","status":404}` (orders_ext)
409	(extra_order_fields) a referência do pedido é ambígua; (orders_ext) a letra `U` não existe no cadastro de status da loja	`{"message":"Order reference is ambiguous","status":409}` ou `{"message":"ERP status U is not configured for this tenant","status":409}`
422	Nota de marketplace inválida (chave ou XML)	`{"message":"Failed to store marketplace invoice: ...","status":422}`
500	Falha interna, ou (orders_ext) pedido com estorno pendente	`{"message":"orderSAP update failed: ...","status":500}`

Veja também

Fatura e NF-e
Alterar pedido

Sincronização com ERP

Rotas de retorno do ERP para o pedido, para gravar a nota fiscal, o código do pedido no ERP e a confirmação de importação (orderSAP).

PUT/api/v1.0/extra_order_fields/{order_id}Admin

Gravar os dados da nota fiscal no pedido

Se o pedido veio de um marketplace externo (Shopee, TikTok) e o corpo traz a chave da nota e o XML, a nota também é enviada ao marketplace.

Parâmetros de caminho

order_idstringobrigatório

Id do pedido (UUID, ou o decimal da rota /api/extra_order_fields/{order_id}). O número do pedido (PEDIDO-...) não é aceito aqui.

Corpo da requisição

codigo_pedido_erpstring

Código do pedido no ERP.

link_notastring

Link para visualizar a nota fiscal.

chave_notastring

Chave de acesso da NF-e (44 dígitos).

nota_fiscalstring

Número da nota fiscal.

xml_notastring

XML da NF-e (texto ou base64).

pdf_notastring

DANFE em PDF (link ou base64).

base64_xmlstring

XML da NF-e em base64. Para pedido de marketplace, é o campo usado no envio ao canal.

PUT/api/v1.0/orders_ext/{id}Admin

Gravar o número do pedido no ERP (orderSAP)

A letra U precisa existir (e estar ativa) no cadastro de status da loja; senão a chamada responde 409 e nada é gravado. Pedido com estorno pendente não aceita a mudança (a resposta é 500).

O orderSAP volta no detalhe do pedido (Consultar pedido).

Parâmetros de caminho

idstringobrigatório

Id do pedido (UUID, ou decimal em /api/orders_ext/{id}).

Corpo da requisição

orderSAPstringobrigatório

Número do pedido no ERP. Não pode ser vazio.

Exemplo de requisição

bash

# 1) Confirmar a importação e gravar o número do pedido no ERP
curl -X PUT "$BASE_URL/api/v1.0/orders_ext/$ORDER_ID" \
  -u "$EMAIL:$API_KEY" -H "Content-Type: application/json" \
  -d '{"orderSAP":"SAP-1001"}'

# 2) Depois de faturar, devolver a nota
curl -X PUT "$BASE_URL/api/v1.0/extra_order_fields/$ORDER_ID" \
  -u "$EMAIL:$API_KEY" -H "Content-Type: application/json" \
  -d '{
    "codigo_pedido_erp": "ERP-8841",
    "nota_fiscal": "123",
    "chave_nota": "35261011222333000181550010000001231000001234",
    "link_nota": "https://erp.exemplo.com.br/nf/123.pdf"
  }'

Resposta

200extra_order_fields: dados gravados

json

{ "order_id": "fdbcc184-7cdc-4cf9-aaf7-5a1f7b6370e2", "fields_saved": 4 }

200orders_ext: orderSAP gravado

json

{ "id": "fdbcc184-7cdc-4cf9-aaf7-5a1f7b6370e2", "success": true }

Campos da resposta

order_idstring

(extra_order_fields) Id do pedido.

fields_savedinteger

(extra_order_fields) Quantos campos não vazios foram gravados.

idstring

(orders_ext) Id do pedido, como foi enviado na URL.

successboolean

(orders_ext) true quando o orderSAP e (na primeira gravação) o status foram gravados.

Erros

Status	Quando	Corpo
400	Corpo que não é JSON	`{"message":"Invalid JSON body","status":400}`
400	(orders_ext) `orderSAP` vazio ou ausente	`{"message":"orderSAP is required","status":400}`
401	Sem credenciais ou chave inválida	`{"message":"Invalid credentials","status":401}`
403	Usuário não administrador	`{"message":"Forbidden: admin scope required","status":403}`
404	Pedido não encontrado (inclusive número de pedido no lugar do id)	`{"message":"Order not found","status":404}` (extra_order_fields) ou `{"message":"order not found","status":404}` (orders_ext)
409	(extra_order_fields) a referência do pedido é ambígua; (orders_ext) a letra `U` não existe no cadastro de status da loja	`{"message":"Order reference is ambiguous","status":409}` ou `{"message":"ERP status U is not configured for this tenant","status":409}`
422	Nota de marketplace inválida (chave ou XML)	`{"message":"Failed to store marketplace invoice: ...","status":422}`
500	Falha interna, ou (orders_ext) pedido com estorno pendente	`{"message":"orderSAP update failed: ...","status":500}`

Veja também

Fatura e NF-e
Alterar pedido