> ## Documentation Index
> Fetch the complete documentation index at: https://muveya.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Histórico de custódia
> Acompanhe as caixas, os movimentos de estoque e os registros de entrega, recebimento e encerramento de um pedido, e leia o mesmo histórico pela API.
O detalhe de custódia conta toda a história da entrega de um pedido: quais caixas foram reservadas, quem as retirou e despachou, quem confirmou a entrega, o que o destino aceitou ou contestou e quem encerrou o pedido. Use-o para acompanhar uma entrega no dia a dia e para responder a perguntas de auditoria ou contestações depois.
## Quem pode ver
* Permissão `fulfillment.read` (**Ver atendimento**).
* A unidade do pedido no seu **Acesso às unidades**.
Sem a permissão, a tela diz "Você não pode ver entregas. Peça a permissão ao administrador da sua clínica." Um pedido fora das suas unidades, ou que ainda não tem registro de custódia, responde "Esta entrega não existe ou você não pode vê-la."
## Onde
* Em **Entregas**, abra **A encerrar** ou **Problemas de entrega** e selecione o número do pedido.
* Na página do pedido, **Acompanhar a entrega** (aparece para quem tem alguma permissão de custódia). Veja [Criar e acompanhar pedidos](/docs/pt/orders/create-and-track).
* Depois de confirmar um recebimento, o link abaixo da mensagem de confirmação.
* Na tela de preparação de um pedido que não está mais sendo preparado, o link **Acompanhamento do pedido #1042**.
* Caminho direto: `console.muveya.com/fulfillment/:orderId`.
## O que a tela mostra
A tela se chama **Acompanhamento do pedido #1042**, com **Voltar às entregas** para retornar à lista.
### Dados e próxima etapa
| Dado | O que mostra |
| - | - |
| **Status** | O status de custódia, por exemplo **Despachado**. Veja a [tabela de status](/docs/pt/deliveries/overview#etapas-da-entrega). |
| **Clínica** | A unidade do pedido. |
| **Entregar em** | O depósito de destino. |
Abaixo dos dados, a tela oferece a próxima etapa quando ela cabe a você:
| Status | Link ou painel | Aparece para quem tem |
| - | - | - |
| **Estoque reservado**, **Em preparação** | **Preparar o pedido** | `fulfillment.pick` |
| **Despachado** | **Confirmar a entrega** | `delivery.confirm` |
| **Entregue** | **Receber o pedido** | `receipt.confirm` |
| **Recebido**, **Recebido em parte** | "Tudo foi recebido ou devolvido. Encerre o pedido para concluí-lo." com **Encerrar pedido** | `fulfillment.close` |
| **Problema de entrega** | "A resolução está pendente com o dono da clínica. Por enquanto não há mais nada a fazer aqui." | Todos que podem ver a página |
Para encerrar, veja [Encerrar o pedido](/docs/pt/deliveries/delivery-and-receipt#encerrar-o-pedido).
### Caixas
**Caixas** lista cada caixa atribuída ao pedido. No celular, cada caixa aparece como um cartão com rótulos.
| Coluna | O que mostra |
| - | - |
| **Código da caixa** | O código impresso na etiqueta. |
| **Situação da caixa** | A situação atual da caixa (veja abaixo). |
| **Insumo** | O nome e o SKU do insumo. |
| **Quantidade** | A quantidade que a caixa leva para este pedido. |
| **Lote** | O número do lote, quando a caixa tem um. |
| **Vence** | A data de validade, quando a caixa tem uma. |
| Situação da caixa | O que significa na custódia |
| - | - |
| **Ativa** | Reservada ou retirada e ainda no depósito de origem, ou aceita no destino, ou devolvida sem quarentena. |
| **Em trânsito** | Despachada e ainda não recebida nem devolvida. |
| **Em quarentena** | Devolvida por uma contestação com quarentena, ou colocada em quarentena por outro motivo (por exemplo um [recolhimento de lote](/docs/pt/inventory/lot-recall)). |
| **Vencida**, **Esgotada**, **Descartada** | A caixa mudou depois, fora desta entrega. |
Quando uma caixa foi dividida na preparação, a lista mostra o novo recipiente, não a caixa original. Se nenhuma caixa estiver atribuída, a tela diz "Não há caixas atribuídas a este pedido."
### Histórico
**Histórico** lista o que aconteceu, uma entrada por evento, cada uma com a pessoa e a data e hora no formato do seu navegador. As pessoas aparecem com o nome que têm na equipe; quem está com a sessão aberta aparece como **Você**, as ações que o muveya fez sozinho como **Muveya (automático)**, e quem saiu da equipe como **Ex-integrante da equipe**.
Primeiro vêm os **movimentos de estoque**, do mais antigo ao mais recente. Cada um se lê "movimento · código da caixa · mudança de quantidade", por exemplo "Despachado · BX-000123 · -10". Os movimentos que não mudam a quantidade disponível omitem o número, por exemplo "Retirado para o pedido · BX-000123".
| Movimento | Código | Quando aparece | Mudança de quantidade |
| - | - | - | - |
| **Reservado** | `reserve` | A reserva automática, ou uma reserva que passou para um recipiente dividido. | Nenhuma (a quantidade reservada da caixa aumenta) |
| **Liberado** | `release` | Uma reserva que saiu da caixa original durante uma divisão. | Nenhuma |
| **Separação (saída)** | `split_out` | A quantidade do pedido saiu da caixa original. | Negativa |
| **Separação (entrada)** | `split_in` | A quantidade do pedido entrou no novo recipiente. | Positiva |
| **Retirado para o pedido** | `pick` | Uma caixa foi escaneada para o pedido. | Nenhuma |
| **Despachado** | `dispatch` | A caixa saiu do depósito de origem. | Negativa |
| **Recebido** | `receive` | O destino aceitou a caixa. | Positiva, no destino |
| **Devolvido** | `return` | O destino contestou a caixa e ela voltou à origem. | Positiva, na origem |
Depois dos movimentos vêm os **registros de custódia**:
| Registro | Como aparece |
| - | - |
| Entrega | "Entrega registrada · Ana Torres", ou "Problema de entrega informado · Ana Torres: Chegou danificado" seguido dos detalhes que foram digitados. |
| Recebimento | "Recebimento registrado · Luis Prado", depois "Aceitas: BX-000123, BX-000124" e, em vermelho, uma linha para cada caixa contestada, como "Contestada BX-000125: Danificada". |
| Encerramento | "Pedido encerrado · Luis Prado". |
Se nada aconteceu ainda, a seção diz "Ainda não aconteceu nada."
Os movimentos feitos na caixa original de uma divisão mostram **Caixa que não está mais no registro** no lugar do código, porque a lista **Caixas** só nomeia o novo recipiente. Abra a página da caixa original para ver o histórico dela (veja [Caixas e etiquetas](/docs/pt/inventory/boxes)).
## Usar em auditorias e contestações
| Pergunta | Onde olhar |
| - | - |
| Quais caixas, lotes e validades foram para este destino? | **Caixas**: **Código da caixa**, **Lote**, **Vence**. |
| Quem retirou cada caixa, e quando? | Movimentos **Retirado para o pedido**. |
| Quem despachou, e quando as caixas saíram? | Movimentos **Despachado**. |
| Quem confirmou a entrega, e houve algum problema? | O registro de entrega. |
| O que o destino aceitou ou contestou, e por quê? | O registro de recebimento e, depois, os movimentos **Devolvido**. |
| Onde está agora uma caixa contestada? | **Situação da caixa** (**Em quarentena** ou **Ativa**) e, depois, a página da caixa (veja [Caixas e etiquetas](/docs/pt/inventory/boxes)). |
| Quem encerrou o pedido? | O registro de encerramento. |
Uma revisão típica de contestação:
Verifique se quem retirou, quem despachou e quem confirmou a entrega são as pessoas esperadas da parte de origem, e se o recebimento foi feito pela parte de destino.
Cada caixa da entrega deve aparecer uma vez no recebimento, como aceita ou contestada.
Encontre o movimento **Devolvido** e a **Situação da caixa** atual. Se ela voltou em quarentena, decida o que fazer com ela na página da caixa.
Se o problema pode afetar um lote inteiro, continue em [Recolhimento de lote](/docs/pt/inventory/lot-recall).
### O que a tela não mostra
* O texto de **Evidência do problema** digitado no recebimento. Ele é gravado, mas por enquanto não aparece no console nem é devolvido pela API.
* As observações por caixa de uma contestação e a escolha de quarentena. A API devolve as duas.
* A referência da transportadora digitada no despacho. `GET /v1/fulfillments` a devolve como `carrierRef`.
* O registro de auditoria. Por enquanto não há uma tela de auditoria no console.
* Uma exportação. Para guardar os históricos de custódia fora do muveya, leia-os pela API.
Os registros só aceitam novos lançamentos: nada neste histórico pode ser editado ou apagado. Uma caixa contestada é corrigida por um novo movimento **Devolvido**, nunca alterando o **Despachado**.
## Ler pela API
A operação `GET /v1/fulfillments/{orderId}` devolve o mesmo histórico de custódia para integrações e relatórios.
* **Autenticação:** uma chave de API (`mvy_test_...`) no cabeçalho `Authorization: Bearer`. Por enquanto as chaves de API não são criadas pelo console; veja [Autenticação](/docs/pt/api-reference/authentication).
* **Escopo:** `fulfillment:read`. Veja [Escopos](/docs/pt/api-reference/scopes).
* **Alcance:** toda a conta de clínica odontológica da chave. Uma chave não tem filtro por unidade.
* **Somente leitura:** as etapas de custódia (preparar, despachar, entregar, receber, encerrar) não podem ser feitas pela API nem pelo MCP.
```bash curl theme={null}
curl https://api.muveya.com/v1/fulfillments/66f0c1a2b3c4d5e6f7a8b9c0 \
-H "Authorization: Bearer $MUVEYA_API_KEY"
```
### Resposta
O id do pedido.
O status de custódia: `allocating`, `allocated`, `picking`, `dispatched`, `delivered`, `exception`, `received`, `partially_fulfilled` ou `closed`.
Os movimentos de estoque do pedido, do mais antigo ao mais recente. Cada um tem `movementId`, `type`, `boxId`, `catalogItemId`, `quantityDelta`, `actorId`, `occurredAt` e `recordedAt` e, quando se aplicam, `reservedDelta`, `fromWarehouseId`, `toWarehouseId`, `reasonCode`, `secondActorId`, `idempotencyKey` e `correlationId`.
Presente depois que a entrega foi confirmada: `actorUserId`, `deliveredAt`, `boxIds` e, para um problema de entrega, `exception` com `reason` e `note` opcional.
Presente depois que o recebimento foi confirmado: `actorUserId`, `receivedAt`, `acceptedBoxIds` e `disputed`, uma lista com `boxId`, `reason`, `quarantine` e `note` opcional.
Presente depois que o pedido foi encerrado: `actorUserId` e `closedAt`.
```json Exemplo de resposta theme={null}
{
"orderId": "66f0c1a2b3c4d5e6f7a8b9c0",
"status": "partially_fulfilled",
"movements": [
{
"movementId": "66f0c3000000000000000001",
"type": "reserve",
"boxId": "66e9a1000000000000000125",
"catalogItemId": "66e1b2000000000000000045",
"quantityDelta": 0,
"reservedDelta": 10,
"fromWarehouseId": "66e0f0000000000000000007",
"actorId": "system:fulfillment",
"occurredAt": "2026-09-14T13:02:11.000Z",
"recordedAt": "2026-09-14T13:02:11.000Z"
},
{
"movementId": "66f0c3000000000000000002",
"type": "dispatch",
"boxId": "66e9a1000000000000000125",
"catalogItemId": "66e1b2000000000000000045",
"quantityDelta": -10,
"reservedDelta": -10,
"fromWarehouseId": "66e0f0000000000000000007",
"actorId": "66d7e4000000000000000031",
"occurredAt": "2026-09-14T15:40:02.000Z",
"recordedAt": "2026-09-14T15:40:02.000Z"
},
{
"movementId": "66f0c3000000000000000003",
"type": "return",
"boxId": "66e9a1000000000000000125",
"catalogItemId": "66e1b2000000000000000045",
"quantityDelta": 10,
"reservedDelta": 0,
"reasonCode": "damaged",
"actorId": "66d7e4000000000000000058",
"occurredAt": "2026-09-15T09:12:44.000Z",
"recordedAt": "2026-09-15T09:12:44.000Z"
}
],
"delivery": {
"actorUserId": "66d7e4000000000000000031",
"deliveredAt": "2026-09-15T08:55:10.000Z",
"boxIds": ["66e9a1000000000000000125"]
},
"receipt": {
"actorUserId": "66d7e4000000000000000058",
"receivedAt": "2026-09-15T09:12:44.000Z",
"acceptedBoxIds": [],
"disputed": [
{
"boxId": "66e9a1000000000000000125",
"reason": "damaged",
"quarantine": true,
"note": "Lacre rompido na chegada"
}
]
}
}
```
Como a API difere da tela:
* Ela devolve ids, não nomes nem códigos de caixa. Leia o código e a situação de uma caixa com `GET /v1/inventory/boxes/{boxId}` (escopo `inventory:read`), e um insumo com `GET /v1/catalog/items/{itemId}` (escopo `catalog:read`).
* `actorId` e `actorUserId` são ids de integrantes. As ações que o muveya fez sozinho trazem `system:fulfillment`.
* O status `allocating` pode aparecer por um instante enquanto a reserva roda; o console o mostra como **Reservando estoque**.
* Ela responde `404` quando o pedido não existe, pertence a outra conta de clínica odontológica ou ainda não tem registro de custódia (um pedido aprovado cujo estoque não foi reservado).
* Outras respostas: `401` para chave ausente ou inválida, `403` quando a chave não tem `fulfillment:read`, `429` quando a chave passa do limite de uso. Veja [Erros](/docs/pt/api-reference/errors) e [Limites de uso](/docs/pt/api-reference/rate-limits).
Para listar registros de custódia, use `GET /v1/fulfillments` com o filtro opcional `status`, `limit` (de 1 a 200, padrão 50) e `cursor`. Cada item tem `orderId`, `status`, `createdAt`, `updatedAt` e, quando se aplicam, `sourceWarehouseId`, `dispatchedAt` e `carrierRef`. Veja [Paginação](/docs/pt/api-reference/pagination).
A ferramenta MCP `fulfillment.get_pick_list` precisa da permissão `fulfillment.pick`, que os escopos OAuth atuais de somente leitura não concedem, então por enquanto ela é recusada no endpoint `/mcp`. Veja [Ferramentas MCP](/docs/pt/mcp/tools).
## Páginas relacionadas
Etapas da custódia, permissões e partes.
Como os registros de entrega, recebimento e encerramento são criados.
O histórico completo de uma caixa.
Qual escopo cada leitura precisa.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.