Coverage by Postal Code

Gets the destination branch corresponding to a postal code. Useful for auto-completing DestinoCode before creating shipping guides.

GET /api/sucursales/cobertura/{codigoPostal}

Required permission: guias.read

Parameters

Parameter	Type	Description
codigoPostal	string	5-digit postal code (e.g., 44100)

Example

curl -X GET "https://ws-api.masaprisaoperativo.com/api/sucursales/cobertura/44100" \
  -H "Authorization: Bearer {token}"

Response with Coverage

{
  "response": "OK",
  "message": "Postal code with coverage",
  "data": {
    "codigo_postal": "44100",
    "asentamiento": "Centro",
    "municipio": "Guadalajara",
    "estado": "Jalisco",
    "tiene_cobertura": true,
    "sucursal": {
      "sucu_id": 12,
      "sucu_sucursal": "GDLGL",
      "sucu_descripcion": "GUADALAJARA GONZALES GALLO"
    }
  }
}

Response without Coverage

{
  "response": "OK",
  "message": "Valid postal code but no branch coverage",
  "data": {
    "codigo_postal": "99999",
    "asentamiento": "Colonia X",
    "municipio": "Municipio Y",
    "estado": "Estado Z",
    "tiene_cobertura": false,
    "sucursal": null
  }
}

Error Response

{
  "response": "ERROR",
  "message": "Postal code not found"
}

Recommended Usage

1. User enters the recipient's postal code
2. Call this endpoint to verify coverage
3. If tiene_cobertura is true, use sucursal.sucu_sucursal as DestinoCode
4. If no coverage, display message to user

const response = await fetch(`/api/sucursales/cobertura/${postalCode}`, {
  headers: { 'Authorization': 'Bearer ' + token }
});
const data = await response.json();

if (data.data?.tiene_cobertura) {
  // Use data.data.sucursal.sucu_sucursal as DestinoCode
  console.log('Branch:', data.data.sucursal.sucu_sucursal);
} else {
  // Show error: no coverage for that postal code
  console.log('No coverage');
}

:::tip Alternative You can also send only CodigoPostal when creating a guide and the system will get the branch automatically. See Create Guide. :::