Actividades empresariales

Catálogo de actividades empresariales por país, necesario para obtener el activityCode válido al dar de alta una organización.

Estos endpoints sirven como catálogo de solo lectura para construir la petición de alta de una organización (ver Alta de una organización cliente). El activityCode que envías en el alta debe existir en este catálogo para el país de la organización; si no, el alta responde 404.

Convenciones comunes

• Base URL Sandbox: https://api-sandbox.zertiban.com
• Headers requeridos en todas las llamadas:
  • Authorization: Bearer {access_token}
  • x-tenant-id: {businessUuid}

1. Listar grupos de actividad de un país

GET/business-activity/v1/business-activity-groups

Devuelve el árbol de grupos de actividad para el país indicado, con las actividades anidadas dentro de cada grupo. Es la forma natural de presentar el catálogo en un desplegable de selección.

Query parameters:

Parámetro	Tipo	Oblig.	Descripción
country	String	Sí	Código ISO 3166 alpha-2 (ej. "ES").

curl "https://api-sandbox.zertiban.com/business-activity/v1/business-activity-groups?country=ES" \
  -H "Authorization: Bearer {access_token}" \
  -H "x-tenant-id: {businessUuid}"

Respuesta (200):

{
  "businessActivityGroups": [
    {
      "uuid": "b1a2c3d4-...",
      "code": "J",
      "description": "Información y comunicaciones",
      "businessActivities": [
        {
          "uuid": "e5f6a7b8-...",
          "code": "6201",
          "description": "Actividades de programación informática",
          "favourite": true
        },
        {
          "uuid": "c9d0e1f2-...",
          "code": "6202",
          "description": "Actividades de consultoría informática",
          "favourite": false
        }
      ]
    }
  ]
}

Campo	Descripción
businessActivityGroups[i].code	Código del grupo (agrupador de alto nivel).
businessActivityGroups[i].description	Descripción del grupo, localizada al país.
businessActivities[j].code	Código concreto de actividad. Este es el valor que envías como activityCode.
businessActivities[j].favourite	Indica actividades destacadas por Zertiban, útiles para posicionarlas arriba.

2. Buscar una actividad concreta

GET/business-activity/v1/business-activities

Recupera una actividad concreta a partir del país y el código. Útil cuando ya conoces el activityCode y quieres validar que existe o recuperar su descripción y grupo asociado.

Query parameters:

Parámetro	Tipo	Oblig.	Descripción
country	String	Sí	Código ISO 3166 alpha-2 (ej. "ES").
code	String	Sí	Código de actividad (ej. "6201").

curl "https://api-sandbox.zertiban.com/business-activity/v1/business-activities?country=ES&code=6201" \
  -H "Authorization: Bearer {access_token}" \
  -H "x-tenant-id: {businessUuid}"

Respuesta (200):

{
  "uuid": "e5f6a7b8-1234-4abc-9def-012345678901",
  "code": "6201",
  "description": "Actividades de programación informática",
  "favourite": true,
  "group": {
    "uuid": "b1a2c3d4-5678-4abc-9def-012345678901",
    "code": "J",
    "description": "Información y comunicaciones"
  }
}

3. Detalle por código (sin país)

GET/business-activity/v1/business-activities/by-code/{code}

Devuelve la actividad asociada al código indicado, resolviendo el país a partir del x-tenant-id (el país de la organización actual). Úsalo cuando ya operas dentro del contexto de una organización y solo necesitas resolver un código.

Path parameters:

Parámetro	Tipo	Descripción
code	String	Código de actividad (2 dígitos, formato ^[0-9]{2}$).

curl https://api-sandbox.zertiban.com/business-activity/v1/business-activities/by-code/20 \
  -H "Authorization: Bearer {access_token}" \
  -H "x-tenant-id: {businessUuid}"

Respuesta (200):

{
  "code": "20",
  "description": "Fabricación de productos farmacéuticos"
}

Tabla resumen

Método	Endpoint	Descripción
GET	/business-activity/v1/business-activity-groups?country={cc}	Árbol de grupos y actividades del país
GET	/business-activity/v1/business-activities?country={cc}&code={code}	Actividad concreta por país y código
GET	/business-activity/v1/business-activities/by-code/{code}	Actividad por código, usando el tenant

Errores frecuentes

Código	Causa típica
400	country ausente o formato de código inválido.
401	Token expirado o credenciales inválidas.
403	x-tenant-id incorrecto o permisos insuficientes.
404	No existe actividad para el par (country, code).