Carbob API - Documentação Completa

Visão Geral

Esta documentação descreve todos os endpoints disponíveis na API Carbob. A API utiliza Laravel Passport para autenticação OAuth2 com suporte a multi-tenancy, incluindo funcionalidades de autenticação, gestão de usuários, password recovery e gestão de recursos.

Base URL

https://api.carbob.pt

Versionamento da API

A API Carbob suporta acesso aos endpoints de duas formas:

Rotas Versionadas

Todas as rotas podem ser acessadas com prefixo de versão explícito (ex: /v1/clients). Estas rotas sempre funcionam e garantem compatibilidade total, mesmo quando a versão padrão mudar no futuro.

Rotas Sem Versão (Versão Padrão)

As rotas também podem ser acessadas sem prefixo de versão (ex: /clients), apontando automaticamente para a versão padrão configurada em config/api.php. Atualmente, a versão padrão é v1.

Exemplos:

POST /v1/register ou POST /register - Ambas funcionam

GET /v1/clients ou GET /clients - Ambas funcionam

Nota: Rotas OAuth (/oauth/*) não têm versão e permanecem como estão.

Recomendação: Para integrações de longo prazo, use rotas versionadas (/v1/*) para garantir estabilidade. Use rotas sem versão (/*) apenas quando quiser automaticamente usar a versão mais recente configurada.

Status da API

Versão: 1.0.0

Última Atualização: Janeiro 2025

Funcionalidades: Autenticação, Multi-tenancy, Password Recovery, Gestão de Projetos

Índice

1. [Autenticação](#autenticação)

2. [Endpoints de Autenticação](#endpoints-de-autenticação)

- [Registro de Usuário](#1-registro-de-novo-usuário-e-tenant)
- [Obter Token](#2-obter-token-de-acesso)
- [Solicitar Reset de Senha](#3-solicitar-reset-de-senha)
- [Resetar Senha](#4-resetar-senha)

3. [Endpoints OAuth2](#5-endpoints-oauth2-do-passport)

4. [Endpoints de Recursos](#endpoints-de-recursos)

5. [Endpoints de Gestão de Usuário](#endpoints-de-gestão-de-usuário)

6. [Endpoints de Teste](#endpoints-de-teste-e-debug)

7. [Códigos de Status](#códigos-de-status-http)

8. [Tratamento de Erros](#tratamento-de-erros)

9. [Fluxo de Autenticação](#fluxo-de-autenticação-completo)

10. [Exemplos de Uso](#exemplos-de-uso-com-curl)

11. [Notas de Segurança](#notas-de-segurança)

Autenticação

A API utiliza Bearer Token authentication com suporte a multi-tenancy através do header X-TENANT-ID.

Headers Obrigatórios para Rotas Protegidas

Authorization: Bearer <access_token>

X-TENANT-ID: <tenant_id>

Content-Type: application/json (para requisições POST/PUT)

Endpoints de Autenticação

1. Registro de Novo Usuário e Tenant

Cria um novo tenant e usuário no sistema.

Endpoint: POST /v1/register ou POST /register

Nota: Ambas as formas funcionam. A rota sem versão aponta para a versão padrão (v1).

Headers:

Content-Type: application/json

Body:

{

  "tenant_name": "Nome da Empresa",

  "name": "Nome do Usuário",

  "email": "usuario@exemplo.com",

  "password": "senha123456",

  "password_confirmation": "senha123456"

}

Resposta de Sucesso (201):

{

  "message": "Account created successfully",

  "tenant_id": 1,

  "user_id": 1

}

Resposta de Erro (422):

{

  "message": "The given data was invalid.",

  "errors": {

    "email": ["The email field is required."],

    "password": ["The password must be at least 8 characters."],

    "password_confirmation": ["The password confirmation does not match."]

  }

}

Exemplo de Uso:

Usando rota versionada (recomendado para compatibilidade)


curl -X POST https://api.carbob.pt/v1/register \

  -H "Content-Type: application/json" \

  -d '{

    "tenant_name": "Empresa ABC",

    "name": "João Silva",

    "email": "joao@empresa.com",

    "password": "minhasenha123",

    "password_confirmation": "minhasenha123"

  }'



Ou usando rota sem versão (aponta para versão padrão)


curl -X POST https://api.carbob.pt/register \

  -H "Content-Type: application/json" \

  -d '{

    "tenant_name": "Empresa ABC",

    "name": "João Silva",

    "email": "joao@empresa.com",

    "password": "minhasenha123",

    "password_confirmation": "minhasenha123"

  }'

2. Obter Token de Acesso

Gera um token de acesso OAuth2 para autenticação nas rotas protegidas.

Endpoint: POST /oauth/token

Headers:

Content-Type: application/x-www-form-urlencoded

Accept: application/json

Body (form-urlencoded):

grant_type=password

client_id=seu_client_id

client_secret=seu_client_secret

username=usuario@exemplo.com

password=senha123456

scope=*

Resposta de Sucesso (200):

{

  "token_type": "Bearer",

  "expires_in": 1296000,

  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9...",

  "refresh_token": "def50200...",

  "tenant_id": 1

}

Resposta de Erro (401):

{

  "error": "invalid_credentials",

  "error_description": "The user credentials were incorrect."

}

Exemplo de Uso:

curl -X POST https://api.carbob.pt/oauth/token \

  -H "Content-Type: application/x-www-form-urlencoded" \

  -H "Accept: application/json" \

  -d "grant_type=password" \

  -d "client_id=seu_client_id" \

  -d "client_secret=seu_client_secret" \

  -d "username=joao@empresa.com" \

  -d "password=minhasenha123" \

  -d "scope=*"

Nota: Este endpoint requer um Password Client OAuth2. Para criar um, execute:

php artisan passport:client --password

3. Solicitar Reset de Senha

Envia um link de reset de senha para o email do usuário.

Endpoint: POST /v1/forgot-password

Headers:

Content-Type: application/json

Body:

{

  "email": "usuario@exemplo.com"

}

Resposta de Sucesso (200):

{

  "message": "Password reset link sent to your email address.",

  "email": "usuario@exemplo.com"

}

Resposta de Erro (422):

{

  "message": "The given data was invalid.",

  "errors": {

    "email": ["The email field must be a valid email address."]

  }

}

Exemplo de Uso:

curl -X POST https://api.carbob.pt/v1/forgot-password \

  -H "Content-Type: application/json" \

  -d '{

    "email": "joao@empresa.com"

  }'

4. Resetar Senha

Define uma nova senha usando o token recebido por email.

Endpoint: POST /v1/reset-password

Headers:

Content-Type: application/json

Body:

{

  "email": "usuario@exemplo.com",

  "token": "token_recebido_por_email",

  "password": "nova_senha123456",

  "password_confirmation": "nova_senha123456"

}

Resposta de Sucesso (200):

{

  "message": "Password has been reset successfully.",

  "status": "success"

}

Resposta de Erro (422):

{

  "message": "Unable to reset password.",

  "errors": {

    "token": ["The password reset token is invalid or has expired."]

  }

}

Exemplo de Uso:

curl -X POST https://api.carbob.pt/v1/reset-password \

  -H "Content-Type: application/json" \

  -d '{

    "email": "joao@empresa.com",

    "token": "abc123def456",

    "password": "minhanovasenha123",

    "password_confirmation": "minhanovasenha123"

  }'

5. Endpoints OAuth2 do Passport

A API também suporta os endpoints padrão do Laravel Passport:

5.1. Obter Token OAuth2

Endpoint: POST /oauth/token

5.2. Renovar Token

Endpoint: POST /oauth/token/refresh

5.3. Autorização OAuth2

Endpoint: GET /oauth/authorize
Endpoint: POST /oauth/authorize
Endpoint: DELETE /oauth/authorize

Endpoints de Recursos

Endpoints de Gestão de Usuário

1. Obter Informações do Usuário

Retorna as informações do usuário autenticado.

Endpoint: GET /v1/user

Headers:

Authorization: Bearer <access_token>

X-TENANT-ID: <tenant_id>

Resposta de Sucesso (200):

{

  "id": 1,

  "name": "João Silva",

  "email": "joao@empresa.com",

  "tenant_id": 1,

  "created_at": "2024-01-15T10:30:00.000000Z",

  "updated_at": "2024-01-15T10:30:00.000000Z"

}

Exemplo de Uso:

curl https://api.carbob.pt/v1/user \

  -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9..." \

  -H "X-TENANT-ID: 1"

2. Atualizar Informações do Usuário

Atualiza nome e/ou email do usuário autenticado.

Endpoint: PUT /v1/user

Headers:

Authorization: Bearer <access_token>

X-TENANT-ID: <tenant_id>

Content-Type: application/json

Body:

{

  "name": "João Silva Santos",

  "email": "joao.santos@empresa.com"

}

Resposta de Sucesso (200):

{

  "message": "User information updated successfully.",

  "user": {

    "id": 1,

    "name": "João Silva Santos",

    "email": "joao.santos@empresa.com",

    "tenant_id": 1,

    "updated_at": "2024-01-15T11:00:00.000000Z"

  }

}

Resposta de Erro (422):

{

  "message": "The given data was invalid.",

  "errors": {

    "email": ["The email has already been taken."]

  }

}

Exemplo de Uso:

curl -X PUT https://api.carbob.pt/v1/user \

  -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9..." \

  -H "X-TENANT-ID: 1" \

  -H "Content-Type: application/json" \

  -d '{

    "name": "João Silva Santos",

    "email": "joao.santos@empresa.com"

  }'

3. Alterar Senha

Altera a senha do usuário autenticado.

Endpoint: POST /v1/user/change-password

Headers:

Authorization: Bearer <access_token>

X-TENANT-ID: <tenant_id>

Content-Type: application/json

Body:

{

  "current_password": "senha_atual123",

  "password": "nova_senha123456",

  "password_confirmation": "nova_senha123456"

}

Resposta de Sucesso (200):

{

  "message": "Password changed successfully. Please log in again.",

  "status": "success"

}

Resposta de Erro (422):

{

  "message": "The given data was invalid.",

  "errors": {

    "current_password": ["The current password is incorrect."]

  }

}

Exemplo de Uso:

curl -X POST https://api.carbob.pt/v1/user/change-password \

  -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9..." \

  -H "X-TENANT-ID: 1" \

  -H "Content-Type: application/json" \

  -d '{

    "current_password": "senha_atual123",

    "password": "nova_senha123456",

    "password_confirmation": "nova_senha123456"

  }'

Nota Importante: Após alterar a senha, todos os tokens existentes são revogados por segurança. O usuário precisará fazer login novamente.

Endpoints de Teste e Debug

1. Health Check

Verifica o status da API.

Endpoint: GET /v1/health

Resposta:

{

  "status": "ok",

  "time": "2024-01-15T10:30:00.000000Z"

}

2. Ping

Endpoint simples para verificar conectividade.

Endpoint: GET /v1/ping

Resposta:

{

  "message": "pong",

  "timestamp": "2024-01-15T10:30:00.000000Z"

}

3. Teste de Autenticação

Testa se a autenticação está funcionando corretamente.

Endpoint: GET /v1/test-auth

Headers:

Authorization: Bearer <access_token>

Resposta:

{

  "message": "Auth working",

  "user": "usuario@exemplo.com"

}

4. Debug de Token

Endpoint para debug de informações do token.

Endpoint: GET /v1/debug-token

Resposta:

{

  "has_auth_header": true,

  "auth_header": "Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9...",

  "bearer_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9...",

  "user": "usuario@exemplo.com",

  "guard": "api"

}

Códigos de Status HTTP

| Código | Descrição |
|--------|-----------|
| 200 | Sucesso |
| 201 | Criado com sucesso |
| 401 | Não autorizado |
| 403 | Acesso negado |
| 422 | Dados inválidos |
| 500 | Erro interno do servidor |

Tratamento de Erros

Erro de Credenciais Inválidas (401)

{

  "error": "invalid_credentials",

  "message": "The user credentials were incorrect."

}

Erro de Header Tenant Ausente (403)

{

  "error": "Missing X-TENANT-ID header"

}

Erro de Tenant Incorreto (403)

{

  "error": "User does not belong to this tenant"

}

Erro de Validação (422)

{

  "message": "The given data was invalid.",

  "errors": {

    "field_name": ["Error message"]

  }

}

Fluxo de Autenticação Completo

1. Registro

1. Fazer POST para /v1/register com dados do tenant e usuário

2. Receber tenant_id e user_id na resposta

3. Guardar o tenant_id para uso posterior

2. Autenticação

1. Fazer POST para /oauth/token com grant_type, client_id, client_secret, username e senha

2. Receber access_token, refresh_token e tenant_id na resposta

3. Guardar o access_token e tenant_id para uso posterior

3. Acesso a Recursos Protegidos

1. Incluir header Authorization: Bearer <access_token>

2. Incluir header X-TENANT-ID: <tenant_id>

3. Fazer requisições para endpoints protegidos

4. Recuperação de Senha

1. Fazer POST para /v1/forgot-password com email

2. Receber confirmação de envio do email

3. Verificar email e clicar no link de reset

4. Fazer POST para /v1/reset-password com token e nova senha

5. Fazer login com nova senha via /oauth/token

Exemplos de Uso com cURL

Registro Completo

1. Registrar novo usuário e tenant


curl -X POST https://api.carbob.pt/v1/register \

  -H "Content-Type: application/json" \

  -d '{

    "tenant_name": "Minha Empresa",

    "name": "João Silva",

    "email": "joao@minhaempresa.com",

    "password": "senha123456",

    "password_confirmation": "senha123456"

  }'



Resposta esperada:


{


  "message": "Account created successfully",


  "tenant_id": 1,


  "user_id": 1


}

Autenticação

2. Obter token de acesso


curl -X POST https://api.carbob.pt/oauth/token \

  -H "Content-Type: application/x-www-form-urlencoded" \

  -H "Accept: application/json" \

  -d "grant_type=password" \

  -d "client_id=seu_client_id" \

  -d "client_secret=seu_client_secret" \

  -d "username=joao@minhaempresa.com" \

  -d "password=senha123456" \

  -d "scope=*"



Resposta esperada:


{


  "token_type": "Bearer",


  "expires_in": 1296000,


  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9...",


  "refresh_token": "def50200...",


  "tenant_id": 1


}

Acesso a Recursos Protegidos

3. Acessar recursos protegidos


curl https://api.carbob.pt/v1/clients \

  -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9..." \

  -H "X-TENANT-ID: 1"

Password Recovery

4. Solicitar reset de senha


curl -X POST https://api.carbob.pt/v1/forgot-password \

  -H "Content-Type: application/json" \

  -d '{

    "email": "joao@minhaempresa.com"

  }'



Resposta esperada:


{


  "message": "Password reset link sent to your email address.",


  "email": "joao@minhaempresa.com"


}




5. Resetar senha (usar token do email)


curl -X POST https://api.carbob.pt/v1/reset-password \

  -H "Content-Type: application/json" \

  -d '{

    "email": "joao@minhaempresa.com",

    "token": "abc123def456",

    "password": "novasenha123456",

    "password_confirmation": "novasenha123456"

  }'



Resposta esperada:


{


  "message": "Password has been reset successfully.",


  "status": "success"


}

Refresh Token

6. Renovar token (se necessário)


curl -X POST https://api.carbob.pt/oauth/token/refresh \

  -H "Content-Type: application/x-www-form-urlencoded" \

  -d "grant_type=refresh_token" \

  -d "refresh_token=def50200..." \

  -d "client_id=1" \

  -d "client_secret=secret"

Notas de Segurança

1. Tokens de Acesso: Expirem em 1 ano (31536000 segundos)

2. Refresh Tokens: Expirem em 30 dias, renovação automática recomendada

3. Multi-tenancy: Todos os dados são automaticamente filtrados por tenant_id

4. Header Obrigatório: O header X-TENANT-ID é obrigatório para todas as rotas protegidas

5. Validação de Tenant: Usuários só podem acessar recursos do seu próprio tenant

6. Password Recovery:

- Tokens de reset expiram em 60 minutos
- Throttle de 60 segundos entre tentativas
- Todos os tokens são revogados após reset

7. Rate Limiting: Considere implementar rate limiting nos endpoints de autenticação

8. HTTPS: Sempre use HTTPS em produção

9. Validação de Email: Emails são validados antes do envio de reset

Configuração de Email

Para que o password recovery funcione, configure o envio de emails no .env:

Email Configuration


MAIL_MAILER=smtp

MAIL_HOST=smtp.gmail.com

MAIL_PORT=587

MAIL_USERNAME=your-email@gmail.com

MAIL_PASSWORD=your-app-password

MAIL_ENCRYPTION=tls

MAIL_FROM_ADDRESS=noreply@carbob.pt

MAIL_FROM_NAME="Carbob API"

Configuração do Frontend URL

Para links de reset de senha funcionarem corretamente:

Frontend URL para links de reset


CARBOB_FRONTEND_URL=https://manager.carbob.pt

Suporte

Para dúvidas ou problemas com a autenticação, consulte:

Documentação do Laravel Passport: https://laravel.com/docs/passport

Testes automatizados: tests/Feature/AuthFlowTest.php

Testes de Password Recovery: tests/Feature/PasswordRecoveryTest.php

Logs da aplicação: storage/logs/laravel.log

Coleção Postman: docs/carbob-auth-postman.json

Changelog

v1.0.0 (Janeiro 2025)

✅ Implementação inicial da API

✅ Autenticação OAuth2 com Passport

✅ Multi-tenancy com headers

✅ Gestão de projetos

✅ Password recovery completo

✅ Refresh token automático

✅ Documentação completa

✅ Testes automatizados

✅ Coleção Postman