> ## 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.
# Entregas: visão geral
> Entenda a tela Entregas, as etapas de custódia de um pedido aprovado até um pedido encerrado e quem pode executar cada etapa.
Uma **entrega** é o percurso físico de um pedido aprovado: o muveya reserva caixas de estoque para ele, alguém retira e despacha as caixas do depósito de origem, alguém confirma a entrega, e o destino recebe e encerra o pedido. O muveya registra cada etapa como custódia de caixas inteiras, então você sempre sabe qual caixa saiu de qual depósito, quem a entregou e quem a recebeu.
Na API e no código esse processo se chama `fulfillment`. No console ele fica em **Entregas**.
## Onde encontrar
* **Entregas**, na navegação principal, abre `console.muveya.com/fulfillment`. A opção só aparece para integrantes com pelo menos uma permissão de custódia (veja [Quem pode fazer cada etapa](#quem-pode-fazer-cada-etapa)).
* **Início** mostra os cartões **Pedidos a preparar**, **Entregas a confirmar**, **Pedidos a receber** e **Pedidos a encerrar** quando algo espera por você. Cada cartão abre **Entregas**.
* Na página de um pedido, **Acompanhar a entrega** abre o detalhe de custódia desse pedido. Veja [Criar e acompanhar pedidos](/docs/pt/orders/create-and-track).
O muveya não envia e-mails nem mensagens de WhatsApp quando uma entrega muda de etapa. Consulte **Início** e **Entregas** para ver o que espera por você.
## A tela Entregas
A tela se chama **Entregas** ("Pedidos das suas clínicas a preparar, entregar, receber ou encerrar.") e mostra uma seção para cada etapa de custódia de que você participa. Você só vê as seções que suas permissões permitem.
| Seção | Pedidos listados (status) | Aparece para quem tem | O link do pedido abre |
| - | - | - | - |
| **A preparar** | `allocated`, `picking` | `fulfillment.pick` ou `fulfillment.dispatch` | A tela de preparação, `/fulfillment/:orderId/pick` |
| **A entregar** | `dispatched` | `delivery.confirm` | A tela de entrega, `/fulfillment/:orderId/delivery` |
| **A receber** | `delivered` | `receipt.confirm` | A tela de recebimento, `/fulfillment/:orderId/receipt` |
| **A encerrar** | `received`, `partially_fulfilled` | `fulfillment.close` | O detalhe de custódia, `/fulfillment/:orderId` |
| **Problemas de entrega** | `exception` | `fulfillment.read` | O detalhe de custódia, `/fulfillment/:orderId` |
Cada seção é uma tabela com estas colunas:
| Coluna | O que mostra |
| - | - |
| **Pedido** | O número do pedido, por exemplo `#1042`. Selecione-o para abrir a etapa. |
| **Status** | O status atual do pedido, com o rótulo do console (veja a tabela abaixo). |
| **Clínica** | A unidade à qual o pedido pertence. |
| **Entregar em** | O depósito de destino. |
Regras da lista:
* Você vê os pedidos das unidades incluídas no seu **Acesso às unidades**. Com **Todas as unidades desta conta**, você vê os pedidos de todas.
* Cada seção mostra até 50 pedidos, do mais recente ao mais antigo. Quando há mais, a seção diz "Mostrando os primeiros 50. Termine estes para ver o restante."
* Uma seção vazia diz "Não há nada aqui por enquanto."
* Se você não tem nenhuma permissão de custódia, a tela diz "Você não participa das entregas. Pergunte ao administrador da sua clínica se você deveria preparar, entregar ou receber pedidos."
## Etapas da entrega
Um pedido entra em custódia quando é aprovado, seja por uma pessoa (veja [Aprovar ou rejeitar pedidos](/docs/pt/orders/approvals)), seja automaticamente pela [política de aprovação](/docs/pt/orders/approval-policy). A partir daí, o registro de custódia passa por estes status:
```mermaid theme={null}
stateDiagram-v2
approved: Pedido aprovado
allocating: Reservando estoque
allocated: Estoque reservado
picking: Em preparação
dispatched: Despachado
delivered: Entregue
exception: Problema de entrega
received: Recebido
partially_fulfilled: Recebido em parte
closed: Encerrado
[*] --> approved
approved --> allocating: reserva automática
allocating --> allocated: todas as linhas reservadas
allocating --> approved: estoque insuficiente, nada fica reservado
allocated --> picking: primeira caixa escaneada
picking --> dispatched: despacho
dispatched --> delivered: entrega confirmada
dispatched --> exception: problema de entrega informado
delivered --> received: todas as caixas aceitas
delivered --> partially_fulfilled: pelo menos uma caixa contestada
received --> closed: encerramento
partially_fulfilled --> closed: encerramento
closed --> [*]
```
| Status | Rótulo no console | O que significa | Próxima etapa |
| - | - | - | - |
| `allocating` | **Reservando estoque** | O muveya está reservando caixas para o pedido. Só o registro de custódia tem esse status: o pedido continua mostrando **Aprovado**. | Automática. |
| `allocated` | **Estoque reservado** | Todas as linhas do pedido têm caixas reservadas. | Retirar as caixas. |
| `picking` | **Em preparação** | Pelo menos uma caixa reservada foi escaneada. | Retirar o restante e despachar. |
| `dispatched` | **Despachado** | As caixas retiradas saíram do depósito de origem. Estão **Em trânsito**. | Confirmar a entrega. |
| `delivered` | **Entregue** | A entrega no destino foi confirmada. | Confirmar o recebimento. |
| `exception` | **Problema de entrega** | Foi informado um problema em vez de uma entrega normal. O pedido para aqui. | Nenhuma no console por enquanto (veja [Problemas de entrega](/docs/pt/deliveries/delivery-and-receipt#se-um-problema-de-entrega-for-informado)). |
| `received` | **Recebido** | O destino aceitou todas as caixas. | Encerrar o pedido. |
| `partially_fulfilled` | **Recebido em parte** | O destino contestou pelo menos uma caixa, que voltou à origem. | Encerrar o pedido. |
| `closed` | **Encerrado** | A custódia terminou. | Nenhuma. |
O status do pedido segue as mesmas etapas (`allocated`, `picking`, `dispatched`, `delivered`, `exception`, `received`, `partially_fulfilled`, `closed`), então as telas **Pedidos** e **Entregas** sempre coincidem (veja [Criar e acompanhar pedidos](/docs/pt/orders/create-and-track)).
### Etapa 1: o sistema reserva o estoque
Ninguém reserva estoque manualmente. Quando um pedido é aprovado, o muveya faz a reserva sozinho:
1. Para cada linha do pedido, ele considera as caixas utilizáveis daquele insumo: caixas com situação **Ativa**, que não passaram da data de validade e que usam a mesma unidade de medida da linha.
2. Se o pedido indica um depósito de origem (**Retirar estoque de**, no pedido), só contam as caixas desse depósito.
3. Ele ordena as caixas por **FEFO** (primeiro a vencer, primeiro a sair: a validade mais próxima primeiro, caixas sem validade no final e, depois, o recebimento mais antigo) quando pelo menos uma caixa candidata tem data de validade, e por **FIFO** (o recebimento mais antigo primeiro) nos demais casos.
4. Ele reserva da primeira caixa, depois da seguinte, até cobrir a quantidade da linha. Uma linha pode usar várias caixas, e uma caixa pode ficar reservada só por parte do seu conteúdo.
5. A reserva é tudo ou nada. Se alguma linha não puder ser coberta, o muveya libera tudo o que tinha reservado para esse pedido e o deixa em **Aprovado**.
Essas reservas aparecem no histórico do pedido como movimentos **Reservado** feitos por **Muveya (automático)**.
Se o pedido ficou com **Qualquer depósito central**, a reserva não se limita a um depósito: o muveya ordena todas as caixas utilizáveis daquele insumo na conta de clínica odontológica. Antes de preparar, confira a coluna **Retirar de** da lista para ver onde cada caixa realmente está.
Se um pedido aprovado não pôde ser reservado:
* Ele não aparece em **Entregas**, e a página dele continua dizendo "O pedido está passando para o próximo passo. Esta tela se atualiza sozinha em alguns segundos."
* O muveya tenta de novo sempre que outro pedido da mesma conta de clínica odontológica é aprovado. Por enquanto não há um botão para tentar de novo no console.
* Receba ou movimente o estoque que falta ([Receber estoque](/docs/pt/inventory/receive), [Registrar consumo e transferir caixas](/docs/pt/inventory/use-and-moves)). Se o pedido continuar em **Aprovado**, escreva para [team@muveya.com](mailto:team@muveya.com) com o número do pedido.
## Custódia por caixa inteira
O muveya movimenta a custódia uma **caixa inteira** por vez. Uma caixa (qualquer recipiente etiquetado com um código como `BX-000123`) é retirada, despachada, entregue e recebida como uma única unidade. Na prática:
* **Uma caixa do tamanho do pedido** viaja como está.
* **Uma caixa com mais do que o pedido precisa** é dividida quando você a escaneia: o muveya separa exatamente a quantidade reservada em um novo recipiente, com etiqueta própria, e só esse recipiente viaja. O restante fica na caixa original, no depósito dela. Veja [Dividir uma caixa ao preparar](/docs/pt/deliveries/picking#dividir-uma-caixa-ao-preparar).
* **O recebimento é por caixa.** O destino aceita ou contesta cada caixa inteira. Não é possível aceitar parte de uma caixa. Se uma caixa chegou com menos unidades do que a etiqueta indica, veja [Quantidades parciais](/docs/pt/deliveries/delivery-and-receipt#quantidades-parciais).
* **Enquanto uma caixa viaja**, ela fica **Em trânsito**. Ela não conta mais no depósito de origem e só conta no destino depois de aceita.
Para saber como as caixas são etiquetadas e acompanhadas em geral, veja [Caixas e etiquetas](/docs/pt/inventory/boxes).
## Quem pode fazer cada etapa
Cada etapa de custódia tem sua própria permissão. As permissões nunca são herdadas do nome de uma função: um integrante só executa uma etapa se um administrador concedeu essa permissão exata na tela **Equipe**. Veja [Funções e permissões](/docs/pt/account/roles-and-permissions).
| Permissão | Rótulo na tela Equipe | O que permite | Parte |
| - | - | - | - |
| `fulfillment.read` | **Ver atendimento** | Abrir o detalhe de custódia e ver **Problemas de entrega**. | Qualquer uma |
| `fulfillment.pick` | **Preparar pedidos** | Abrir a tela de preparação, ver a lista e escanear caixas. | Origem |
| `fulfillment.dispatch` | **Despachar pedidos** | Despachar as caixas retiradas. | Origem |
| `delivery.confirm` | **Confirmar entrega** | Confirmar a entrega ou informar um problema de entrega. | Origem |
| `receipt.confirm` | **Confirmar recebimento** | Aceitar ou contestar as caixas entregues. | Destino |
| `fulfillment.close` | **Encerrar atendimento** | Encerrar um pedido recebido ou recebido em parte. | Destino |
Algumas telas do console precisam de duas permissões juntas:
* **Despachar** acontece na tela de preparação, que só abre com `fulfillment.pick`. Um integrante que tem apenas `fulfillment.dispatch` vê o pedido em **A preparar**, mas não consegue despachá-lo pelo console.
* **Receber** caixa por caixa precisa de `receipt.confirm` e `fulfillment.read`. Sem `fulfillment.read`, a tela de recebimento diz "Para receber caixa por caixa você também precisa de permissão para ver entregas. Peça ao administrador da sua clínica."
* **Encerrar** acontece no detalhe de custódia, que precisa de `fulfillment.read`. Um integrante que tem apenas `fulfillment.close` não chega ao botão **Encerrar pedido**.
As etapas de custódia nunca pedem verificação pelo aplicativo autenticador (TOTP).
## Parte de origem e parte de destino
Toda entrega tem duas partes, e o muveya verifica cada etapa conforme a parte a que ela pertence.
* **Parte de origem**: as pessoas que preparam, despacham e entregam as caixas. O muveya compara o **Acesso às unidades** delas com a unidade dona do **depósito de origem**. Quando a origem é um depósito central, ou o pedido não indicou origem, ele compara com a unidade do pedido.
* **Parte de destino**: as pessoas que recebem e encerram. O muveya compara o **Acesso às unidades** delas com a unidade dona do **depósito de destino**, ou com a unidade do pedido quando o destino é um depósito central.
Regras adicionais:
* **Preparar e visualizar** são verificados contra a unidade do pedido.
* **O acesso aos depósitos importa na origem.** Para escanear uma caixa, seu **Acesso aos depósitos** precisa incluir o depósito onde a caixa está; uma caixa fora dele é tratada como "não reservada para este pedido". Despachar também exige acesso ao depósito de cada caixa.
* **Separação de funções entre unidades.** Quando os depósitos de origem e de destino pertencem a duas unidades diferentes, um integrante cujo **Acesso às unidades** inclui a unidade de origem não pode receber nem encerrar esse pedido. O muveya responde "Sua conta não tem permissão para esta ação." Essa regra não bloqueia quem tem **Todas as unidades desta conta**; nesse caso, só as permissões decidem.
* Um pedido fora das suas unidades se comporta como se não existisse: o detalhe de custódia e a tela de recebimento dizem "Esta entrega não existe ou você não pode vê-la.", e as telas de separação e de entrega dizem "Este registro não está disponível na conta de clínica odontológica ativa."
## O que o sistema registra
| Etapa | Movimentos registrados | Status do pedido depois | Registro de auditoria |
| - | - | - | - |
| Reserva | **Reservado** em cada caixa (sem mudar a quantidade disponível) | `allocated` | `fulfillment.allocated` |
| Separação | **Retirado para o pedido** em cada caixa (sem mudar a quantidade); **Separação (saída)** e **Separação (entrada)** quando uma caixa é dividida | `picking` | `fulfillment.picked` |
| Despacho | **Despachado** em cada caixa (a quantidade sai do depósito de origem) | `dispatched` | `fulfillment.dispatched` |
| Entrega | Nenhum: as caixas continuam **Em trânsito** | `delivered` ou `exception` | `fulfillment.delivered` ou `fulfillment.delivery_exception` |
| Recebimento | **Recebido** no destino para cada caixa aceita; **Devolvido** na origem para cada caixa contestada | `received` ou `partially_fulfilled` | `fulfillment.received` ou `fulfillment.received.disputed` |
| Encerramento | Nenhum | `closed` | `fulfillment.closed` |
O registro só aceita novos lançamentos: uma caixa contestada não é apagada do despacho, ela recebe um novo movimento **Devolvido**. O detalhe de custódia mostra tudo isso para um pedido; veja [Histórico de custódia](/docs/pt/deliveries/custody-history). Por enquanto não há uma tela de auditoria no console.
Todas as ações de custódia podem ser repetidas sem risco. Despachar, confirmar uma entrega, confirmar um recebimento ou encerrar um pedido pela segunda vez não muda nada: a tela responde que isso já estava registrado.
## Páginas relacionadas
Escaneie as caixas reservadas, divida as caixas maiores e despache o pedido.
Confirme a entrega, receba ou conteste cada caixa e encerre o pedido.
Veja quem fez o quê e quando, para auditorias e contestações.
Como um pedido é aprovado e entra em custódia.
Códigos de caixa, situações e movimentos de cada caixa.
Conceda as permissões de custódia e o acesso às unidades.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.