Tabelas de Domínio — Support API

1. Visão Geral

Sem esse serviço, um integrador poderia enviar um código de país, uma categoria de atividade econômica ou um CEP que a plataforma desconhece — e o cadastro seria reprovado. O serviço resolve esse problema fornecendo, com antecedência, os conjuntos exatos de valores aceitos.

2. Contexto e Casos de Uso

Cenários reais de uso

Exemplo de negócio: Um canal que está onboardando um médico autônomo consulta primeiro GET /domains/acquirer-merchant-categories?natural_person para obter a lista de categorias PF, apresenta-a ao merchant, e então usa o code da categoria selecionada no payload de cadastro. Da mesma forma, o canal consulta o CEP do consultório via GET /domains/zipcode/{postal_code} para pré-preencher o formulário de endereço e garantir que o CEP existe na base Getnet.

3. Fluxo Principal

O diagrama abaixo ilustra como as tabelas de domínio se encaixam na jornada de cadastro de um merchant:

Relacionamento entre os endpoints

4. Pré-requisitos

Autenticação

Dependências

Permissões

É necessário ter um perfil com permissão de acesso à API de onboarding da plataforma Getnet. Consulte o time de integração Getnet para verificar as permissões do seu credencial.

5. Guia de Integração Rápida

Cenário: Validar um CEP antes de cadastrar o endereço

Cenário: Obter categorias de atividade econômica para Pessoa Física

Cenário: Obter lista de países

6. Regras de Negócio

Consulta de CEP (GET /domains/zipcode/{postal_code})

• O CEP deve ser informado somente com dígitos, sem hífen, com exatamente 8 caracteres (ex.: 92410670).
• Um CEP que retorne 404 (não encontrado) não pode ser utilizado no cadastro de endereço — o merchant será reprovado na qualificação se um CEP inválido for enviado.
• CEPs de abrangência municipal (cidades pequenas) retornam sem os campos street e district. Nesses casos, solicite esses dados manualmente ao merchant.
• Os campos number (número do imóvel) e suite (complemento) nunca são retornados por este endpoint — devem ser coletados do merchant e adicionados ao endereço antes de enviar no PUT /merchants/{merchant_id}.
• O campo number é obrigatório quando o imóvel possuir número. O campo suite é obrigatório quando o imóvel não possuir número.

Categorias de atividade econômica (GET /domains/acquirer-merchant-categories)

• O parâmetro natural_person é um flag sem valor — deve ser enviado apenas como ?natural_person na query string para filtrar categorias aplicáveis a Pessoa Física.
• O código "2119" (PROFISSIONAL AUTONOMO) é o valor padrão para PF quando a categoria específica do merchant não é conhecida.
• O valor enviado no campo acquirer_merchant_category_code do cadastro deve obrigatoriamente existir na lista retornada por este endpoint. Códigos fora da tabela resultam em erro de validação.

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

• Os códigos seguem o padrão ISO 3166-1 alpha-2 (duas letras maiúsculas, ex.: BR, US, PT).
• Os valores enviados nos campos country_of_birth e nationality do cadastro devem obrigatoriamente existir na lista retornada por este endpoint.

7. Tratamento de Erros

Corpo padrão de erro

Todos os erros retornam o seguinte formato:

Atenção ao erro 404 no CEP: Este é o único erro com impacto direto no cadastro do merchant. Um CEP que retorna 404 não pode ser utilizado no PUT /merchants/{merchant_id} — o merchant será reprovado na qualificação. Trate este caso exibindo uma mensagem clara ao usuário para que corrija o CEP antes de prosseguir.

8. Glossário