Capacidade de pedido

• Nome do recurso: br.dev.bcp.shopping.order

Visão geral

Os pedidos representam transações confirmadas resultantes de uma finalização de compra bem-sucedida submissão. Eles fornecem um registro completo do que foi comprado, como será entregue e o que aconteceu desde a colocação do pedido.

Conceitos-chave

Os pedidos têm três componentes principais:

Itens de linha — o que foi comprado na finalização da compra:

• Inclui contagens de quantidade atuais (total, cumprido)
• Pode alterar pós-pedido (ex.: edições de pedidos, trocas); DEVE incluir todos itens de linha que já existiram no pedido, independentemente de edições ou alterações

Atendimento — como os itens são entregues:

• Expectativas — promessas voltadas para o comprador sobre quando/como os itens chegarão
• Eventos (registro somente anexado) — o que realmente aconteceu (por exemplo, 👕 foi enviado)

Ajustes — eventos pós-pedido independentes do atendimento:

• Normalmente movimentos de dinheiro (reembolsos, devoluções, créditos, disputas, cancelamentos) *Pode ser qualquer alteração pós-pedido
• Pode acontecer antes, durante ou depois do cumprimento
• As empresas DEVERÃO acrescentar novas entradas em vez de alterar as existentes; O livro razão somente anexado é o preferido. Empresas que não mantêm reajuste histórico PODE realizar atualizações locais de entradas existentes (por exemplo, um único ajuste return pode fazer a transição de pending para completed)

Modelo de dados

Itens de linha

Os itens de linha refletem o que foi comprado na finalização da compra e seu estado atual:

• Detalhes do item (produto, preço, quantidade encomendada)
• Contagens de quantidade e status de cumprimento

Cumprimento

O atendimento rastreia como os itens são entregues ao comprador.

Expectativas

Expectativas são agrupamentos de itens voltados para o comprador (por exemplo, "pacote 📦"). Eles representam:

• Quais itens estão agrupados Para onde eles estão indo (destination) Como estão sendo entregues (method_type)
• Quando chegarão (description, fulfillable_on)

As expectativas podem ser divididas, mescladas ou ajustadas após o pedido. Por exemplo:

• Agrupe tudo por data de entrega: "o que vem quando"
• Use uma única expectativa com um amplo intervalo de datas para flexibilidade
• O objetivo é definir as expectativas do comprador – para obter a melhor experiência do comprador

Eventos de Cumprimento

Eventos de atendimento são um registro apenas anexado que rastreia remessas físicas:

• Itens de linha de referência por ID e quantidade
• Incluir informações de rastreamento
• O tipo é um campo de string aberto – as empresas podem usar qualquer valor que faça sentido (exemplos comuns: processing, shipped, in_transit, delivered, failed_attempt, canceled, undeliverable, returned_to_sender)

Atribuição

As empresas PODEM exibir um instantâneo do checkout de origem attribution no pedido. Somente leitura no pedido – os agentes não escrevem order.attribution. Consulte Atribuição para contrato subjacente.

Ajustes

Ajustes são eventos pós-pedido que existem independentemente de cumprimento:

• O tipo é um campo de string aberto – as empresas podem usar qualquer valor que faça sentido (normalmente movimentos de dinheiro como refund, return, credit, price_adjustment, dispute, cancellation) *Pode ser qualquer alteração pós-pedido
• Opcionalmente, vincule a itens de linha (ou ao nível do pedido para itens como reembolsos de frete)
• Quantidades e valores são assinados – negativo para reduções (devoluções, reembolsos), positivo para adições (trocas)
• Incluir detalhamento dos totais quando relevante
• Pode acontecer a qualquer momento, independentemente do status de cumprimento

Esquema

Pedido

Name	Type	Required	Description
ucp	any	Yes	UCP metadata for order responses. No payment handlers needed post-purchase.
id	string	Yes	Unique order identifier.
label	string	No	Human-readable label for identifying the order. MUST only be provided by the business.
checkout_id	string	Yes	Associated checkout ID for reconciliation.
permalink_url	string	Yes	Permalink to access the order on merchant site.
line_items	Array[Order Line Item]	Yes	Line items representing what was purchased — can change post-order via edits or exchanges.
fulfillment	object	Yes	Fulfillment data: buyer expectations and what actually happened.
adjustments	Array[Adjustment]	No	Post-order events (refunds, returns, credits, disputes, cancellations, etc.) that exist independently of fulfillment.
currency	string	Yes	ISO 4217 currency code. MUST match the currency from the originating checkout session.
totals	Totals	Yes	Different totals for the order.
messages	Array[Message]	No	Business outcome messages (errors, warnings, informational). Present when the business needs to communicate status or issues to the platform.
attribution	Attribution	No	Snapshot of the attribution associated with the originating checkout. Read-only on the order.

Item de linha do pedido

Os itens de linha refletem o que foi comprado na finalização da compra e seu estado atual.

Name	Type	Required	Description
id	string	Yes	Line item identifier.
item	Item	Yes	Product data (id, title, price, image_url).
quantity	object	Yes	Quantity tracking for the line item.
totals	Array[Total]	Yes	Line item totals breakdown.
status	string	Yes	Derived status: removed if quantity.total == 0, fulfilled if quantity.total > 0 and quantity.fulfilled == quantity.total, partial if quantity.total > 0 and quantity.fulfilled > 0, otherwise processing. Enum: processing, partial, fulfilled, removed
parent_id	string	No	Parent line item identifier for any nested structures.

Estrutura quantitativa:json { "original": 3, // Quantity from the original checkout "total": 3, // Current total (may differ after edits/exchanges) "fulfilled": 2 // What has been fulfilled }Derivação de status:text if (total == 0) → "removed" else if (fulfilled == total) → "fulfilled" else if (fulfilled > 0) → "partial" else → "processing"### Expectativa

As expectativas são agrupamentos voltados para o comprador que representam quando/como os itens serão entregue. Eles representam a promessa atual ao comprador e podem ser pós-ordem dividida, mesclada ou ajustada.

Name	Type	Required	Description
id	string	Yes	Expectation identifier.
line_items	Array[object]	Yes	Which line items and quantities are in this expectation.
method_type	string	Yes	Delivery method type (shipping, pickup, digital). Enum: shipping, pickup, digital
destination	Postal Address	Yes	Delivery destination address.
description	string	No	Human-readable delivery description (e.g., 'Arrives in 5-8 business days').
fulfillable_on	string	No	When this expectation can be fulfilled: 'now' or ISO 8601 timestamp for future date (backorder, pre-order).

Evento de Cumprimento

Os eventos são registros somente anexados que rastreiam remessas reais. O campo type é uma cadeia aberta - as empresas podem usar quaisquer valores que façam sentido para seus processo de cumprimento.

Name	Type	Required	Description
id	string	Yes	Fulfillment event identifier.
occurred_at	string	Yes	RFC 3339 timestamp when this fulfillment event occurred.
type	string	Yes	Fulfillment event type. Common values include: processing (preparing to ship), shipped (handed to carrier), in_transit (in delivery network), delivered (received by buyer), failed_attempt (delivery attempt failed), canceled (fulfillment canceled), undeliverable (cannot be delivered), returned_to_sender (returned to merchant).
line_items	Array[object]	Yes	Which line items and quantities are fulfilled in this event.
tracking_number	string	No	Carrier tracking number (required if type != processing).
tracking_url	string	No	URL to track this shipment (required if type != processing).
carrier	string	No	Carrier name (e.g., 'FedEx', 'USPS').
description	string	No	Human-readable description of the shipment status or delivery information (e.g., 'Delivered to front door', 'Out for delivery').

Exemplos: processing, shipped, in_transit, delivered, failed_attempt, canceled, undeliverable, returned_to_sender, etc.

Ajuste

Os ajustes são eventos polimórficos que existem independentemente da realização. O campo type é uma string aberta - as empresas podem usar qualquer valor que faça sentido para eles.

Name	Type	Required	Description
id	string	Yes	Adjustment event identifier.
type	string	Yes	Type of adjustment (open string). Typically money-related like: refund, return, credit, price_adjustment, dispute, cancellation. Can be any value that makes sense for the merchant's business.
occurred_at	string	Yes	RFC 3339 timestamp when this adjustment occurred.
status	string	Yes	Adjustment status. Enum: pending, completed, failed
line_items	Array[object]	No	Which line items and quantities are affected (optional).
totals	Array[Total]	No	Adjustment totals breakdown. Signed values - negative for money returned to buyer (refunds, credits), positive for additional charges (exchanges).
description	string	No	Human-readable reason or description (e.g., 'Defective item', 'Customer requested').

Exemplos: refund, return, credit, price_adjustment, dispute, cancellation, etc.

Exemplo```json

{ "ucp": { "version": "2026-07-14", "capabilities": { "br.dev.bcp.shopping.order": [{"version": "2026-07-14"}] } }, "id": "order_abc123", "checkout_id": "checkout_xyz789", "permalink_url": "https://business.example.com/orders/abc123", "currency": "USD", "line_items": [ { "id": "li_shoes", "item": { "id": "prod_shoes", "title": "Running Shoes", "price": 3000 }, "quantity": { "original": 3, "total": 3, "fulfilled": 3 }, "totals": [ {"type": "subtotal", "amount": 9000}, {"type": "total", "amount": 9000} ], "status": "fulfilled" }, { "id": "li_shirts", "item": { "id": "prod_shirts", "title": "Cotton T-Shirt", "price": 2000 }, "quantity": { "original": 2, "total": 2, "fulfilled": 0 }, "totals": [ {"type": "subtotal", "amount": 4000}, {"type": "total", "amount": 4000} ], "status": "processing" } ], "fulfillment": { "expectations": [ { "id": "exp_1", "line_items": [{ "id": "li_shoes", "quantity": 3 }], "method_type": "shipping", "destination": { "street_address": "123 Main St", "address_locality": "Austin", "address_region": "TX", "address_country": "US", "postal_code": "78701" }, "description": "Arrives in 2-3 business days", "fulfillable_on": "now" }, { "id": "exp_2", "line_items": [{ "id": "li_shirts", "quantity": 2 }], "method_type": "shipping", "destination": { "street_address": "123 Main St", "address_locality": "Austin", "address_region": "TX", "address_country": "US", "postal_code": "78701" }, "description": "Backordered - ships Jan 15, arrives in 7-10 days", "fulfillable_on": "2025-01-15T00:00:00Z" } ], "events": [ { "id": "evt_1", "occurred_at": "2025-01-08T10:30:00Z", "type": "delivered", "line_items": [{ "id": "li_shoes", "quantity": 3 }], "tracking_number": "123456789", "tracking_url": "https://fedex.com/track/123456789", "description": "Delivered to front door" } ] }, "adjustments": [ { "id": "adj_1", "type": "refund", "occurred_at": "2025-01-10T14:30:00Z", "status": "completed", "line_items": [{ "id": "li_shoes", "quantity": -1 }], "totals": [ { "type": "total", "amount": -3000 } ], "description": "Defective item" } ], "totals": [ { "type": "subtotal", "amount": 13000 }, { "type": "fulfillment", "amount": 1200 }, { "type": "tax", "amount": 1142 }, { "type": "total", "amount": 15342 } ] } ```## Escopos

O recurso Order define os seguintes escopos conhecidos para acesso autenticado pelo usuário:

Escopo	Descrição
br.dev.bcp.shopping.order:read	Acesso de leitura aos pedidos do usuário — Obtenha pedidos nos recursos pertencentes ao usuário autenticado.
br.dev.bcp.shopping.order:manage	Operações pós-compra nos pedidos do usuário — cancelamento, devoluções e outras modificações.

Declaração de escopo, derivação e regras para estender este conjunto com escopos personalizados são definidos em Vinculação de identidade — Escopos.

Operações

A entidade do pedido é um instantâneo do estado atual: o mais recente estado do pedido no momento da recuperação ou entrega. As empresas DEVEM retornar a entidade completa do pedido em cada resposta. O mesmo esquema é usado para recuperação síncrona (esta seção) e evento assíncrono entrega (veja Eventos).

O permalink_url é a referência oficial para o pedido completo experiência - cronograma, operações pós-compra, devoluções. A API fornece acesso programático ao estado atual para uso conversacional e operacional casos.

Operação	Método	Ponto final	Descrição
Obter pedido	GET	/orders/{id}	A plataforma recupera o estado atual do pedido.

Para obter detalhes específicos do transporte, consulte Ligação REST (não incluída nesta versão do BCP) e Encadernação MCP

Obter pedido

Retorna o instantâneo do estado atual de um pedido.

Autorização

A empresa DEVE autenticar as solicitações de dados do pedido antes de retornar um resposta, usando qualquer mecanismo BCP compatível - chaves de API, OAuth 2.0, mútuo TLS ou assinaturas de mensagens HTTP (consulte Identidade e Autenticação (não incluídas nesta versão do BCP)). O O método de autenticação determina quais pedidos são acessíveis ao chamador:

Autenticação	Pedidos acessíveis
Credenciais da plataforma	Pedidos originados pela plataforma
Autorização do comprador	Pedidos de propriedade do comprador, sujeitos aos escopos OAuth concedidos

Credenciais da plataforma (chave de API, assinaturas, credenciais do cliente OAuth) - as empresas PODEM permitir o acesso para pedidos originados pela plataforma. O plataforma forneceu informações do comprador e de pagamento durante o fluxo de checkout, observou a confirmação do pedido e está recuperando o estado mais recente de um pedido para o qual já tem contexto.

Autorização do comprador - a plataforma obtém autorização do comprador via Identity Linking com os escopos necessários, ou um mecanismo semelhante. Isso concede acesso aos pedidos do comprador, independentemente de qual plataforma os originou.

As empresas PODEM definir políticas de acesso adicionais (por exemplo, parceiro confiável acordos), impor restrições de disponibilidade de dados (por exemplo, retenção janelas, eliminação regulatória) e omitir ou redigir campos opcionais da resposta com base no contexto, política comercial ou outros requisitos - independentemente de autorização.

Respostas de erro

Quando a empresa não consegue devolver um pedido, a resposta retorna um erro que inclui uma matriz messages descrevendo o resultado:

Pedido não encontrado:json { "ucp": { "version": "2026-07-14", "status": "error", "capabilities": { "br.dev.bcp.shopping.order": [{"version": "2026-07-14"}] } }, "messages": [ { "type": "error", "code": "not_found", "severity": "unrecoverable", "content": "Order not found." } ] }Não autorizado:json { "ucp": { "version": "2026-07-14", "status": "error", "capabilities": { "br.dev.bcp.shopping.order": [{"version": "2026-07-14"}] } }, "messages": [ { "type": "error", "code": "unauthorized", "severity": "unrecoverable", "content": "Not authorized to access this order." } ] }### Diretrizes {: #diretrizes de operações }

Plataforma:

• DEVE incluir o cabeçalho BCP-Agent com URL do perfil em todas as solicitações
• DEVERIA contar com webhooks (consulte Eventos) como canal principal de atualização de pedidos e use Get Order para reconciliação ou recuperação sob demanda
• DEVE tratar os dados do pedido como efêmeros e descartá-los quando não forem mais necessários para fluxos de comércio ativos

Negócios:

• DEVE autenticar solicitações para solicitar dados antes de retornar uma resposta (veja Autorização)

Eventos

As empresas enviam atualizações do ciclo de vida dos pedidos para a plataforma por meio de webhooks. O a carga útil é o mesmo instantâneo do estado atual descrito em Operações — a entidade completa do pedido.

Evento	Método	Ponto final	Descrição
Webhook de evento de pedido	POST	URL fornecido pela plataforma	A empresa envia eventos do ciclo de vida do pedido para a plataforma.

Webhook de evento de pedido

As empresas POST solicitam eventos em um URL de webhook fornecido pela plataforma durante a integração do parceiro. O formato da URL é específico da plataforma.

Os cabeçalhos seguem Webhooks padrão; exceto para assinatura de solicitação, que segue RFC 9421. Consulte Assinaturas de mensagens para obter mais detalhes.

Cabeçalhos obrigatórios:

Cabeçalho	Descrição
Webhook-Timestamp	Carimbo de data e hora da ocorrência do evento (unix)
Webhook-Id	Identificador único do evento

A descrição do serviço OpenAPI para webhooks de pedidos não está publicada neste BCP lançamento. O corpo do webhook usa o envelope de resposta do pedido e a mesma assinatura requisitos descritos nesta seção.

Configuração de URL do webhook

A plataforma fornece seu URL de webhook no campo config do recurso de pedido durante a negociação de capacidade. A empresa descobre esse URL no perfil da plataforma e o utiliza para enviar eventos do ciclo de vida do pedido.

Platform's order capability configuration.

Name	Type	Required	Description
webhook_url	string	Yes	URL where merchant sends order lifecycle events (webhooks).

Exemplo:json { "br.dev.bcp.shopping.order": [ { "version": "2026-07-14", "spec": "https://bcp.dev.br/2026-07-14/specification/order", "schema": "https://bcp.dev.br/2026-07-14/schemas/shopping/order.json", "config": { "webhook_url": "https://platform.example.com/webhooks/ucp/orders" } } ] }### Verificação de assinatura de webhook

As cargas úteis do webhook DEVEM ser assinadas pela empresa e verificadas pela plataforma para garantir autenticidade e integridade. As assinaturas seguem o Especificação Message Signatures usando a ligação REST (RFC 9421).

Cabeçalhos obrigatórios:

Cabeçalho	Descrição
BCP-Agent	URL do perfil comercial (Dicionário RFC 8941)
Signature-Input	Descreve componentes assinados
Signature	Contém o valor da assinatura
Content-Digest	Resumo corporal (RFC 9530)

Exemplo de solicitação de webhook:```http POST /webhooks/ucp/orders HTTP/1.1 Host: platform.example.com Content-Type: application/json BCP-Agent: profile="https://merchant.example/.well-known/ucp" Content-Digest: sha-256=:X48E9q...: Signature-Input: sig1=("@method" "@authority" "@path" "content-digest" "content-type");keyid="merchant-2026" Signature: sig1=:MEUCIQDTxNq8h7LGHpvVZQp1iHkFp9+3N8Mxk2zH1wK4YuVN8w...:

{"id":"order_abc123","event_id":"evt_123","created_time":"2026-01-15T12:00:00Z",...} ```#### Assinatura (Negócios)

1. Calcule o resumo SHA-256 do corpo da solicitação bruta e defina o cabeçalho Content-Digest
2. Construir base de assinatura de acordo com RFC 9421
3. Assine usando uma chave de keys no perfil BCP da empresa
4. Defina os cabeçalhos Signature-Input e Signature

Consulte Assinaturas de mensagens - Assinatura de solicitação REST para algoritmo completo.

Verificação (plataforma)

Autenticação (verificação de assinatura):

1. Analise Signature-Input para extrair keyid e componentes assinados
2. Obtenha o perfil BCP da empresa em /.well-known/ucp (cache conforme apropriado)
3. Localize a chave em keys com kid correspondente
4. Verifique se Content-Digest corresponde a SHA-256 do corpo bruto
5. Reconstrua a base de assinatura e verifique a assinatura

Consulte Assinaturas de mensagens - Verificação de solicitação REST para algoritmo completo.

Autorização (propriedade do pedido):

Depois de verificar a assinatura, a plataforma DEVE confirmar que o signatário está autorizado a enviar eventos para o pedido referenciado:

1. Extraia o ID do pedido da carga útil do webhook
2. Verifique se o pedido foi criado com esta empresa (o URL do perfil corresponde)
3. Rejeite webhooks em que o perfil do signatário não corresponda ao negócio do pedido

Isso evita que uma empresa mal-intencionada envie eventos falsos para outra ordens comerciais, mesmo com uma assinatura válida.

Rotação de teclas

Consulte Assinaturas de mensagens - rotação de teclas para procedimentos de rotação de chaves com tempo de inatividade zero.

Diretrizes

Plataforma:

• DEVE responder rapidamente com um código de status HTTP 2xx para reconhecer o webhook recibo; processar eventos de forma assíncrona após responder

Negócios:

• DEVE incluir o cabeçalho BCP-Agent com URL do perfil para identificação do signatário
• DEVE assinar todas as cargas úteis do webhook de acordo com o Especificação de Assinaturas de mensagens usando cabeçalhos RFC 9421 (Signature, Signature-Input, Content-Digest)
• DEVE enviar o evento "Pedido criado" com a entidade do pedido totalmente preenchida
• DEVE enviar a entidade completa do pedido nas atualizações (não deltas incrementais)
• DEVE tentar novamente entregas de webhook com falha

Entidades

Artigo

Name	Type	Required	Description
id	string	Yes	The product identifier, often the SKU, required to resolve the product details associated with this line item. Should be recognized by both the Platform, and the Business.
title	string	Yes	Product title.
price	Amount	Yes	Unit price in ISO 4217 minor units.
image_url	string	No	Product image URI.

Endereço postal

Name	Type	Required	Description
extended_address	string	No	An address extension such as an apartment number, C/O or alternative name.
street_address	string	No	The street address.
address_locality	string	No	The locality in which the street address is, and which is in the region. For example, Mountain View.
address_region	string	No	The region in which the locality is, and which is in the country. Required for applicable countries (i.e. state in US, province in CA). For example, California or another appropriate first-level Administrative division.
address_country	string	No	The country. Recommended to be in 2-letter ISO 3166-1 alpha-2 format, for example "US". For backward compatibility, a 3-letter ISO 3166-1 alpha-3 country code such as "SGP" or a full country name such as "Singapore" can also be used.
postal_code	string	No	The postal code. For example, 94043.
first_name	string	No	Optional. First name of the contact associated with the address.
last_name	string	No	Optional. Last name of the contact associated with the address.
phone_number	string	No	Optional. Phone number of the contact associated with the address.

Resposta

Capability reference in responses. Only name/version required to confirm active capabilities.

Name	Type	Required	Description
version	string	Yes	Entity version in YYYY-MM-DD format.
spec	string	No	URL to human-readable specification document.
schema	string	No	URL to JSON Schema defining this entity's structure and payloads.
id	string	No	Unique identifier for this entity instance. Used to disambiguate when multiple instances exist.
config	object	No	Entity-specific configuration. Structure defined by each entity's schema.
extends	OneOf[string, array]	No	Parent capability(s) this extends. Present for extensions, absent for root capabilities. Use array for multi-parent extensions.

Total

Name	Type	Required	Description
type	string	Yes	Cost category. Well-known values: subtotal, items_discount, discount, fulfillment, tax, fee, total. Businesses MAY use additional values.
display_text	string	No	Text to display against the amount. Should reflect appropriate method (e.g., 'Shipping', 'Delivery').
amount	Signed Amount	Yes	Monetary amount in the currency's minor unit as defined by ISO 4217. Refer to the currency's exponent to determine minor-to-major ratio (e.g., 2 for USD, 0 for JPY, 3 for KWD). May be negative — the sign is intrinsic to the value (e.g., discounts are negative, charges are positive).

Esquema de pedido de resposta BCP

UCP metadata for order responses. No payment handlers needed post-purchase.

Name	Type	Required	Description
version	string	Yes	UCP version in YYYY-MM-DD format.
status	string	No	Application-level status of the UCP operation. Enum: success, error
services	object	No	Service registry keyed by reverse-domain name.
capabilities	object	No	Capability registry keyed by reverse-domain name.
payment_handlers	object	No	Payment handler registry keyed by reverse-domain name.
capabilities	any	No