Tablas de Dominio — Support API

1. Visión General

Sin este servicio, un integrador podría enviar un código de país, una categoría de actividad económica o un código postal que la plataforma desconoce —y el registro sería rechazado. El servicio resuelve este problema proporcionando, con anticipación, los conjuntos exactos de valores aceptados.

2. Contexto y Casos de Uso

Escenarios reales de uso

Ejemplo de negocio: Un canal que está incorporando a un médico autónomo consulta primero GET /domains/acquirer-merchant-categories?natural_person para obtener la lista de categorías de persona física, se la presenta al merchant, y luego usa el code de la categoría seleccionada en el payload de registro. De la misma forma, el canal consulta el código postal del consultorio vía GET /domains/zipcode/{postal_code} para precompletar el formulario de dirección y garantizar que el código postal existe en la base de Getnet.

3. Flujo Principal

El diagrama a continuación ilustra cómo las tablas de dominio encajan en la jornada de registro de un merchant:

Relación entre los endpoints

4. Prerrequisitos

Autenticación

Dependencias

Permisos

Es necesario tener un perfil con permiso de acceso a la API de onboarding de la plataforma Getnet. Consulta al equipo de integración de Getnet para verificar los permisos de tu credencial.

5. Guía Rápida de Integración

Escenario: Validar un código postal antes de registrar la dirección

Escenario: Obtener categorías de actividad económica para Persona Física

Escenario: Obtener lista de países

6. Reglas de Negocio

Consulta de código postal (GET /domains/zipcode/{postal_code})

• El código postal debe informarse solo con dígitos, sin guion, con exactamente 8 caracteres (ej.: 92410670).
• Un código postal que devuelva 404 (no encontrado) no puede ser utilizado en el registro de dirección —el merchant será rechazado en la calificación si se envía un código postal inválido.
• Los códigos postales de alcance municipal (ciudades pequeñas) se devuelven sin los campos street y district. En esos casos, solicita estos datos manualmente al merchant.
• Los campos number (número del inmueble) y suite (complemento) nunca son devueltos por este endpoint —deben ser recopilados del merchant y agregados a la dirección antes de enviar en PUT /merchants/{merchant_id}.
• El campo number es obligatorio cuando el inmueble tiene número. El campo suite es obligatorio cuando el inmueble no tiene número.

Categorías de actividad económica (GET /domains/acquirer-merchant-categories)

• El parámetro natural_person es un flag sin valor —debe enviarse solo como ?natural_person en la query string para filtrar categorías aplicables a Persona Física.
• El código "2119" (PROFISSIONAL AUTONOMO) es el valor por defecto para PF cuando no se conoce la categoría específica del merchant.
• El valor enviado en el campo acquirer_merchant_category_code del registro debe existir obligatoriamente en la lista devuelta por este endpoint. Los códigos fuera de la tabla resultan en un error de validación.

Lista de países (GET /domains/countries)

• Los códigos siguen el estándar ISO 3166-1 alpha-2 (dos letras mayúsculas, ej.: BR, US, PT).
• Los valores enviados en los campos country_of_birth y nationality del registro deben existir obligatoriamente en la lista devuelta por este endpoint.

7. Tratamiento de Errores

Cuerpo estándar de error

Todos los errores devuelven el siguiente formato:

Atención al error 404 en el código postal: Este es el único error con impacto directo en el registro del merchant. Un código postal que devuelve 404 no puede ser utilizado en PUT /merchants/{merchant_id} —el merchant será rechazado en la calificación. Trata este caso mostrando un mensaje claro al usuario para que corrija el código postal antes de continuar.

8. Glosario