🏢 API de Organizaciones

📋 Descripción

API para gestionar organizaciones a las que tiene acceso el usuario autenticado. Incluye consulta de organizaciones asignadas, información detallada por RUC y registro de facturación electrónica.

🌐 Base URL

/api/v1/organizations

Autenticación requerida: Bearer Token (Sanctum)

📋 Endpoints

🏢 1. Obtener Organizaciones del Usuario

GET /api/v1/organizations

Obtiene todas las organizaciones asignadas al usuario autenticado, incluyendo información del token actual.

📤 Headers

Authorization: Bearer {token}
Accept: application/json

📥 Respuesta Exitosa (200)

{
  "data": [
    {
      "id": 1,
      "name": "Empresa Demo S.A.",
      "ruc": "1234567-8-123456"
    },
    {
      "id": 2,
      "name": "Comercial XYZ",
      "ruc": "9876543-1-654321"
    }
  ],
  "token_organization": {
    "organization_id": 1,
    "point_sale": "001-001",
    "name": "Token Principal"
  }
}

📋 2. Obtener Información de Organización por RUC

GET /api/v1/organizations/{ruc}

Obtiene información detallada de una organización específica usando su RUC.

📝 Parámetros de Ruta

• ruc (string, requerido): RUC de la organización (ej: "1234567-8-123456")

📤 Headers

Authorization: Bearer {token}
Accept: application/json

📥 Respuesta Exitosa (200)

{
  "id": 1,
  "codigo_provincia_distrito": "8-1",
  "coordenadas_geograficas": "8.9824,-79.5199",
  "provincia_id": 8,
  "distrito_id": 1,
  "corregimiento_id": 1,
  "province_name": "PANAMA",
  "district_name": "PANAMA",
  "corregimiento_name": "SAN FELIPE",
  "nombre": "Empresa Demo S.A.",
  "ruc": "1234567-8-123456",
  "dv": "8",
  "tipo_contribuyente_id": 1,
  "telefono": "507-1234-5678",
  "direccion_sucursal": "Calle 50, Edificio Torre del Sol",
  "email_empresa": "contacto@empresademo.com",
  "id_empresa": "EMP001",
  "province": {
    "id": 8,
    "nombre": "PANAMA",
    "codigo": "8"
  },
  "district": {
    "id": 1,
    "nombre": "PANAMA",
    "codigo": "8"
  },
  "corregimiento": {
    "id": 1,
    "nombre": "SAN FELIPE",
    "codigo": "1"
  },
  "contributor_type": {
    "id": 1,
    "nombre": "Natural"
  },
  "company": {
    "id": 1,
    "nombre": "Matriz Principal"
  },
  "type_contribution_name": "Natural",
  "token_organization": {
    "organization_id": 1,
    "point_sale": "001-001",
    "name": "Token Principal"
  }
}

❌ Respuesta de Error (404)

{
  "token_organization": {
    "organization_id": 1,
    "point_sale": "001-001",
    "name": "Token Principal"
  }
}

📄 3. Registrar Emisión de Facturación Electrónica

POST /api/v1/organizations/emission_fe

Registra una factura para verificación de emisión desde ACI-CLOUD.

📤 Headers

Authorization: Bearer {token}
Accept: application/json
Content-Type: application/json

📝 Cuerpo de la Petición

{
  "aci_organizacion_id": "ORG123456",
  "zoho_invoice_id": "INV789012",
  "date": "2025-01-15",
  "status": "pending",
  "type": "invoice",
  "message": "Factura pendiente de procesamiento"
}

📥 Respuesta Exitosa (200)

{
  "id": 1,
  "aci_organizacion_id": "ORG123456",
  "zoho_invoice_id": "INV789012",
  "date": "2025-01-15T00:00:00.000000Z",
  "status": "pending",
  "type": "invoice",
  "message": "Factura pendiente de procesamiento",
  "created_at": "2025-01-15T10:30:00.000000Z",
  "updated_at": "2025-01-15T10:30:00.000000Z"
}

👤 4. Obtener Información del Usuario Autenticado

GET /api/user

Obtiene la información completa del usuario autenticado, incluyendo sus organizaciones asociadas.

📤 Headers

Authorization: Bearer {token}
Accept: application/json

📥 Respuesta Exitosa (200)

{
  "id": 1,
  "name": "Juan Pérez",
  "email": "juan.perez@empresa.com",
  "organization_id": 1,
  "organization": {
    "id": 1,
    "name": "Empresa Principal",
    "ruc": "155757563-2-2024"
  },
  "organizations": [
    {
      "id": 1,
      "name": "Empresa Principal"
    },
    {
      "id": 2,
      "name": "Sucursal Norte"
    }
  ],
  "import_configuration": {
    "auto_import": true,
    "default_format": "xml"
  },
  "token_organization": {
    "organization_id": 1,
    "point_sale": "001",
    "name": "Token Activo"
  }
}

📊 Estructura de Datos

🏢 Organización (Lista)

🏢 Organización (Detallada)

🏷️ Token Organization

📄 Emisión FE

✅ Validaciones

EmissionFERequest

💡 Casos de Uso

1. Listar Organizaciones del Usuario

curl -X GET "http://localhost:8000/api/v1/organizations" \
     -H "Authorization: Bearer YOUR_TOKEN" \
     -H "Accept: application/json"

2. Consultar Organización por RUC

curl -X GET "http://localhost:8000/api/v1/organizations/155757563-2-2024" \
     -H "Authorization: Bearer YOUR_TOKEN" \
     -H "Accept: application/json"

3. Registrar Emisión FE

curl -X POST "http://localhost:8000/api/v1/organizations/emission_fe" \
     -H "Authorization: Bearer YOUR_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
    "aci_organizacion_id": "ORG123456",
    "zoho_invoice_id": "INV789012",
    "date": "2024-01-20",
    "status": "pending",
    "type": "invoice"
  }'

4. Obtener Información del Usuario

curl -X GET "http://localhost:8000/api/user" \
     -H "Authorization: Bearer YOUR_TOKEN" \
     -H "Accept: application/json"

📊 Códigos de Estado HTTP

⚠️ Notas Adicionales

• Organizaciones del usuario: Se obtienen según las asignadas al usuario autenticado
• Formato RUC: Debe seguir el formato panameño válido
• Token organization: Incluye datos del token actual en todas las respuestas
• Emisiones FE: Se registran para tracking desde ACI-CLOUD
• Fechas ISO 8601: Todas las fechas se manejan en formato estándar
• Endpoint /api/user: No requiere middleware de organización activa

📞 Soporte

Para soporte con organizaciones:

• Email: desarrollo@apconpanama.me
• GitHub: Reportar Issues
• Documentación: Índice de APIs