API legada/Referência completa/Pedidos: rotas sem versão e app do seller

Ganchos de ERP sem versão

Grava a nota fiscal, o número do pedido no ERP e o limite de crédito de um cliente pelas rotas extra_order_fields, orders_ext e order_limit.

Um ERP (sistema de gestão da empresa) costuma ser a fonte da verdade da nota fiscal e do crédito dos clientes. Estas rotas servem para ele devolver informação à plataforma depois de processar um pedido: o número que o pedido recebeu no ERP, os dados da nota fiscal e o limite de crédito do cliente. As três exigem um administrador e respondem no formato simples da API 1.0 ({"message","status"} nos erros).

PUT/api/extra_order_fields/{order_id}Admin

Gravar os dados da nota fiscal no pedido, forma sem versão

Cada campo enviado e não vazio vira 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. Campos ausentes ou vazios são ignorados. Se o pedido veio de um marketplace externo (Shopee, TikTok) e o corpo traz a chave e o XML da nota, a nota também é enviada ao marketplace.

Parâmetros de caminho

order_idstringobrigatório

Id do pedido, decimal em string (ou UUID). O número do pedido (PEDIDO-...) não é aceito.

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. Em pedido de marketplace, é o campo usado no envio ao canal.

PUT/api/orders_ext/{id}Admin

Gravar o número do pedido no ERP (orderSAP), forma sem versão

Registra o número do pedido no ERP e marca o pedido como importado. Na primeira gravação de um orderSAP, o pedido passa para o status de letra U (importado pelo ERP) do cadastro da loja; gravações seguintes só atualizam o número. Se a loja não tem o status U ativo, a chamada responde 409 e nada é gravado. Pedido com estorno pendente não aceita a mudança (500).

Parâmetros de caminho

idstringobrigatório

UUID do pedido. Nesta rota o id decimal não é traduzido: um decimal responde 500. Pegue o UUID na forma /api/v1.0/orders.

Corpo da requisição

orderSAPstringobrigatório

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

PUT/api/v1.0/order_limitAdmin

Definir o limite de crédito de um cliente (ids UUID)

Define o limite de crédito (limite de pedido B2B) de um cliente, para um seller ou para a loja toda. O valor substitui o limite anterior e a mudança fica registrada no histórico de limites com origem erp. O limite disponível para novos pedidos é o limite menos o crédito já consumido por pedidos em aberto.

Corpo da requisição

user_idstringobrigatório

Cliente, em UUID. O cliente precisa existir.

vendor_idstring

Seller ao qual o limite se aplica, em UUID. Omitido ou vazio vale para a loja toda (limite do marketplace).

order_limitnumberobrigatório

Limite em reais, como número (1500.5). Não pode ser negativo. É convertido para centavos e a fração além dos centavos é descartada.

PUT/api/order_limitAdmin

Definir o limite de crédito de um cliente, forma sem versão (ids decimais)

Igual a PUT /api/v1.0/order_limit, mas user_id e vendor_id do corpo (e da resposta) são ids decimais.

Corpo da requisição

user_idstringobrigatório

Cliente, id decimal (ou UUID).

vendor_idstring

Seller, id decimal (ou UUID). Vazio vale para a loja toda.

order_limitnumberobrigatório

Limite em reais, como número.

Exemplo de requisição

bash

curl -X PUT "$BASE_URL/api/extra_order_fields/1794666195" \
  -u "$EMAIL:$API_KEY" -H "Content-Type: application/json" \
  -d '{"codigo_pedido_erp":"ERP-8841","nota_fiscal":"123","chave_nota":"35261011222333000181550010000001231000001234"}'

curl -X PUT "$BASE_URL/api/orders_ext/3f73310d-bfdd-4713-a664-305c08eda58b" \
  -u "$EMAIL:$API_KEY" -H "Content-Type: application/json" \
  -d '{"orderSAP":"SAP-1001"}'

curl -X PUT "$BASE_URL/api/order_limit" \
  -u "$EMAIL:$API_KEY" -H "Content-Type: application/json" \
  -d '{"user_id":"642412737","order_limit":1500.5}'

Resposta

200Limite definido

json

{
  "user_id": "642412737",
  "vendor_id": "",
  "order_limit": "1500.50",
  "status": "updated"
}

200Campos da nota gravados

json

{ "order_id": "1794666195", "fields_saved": 3 }

200orderSAP gravado

json

{ "id": "3f73310d-bfdd-4713-a664-305c08eda58b", "success": true }

Campos da resposta

user_idstring

(order_limit) Cliente, no mesmo formato enviado (UUID ou decimal).

vendor_idstring

(order_limit) Seller do limite; vazio quando o limite é da loja toda.

order_limitstring

(order_limit) Limite gravado, em string decimal ("1500.50").

statusstring

(order_limit) Sempre updated.

order_idstring

(extra_order_fields) Id do pedido, no formato enviado.

fields_savedinteger

(extra_order_fields) Quantos campos foram gravados (os ausentes ou vazios não contam).

idstring

(orders_ext) Id do pedido, como foi enviado.

successboolean

(orders_ext) true quando gravou.

Os registros gravados por extra_order_fields ficam no pedido e aparecem em Consultar pedido.

Erros

Status	Quando	Corpo
400	Corpo que não é JSON	`{"message":"Invalid JSON body","status":400}` (em `orders_ext`: `invalid request body`)
400	(`orders_ext`) `orderSAP` vazio ou ausente	`{"message":"orderSAP is required","status":400}`
400	(`order_limit`) sem `user_id`	`{"message":"user_id is required","status":400}`
401	Sem credenciais, chave inválida ou token expirado	`{"message":"Invalid credentials","status":401}`
403	Usuário que 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`) referência de pedido ambígua; (`orders_ext`) a loja não tem o status `U`	`{"message":"Order reference is ambiguous","status":409}` ou `{"message":"ERP status U is not configured for this tenant","status":409}`
409 ou 422	(`extra_order_fields`) a nota de marketplace foi recusada: 422 quando a chave ou o XML são inválidos, 409 nos demais conflitos	`{"message":"Failed to store marketplace invoice: ...","status":422}`
500	(`orders_ext`) `{id}` decimal; pedido com estorno pendente	`{"message":"orderSAP update failed: ...","status":500}`
500	(`order_limit`) cliente inexistente, limite negativo ou falha ao gravar	`{"message":"Failed to set order limit: ...","status":500}`
501	(`order_limit`) a loja não tem o serviço de limites	`{"message":"Order limit service not available","status":501}`

Veja também

Ganchos de ERP sem versão

Grava a nota fiscal, o número do pedido no ERP e o limite de crédito de um cliente pelas rotas extra_order_fields, orders_ext e order_limit.

PUT/api/extra_order_fields/{order_id}Admin

Gravar os dados da nota fiscal no pedido, forma sem versão

Parâmetros de caminho

order_idstringobrigatório

Id do pedido, decimal em string (ou UUID). O número do pedido (PEDIDO-...) não é aceito.

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. Em pedido de marketplace, é o campo usado no envio ao canal.

PUT/api/orders_ext/{id}Admin

Gravar o número do pedido no ERP (orderSAP), forma sem versão

Parâmetros de caminho

idstringobrigatório

UUID do pedido. Nesta rota o id decimal não é traduzido: um decimal responde 500. Pegue o UUID na forma /api/v1.0/orders.

Corpo da requisição

orderSAPstringobrigatório

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

PUT/api/v1.0/order_limitAdmin

Definir o limite de crédito de um cliente (ids UUID)

Corpo da requisição

user_idstringobrigatório

Cliente, em UUID. O cliente precisa existir.

vendor_idstring

Seller ao qual o limite se aplica, em UUID. Omitido ou vazio vale para a loja toda (limite do marketplace).

order_limitnumberobrigatório

Limite em reais, como número (1500.5). Não pode ser negativo. É convertido para centavos e a fração além dos centavos é descartada.

PUT/api/order_limitAdmin

Definir o limite de crédito de um cliente, forma sem versão (ids decimais)

Igual a PUT /api/v1.0/order_limit, mas user_id e vendor_id do corpo (e da resposta) são ids decimais.

Corpo da requisição

user_idstringobrigatório

Cliente, id decimal (ou UUID).

vendor_idstring

Seller, id decimal (ou UUID). Vazio vale para a loja toda.

order_limitnumberobrigatório

Limite em reais, como número.

Exemplo de requisição

bash

curl -X PUT "$BASE_URL/api/extra_order_fields/1794666195" \
  -u "$EMAIL:$API_KEY" -H "Content-Type: application/json" \
  -d '{"codigo_pedido_erp":"ERP-8841","nota_fiscal":"123","chave_nota":"35261011222333000181550010000001231000001234"}'

curl -X PUT "$BASE_URL/api/orders_ext/3f73310d-bfdd-4713-a664-305c08eda58b" \
  -u "$EMAIL:$API_KEY" -H "Content-Type: application/json" \
  -d '{"orderSAP":"SAP-1001"}'

curl -X PUT "$BASE_URL/api/order_limit" \
  -u "$EMAIL:$API_KEY" -H "Content-Type: application/json" \
  -d '{"user_id":"642412737","order_limit":1500.5}'

Resposta

200Limite definido

json

{
  "user_id": "642412737",
  "vendor_id": "",
  "order_limit": "1500.50",
  "status": "updated"
}

200Campos da nota gravados

json

{ "order_id": "1794666195", "fields_saved": 3 }

200orderSAP gravado

json

{ "id": "3f73310d-bfdd-4713-a664-305c08eda58b", "success": true }

Campos da resposta

user_idstring

(order_limit) Cliente, no mesmo formato enviado (UUID ou decimal).

vendor_idstring

(order_limit) Seller do limite; vazio quando o limite é da loja toda.

order_limitstring

(order_limit) Limite gravado, em string decimal ("1500.50").

statusstring

(order_limit) Sempre updated.

order_idstring

(extra_order_fields) Id do pedido, no formato enviado.

fields_savedinteger

(extra_order_fields) Quantos campos foram gravados (os ausentes ou vazios não contam).

idstring

(orders_ext) Id do pedido, como foi enviado.

successboolean

(orders_ext) true quando gravou.

Os registros gravados por extra_order_fields ficam no pedido e aparecem em Consultar pedido.

Erros

Status	Quando	Corpo
400	Corpo que não é JSON	`{"message":"Invalid JSON body","status":400}` (em `orders_ext`: `invalid request body`)
400	(`orders_ext`) `orderSAP` vazio ou ausente	`{"message":"orderSAP is required","status":400}`
400	(`order_limit`) sem `user_id`	`{"message":"user_id is required","status":400}`
401	Sem credenciais, chave inválida ou token expirado	`{"message":"Invalid credentials","status":401}`
403	Usuário que 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`) referência de pedido ambígua; (`orders_ext`) a loja não tem o status `U`	`{"message":"Order reference is ambiguous","status":409}` ou `{"message":"ERP status U is not configured for this tenant","status":409}`
409 ou 422	(`extra_order_fields`) a nota de marketplace foi recusada: 422 quando a chave ou o XML são inválidos, 409 nos demais conflitos	`{"message":"Failed to store marketplace invoice: ...","status":422}`
500	(`orders_ext`) `{id}` decimal; pedido com estorno pendente	`{"message":"orderSAP update failed: ...","status":500}`
500	(`order_limit`) cliente inexistente, limite negativo ou falha ao gravar	`{"message":"Failed to set order limit: ...","status":500}`
501	(`order_limit`) a loja não tem o serviço de limites	`{"message":"Order limit service not available","status":501}`