Skip to main content
POST
/
api
/
v1
/
sucursales
Create Branch Office
curl --request POST \
  --url https://api.example.com/api/v1/sucursales \
  --header 'Content-Type: application/json' \
  --data '
{
  "codigoSucursal": "<string>",
  "nombreSucursal": "<string>",
  "direccion": "<string>",
  "ciudad": "<string>"
}
'
{
  "id": 123,
  "codigoSucursal": "<string>",
  "nombreSucursal": "<string>",
  "direccion": "<string>",
  "ciudad": "<string>"
}

​
Endpoint

POST /api/v1/sucursales
Create a new branch office location for package drop-off and pickup operations.

​
Request Body

​
codigoSucursal
string
required
Unique branch code (e.g., “LIM-001”, “CUS-001”, “AQP-001”)
​
nombreSucursal
string
required
Descriptive name for the branch office
​
direccion
string
required
Complete physical address of the branch
​
ciudad
string
required
City where the branch is located

​
Response

Returns the created branch office object:
​
id
number
Unique branch identifier (auto-generated)
​
codigoSucursal
string
Branch code
​
nombreSucursal
string
Branch office name
​
direccion
string
Physical address
​
ciudad
string
City location

​
Example Request

curl -X POST http://localhost:8080/api/v1/sucursales \
  -H "Content-Type: application/json" \
  -d '{
    "codigoSucursal": "TRU-001",
    "nombreSucursal": "Trujillo Centro",
    "direccion": "Av. España 567",
    "ciudad": "Trujillo"
  }'

​
Example Response

{
  "id": 4,
  "codigoSucursal": "TRU-001",
  "nombreSucursal": "Trujillo Centro",
  "direccion": "Av. España 567",
  "ciudad": "Trujillo"
}

​
Branch Code Conventions

Use a consistent naming convention for branch codes:
  • First 3 letters: City abbreviation (LIM, CUS, AQP, TRU, PIU, etc.)
  • Dash separator: -
  • 3 digits: Sequential number (001, 002, 003)
Examples: LIM-001, CUS-002, AQP-001

​
Validation Rules

  • codigoSucursal: Must be unique across all branches
  • nombreSucursal: Cannot be empty
  • direccion: Should be complete for accurate logistics
  • ciudad: Used for semantic search and route planning

​
Use Cases

  • Expanding to new cities or regions
  • Opening additional branches in existing cities
  • Administrative branch management
  • Network planning and logistics optimization

​
Integration with Shipments

Once created, branch offices can be used as:
  • Origin (sucursalOrigenId) - Where customers drop off packages
  • Destination (sucursalDestinoId) - Where packages are delivered for pickup

Build docs developers (and LLMs) love

Get started for freeTalk to us