Registra uma encomenda
POST/api/parcels/spaces/{spaceId}/parcels
- Auth
- Requiere token
- Quién puede:
- owner
- admin
- moderator
- finance
- X-CommunityId
X-CommunityIdEnvía el X-CommunityId de la comunidad en la que ocurre la operación.
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`.
Parámetros
| Nombre | Dónde | Tipo | Descripción |
|---|---|---|---|
spaceIdobligatorio | path | string (uuid) |
Headers
| Nombre | Tipo | Descripción |
|---|---|---|
X-CommunityIdopcional | string (uuid) | ID da comunidade em que a operação acontece. Obrigatório na maioria dos endpoints com escopo de comunidade. |
Cuerpo de la solicitud application/json
| Nombre | Tipo | Descripción |
|---|---|---|
recipientProfileIdobligatorio | string (uuid) | Perfil (pessoa ou empresa) da comunidade, com acesso ao space. |
kindobligatorio | LETTER | PACKAGE | OTHER | |
kindLabelopcional | string | Obrigatório com `OTHER`; até 60 caracteres. |
senderNameopcional | string | |
carrieropcional | string | |
trackingCodeopcional | string | |
notesopcional | string | |
lockerLabelopcional | string | Só com `lockerMode: free`; ignorado com `none`. |
lockerPickupCodeopcional | string | 4 a 12 caracteres. Só com `lockerPickupCode: true` na configuração do space; ignorado fora disso. |
mediaIdsopcional | string (uuid)[] | Fotos já enviadas por `/api/media` com `purpose: parcelPhoto` e confirmadas. |
clientRequestIdopcional | string | Idempotência: o mesmo valor no mesmo space devolve a encomenda já criada (200, `alreadyRegistered: true`) e não envia outro e-mail. |
forceopcional | boolean | Registra mesmo com a mesma encomenda (mesmo destinatário, tipo e rastreio) nas últimas 24 h. |
Respuestas
| Código | Descripción |
|---|---|
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. |
Ejemplo con curl
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"}'