Tong Shu (escolha de data)

O Tong Shu (通書) é o almanaque chinês usado tradicionalmente para escolher um dia. Duas das suas camadas calculam-se com exatidão, e são essas que estão implementadas aqui: os doze oficiais do dia (建除十二神) e as vinte e oito mansões lunares (二十八宿).

Endpoints

Endpoint	Créditos	O que devolve
POST /v1/chinese/tong-shu	10	Um dia: pilar do dia, oficial, mansão, animal de choque
POST /v1/chinese/tong-shu/select	20	Os dias de um intervalo que o registo aprova para uma ação

Os doze oficiais do dia

A regra é uma só. O dia cujo ramo terrestre coincide com o ramo do mês é 建 Establish, e a partir daí os doze seguem em ciclo. O mês é definido aqui pelo momento exato do termo solar, não pelo dia 1, por isso o oficial pode mudar a meio de um mês do calendário.

#	中文	Nome	De que trata o dia
1	建	Establish	Começar, mas não concluir
2	除	Remove	Limpar, livrar-se de algo
3	滿	Full	Plenitude, assinaturas, inaugurações
4	平	Balance	Dia plano, rotineiro, seguro
5	定	Stable	O que deve durar
6	執	Control	Tomar nas mãos
7	破	Destruction	O dia que choca com o mês
8	危	Danger	Altura e risco
9	成	Success	O mais favorável dos doze
10	收	Collect	Recolher, receber
11	開	Open	Abrir, deixar entrar
12	閉	Close	Selar; estes ficam em último lugar

As vinte e oito mansões lunares

A mansão muda todos os dias num ciclo contínuo de 28 dias, e esse ciclo está preso à semana: 角 é sempre quinta-feira, porque 28 são exatamente quatro semanas. Esta propriedade não é decorativa, é ela própria a verificação: uma âncora errada ou deslocaria a sequência em relação ao almanaque publicado, ou estragaria o dia da semana.

Exemplo

Um dia

curl -X POST https://api.astroway.info/v1/chinese/tong-shu \
  -H "X-Api-Key: aw_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "date": "2026-09-12" }'

Escolha de data

curl -X POST https://api.astroway.info/v1/chinese/tong-shu/select \
  -H "X-Api-Key: aw_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "from": "2026-09-01", "to": "2026-12-31",
        "activity": "marriage", "avoidClashWith": "Rat" }'

Ações: marriage, opening, moving, travel, contract, construction, demolition, medical, funeral, education.

Nota

Três veredictos, e neutral não significa “tanto faz”. suitable e unsuitable são o que o registo diz explicitamente. neutral significa que a tradição nada diz sobre essa ação. Por isso os dias silenciosos não entram na seleção por omissão, e podes pedi-los através de includeNeutral.

Cuidado

O intervalo está limitado a 366 dias, e um intervalo mais longo é rejeitado, não cortado. Uma resposta encurtada em silêncio seria lida como “depois de março não há dias bons”, quando na verdade ninguém olhou para lá. A resposta traz sempre scanned, matched e dropped com a respetiva decomposição, para que a soma bata certo.

O que foi verificado

• Os oficiais foram comparados com um exemplo resolvido publicado: dezembro de 2020, no mês do Rato, em que 11 de dezembro é o primeiro Establish e 8, 9 e 10 de dezembro são Collect, Open e Close. Os quatro coincidem.
• As mansões foram comparadas com a sequência diária de um almanaque japonês de agosto de 2026: vinte dias seguidos, de 女 a 1 de agosto até 角 a 20. Mais o invariante do dia da semana, verificado num século de datas.
• O pilar do dia está agora fixado por três datas publicadas (1949-10-01 甲子, 2000-01-01 戊午, 2024-02-10 甲辰). Antes estavam apenas mencionadas num comentário e nada as verificava.

A seleção é feita pelos oficiais, não pelas mansões. A mansão é devolvida para cada dia, mas não filtra: o seu registo de eventos difere entre almanaques, e não o inventamos. Pela mesma razão, as tabelas 神煞 não estão implementadas: são dezenas de séries sobrepostas, sem acordo entre as fontes.