Registra uma encomenda
POST/api/parcels/spaces/{spaceId}/parcels
- Auth
- Requires a token
- Who can call it:
- owner
- admin
- moderator
- finance
- X-CommunityId
X-CommunityIdSend the X-CommunityId of the community the operation happens in.
Só a equipe (owner, admin, moderador e financeiro); membro recebe 403. Cria a encomenda `RECEIVED`, liga as fotos (`mediaIds`, até 5) e **enfileira o e-mail ao destinatário** (nunca na requisição; no fuso da comunidade, com miniatura de 300 px e link de 72 h se `emailIncludesPhoto`). O destinatário precisa ser perfil da comunidade com acesso ao space (outra comunidade: 404; sem acesso: 400). Sem `recipientProfileId` ou `kind`: 400 com um item em `errors` por campo. Com `lockerMode: none` os campos de locker são ignorados. **Idempotente** por `clientRequestId`: o segundo toque devolve a mesma encomenda (200, `alreadyRegistered: true`) sem novo e-mail. Mesma encomenda (destinatário, tipo e rastreio) em 24 h: 409 com `data.duplicateOf`, salvo com `force: true`. Cria: `201`.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
spaceIdrequired | path | string (uuid) |
Headers
| Name | Type | Description |
|---|---|---|
X-CommunityIdoptional | string (uuid) | ID da comunidade em que a operação acontece. Obrigatório na maioria dos endpoints com escopo de comunidade. |
Request body application/json
| Name | Type | Description |
|---|---|---|
recipientProfileIdrequired | string (uuid) | Perfil (pessoa ou empresa) da comunidade, com acesso ao space. |
kindrequired | LETTER | PACKAGE | OTHER | |
kindLabeloptional | string | Obrigatório com `OTHER`; até 60 caracteres. |
senderNameoptional | string | |
carrieroptional | string | |
trackingCodeoptional | string | |
notesoptional | string | |
lockerLabeloptional | string | Só com `lockerMode: free`; ignorado com `none`. |
lockerPickupCodeoptional | string | 4 a 12 caracteres. Só com `lockerPickupCode: true` na configuração do space; ignorado fora disso. |
mediaIdsoptional | string (uuid)[] | Fotos já enviadas por `/api/media` com `purpose: parcelPhoto` e confirmadas. |
clientRequestIdoptional | string | Idempotência: o mesmo valor no mesmo space devolve a encomenda já criada (200, `alreadyRegistered: true`) e não envia outro e-mail. |
forceoptional | boolean | Registra mesmo com a mesma encomenda (mesmo destinatário, tipo e rastreio) nas últimas 24 h. |
Responses
| Status | Description |
|---|---|
200 | Já registrada com o mesmo `clientRequestId`. |
201 | Encomenda registrada. |
400 | Requisição inválida — falha de validação. |
401 | Token ausente, inválido ou expirado. |
403 | Autenticado, mas sem permissão para esta operação. |
404 | Recurso não encontrado. |
409 | Conflito com o estado atual do recurso. |
500 | Erro interno do servidor. |
curl example
curl -X POST "https://api.memberfy.net/api/parcels/spaces/<spaceId>/parcels" \
-H "Authorization: Bearer $TOKEN" \
-H "X-CommunityId: $COMMUNITY_ID" \
-H "Content-Type: application/json" \
-d '{"recipientProfileId":"00000000-0000-0000-0000-000000000000","kind":"LETTER"}'