Skip to main content

​
Overview

Profiles represent Mexican taxpayers (Personas Físicas or Personas Morales) in Tresa Contafy. Each profile contains:
  • RFC (Registro Federal de Contribuyentes)
  • Legal name
  • Taxpayer type (Physical or Moral person)
  • Fiscal regimes (one or more SAT regime codes)
  • Validation settings
Profiles are used to associate invoices, expenses, and other fiscal documents with specific taxpayers.

​
Authentication

All profile endpoints require authentication: 
Authorization: Bearer YOUR_JWT_TOKEN

​
Creating a Profile

1

Prepare profile information

Gather the taxpayer’s RFC, legal name, type, and fiscal regimes.
2

Validate RFC format

Ensure the RFC follows Mexican format: 3-4 letters + 6 digits + 3 characters.
3

Create the profile

Send a POST request to /api/profiles with the profile data.

​
Create Profile Endpoint

curl -X POST https://api.contafy.com/api/profiles \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "nombre": "Mi Empresa SA de CV",
    "rfc": "XAXX010101000",
    "tipo_persona": "MORAL",
    "regimenes_fiscales": ["601", "603"],
    "validaciones_habilitadas": {
      "validar_regimen_fiscal": true,
      "validar_rfc": true
    }
  }'

​
Request Body

​
nombre
string
required
Legal name of the taxpayer (2-255 characters)
​
rfc
string
required
RFC (Registro Federal de Contribuyentes) in valid Mexican formatFormat: [A-Z&Ñ]{3,4}\d{6}[A-V1-9][A-Z1-9][0-9A]
​
tipo_persona
string
required
Type of taxpayer: FISICA (Physical person) or MORAL (Legal entity)
​
regimenes_fiscales
array
Array of SAT fiscal regime codes (3-digit strings)Common codes:
  • 601: General de Ley Personas Morales
  • 603: Personas Morales con Fines no Lucrativos
  • 605: Sueldos y Salarios e Ingresos Asimilados a Salarios
  • 606: Arrendamiento
  • 608: Demás ingresos
  • 612: Personas Físicas con Actividades Empresariales y Profesionales
  • 621: Incorporación Fiscal
​
validaciones_habilitadas
object
Custom validation settings (optional)
{
  "validar_regimen_fiscal": true,
  "validar_rfc": true
}

​
Response

{
  "message": "Perfil creado exitosamente",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "user_id": "123e4567-e89b-12d3-a456-426614174000",
    "nombre": "Mi Empresa SA de CV",
    "rfc": "XAXX010101000",
    "tipo_persona": "MORAL",
    "regimenes_fiscales": ["601", "603"],
    "validaciones_habilitadas": {
      "validar_regimen_fiscal": true,
      "validar_rfc": true
    },
    "frozen": false,
    "created_at": "2024-03-15T10:30:00.000Z",
    "updated_at": "2024-03-15T10:30:00.000Z"
  }
}

​
RFC Validation

RFC Uniqueness: Each RFC can only exist once across all Contafy accounts. If an RFC is already registered, you’ll receive an error:
{
  "error": "Este RFC ya está en uso",
  "message": "Este RFC ya está registrado en Contafy por otro usuario. Si requiere ayuda para resolver este problema, contacte a [email protected]",
  "code": "RFC_IN_USE"
}
This prevents multiple users from managing the same taxpayer’s fiscal information.

​
Listing Profiles

Retrieve all profiles for the authenticated user: 
curl -X GET https://api.contafy.com/api/profiles \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

​
Response

{
  "message": "Perfiles obtenidos exitosamente",
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "nombre": "Mi Empresa SA de CV",
      "rfc": "XAXX010101000",
      "tipo_persona": "MORAL",
      "regimenes_fiscales": ["601", "603"],
      "frozen": false,
      "created_at": "2024-03-15T10:30:00.000Z"
    },
    {
      "id": "660e8400-e29b-41d4-a716-446655440000",
      "nombre": "Juan Pérez García",
      "rfc": "PEGJ800101000",
      "tipo_persona": "FISICA",
      "regimenes_fiscales": ["612"],
      "frozen": false,
      "created_at": "2024-03-16T14:20:00.000Z"
    }
  ],
  "count": 2
}

​
Getting a Single Profile

curl -X GET https://api.contafy.com/api/profiles/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

​
Updating a Profile

Update any profile field except the user association: 
curl -X PUT https://api.contafy.com/api/profiles/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "nombre": "Mi Empresa Actualizada SA de CV",
    "regimenes_fiscales": ["601", "603", "605"]
  }'
All fields are optional when updating. Only provide the fields you want to change.

​
Updating RFC

You can update the RFC, but the new RFC must not be in use by another account: 
{
  "rfc": "XBXX010101000"
}

​
Deleting a Profile

Deleting a profile is permanent and will cascade delete all associated data:
  • Invoices
  • Expenses
  • Payment complements
  • Metrics
  • Periods
curl -X DELETE https://api.contafy.com/api/profiles/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

​
Profile Freezing

When downgrading subscription plans, profiles may be frozen if you exceed your plan’s profile limit.

​
Freezing Excess Profiles

Freeze profiles when exceeding plan limits: 
curl -X POST https://api.contafy.com/api/profiles/freeze-others \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "preserveProfileId": "550e8400-e29b-41d4-a716-446655440000",
    "targetPlan": "FREE"
  }'
​
preserveProfileId
string
required
UUID of the profile to keep active
​
targetPlan
string
Target plan: FREE, BASIC, PRO, or ENTERPRISEIf not provided, uses current subscription plan

​
Response

{
  "message": "Perfiles congelados exitosamente",
  "frozen": [
    {
      "id": "660e8400-e29b-41d4-a716-446655440000",
      "nombre": "Juan Pérez García",
      "rfc": "PEGJ800101000",
      "frozen": true,
      "frozen_reason": "plan_limit",
      "frozen_at": "2024-03-17T10:00:00.000Z"
    }
  ],
  "active": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "nombre": "Mi Empresa SA de CV",
    "rfc": "XAXX010101000",
    "frozen": false
  },
  "count": {
    "frozen": 1,
    "total": 2
  }
}

​
Unfreezing a Profile

Unfreeze a profile if your plan allows: 
curl -X PUT https://api.contafy.com/api/profiles/660e8400-e29b-41d4-a716-446655440000/unfreeze \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
Unfreezing fails if you’ve reached your plan’s profile limit. Upgrade your plan or freeze another profile first.

​
Plan Limits

Profile limits vary by subscription plan:
PlanMax Profiles
FREE1
BASIC5
PRO20
ENTERPRISEUnlimited

​
Checking Profile Limit

When creating a profile, you may receive: 
{
  "error": "Has alcanzado el límite de perfiles para tu plan FREE",
  "limit": 1,
  "current": 1,
  "code": "PROFILE_LIMIT_REACHED"
}
To resolve this:
  1. Upgrade your subscription
  2. Delete unused profiles
  3. Contact support for ENTERPRISE plans

​
Getting Profile Plugins

Plugins are add-ons associated with profiles: 
curl -X GET https://api.contafy.com/api/profiles/550e8400-e29b-41d4-a716-446655440000/plugins \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
See the Plugins API reference for more details.

​
Best Practices

  1. Validate RFC format: Use the RFC regex pattern before submitting
  2. Store profile IDs: Cache profile IDs in your application to avoid repeated lookups
  3. Handle RFC conflicts gracefully: Inform users if an RFC is already in use
  4. Use meaningful names: Include legal names exactly as they appear in SAT records
  5. Configure fiscal regimes: Add all applicable regime codes for better validation
  6. Monitor plan limits: Track profile count and prompt upgrades when approaching limits
  7. Freeze strategically: When downgrading, freeze inactive profiles first

​
Common Errors

​
Invalid RFC Format

{
  "errors": [
    {
      "msg": "Formato de RFC inválido",
      "param": "rfc",
      "location": "body"
    }
  ]
}

​
Profile Not Found

{
  "error": "Perfil no encontrado"
}
This occurs when:
  • The profile ID doesn’t exist
  • The profile belongs to another user
  • The profile was deleted

​
Plan Limit Reached

{
  "error": "Has alcanzado el límite de perfiles para tu plan BASIC",
  "limit": 5,
  "current": 5,
  "code": "PROFILE_LIMIT_REACHED"
}

​
Next Steps

Build docs developers (and LLMs) love

Get started for freeTalk to us