Índice da referência

Geral

Visão geral

Auth

Autenticar usuário
Registrar usuário
Usuário da sessão
Permissões do usuário
Encerrar sessão
Manter sessão
Esqueci a senha
Redefinir a senha
Emitir token de handoff
Trocar token de handoff

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 por cookie de sessão BFF 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 cookie de sessão HttpOnly que o login grava - nenhuma credencial volta no corpo, e nem `token` nem `jwt` existem mais como campo; chamadas que alteram dados ainda devolvem o cookie XSRF-TOKEN no cabeçalho X-XSRF-TOKEN. Depois de um reload, reconstrua o usuário com GET /auth/me em vez de pedir a senha de novo. Accept-Language (pt-BR, en, es, gn) traduz nomes e mensagens.

Servidor

https://echosistema.live

Uma origem só, a deste deploy: `NUXT_PUBLIC_API_PROD_BASE_URL` no .env, a mesma que o site usa para login e demais chamadas. Apontar para outro ambiente é trocar essa variável - e ela move a documentação, o painel de teste e a aplicação juntos.

Autenticar usuário

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

Autentica via HTTP Basic (email:senha em Base64) e abre uma sessão BFF por cookie: o 200 grava echosistema_bff_session (HttpOnly, validade absoluta de 7 dias) e o XSRF-TOKEN legível. Nenhuma credencial volta no corpo - a resposta não traz `token` nem `jwt`. A identidade é projetada no Keycloak em segundo plano e o JWT resultante fica no servidor; falhar ali não invalida o 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

devicestringobrigatório
Nome do dispositivo, registrado para auditoria. Não rotula mais nenhum token.
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 cookie de sessão foi gravado e o corpo traz o usuário, sem credencial de nenhum tipo.
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" \
  --cookie-jar cookies.txt \
  -d '{ "device": "web-browser" }'

Resposta 200

{
  "message": "User authenticated successfully!",
  "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"
        }
      ],
      "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"
        }
      ],
      "is_backoffice": false,
      "is_service_provider": false
    }
  },
  "visitor_ip": "203.0.113.42"
}

Testar endpoint

Servidor

https://echosistema.live

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. Abre a sessão por cookie e devolve o bloco jwt igual ao 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, registrado para auditoria. Não rotula mais nenhum token.
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"
        }
      ],
      "is_backoffice": false,
      "is_service_provider": false
    }
  },
  "visitor_ip": "203.0.113.42"
}

Testar endpoint

Servidor

https://echosistema.live

X-PUBLIC-KEYobrigatórioAccept-Language

with_projects

Corpo (JSON)

Encerrar sessão

POST/api/v1/auth/logoutCookie de sessão

Destrói a sessão BFF, limpa o JWT do Keycloak em cache 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 os dois cookies são apagados de todo jeito.

Cabeçalhos

Cookiestringobrigatório
Cookie de sessão HttpOnly, gravado pelo login e reenviado pelo navegador. No navegador nunca se monta à mão: basta enviar a chamada com credentials: 'include'.
X-XSRF-TOKENstringobrigatório
Dupla submissão de CSRF: o valor do cookie legível XSRF-TOKEN. Obrigatório em POST, PUT, PATCH e DELETE; sem ele a resposta é 419.

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 \
  --cookie cookies.txt \
  -H "X-PUBLIC-KEY: 33333333-3333-3333-3333-333333333333" \
  -H "X-XSRF-TOKEN: eyJpdiI6..."

Resposta 200

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

Testar endpoint

Servidor

https://echosistema.live

CookieobrigatórioX-XSRF-TOKENobrigatório

Manter sessão

GET/api/v1/auth/keep-aliveCookie de sessão

Renova o JWT do Keycloak a partir do Redis. NÃO estende a sessão: a janela do BFF é absoluta e nada a renova, então uma renovação que falha nunca custa a sessão de quem chamou. Três variantes: jwt renovado; jwt null com warning jwt_refresh_failed; ou resposta sem a chave jwt quando nunca houve SSO.

Cabeçalhos

Cookiestringobrigatório
Cookie de sessão HttpOnly, gravado pelo login e reenviado pelo navegador. No navegador nunca se monta à mão: basta enviar a chamada com credentials: 'include'.

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 \
  --cookie cookies.txt \
  -H "X-PUBLIC-KEY: 33333333-3333-3333-3333-333333333333"

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

https://echosistema.live

Cookieobrigatório

Usuário da sessão

GET/api/v1/auth/meCookie de sessão

Devolve o usuário da sessão no MESMO formato do login. É a rota do reload: o cookie sobrevive, o data.user que estava em memória não. Não emite cookie, não emite token e não dispara projeção no Keycloak, então chamá-la a cada carga de página é livre de efeito colateral.

Cabeçalhos

Cookiestringobrigatório
Cookie de sessão HttpOnly, gravado pelo login e reenviado pelo navegador. No navegador nunca se monta à mão: basta enviar a chamada com credentials: 'include'.
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.

Respostas

200
O usuário da sessão, no mesmo formato do login. Sem Set-Cookie e sem credencial.
401
Bearer ausente ou inválido.
500
Erro interno.

Requisição

curl https://echosistema.live/api/v1/auth/me \
  --cookie cookies.txt \
  -H "X-PUBLIC-KEY: 33333333-3333-3333-3333-333333333333" \
  -H "Accept-Language: pt-BR"

Resposta 200

{
  "message": "Sample User successfully authenticated!",
  "data": {
    "user": {
      "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "Sample User",
      "email": "sample.user@domain.com",
      "avatar": { "url": "https://example.com/avatar.png", "usage": "avatar" },
      "language": "pt-BR",
      "currency": "BRL",
      "roles": [
        {
          "id": 1,
          "platform": {
            "uuid": "22222222-2222-2222-2222-222222222222",
            "name": "Sample Platform",
            "public_key": "33333333-3333-3333-3333-333333333333"
          },
          "name": "guest",
          "localized_name": "Convidado"
        }
      ],
      "is_backoffice": false,
      "is_service_provider": false
    }
  },
  "visitor_ip": "203.0.113.42"
}

Testar endpoint

Servidor

https://echosistema.live

CookieobrigatórioX-PUBLIC-KEYobrigatórioAccept-Language

with_projects

Permissões do usuário

GET/api/v1/auth/permissionsCookie de sessão

A fonte única de autorização do SPA. As permissões chegam em dois formatos da MESMA lista: permissions (strings acao.escopo, para checagem programática) e permissions_formatted (objetos, para telas que agrupam por assunto). O teste é match exato OU o curinga .all. Nunca derive permissão de data.user.roles: papel é escopo, não permissão.

Cabeçalhos

Cookiestringobrigatório
Cookie de sessão HttpOnly, gravado pelo login e reenviado pelo navegador. No navegador nunca se monta à mão: basta enviar a chamada com credentials: 'include'.
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
Papéis (zero ou um, escopados nesta plataforma) e a lista de permissões em dois formatos.
401
Bearer ausente ou inválido.
500
Erro interno.

Requisição

curl https://echosistema.live/api/v1/auth/permissions \
  --cookie cookies.txt \
  -H "X-PUBLIC-KEY: 33333333-3333-3333-3333-333333333333"

Resposta 200

{
  "success": true,
  "roles": [
    {
      "id": 2,
      "name": "administrator",
      "localized_name": "Administrador",
      "platform": {
        "uuid": "8f14e45f-ceea-4b8f-8c0e-5a4a1b3d1a2c",
        "name": "EchoSistema",
        "public_key": "33333333-3333-3333-3333-333333333333"
      }
    }
  ],
  "permissions": ["destroy.schedule", "index.all", "index.schedule", "show.all"],
  "permissions_formatted": [
    { "action": "destroy", "subject": "schedule" },
    { "action": "index",   "subject": "all" },
    { "action": "index",   "subject": "schedule" },
    { "action": "show",    "subject": "all" }
  ]
}

Testar endpoint

Servidor

https://echosistema.live

CookieobrigatórioX-PUBLIC-KEYobrigatórioAccept-Language

Esqueci a senha

POST/api/v1/auth/password/forgotPública

Dispara o e-mail de recuperação. Responde 200 exista o endereço ou não, de propósito: distinguir os dois casos entregaria a lista de quem tem conta na plataforma. Não interprete a mensagem para inferir existência.

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.

Corpo

emailstring (email)obrigatório
E-mail, único por plataforma.

Respostas

200
Pedido recebido. Vem 200 mesmo quando o endereço não existe.
422
Erro de validação nos campos ou parâmetros.
429
Rate limit excedido.
500
Erro interno.

Requisição

curl -X POST https://echosistema.live/api/v1/auth/password/forgot \
  -H "X-PUBLIC-KEY: 33333333-3333-3333-3333-333333333333" \
  -H "Content-Type: application/json" \
  -d '{ "email": "sample.user@domain.com" }'

Resposta 200

{
  "success": true,
  "message": "Enviamos seu link de redefinição de senha por e-mail!"
}

Testar endpoint

Servidor

https://echosistema.live

X-PUBLIC-KEYobrigatórioAccept-Language

Corpo (JSON)

Redefinir a senha

POST/api/v1/auth/password/resetPública

Redefine a senha pelo link do e-mail. O token e o e-mail vêm da query do link (?token= e ?email=) e voltam no corpo exatamente como chegaram. O token é assinado, de uso único e expira; um 400 significa pedir um link novo, não tentar de novo.

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.

Corpo

emailstring (email)obrigatório
E-mail, único por plataforma.
tokenstringobrigatório
Token assinado que veio no ?token= do link de recuperação, devolvido como chegou.
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 redefinida; o token foi consumido e não serve de novo.
400
Token já usado, expirado ou que não corresponde ao e-mail. Peça um link novo.
422
Erro de validação nos campos ou parâmetros.
429
Rate limit excedido.
500
Erro interno.

Requisição

curl -X POST https://echosistema.live/api/v1/auth/password/reset \
  -H "X-PUBLIC-KEY: 33333333-3333-3333-3333-333333333333" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "sample.user@domain.com",
    "token": "9f2c1a...",
    "password": "newSecurePassword456",
    "password_confirmation": "newSecurePassword456"
  }'

Resposta 200

{
  "success": true,
  "message": "Senha redefinida com sucesso!"
}

Testar endpoint

Servidor

https://echosistema.live

X-PUBLIC-KEYobrigatórioAccept-Language

Corpo (JSON)

Emitir token de handoff

POST/api/v1/auth/flash-token/issueCookie de sessão

Cunha um token de handoff de uso único, válido por 60 segundos, para a sessão atual. Serve para levar a sessão a outro domínio do grupo sem repetir a senha: o cookie é preso a um domínio, e este token é o direito de abrir sessão na outra origem.

Cabeçalhos

Cookiestringobrigatório
Cookie de sessão HttpOnly, gravado pelo login e reenviado pelo navegador. No navegador nunca se monta à mão: basta enviar a chamada com credentials: 'include'.
X-XSRF-TOKENstringobrigatório
Dupla submissão de CSRF: o valor do cookie legível XSRF-TOKEN. Obrigatório em POST, PUT, PATCH e DELETE; sem ele a resposta é 419.
X-PUBLIC-KEYstring (uuid)obrigatório
Chave pública que identifica a plataforma.

Corpo

devicestring
Nome do dispositivo, registrado para auditoria. Não rotula mais nenhum token.

Respostas

200
Token cunhado, com expires_in sempre 60.
401
Bearer ausente ou inválido.
429
Rate limit excedido.
500
Erro interno.

Requisição

curl -X POST https://echosistema.live/api/v1/auth/flash-token/issue \
  --cookie cookies.txt \
  -H "X-PUBLIC-KEY: 33333333-3333-3333-3333-333333333333" \
  -H "X-XSRF-TOKEN: eyJpdiI6..." \
  -H "Content-Type: application/json" \
  -d '{ "device": "web-browser" }'

Resposta 200

{
  "success": true,
  "flash_token": "6791a3b2c4d5e6f7.es3a7b9c1d2e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1",
  "expires_in": 60
}

Testar endpoint

Servidor

https://echosistema.live

CookieobrigatórioX-XSRF-TOKENobrigatórioX-PUBLIC-KEYobrigatório

Corpo (JSON)

Trocar token de handoff

POST/api/v1/auth/flash-tokenPública

Gasta o token de handoff e abre uma sessão NOVA nesta origem. É público porque o token é a credencial, e por isso também é isento de CSRF. Transporte o token no FRAGMENTO da URL (#flash=), nunca na query string, e limpe-o do endereço assim que for gasto.

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.

Corpo

flash_tokenstring (32-512)obrigatório
O token de handoff em texto puro, no formato .es. Se você o transportou em base64, decodifique antes de enviar.
devicestring
Nome do dispositivo, registrado para auditoria. Não rotula mais nenhum token.

Respostas

200
Sessão aberta nesta origem; vêm os dois cookies, como no login.
401
Token inexistente, já gasto ou expirado. Ele morre na primeira leitura, então não há o que repetir.
422
Erro de validação nos campos ou parâmetros.
429
Rate limit excedido.
500
Erro interno.

Requisição

curl -X POST https://echosistema.live/api/v1/auth/flash-token \
  -H "X-PUBLIC-KEY: 33333333-3333-3333-3333-333333333333" \
  -H "Content-Type: application/json" \
  --cookie-jar cookies.txt \
  -d '{ "flash_token": "6791a3b2c4d5e6f7.es3a7b...", "device": "web-browser" }'

Resposta 200

{
  "message": "Sample User successfully authenticated!",
  "data": {
    "user": {
      "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "Sample User",
      "email": "sample.user@domain.com",
      "is_backoffice": false,
      "is_service_provider": false
    }
  },
  "visitor_ip": "203.0.113.42"
}

Testar endpoint

Servidor

https://echosistema.live

X-PUBLIC-KEYobrigatórioAccept-Language

Corpo (JSON)

Perfil do usuário

GET/api/v1/me/profileCookie de sessão

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

Cookiestringobrigatório
Cookie de sessão HttpOnly, gravado pelo login e reenviado pelo navegador. No navegador nunca se monta à mão: basta enviar a chamada com credentials: 'include'.
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 \
  --cookie cookies.txt \
  -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

https://echosistema.live

CookieobrigatórioX-PUBLIC-KEYobrigatórioAccept-Language

Atualizar senha

PUT/api/v1/me/passwordCookie de sessão

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

Cookiestringobrigatório
Cookie de sessão HttpOnly, gravado pelo login e reenviado pelo navegador. No navegador nunca se monta à mão: basta enviar a chamada com credentials: 'include'.
X-XSRF-TOKENstringobrigatório
Dupla submissão de CSRF: o valor do cookie legível XSRF-TOKEN. Obrigatório em POST, PUT, PATCH e DELETE; sem ele a resposta é 419.
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 \
  --cookie cookies.txt \
  -H "X-XSRF-TOKEN: eyJpdiI6..." \
  -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

https://echosistema.live

CookieobrigatórioX-XSRF-TOKENobrigató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

https://echosistema.live

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

https://echosistema.live

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

https://echosistema.live

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

https://echosistema.live

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

https://echosistema.live

X-PUBLIC-KEYobrigatórioAccept-Language

cityobrigatório

language