📘

Os endereços não são criados por um endpoint separado. O endereço é registrado junto com a entidade, incluindo os campos de endereço no mesmo payload do POST api/Entity (veja Como criar um cliente, fornecedor, transportadora ou funcionário).

O endereço é opcional, mas é validado como um bloco de tudo-ou-nada: se você preencher qualquer campo de endereço, o bloco inteiro passa a ser obrigatório.

Campos de endereço

🚧

O bloco de endereço é tudo-ou-nada. Se você preencher qualquer um dos campos street, zipCode, district, city ou initialsState, todos os cinco tornam-se obrigatórios. Se algum faltar, a requisição é rejeitada com: Os campos de endereço '...' são obrigatórios se qualquer outro campo relacionado ao endereço for preenchido.

state, initialsState e country

Estes três campos trabalham em conjunto para definir o estado da entidade. O comportamento deles tem algumas especificidades:

• initialsState tem precedência. Se você enviar a sigla do estado (ex.: SP), ela é usada como está e state / country são ignorados na resolução do estado.
• state é um fallback. Quando initialsState não é informado, mas state sim, a API resolve internamente a sigla correspondente a partir do nome do estado/distrito (a comparação por nome é insensível a maiúsculas/acentos, seguindo a collation do banco). Como essa resolução ocorre antes da validação, enviar apenas state já é suficiente para satisfazer o campo obrigatório initialsState.
• country desambigua. É opcional. Só é usado ao resolver state pelo nome quando o mesmo nome existe em mais de um país. Não informá-lo continua sendo uma ação válida.

Regras de resolução (quando initialsState está vazio e state é informado)

Exemplos

Entidade com endereço completo, usando a sigla do estado diretamente:

[
  {
    "name": "John Doe",
    "tradeName": "John Doe",
    "personType": 2,
    "entityTypeId": 1,
    "relationalEntityCode": "8504",
    "situationCode": 1,
    "street": "Av. Paulista, 1000",
    "district": "Bela Vista",
    "city": "São Paulo",
    "zipCode": "01310-100",
    "initialsState": "SP",       // sigla do estado
    "typeAddressCode": 4         // 4 = Entrega
  }
]

O mesmo endereço, mas deixando a API resolver a sigla a partir do nome do estado (state), desambiguado por country:

[
  {
    "name": "John Doe",
    "tradeName": "John Doe",
    "personType": 2,
    "entityTypeId": 1,
    "relationalEntityCode": "8504",
    "situationCode": 1,
    "street": "Av. Paulista, 1000",
    "district": "Bela Vista",
    "city": "São Paulo",
    "zipCode": "01310-100",
    "state": "São Paulo",        // resolvido internamente para "SP"
    "country": "Brasil",         // opcional — apenas desambiguação
    "typeAddressCode": 4
  }
]

Para mais informações sobre as propriedades, consulte a nossa Referência da API aqui.