feat: implement PJ invite flow with email token-based registration

- Add CompanyInvite model and CompanyStatus enum
- Make Company fields nullable to support partial initial creation
- Add invite CRUD functions (create_company_initial, create_company_invite, etc.)
- Add invite token generation/verification utils
- Create PJ invite email template in Portuguese
- Add invite API routes: send, resend, validate, complete registration
- Add Alembic migration for companyinvite table and company changes
- Add InvitesService to frontend client SDK
- Create public /pj-registration route with token validation
- Add invite dialog to companies page for sending invites
- Confirmation modal before saving registration data
- RAZÃO SOCIAL read-only during PJ registration

Co-Authored-By: daniel.resgate <daniel.rider69@gmail.com>

Author: devin-ai-integration[bot]

backend/app/alembic/versions/b2c3d4e5f6g7_add_company_invite.py

@@ -0,0 +1,104 @@
+"""Add company invite table and update company fields
+
+Revision ID: b2c3d4e5f6g7
+Revises: a1b2c3d4e5f6
+Create Date: 2026-03-26 16:00:00.000000
+
+"""
+import sqlalchemy as sa
+import sqlmodel.sql.sqltypes
+from alembic import op
+
+# revision identifiers, used by Alembic.
+revision = "b2c3d4e5f6g7"
+down_revision = "a1b2c3d4e5f6"
+branch_labels = None
+depends_on = None
+
+
+def upgrade():
+    # Add new columns to company table
+    op.add_column(
+        "company",
+        sa.Column("email", sqlmodel.sql.sqltypes.AutoString(length=255), nullable=True),
+    )
+    op.add_column(
+        "company",
+        sa.Column(
+            "status",
+            sqlmodel.sql.sqltypes.AutoString(),
+            nullable=False,
+            server_default="completed",
+        ),
+    )
+
+    # Make company fields nullable to support partial initial creation
+    columns_to_make_nullable = [
+        "razao_social", "representante_legal", "nome_fantasia", "porte",
+        "atividade_economica_principal", "atividade_economica_secundaria",
+        "natureza_juridica", "logradouro", "numero", "complemento", "cep",
+        "bairro", "municipio", "uf", "endereco_eletronico", "telefone_comercial",
+        "situacao_cadastral", "cpf_representante_legal",
+        "identidade_representante_legal", "logradouro_representante_legal",
+        "numero_representante_legal", "complemento_representante_legal",
+        "cep_representante_legal", "bairro_representante_legal",
+        "municipio_representante_legal", "uf_representante_legal",
+        "endereco_eletronico_representante_legal", "telefones_representante_legal",
+        "banco_cc_cnpj", "agencia_cc_cnpj",
+    ]
+    date_columns_to_make_nullable = [
+        "data_abertura", "data_situacao_cadastral", "data_nascimento_representante_legal",
+    ]
+
+    for col_name in columns_to_make_nullable:
+        op.alter_column("company", col_name, existing_type=sa.String(), nullable=True)
+
+    for col_name in date_columns_to_make_nullable:
+        op.alter_column("company", col_name, existing_type=sa.Date(), nullable=True)
+
+    # Create companyinvite table
+    op.create_table(
+        "companyinvite",
+        sa.Column("email", sqlmodel.sql.sqltypes.AutoString(length=255), nullable=False),
+        sa.Column("id", sa.Uuid(), nullable=False),
+        sa.Column("company_id", sa.Uuid(), nullable=False),
+        sa.Column("token", sqlmodel.sql.sqltypes.AutoString(length=500), nullable=False),
+        sa.Column("expires_at", sa.DateTime(timezone=True), nullable=False),
+        sa.Column("used", sa.Boolean(), nullable=False, server_default=sa.text("false")),
+        sa.Column("created_at", sa.DateTime(timezone=True), nullable=True),
+        sa.ForeignKeyConstraint(["company_id"], ["company.id"], ondelete="CASCADE"),
+        sa.PrimaryKeyConstraint("id"),
+    )
+    op.create_index(op.f("ix_companyinvite_token"), "companyinvite", ["token"], unique=True)
+
+
+def downgrade():
+    op.drop_index(op.f("ix_companyinvite_token"), table_name="companyinvite")
+    op.drop_table("companyinvite")
+
+    # Revert company columns to non-nullable
+    columns_to_make_non_nullable = [
+        "razao_social", "representante_legal", "nome_fantasia", "porte",
+        "atividade_economica_principal", "atividade_economica_secundaria",
+        "natureza_juridica", "logradouro", "numero", "complemento", "cep",
+        "bairro", "municipio", "uf", "endereco_eletronico", "telefone_comercial",
+        "situacao_cadastral", "cpf_representante_legal",
+        "identidade_representante_legal", "logradouro_representante_legal",
+        "numero_representante_legal", "complemento_representante_legal",
+        "cep_representante_legal", "bairro_representante_legal",
+        "municipio_representante_legal", "uf_representante_legal",
+        "endereco_eletronico_representante_legal", "telefones_representante_legal",
+        "banco_cc_cnpj", "agencia_cc_cnpj",
+    ]
+    date_columns_to_make_non_nullable = [
+        "data_abertura", "data_situacao_cadastral", "data_nascimento_representante_legal",
+    ]
+
+    for col_name in columns_to_make_non_nullable:
+        op.alter_column("company", col_name, existing_type=sa.String(), nullable=False)
+
+    for col_name in date_columns_to_make_non_nullable:
+        op.alter_column("company", col_name, existing_type=sa.Date(), nullable=False)
+
+    op.drop_column("company", "status")
+    op.drop_column("company", "email")

backend/app/api/main.py

@@ -1,6 +1,6 @@
 from fastapi import APIRouter
 
-from app.api.routes import companies, items, login, private, users, utils
+from app.api.routes import companies, invites, items, login, private, users, utils
 from app.core.config import settings
 
 api_router = APIRouter()
@@ -9,6 +9,7 @@
 api_router.include_router(utils.router)
 api_router.include_router(items.router)
 api_router.include_router(companies.router)
+api_router.include_router(invites.router)
 
 
 if settings.ENVIRONMENT == "local":

backend/app/api/routes/invites.py

@@ -0,0 +1,275 @@
+import logging
+import uuid as uuid_mod
+from typing import Any
+
+from fastapi import APIRouter, HTTPException
+from sqlmodel import select
+
+from app.api.deps import CurrentUser, SessionDep
+from app.core.config import settings
+from app.crud import (
+    complete_company_registration,
+    create_company_initial,
+    create_company_invite,
+    get_company_by_cnpj,
+    get_invite_by_token,
+)
+from app.models import (
+    CompanyInvite,
+    CompanyInviteCreate,
+    CompanyInvitePublic,
+    CompanyInviteValidation,
+    CompanyPublic,
+    CompanyRegistrationComplete,
+    CompanyStatus,
+)
+from app.utils import (
+    generate_invite_token,
+    generate_pj_invite_email,
+    send_email,
+    verify_invite_token,
+)
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter(prefix="/invites", tags=["invites"])
+
+
+@router.post("/", response_model=CompanyInvitePublic)
+def send_invite(
+    *,
+    session: SessionDep,
+    current_user: CurrentUser,  # noqa: ARG001
+    invite_in: CompanyInviteCreate,
+) -> Any:
+    """
+    Send a PJ registration invite. Creates initial company record and sends email.
+    Only authorized internal users (Juridico, Financeiro, RH, Comercial) can send invites.
+    """
+    existing_company = get_company_by_cnpj(session=session, cnpj=invite_in.cnpj)
+
+    if existing_company and existing_company.status == CompanyStatus.completed:
+        raise HTTPException(
+            status_code=400,
+            detail="Uma empresa com este CNPJ já possui cadastro completo.",
+        )
+
+    if existing_company:
+        company = existing_company
+        company.email = invite_in.email
+        session.add(company)
+        session.commit()
+        session.refresh(company)
+    else:
+        company = create_company_initial(
+            session=session,
+            cnpj=invite_in.cnpj,
+            email=invite_in.email,
+        )
+
+    token, expires_at = generate_invite_token(
+        company_id=str(company.id),
+        email=invite_in.email,
+    )
+
+    invite = create_company_invite(
+        session=session,
+        company_id=company.id,
+        email=invite_in.email,
+        token=token,
+        expires_at=expires_at,
+    )
+
+    link = f"{settings.FRONTEND_HOST}/pj-registration?token={token}"
+
+    try:
+        email_data = generate_pj_invite_email(
+            email_to=invite_in.email,
+            link=link,
+            valid_days=settings.INVITE_TOKEN_EXPIRE_DAYS,
+        )
+        send_email(
+            email_to=invite_in.email,
+            subject=email_data.subject,
+            html_content=email_data.html_content,
+        )
+    except Exception as e:
+        logger.error(
+            "Falha ao enviar e-mail de convite para %s (company_id=%s, invite_id=%s): %s",
+            invite_in.email,
+            company.id,
+            invite.id,
+            e,
+        )
+        raise HTTPException(
+            status_code=500,
+            detail="Falha ao enviar o e-mail de convite. O convite foi criado, tente reenviar.",
+        )
+
+    return invite
+
+
+@router.post("/{invite_id}/resend", response_model=CompanyInvitePublic)
+def resend_invite(
+    *,
+    session: SessionDep,
+    current_user: CurrentUser,  # noqa: ARG001
+    invite_id: str,
+) -> Any:
+    """
+    Resend a PJ registration invite. Generates a new token and sends a new email.
+    """
+    try:
+        invite_uuid = uuid_mod.UUID(invite_id)
+    except ValueError:
+        raise HTTPException(status_code=400, detail="ID de convite inválido.")
+
+    statement = select(CompanyInvite).where(CompanyInvite.id == invite_uuid)
+    old_invite = session.exec(statement).first()
+
+    if not old_invite:
+        raise HTTPException(status_code=404, detail="Convite não encontrado.")
+
+    if old_invite.used:
+        raise HTTPException(
+            status_code=400,
+            detail="Este convite já foi utilizado. O cadastro já foi completado.",
+        )
+
+    company = old_invite.company
+    if not company:
+        raise HTTPException(status_code=404, detail="Empresa não encontrada.")
+
+    old_invite.used = True
+    session.add(old_invite)
+    session.commit()
+
+    token, expires_at = generate_invite_token(
+        company_id=str(company.id),
+        email=old_invite.email,
+    )
+
+    new_invite = create_company_invite(
+        session=session,
+        company_id=company.id,
+        email=old_invite.email,
+        token=token,
+        expires_at=expires_at,
+    )
+
+    link = f"{settings.FRONTEND_HOST}/pj-registration?token={token}"
+
+    try:
+        email_data = generate_pj_invite_email(
+            email_to=old_invite.email,
+            link=link,
+            valid_days=settings.INVITE_TOKEN_EXPIRE_DAYS,
+        )
+        send_email(
+            email_to=old_invite.email,
+            subject=email_data.subject,
+            html_content=email_data.html_content,
+        )
+    except Exception as e:
+        logger.error(
+            "Falha ao reenviar e-mail de convite para %s (invite_id=%s): %s",
+            old_invite.email,
+            new_invite.id,
+            e,
+        )
+        raise HTTPException(
+            status_code=500,
+            detail="Falha ao reenviar o e-mail de convite. Tente novamente.",
+        )
+
+    return new_invite
+
+
+@router.get("/validate", response_model=CompanyInviteValidation)
+def validate_invite_token(
+    *,
+    session: SessionDep,
+    token: str,
+) -> Any:
+    """
+    Validate an invite token. Public endpoint (no auth required).
+    Returns company data if token is valid.
+    """
+    token_data = verify_invite_token(token)
+    if not token_data:
+        return CompanyInviteValidation(
+            valid=False,
+            message="O link é inválido ou expirou. Solicite um novo convite ao responsável interno.",
+        )
+
+    invite = get_invite_by_token(session=session, token=token)
+    if not invite:
+        return CompanyInviteValidation(
+            valid=False,
+            message="O link é inválido ou expirou. Solicite um novo convite ao responsável interno.",
+        )
+
+    if invite.used:
+        return CompanyInviteValidation(
+            valid=False,
+            message="Este convite já foi utilizado. O cadastro já foi completado.",
+        )
+
+    company = invite.company
+    if not company:
+        return CompanyInviteValidation(
+            valid=False,
+            message="Empresa não encontrada.",
+        )
+
+    return CompanyInviteValidation(
+        valid=True,
+        company=CompanyPublic.model_validate(company),
+    )
+
+
+@router.put("/complete", response_model=CompanyPublic)
+def complete_registration(
+    *,
+    session: SessionDep,
+    registration_data: CompanyRegistrationComplete,
+) -> Any:
+    """
+    Complete PJ registration. Public endpoint (no auth required).
+    Requires a valid invite token.
+    """
+    token_data = verify_invite_token(registration_data.token)
+    if not token_data:
+        raise HTTPException(
+            status_code=400,
+            detail="O link é inválido ou expirou. Solicite um novo convite ao responsável interno.",
+        )
+
+    invite = get_invite_by_token(session=session, token=registration_data.token)
+    if not invite:
+        raise HTTPException(
+            status_code=400,
+            detail="Convite não encontrado.",
+        )
+
+    if invite.used:
+        raise HTTPException(
+            status_code=400,
+            detail="Este convite já foi utilizado.",
+        )
+
+    company = invite.company
+    if not company:
+        raise HTTPException(
+            status_code=404,
+            detail="Empresa não encontrada.",
+        )
+
+    updated_company = complete_company_registration(
+        session=session,
+        company=company,
+        invite=invite,
+        registration_data=registration_data,
+    )
+
+    return updated_company