Endpoints de Endereços

Endereços podem ser associados a usuários e fazendas.

Todos os endpoints requerem autenticação.

Authorization: Bearer <token>

---

Objeto Address

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "street": "Rua Principal",
  "number": 123,
  "city": "São Paulo",
  "state": "SP",
  "zip_code": "12345-678",
  "country": "Brazil",
  "complement": "Apto 4B",
  "lat": "-23.550520",
  "lng": "-46.633308",
  "is_primary": true,
  "created_at": "2025-11-21T10:30:00Z",
  "updated_at": null
}

---

Códigos de Estado Brasileiros

Valores válidos: AC, AL, AP, AM, BA, CE, DF, ES, GO, MA, MT, MS, MG, PA, PB, PR, PE, PI, RJ, RN, RS, RO, RR, SC, SP, SE, TO

Formato do CEP

• 12345-678 ou 12345678 (8 dígitos)
• Formatado automaticamente para 12345-678

---

POST /addresses/

Cria um endereço para o usuário atual.

Requisição

POST /api/v1/addresses/
Authorization: Bearer <token>
Content-Type: application/json

{
  "street": "Rua das Flores",
  "number": 456,
  "city": "Fortaleza",
  "state": "CE",
  "zip_code": "60000-000",
  "country": "Brazil",
  "complement": "Casa 2",
  "is_primary": false
}

Parâmetros do Body

Campo	Tipo	Obrigatório	Padrão	Descrição
street	string	✅	-	Nome da rua
number	integer	✅	-	Número
city	string	✅	-	Cidade
state	string	✅	-	Código do estado brasileiro (2 letras)
zip_code	string	✅	-	CEP (8 dígitos)
country	string	❌	"Brazil"	País
complement	string	❌	-	Informações adicionais (apto, bloco, etc.)
is_primary	boolean	❌	false	Endereço principal

Resposta 201 Created

{
  "id": "address-uuid",
  "street": "Rua das Flores",
  "number": 456,
  "city": "Fortaleza",
  "state": "CE",
  "zip_code": "60000-000",
  "country": "Brazil",
  "complement": "Casa 2",
  "is_primary": false,
  "created_at": "2025-11-21T10:30:00Z",
  "updated_at": null
}

Possíveis Erros

Status	Detalhe
422	Erro de validação (CEP inválido, código de estado inválido, etc.)

---

GET /addresses/

Lista todos os endereços do usuário atual.

Requisição

GET /api/v1/addresses/
Authorization: Bearer <token>

Resposta 200 OK

Retorna array de objetos de endereço.

---

GET /addresses/{address_id}

Obtém detalhes de um endereço.

Parâmetros de URL

Parâmetro	Tipo	Descrição
address_id	UUID	ID do endereço

Requisição

GET /api/v1/addresses/address-uuid
Authorization: Bearer <token>

Resposta 200 OK

Retorna objeto de endereço.

Possíveis Erros

Status	Detalhe
404	Endereço não encontrado

---

PUT /addresses/{address_id}

Atualiza um endereço.

Parâmetros de URL

Parâmetro	Tipo	Descrição
address_id	UUID	ID do endereço

Requisição

PUT /api/v1/addresses/address-uuid
Authorization: Bearer <token>
Content-Type: application/json

{
  "street": "Rua Nova",
  "number": 789,
  "is_primary": true
}

Parâmetros do Body

Todos os campos são opcionais:

Campo	Tipo	Descrição
street	string	Nome da rua
number	integer	Número
city	string	Cidade
state	string	Código do estado
zip_code	string	CEP
country	string	País
complement	string	Complemento
is_primary	boolean	Endereço principal

Resposta 200 OK

Retorna objeto de endereço atualizado.

Possíveis Erros

Status	Detalhe
404	Endereço não encontrado
422	Erro de validação

---

DELETE /addresses/{address_id}

Exclui um endereço.

Parâmetros de URL

Parâmetro	Tipo	Descrição
address_id	UUID	ID do endereço

Requisição

DELETE /api/v1/addresses/address-uuid
Authorization: Bearer <token>

Resposta 204 No Content

Sem corpo de resposta.

Possíveis Erros

Status	Detalhe
404	Endereço não encontrado

Cuidado

Se o endereço estiver associado a uma fazenda, a associação será removida, mas a fazenda não será excluída.

---

Uso com Fazendas

Ao criar uma fazenda, você pode associar um endereço existente:

{
  "name": "Fazenda Alpha",
  "description": "Fazenda principal",
  "address_id": "address-uuid"
}

Dica

Crie o endereço primeiro usando POST /addresses/ e depois use o address_id retornado ao criar a fazenda.