Índice da referência

Geral

Visão geral

Auth

Autenticar usuário
Registrar usuário
Encerrar sessão
Manter sessão

Shared

Perfil do usuário
Atualizar senha

Países

Listar países
Detalhar país
Detalhar estado
Detalhar cidade
Detalhar cidade (Shared)

Referência da API

Endpoints reais, direto dos contratos OpenAPI do repositório da API: nada aqui é inventado. Autenticação Sanctum com SSO Keycloak, perfil do usuário e o microsserviço de países.

Visão geral

O contrato transversal da API: servidores, chaves e idiomas.

Toda chamada leva X-PUBLIC-KEY, a chave pública que identifica a plataforma. Rotas autenticadas usam o token Sanctum em Authorization: Bearer; o login também fala com o Keycloak e o bloco jwt pode vir null sem invalidar a sessão. Accept-Language (pt-BR, en, es, gn) traduz nomes e mensagens.

Servidores

https://echosistema.live   # production
https://echosistema.dev    # QA / sandbox

Autenticar usuário

POST/api/v1/authBasic (email:senha)

Autentica via HTTP Basic (email:senha em Base64) no Sanctum e devolve o token na raiz da resposta. Em paralelo tenta o SSO no Keycloak: o bloco jwt pode vir null sem invalidar o login, e o refresh_token fica guardado cifrado no Redis do servidor para logout, keep-alive e sso-jwt consumirem depois.

Cabeçalhos

X-PUBLIC-KEYstring (uuid)obrigatório
Chave pública que identifica a plataforma.
Accept-Languagestring
Idioma da resposta: pt-BR, en, es ou gn.

Query

with_projectsboolean
Com true, inclui data.user.accessible_projects na resposta.

Corpo

devicestringobrigatório
Nome do dispositivo que rotula o token Sanctum.
flash_tokenboolean
Com true, devolve um flash token de 60 segundos, uso único e preso ao IP, para handoff entre frontends via POST /api/v1/auth/flash-token.

Respostas

200
Autenticado; o token Sanctum é sempre válido, o jwt pode ser null.
401
Credenciais inválidas ou chave pública ausente ou errada.
422
Erro de validação nos campos ou parâmetros.
500
Erro interno.

Requisição

curl -X POST https://echosistema.live/api/v1/auth \
  -u "sample.user@domain.com:secret123" \
  -H "X-PUBLIC-KEY: 33333333-3333-3333-3333-333333333333" \
  -H "Accept-Language: pt-BR" \
  -H "Content-Type: application/json" \
  -d '{ "device": "web-browser" }'

Resposta 200

{
  "message": "User authenticated successfully!",
  "token": "1|a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0",
  "data": {
    "user": {
      "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "echo_uuid": "e1c1h1o1a1b2c3d4e5f6789012345678901234",
      "name": "Sample User",
      "email": "sample.user@domain.com",
      "avatar": { "url": "https://example.com/avatar.png", "usage": "avatar" },
      "language": "en",
      "currency": "USD",
      "roles": [
        {
          "id": 1,
          "platform": {
            "uuid": "22222222-2222-2222-2222-222222222222",
            "name": "Sample Platform",
            "public_key": "33333333-3333-3333-3333-333333333333"
          },
          "name": "guest",
          "localized_name": "Guest",
          "permissions": [ { "subject": "complaint", "action": "store" } ]
        }
      ],
      "company_roles": [
        {
          "id": 3,
          "platform": {
            "uuid": "22222222-2222-2222-2222-222222222222",
            "name": "Sample Platform",
            "public_key": "33333333-3333-3333-3333-333333333333"
          },
          "company": {
            "id": "64a1b2c3d4e5f6a7b8c9d0e1",
            "uuid": "44444444-4444-4444-4444-444444444444",
            "name": "Sample Company"
          },
          "name": "manager",
          "localized_name": "Manager",
          "permissions": [
            { "subject": "company", "action": "view" },
            { "subject": "company", "action": "update" }
          ]
        }
      ],
      "is_backoffice": false,
      "is_service_provider": false
    }
  },
  "jwt": {
    "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.example",
    "refresh_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.refresh",
    "id_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.idtoken",
    "token_type": "Bearer",
    "expires_in": 300,
    "refresh_expires_in": 1800,
    "scope": "openid profile email",
    "issuer": "https://sso.echosistema.live/realms/echosistema",
    "subject": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "provider": { "driver": "keycloak", "name": "Keycloak Default", "kind": "oidc" }
  },
  "visitor_ip": "203.0.113.42"
}

Testar endpoint

Servidor

E-mailSenha

X-PUBLIC-KEYobrigatórioAccept-Language

with_projects

Corpo (JSON)

Registrar usuário

POST/api/v1/auth/registerPública

Cria o usuário na plataforma do X-PUBLIC-KEY e projeta a identidade no Keycloak. Em plataformas realestate, os flags agent, professional e customer decidem o papel, nesta ordem de prioridade; sem flag, entra como guest, e é um papel só por plataforma. Token Sanctum e bloco jwt voltam como no login.

Cabeçalhos

X-PUBLIC-KEYstring (uuid)obrigatório
Chave pública que identifica a plataforma.
Accept-Languagestring
Idioma da resposta: pt-BR, en, es ou gn.

Query

with_projectsboolean
Com true, inclui data.user.accessible_projects na resposta.

Corpo

namestringobrigatório
Nome completo do usuário.
emailstring (email)obrigatório
E-mail, único por plataforma.
passwordstring (min 8)obrigatório
Senha, mínimo de 8 caracteres.
password_confirmationstringobrigatório
Confirmação, igual à senha.
devicestringobrigatório
Nome do dispositivo que rotula o token Sanctum.
flash_tokenboolean
Com true, devolve um flash token de 60 segundos, uso único e preso ao IP, para handoff entre frontends via POST /api/v1/auth/flash-token.
agent0 | 1
Papel de corretor em plataformas realestate (1 = sim); prioridade agent, depois professional, depois customer.
professional0 | 1
Papel de profissional em plataformas realestate (1 = sim).
customer0 | 1
Papel de cliente em plataformas realestate (1 = sim).
intend_agency0 | 1
Sinaliza intenção de criar ou entrar numa imobiliária; vai para o raw do usuário.
collaborator0 | 1
Cria como colaborador (1 = sim); exige gênero, nascimento, nacionalidades, endereço e contatos.
languagestring
Idioma preferido do usuário (locale IETF).
currencystring
Moeda preferida do usuário.

Respostas

200
Registrado; recently_created true e token na raiz.
422
Erro de validação nos campos ou parâmetros.
500
Erro interno.

Requisição

curl -X POST https://echosistema.live/api/v1/auth/register \
  -H "X-PUBLIC-KEY: aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "User Example",
    "email": "user@example.com",
    "password": "secret123",
    "password_confirmation": "secret123",
    "device": "web"
  }'

Resposta 200

{
  "message": "User Example registered successfully.",
  "recently_created": true,
  "token": "0000|a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0",
  "data": {
    "user": {
      "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "echo_uuid": "e1c1h1o1a1b2c3d4e5f6789012345678901234",
      "name": "User Example",
      "email": "user@example.com",
      "avatar": null,
      "language": "en",
      "currency": "USD",
      "roles": [
        {
          "id": 1,
          "platform": {
            "uuid": "22222222-2222-2222-2222-222222222222",
            "name": "Example Platform",
            "public_key": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"
          },
          "name": "guest",
          "localized_name": "Guest",
          "permissions": [ { "subject": "complaint", "action": "store" } ]
        }
      ],
      "is_backoffice": false,
      "is_service_provider": false
    }
  },
  "jwt": {
    "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.example",
    "refresh_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.refresh",
    "id_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.idtoken",
    "token_type": "Bearer",
    "expires_in": 300,
    "refresh_expires_in": 1800,
    "scope": "openid profile email",
    "issuer": "https://sso.echosistema.live/realms/echosistema",
    "subject": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "provider": { "driver": "keycloak", "name": "Keycloak Default", "kind": "oidc" }
  },
  "visitor_ip": "203.0.113.42"
}

Testar endpoint

Servidor

X-PUBLIC-KEYobrigatórioAccept-Language

with_projects

Corpo (JSON)

Encerrar sessão

POST/api/v1/auth/logoutBearer (Sanctum)

Revoga o token Sanctum atual e tenta encerrar a sessão Keycloak com o refresh_token do cache Redis, em melhor esforço e sem corpo na requisição. A resposta é 200 mesmo se o Keycloak falhar, e o cache é limpo sempre.

Cabeçalhos

Authorizationstringobrigatório
Token Sanctum no formato Bearer.

Respostas

200
Token revogado, em melhor esforço; sempre 200.
401
Bearer ausente ou inválido.
500
Erro interno.

Requisição

curl -X POST https://echosistema.live/api/v1/auth/logout \
  -H "Authorization: Bearer 1|a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0"

Resposta 200

{
  "message": "Goodbye, Sample User!"
}

Testar endpoint

Servidor

Authorizationobrigatório

Manter sessão

GET/api/v1/auth/keep-aliveBearer (Sanctum)

Estende a sessão Sanctum e tenta renovar o JWT do Keycloak a partir do Redis. Três variantes: jwt renovado; jwt null com warning jwt_refresh_failed; ou resposta sem a chave jwt quando nunca houve SSO. A validade do Sanctum nunca depende do Keycloak.

Cabeçalhos

Authorizationstringobrigatório
Token Sanctum no formato Bearer.

Respostas

200
Sessão estendida; jwt renovado, null com warning, ou ausente.
401
Bearer ausente ou inválido.
500
Erro interno.

Requisição

curl https://echosistema.live/api/v1/auth/keep-alive \
  -H "Authorization: Bearer 1|a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0"

Resposta 200

{
  "message": "Session extended, Sample User.",
  "jwt": {
    "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.newtoken",
    "refresh_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.newrefresh",
    "id_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.newidtoken",
    "token_type": "Bearer",
    "expires_in": 300,
    "refresh_expires_in": 1800,
    "scope": "openid profile email",
    "issuer": "https://sso.echosistema.live/realms/echosistema",
    "subject": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "provider": { "driver": "keycloak", "name": "Keycloak Default", "kind": "oidc" }
  },
  "visitor_ip": "203.0.113.42"
}

Testar endpoint

Servidor

Authorizationobrigatório

Perfil do usuário

GET/api/v1/me/profileBearer (Sanctum)

Devolve o perfil completo do usuário autenticado em data: identidade, imagens no formato unificado de cartão (avatar, banner e profile), papéis com permissões, contatos, endereços, nacionalidades, biografia, plataforma e afiliado.

Cabeçalhos

Authorizationstringobrigatório
Token Sanctum no formato Bearer.
X-PUBLIC-KEYstring (uuid)obrigatório
Chave pública que identifica a plataforma.
Accept-Languagestring
Idioma da resposta: pt-BR, en, es ou gn.

Respostas

200
Perfil completo em data.
401
Bearer ausente ou inválido.
403
Sem permissão.
404
Usuário não encontrado.
500
Erro interno.

Requisição

curl https://echosistema.live/api/v1/me/profile \
  -H "Authorization: Bearer 1|a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0" \
  -H "X-PUBLIC-KEY: 33333333-3333-3333-3333-333333333333" \
  -H "Accept-Language: pt-BR"

Resposta 200

{
  "data": {
    "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "echo_uuid": "e1c1h1o1a1b2c3d4e5f6789012345678901234",
    "name": "Sample User",
    "email": "sample.user@domain.com",
    "email_verified_at": "2026-01-15T10:30:00.000000Z",
    "slug": "sample-user",
    "avatar": {
      "unique_id": null,
      "uuid": null,
      "url": "https://storage.echosistema.live/live/common/images/default-avatar.webp",
      "usage": "avatar"
    },
    "banner": {
      "unique_id": null,
      "uuid": null,
      "url": "https://storage.echosistema.live/live/common/images/default-banner.webp",
      "usage": "banner"
    },
    "profile_image": {
      "unique_id": null,
      "uuid": null,
      "url": "https://storage.echosistema.live/live/common/images/default-profile.webp",
      "usage": "profile"
    },
    "age": null,
    "gender": null,
    "gender_name": null,
    "birthday": null,
    "is_banned": false,
    "is_foreign": false,
    "is_master": false,
    "language": "pt-BR",
    "currency": "BRL",
    "created_at": "2025-11-02T14:05:00.000000Z",
    "roles": [
      {
        "id": 1,
        "uuid": "11111111-1111-1111-1111-111111111111",
        "name": "guest",
        "localized_name": "Convidado",
        "permissions": ["complaint.store"]
      }
    ],
    "telephone": null,
    "contacts": [],
    "social_medias": [],
    "address": null,
    "addresses": [],
    "nationalities": [],
    "biography": null,
    "platform": {
      "id": 2,
      "uuid": "22222222-2222-2222-2222-222222222222",
      "name": "Sample Platform"
    },
    "affiliate": null,
    "identities": [],
    "raw": null
  }
}

Testar endpoint

Servidor

AuthorizationobrigatórioX-PUBLIC-KEYobrigatórioAccept-Language

Atualizar senha

PUT/api/v1/me/passwordBearer (Sanctum)

Troca a senha do usuário autenticado: exige a senha atual, mínimo de 6 caracteres e confirmação, e a nova precisa ser diferente. Depois do save local, a senha é propagada em melhor esforço ao provedor de identidade e a cada IdentityProviderLink ativo, com retentativas em back-off; falha de IdP nunca bloqueia a troca local, e a senha em claro nunca vai para log nem para payload de fila.

Cabeçalhos

Authorizationstringobrigatório
Token Sanctum no formato Bearer.
X-PUBLIC-KEYstring (uuid)obrigatório
Chave pública que identifica a plataforma.
Accept-Languagestring
Idioma da resposta: pt-BR, en, es ou gn.

Corpo

current_passwordstring (password)obrigatório
Senha atual, verificada antes da troca.
passwordstring (min 6)obrigatório
Senha nova, mínimo de 6 caracteres e diferente da atual.
password_confirmationstringobrigatório
Confirmação, igual à senha.

Respostas

200
Senha atualizada; a propagação ao SSO segue em segundo plano.
400
A senha nova é igual à atual.
401
Bearer ausente ou inválido.
422
Erro de validação nos campos ou parâmetros.
500
Erro interno.

Requisição

curl -X PUT https://echosistema.live/api/v1/me/password \
  -H "Authorization: Bearer 1|a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0" \
  -H "X-PUBLIC-KEY: 33333333-3333-3333-3333-333333333333" \
  -H "Content-Type: application/json" \
  -d '{
    "current_password": "currentPassword123",
    "password": "newSecurePassword456",
    "password_confirmation": "newSecurePassword456"
  }'

Resposta 200

{
  "message": "Password updated successfully."
}

Testar endpoint

Servidor

AuthorizationobrigatórioX-PUBLIC-KEYobrigatórioAccept-Language

Corpo (JSON)

Listar países

GET/api/v1/public/countriesPública

Lista paginada de países com filtros por código ISO, nome, capital, moeda, idioma e fuso. Rota pública; minimum=true devolve só os campos essenciais, ideal para dropdowns.

Cabeçalhos

X-PUBLIC-KEYstring (uuid)obrigatório
Chave pública que identifica a plataforma.
Accept-Languagestring
Idioma da resposta: pt-BR, en, es ou gn.

Query

codestring (2)
Código ISO 3166-1 alpha-2, busca exata.
namestring
Nome do país, busca parcial sem diferenciar maiúsculas.
cca3string (3)
Código ISO 3166-1 alpha-3.
ccn3string (3)
Código numérico ISO 3166-1.
ciocstring (3)
Código do Comitê Olímpico Internacional.
capitalstring
Nome da capital.
timezonestring
Fuso horário no formato IANA.
currencystring (3)
Código da moeda ISO 4217.
languagesstring
Código do idioma ISO 639-1.
minimumboolean
Com true, devolve só id, uuid, code, name e official_name.
statesstring
Carrega os estados: IDs, nomes, ou vazio para todos.
has_subdivisionsboolean
Filtra pela presença de subdivisões: true só países com estados, false só os que expõem cidades direto.
orderBystring
Campo de ordenação: id, name, code, official_name ou created_at.
pageinteger
Página da paginação.
per_pageinteger (1-200)
Registros por página, de 1 a 200.
no_paginateboolean
Com true, devolve tudo sem paginação.

Respostas

200
Lista paginada em data, com links e meta.
422
Erro de validação nos campos ou parâmetros.
429
Rate limit excedido.
500
Erro interno.

Requisição

curl "https://echosistema.live/api/v1/public/countries?code=BR" \
  -H "X-PUBLIC-KEY: pk_live_abc123def456" \
  -H "Accept-Language: pt-BR"

Resposta 200

{
  "data": [
    {
      "id": 1,
      "uuid": "32860919-8031-3f86-89e8-a71e5452bf6f",
      "code": "BR",
      "name": "Brazil",
      "official_name": "Federative Republic of Brazil",
      "has_subdivisions": true,
      "geolocation": { "latitude": -15.7942, "longitude": -47.8822 },
      "details": {
        "map": "https://goo.gl/maps/waCKk21HeeqFzkNC9",
        "flag": "🇧🇷",
        "name": "Brazil",
        "codes": { "cca3": "BRA", "ccn3": "076", "cioc": "BRA" },
        "region": "Americas",
        "borders": ["ARG", "BOL", "COL", "GUF", "GUY", "PRY", "PER", "SUR", "URY", "VEN"],
        "capital": "Brasília",
        "languages": [{ "code": "por", "name": "Portuguese" }],
        "subregion": "South America",
        "timezones": ["UTC-05:00", "UTC-04:00", "UTC-03:00", "UTC-02:00"],
        "continents": ["South America"],
        "currencies": [{ "code": "BRL", "name": "Brazilian real", "symbol": "R$" }],
        "postal_code": { "regex": "^(\\d{8})$", "format": "#####-###" },
        "coat_of_arms": {
          "png": "https://mainfacts.com/media/images/coats_of_arms/br.png",
          "svg": "https://mainfacts.com/media/images/coats_of_arms/br.svg"
        },
        "official_name": "Federative Republic of Brazil"
      }
    }
  ],
  "links": {
    "first": "http://echosistema.dev/api/v1/public/countries?page=1",
    "last": "http://echosistema.dev/api/v1/public/countries?page=1",
    "prev": null,
    "next": null
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 1,
    "path": "http://echosistema.dev/api/v1/public/countries",
    "per_page": 25,
    "to": 1,
    "total": 1
  }
}

Testar endpoint

Servidor

X-PUBLIC-KEYobrigatórioAccept-Language

codenamecca3ccn3cioccapitaltimezonecurrencylanguagesminimumstateshas_subdivisionsorderBypageper_pageno_paginate

Detalhar país

GET/api/v1/public/countries/{country}Pública

Detalhes completos de um país. O parâmetro country aceita o código ISO alpha-2 (BR) ou o ID numérico. A resposta traz states com todos os estados quando o país tem subdivisões; sem elas, expõe cities. images e texts carregam as relações de CDN e CMS.

Cabeçalhos

X-PUBLIC-KEYstring (uuid)obrigatório
Chave pública que identifica a plataforma.
Accept-Languagestring
Idioma da resposta: pt-BR, en, es ou gn.

Caminho

countrystringobrigatório
Identificador do país: código ISO alpha-2 (BR) ou ID numérico. Verificado no staging: UUID e código alpha-3 (BRA) devolvem 500.

Query

minimumboolean
Com true, devolve só id, uuid, code, name e official_name.
imagesboolean
Com true, carrega a relação images (usage mini_card).
textsboolean
Com true, carrega os textos de CMS; content segue a convenção title + corpo.
statesstring
Carrega os estados: IDs, nomes, ou vazio para todos.

Respostas

200
Detalhes do país em data.
404
País não encontrado.
429
Rate limit excedido.
500
Erro interno.

Requisição

curl https://echosistema.live/api/v1/public/countries/BR \
  -H "X-PUBLIC-KEY: pk_live_abc123def456" \
  -H "Accept-Language: pt-BR"

Resposta 200

{
  "data": {
    "id": 1,
    "uuid": "32860919-8031-3f86-89e8-a71e5452bf6f",
    "code": "BR",
    "name": "Brazil",
    "official_name": "Federative Republic of Brazil",
    "has_subdivisions": true,
    "geolocation": { "latitude": -15.7942, "longitude": -47.8822 },
    "details": {
      "map": "https://goo.gl/maps/waCKk21HeeqFzkNC9",
      "flag": "🇧🇷",
      "name": "Brazil",
      "codes": { "cca3": "BRA", "ccn3": "076", "cioc": "BRA" },
      "region": "Americas",
      "borders": ["ARG", "BOL", "COL", "GUF", "GUY", "PRY", "PER", "SUR", "URY", "VEN"],
      "capital": "Brasília",
      "languages": [{ "code": "por", "name": "Portuguese" }],
      "subregion": "South America",
      "timezones": ["UTC-05:00", "UTC-04:00", "UTC-03:00", "UTC-02:00"],
      "continents": ["South America"],
      "currencies": [{ "code": "BRL", "name": "Brazilian real", "symbol": "R$" }],
      "postal_code": { "regex": "^(\\d{8})$", "format": "#####-###" },
      "coat_of_arms": {
        "png": "https://mainfacts.com/media/images/coats_of_arms/br.png",
        "svg": "https://mainfacts.com/media/images/coats_of_arms/br.svg"
      },
      "official_name": "Federative Republic of Brazil"
    },
    "states": [
      { "id": 1, "uuid": "43181d2e-7efd-3fb4-a831-f19149e0780b", "abbreviation": "AC", "name": "Acre", "region": "Norte" },
      { "id": 2, "uuid": "beee0aab-324c-3683-bd3b-18c9aeda7948", "abbreviation": "AL", "name": "Alagoas", "region": "Nordeste" },
      { "id": 3, "uuid": "11695e3e-d7f0-3b68-bef0-5a97515ade35", "abbreviation": "AP", "name": "Amapá", "region": "Norte" }
    ]
  }
}

Testar endpoint

Servidor

X-PUBLIC-KEYobrigatórioAccept-Language

countryobrigatório

minimumimagestextsstates

Detalhar estado

GET/api/v1/public/countries/{country}/states/{state}Pública

Detalhes de um estado dentro de um país. O parâmetro state aceita o nome, o ID numérico ou o UUID; nome com acento e espaço viaja codificado na URL. A resposta traz o país aninhado e as cidades. O 404 também cobre estado que não pertence ao país informado.

Cabeçalhos

X-PUBLIC-KEYstring (uuid)obrigatório
Chave pública que identifica a plataforma.
Accept-Languagestring
Idioma da resposta: pt-BR, en, es ou gn.

Caminho

countrystringobrigatório
Identificador do país: código ISO alpha-2 (BR) ou ID numérico. Verificado no staging: UUID e código alpha-3 (BRA) devolvem 500.
statestringobrigatório
Identificador do estado: nome (São Paulo), ID numérico ou UUID. Verificado no staging: slug (sao-paulo) devolve 500 e a sigla (SP) devolve 404.

Query

imagesboolean
Com true, carrega a relação images (usage mini_card).
textsboolean
Com true, carrega os textos de CMS; content segue a convenção title + corpo.

Respostas

200
Detalhes do estado em data.
404
Não encontrado: país, estado, ou estado que não pertence ao país.
422
Erro de validação nos campos ou parâmetros.
429
Rate limit excedido.
500
Erro interno.

Requisição

curl "https://echosistema.live/api/v1/public/countries/BR/states/S%C3%A3o%20Paulo" \
  -H "X-PUBLIC-KEY: pk_live_abc123def456" \
  -H "Accept-Language: pt-BR"

Resposta 200

{
  "data": {
    "id": 25,
    "uuid": "db073d1d-ebe2-34e8-bf34-4884acdb475e",
    "country_id": 1,
    "name": "São Paulo",
    "abbreviation": "SP",
    "region": "Sudeste",
    "country": {
      "uuid": "32860919-8031-3f86-89e8-a71e5452bf6f",
      "name": "Brazil",
      "official_name": "Federative Republic of Brazil",
      "code": "BR"
    },
    "cities": [
      {
        "id": 2180,
        "uuid": "b5080cd5-9b2d-38cc-a6ef-7d6dfbfb2e74",
        "name": "São Paulo"
      }
    ]
  }
}

Testar endpoint

Servidor

X-PUBLIC-KEYobrigatórioAccept-Language

countryobrigatóriostateobrigatório

imagestexts

Detalhar cidade

GET/api/v1/public/countries/{country}/states/{state}/cities/{city}Pública

Detalhes de uma cidade dentro de um estado e país, com validação de pertencimento em cadeia. Os identificadores aceitam nome, ID numérico ou UUID; a resposta traz país e estado aninhados.

Cabeçalhos

X-PUBLIC-KEYstring (uuid)obrigatório
Chave pública que identifica a plataforma.
Accept-Languagestring
Idioma da resposta: pt-BR, en, es ou gn.

Caminho

countrystringobrigatório
Identificador do país: código ISO alpha-2 (BR) ou ID numérico. Verificado no staging: UUID e código alpha-3 (BRA) devolvem 500.
statestringobrigatório
Identificador do estado: nome (São Paulo), ID numérico ou UUID. Verificado no staging: slug (sao-paulo) devolve 500 e a sigla (SP) devolve 404.
citystringobrigatório
Identificador da cidade: nome (São Paulo), ID numérico ou UUID.

Query

textsboolean
Com true, carrega os textos de CMS; content segue a convenção title + corpo.

Respostas

200
Detalhes da cidade em data.
404
Não encontrado: país, estado, cidade, ou vínculo quebrado na cadeia.
422
Erro de validação nos campos ou parâmetros.
429
Rate limit excedido.
500
Erro interno.

Requisição

curl "https://echosistema.dev/api/v1/public/countries/BR/states/S%C3%A3o%20Paulo/cities/S%C3%A3o%20Paulo" \
  -H "X-PUBLIC-KEY: pk_live_abc123def456" \
  -H "Accept-Language: pt-BR"

Resposta 200

{
  "data": {
    "id": 2180,
    "uuid": "b5080cd5-9b2d-38cc-a6ef-7d6dfbfb2e74",
    "state_id": 25,
    "country_id": 1,
    "name": "São Paulo",
    "abbreviation": null,
    "country": {
      "uuid": "32860919-8031-3f86-89e8-a71e5452bf6f",
      "name": "Brazil",
      "official_name": "Federative Republic of Brazil",
      "code": "BR"
    },
    "state": {
      "uuid": "db073d1d-ebe2-34e8-bf34-4884acdb475e",
      "name": "São Paulo",
      "abbreviation": "SP",
      "region": "Sudeste"
    }
  }
}

Testar endpoint

Servidor

X-PUBLIC-KEYobrigatórioAccept-Language

countryobrigatóriostateobrigatóriocityobrigatório

texts

Detalhar cidade (Shared)

GET/api/v1/cities/{city}Pública

A ficha rica da cidade, fora da árvore de países: resolve o por UUID ou nome e traz país, estado, imagens e o conteúdo editorial (titles, topics e description). Verificado no staging: exige X-PUBLIC-KEY, e sem ela responde 403.

Cabeçalhos

X-PUBLIC-KEYstring (uuid)obrigatório
Chave pública que identifica a plataforma.
Accept-Languagestring
Idioma da resposta: pt-BR, en, es ou gn.

Caminho

citystringobrigatório
Identificador da cidade: UUID ou nome, detectado automaticamente pelo resolveRouteBinding.

Query

languagestring
Tag IETF que filtra titles, topics e description; entradas com is_default seguem incluídas. Sem ela, vem tudo.

Respostas

200
Ficha da cidade em data, com o conteúdo editorial já filtrado.
403
Chave pública ausente ou inválida.
404
Não encontrado: país, estado, cidade, ou vínculo quebrado na cadeia.
500
Erro interno.

Requisição

curl "https://echosistema.dev/api/v1/cities/Encarnaci%C3%B3n?language=es" \
  -H "X-PUBLIC-KEY: pk_live_abc123def456"

Resposta 200

{
  "data": {
    "uuid": "35e51559-f130-31d0-bfb8-95b6c1caabfc",
    "name": "Encarnación",
    "abbreviation": "ENC",
    "country": {
      "uuid": "2eb81f74-aded-3702-b132-a7f1ce4bdf05",
      "code": "PY",
      "name": "Paraguay"
    },
    "state": {
      "uuid": "c5f7a378-0994-319b-8620-809ce6955557",
      "name": "Itapuá",
      "abb": "IT"
    },
    "images": [
      {
        "usage": "card",
        "url": "https://storage.echosistema.dev/staging/platform/echosistema/images/card/5a1f2e4d-3180-3d3b-9d60-5401e538ce3d.webp",
        "unique_id": "a796787b"
      }
    ],
    "titles": [
      {
        "index": 1,
        "uuid": "35e51559-f130-31d0-bfb8-95b6c1caabfc",
        "content": "Gestión de Propiedades",
        "language": "es",
        "is_default": true,
        "usage": "city_info",
        "details": "Encarnación experimenta un crecimiento inmobiliario acelerado…"
      }
    ],
    "topics": [
      {
        "usage": "cost_of_living",
        "language": "es",
        "is_default": true,
        "title": "Custo de vida",
        "body": "<p>Vivir en Encarnación resulta más accesible que en Asunción…</p>",
        "icon": "ri-money-dollar-circle-line"
      }
    ],
    "description": [
      {
        "usage": "general_description",
        "language": "es",
        "is_default": true,
        "title": null,
        "body": "<p>Encarnación, conocida como La Perla del Sur, es la capital…</p>"
      }
    ]
  }
}

Testar endpoint

Servidor

X-PUBLIC-KEYobrigatórioAccept-Language

cityobrigatório

language