---
title: "Crear (o reutilizar) un destinatario"
method: POST
path: "/recipients"
tags: ["addresses"]
---

# Crear (o reutilizar) un destinatario

`POST /recipients`

## Request

- Base URL: `https://api.enviadores.com.mx/api/v1`
- URL: `https://api.enviadores.com.mx/api/v1/recipients`
- Auth: HTTP bearer

Create-or-reuse bajo el remitente `sender_id` (debe ser visible para la llave; si no → 404 ciego). Mismo dedupe normalizado que el carril de envíos; en una reutilización, `alias`/`referencia`/`delivery_instructions` NO se aplican (no forman parte de la identidad — la fila existente se devuelve intacta). El `postal_code` debe tener 5 dígitos y EXISTIR en el catálogo postal (SEPOMEX); si `city`/`state` vienen, deben ser coherentes con el CP (un desajuste responde 422 nombrando el valor esperado) y si se omiten se AUTOCOMPLETAN del catálogo — la misma validación de exactitud que `POST /contacts/import`. Requiere scope `addresses:write`.

## Headers

- `X-PDV-ID` string

## Request body

- RecipientCreateRequest: El mismo vocabulario de campos que el `to` de `POST /shipments` + `sender_id`, con `city`/`state` opcionales aquí (se autocompletan del catálogo SEPOMEX según el CP — la misma validación de exactitud que `POST /contacts/import`). `alias`/`referencia`/`delivery_instructions` solo se aplican al CREAR (una reutilización devuelve la fila existente intacta).
  - `sender_id` string, required: Remitente dueño (visible para la llave; si no → 404 ciego).
  - `alias` string: Nombre descriptivo ("Casa", "Oficina").
  - `name` string, required
  - `phone` string, required
  - `email` string, email
  - `street` string, required
  - `number` string
  - `colonia` string, required
  - `city` string: Opcional: si se omite se autocompleta del catálogo SEPOMEX según el CP; si viene, debe coincidir con el CP (si no → 422 nombrando la ciudad esperada).
  - `state` string: Opcional: si se omite se autocompleta del catálogo SEPOMEX según el CP; si viene, debe coincidir con el CP (si no → 422 nombrando el estado esperado).
  - `postal_code` string, required: 5 dígitos; debe EXISTIR en el catálogo postal (SEPOMEX).
  - `country` 'MX'
  - `referencia` string: Referencias del domicilio.
  - `delivery_instructions` string

## Response `200`

Destinatario idéntico ya existente reutilizado (`created: false`).

- object
  - `success` unknown, required
  - `data` object, required
    - `recipient` Recipient, required: Recurso destinatario. Su `id` sirve como `to_id` en `POST /rates` y `POST /shipments` (requiere `from_id` del remitente dueño).
      - `id` string, required
      - `sender_id` string, required
      - `alias` string, nullable, required
      - `name` string, nullable, required
      - `phone` string, nullable, required
      - `email` string, nullable, required
      - `street` string, nullable, required
      - `number` string, nullable, required
      - `colonia` string, nullable, required
      - `city` string, nullable, required
      - `state` string, nullable, required
      - `postal_code` string, nullable, required
      - `referencia` string, nullable, required
      - `delivery_instructions` string, nullable, required
      - `created_at` string, nullable, required: ISO-8601 UTC (Z).
    - `created` boolean, required
  - `requestId` string, required: Correlación de logs; también en el header `X-Request-Id`.

## Other responses

- `201`: Destinatario creado (`created: true`).
- `401`: `UNAUTHORIZED` — credencial Bearer ausente/mal formada o llave desconocida/revocada (respuesta idéntica en ambos casos).
- `403`: `INSUFFICIENT_SCOPE` — a la llave le falta el scope requerido · `PDV_NOT_ALLOWED` — violación del carril X-PDV-ID. Nota de orden: el limitador por llave corre ANTES del gate de scope, así que una petición con scope incorrecto y el bucket agotado responde `429 RATE_LIMITED` (el 429 tiene precedencia sobre este 403).
- `404`: `NOT_FOUND` — `sender_id` inexistente o no visible (respuesta idéntica).
- `422`: `VALIDATION_ERROR` — campos faltantes/inválidos o desconocidos (details.fields).
- `429`: `RATE_LIMITED` — bucket de la llave agotado. Espera `Retry-After` s (`details.retry_after_ms` para el hint fino). El limitador corre antes del gate de scope, por lo que un 429 tiene precedencia sobre un 403 `INSUFFICIENT_SCOPE`.
- `500`: `ADDRESS_ERROR` — no se pudo registrar; reintenta.

---

[API](https://skmtc.dev/enviadores/apis/enviadores-public-api.md) · [All operations](https://skmtc.dev/enviadores/apis/enviadores-public-api/llms.txt) · [OpenAPI document](https://skmtc.dev/enviadores/apis/enviadores-public-api/revisions/3633f08c889c?raw)