Domínios e certificados

Toda API nasce com um endereço padrão. Se você quiser usar um endereço seu (api.suaempresa.com.br), cadastre um domínio próprio: o produto verifica que o domínio é seu, emite o certificado e passa a atender nele.

O endereço padrão

Formato: <slug>-<6 caracteres aleatórios>.<sufixo do produto>, por exemplo pedidos-7hq2ab.gw.nnumbers.com.br.

• fixado na criação da API: renomear a API não muda o endereço;
• único no produto inteiro;
• um rótulo só antes do sufixo, de propósito, para caber no certificado curinga do produto.

O endereço padrão atende pela Internet onde o ambiente tem a subzona do produto delegada e um IP público de entrada. Confirme o estado com o time de operação antes de divulgar o endereço.

Domínio próprio

1. Cadastrar

POST /v1/apis/{apiId}/domains com {"hostname":"api.suaempresa.com.br"}.

Regras do nome:

• FQDN minúsculo, sem curinga (*. é recusado), sem esquema, sem porta e sem rótulo vazio;
• comprimento máximo de 253 caracteres;
• fora das zonas reservadas da plataforma (o sufixo do endereço padrão é sempre reservado);
• ainda não precisa ser único no cadastro: vários pedidos pendentes do mesmo nome, de organizações diferentes, coexistem; o nome passa a pertencer a quem provar a posse primeiro. Se alguém já provou, a resposta é 409 domain_taken — sem revelar quem;
• único dentro da mesma API entre os domínios não removidos;
• igual ao endereço padrão de uma API → 409 hostname_in_use_by_api.

A resposta 201 traz state = PENDING_VERIFICATION e a lista dns_records com o que você precisa publicar no seu DNS.

2. Provar a posse (TXT)

Publique um registro TXT:

Tipo	Nome	Valor
TXT	_nnumbers-gw-challenge.api.suaempresa.com.br	nngw=<token>

O token é aleatório, novo a cada cadastro, e vem na resposta do cadastro. O produto consulta resolvedores públicos, sem cache local, e só então muda o estado para VERIFIED.

3. Apontar o tráfego

Tipo	Nome	Valor
CNAME	api.suaempresa.com.br	o endereço padrão da API
ou A	api.suaempresa.com.br	um IP público do gateway

O produto confere que o nome resolve para o gateway antes de pedir o certificado.

4. Verificar agora

POST /v1/apis/{apiId}/domains/{domainId}/verify força a checagem imediata. Sem o TXT, a resposta é 200 com last_error = txt_not_found — não é erro de requisição, é o retrato do estado. Sem o apontamento correto, last_error reflete o motivo.

Quem prova o TXT primeiro fica com o nome; os demais pedidos pendentes do mesmo hostname passam a ERROR com last_error = domain_taken.

5. Certificado e ativação

O certificado não é pedido dentro da sua requisição. Com posse e roteamento confirmados, o verify apenas agenda a emissão (state = CERTIFICATE_PENDING, campo next_issuance_at) e um processo em segundo plano emite por HTTP-01 — nenhuma credencial da sua conta DNS é solicitada. Com o certificado emitido, o endereço entra no ar: state = ACTIVE.

Duas proteções que você vai encontrar se algo der errado:

• backoff: cada falha de emissão aumenta o intervalo até a próxima tentativa (base de 5 min, dobrando até 24 h). Repetir o verify não fura a espera;
• cota por organização: no máximo 10 tentativas por hora (padrão). Acima disso o domínio espera vaga e fica com last_error = issuance_quota_exceeded, sem gastar tentativa.

6. Renovação

Renovação automática diária: o produto renova quando resta um terço da validade, alerta com menos de 14 dias e marca ERROR apenas quando o certificado em uso está a menos de 7 dias de expirar.

Estados

state	Significado	O que fazer
PENDING_VERIFICATION	cadastrado, aguardando TXT (o nome ainda não é seu)	publique o TXT
VERIFIED	posse confirmada — a partir daqui o nome é seu	aponte o CNAME
CERTIFICATE_PENDING	roteamento OK, emissão agendada ou em andamento	aguarde; se demorar, veja last_error
ACTIVE	atendendo com TLS	nada
ERROR	algo falhou (ou o TXT desapareceu por 7 dias)	veja last_error, corrija e verifique de novo
REMOVING	remoção em curso	nada

Reconferência e perda do domínio

A posse é reconferida diariamente. Se o TXT desaparecer por 7 dias seguidos, o domínio vira ERROR, o certificado é revogado, o certificate_id é zerado e o nome fica livre para outro dono — que também terá de provar posse.

Isso evita que um domínio abandonado seja sequestrado: quem cadastrar depois precisa provar que controla o DNS. Se você removeu o TXT por engano, republique-o antes de completar 7 dias.

HTTP para HTTPS

Quando ligado, a porta HTTP pública responde 301 para https://<mesmo host> com o mesmo caminho, e as rotas da API passam a atender somente nas portas HTTPS. Duas exceções, por desenho:

Exceção	Por quê
/.well-known/acme-challenge/…	o desafio HTTP-01 precisa responder em HTTP puro para o certificado ser emitido
/__nn/ping	é o teste de fumaça da publicação e responde igual em qualquer porta pública

Assim você não precisa configurar nada no seu servidor web. Em produção o recurso fica desligado enquanto não houver o certificado curinga do produto: sem ele, o HTTPS do endereço padrão não fecha o handshake e um 301 levaria o cliente a uma página de erro.

Remover

DELETE /v1/apis/{apiId}/domains/{domainId}:

1. revoga o certificado;
2. apaga o material secreto;
3. marca REMOVING com deleted_at;
4. tira o endereço do ar e o nome volta a ficar livre.

A remoção é imediata do ponto de vista do tráfego; a revogação do certificado depende do emissor.

Limitações declaradas

Limitação	Detalhe
Sem curinga de cliente	*.suaempresa.com.br é recusado; cada nome é cadastrado individualmente
Zonas da plataforma bloqueadas	os sufixos reservados da plataforma não podem ser cadastrados
Sem DNS-01 para cliente	o cliente não entrega credencial de DNS; a emissão é HTTP-01 (o domínio precisa responder na porta 80 enquanto o desafio está pendente)
Redirecionamento HTTP para HTTPS em produção	fica desligado enquanto não houver o certificado curinga do produto
409 domain_taken revela existência	a resposta indica que o nome já foi verificado por alguma organização, sem dizer qual
Certificado é do sujeito, não do nome	o certificado é reaproveitado apenas para o mesmo par organização e domínio; um certificado vivo do mesmo hostname que pertença a outro sujeito faz o pedido ser recusado (certificate_in_use)

last_error de domínio

Valor	Significado
txt_not_found	TXT de posse ausente
not_routed	CNAME ou A não aponta para o gateway
domain_taken	outro dono provou o TXT primeiro
issuance_quota_exceeded	cota de emissão da organização esgotada na janela; o domínio espera vaga
acme_not_configured	a emissão automática não está ligada no ambiente
issuance_failed:<motivo>	falha do emissor; a próxima tentativa respeita o backoff

Próximos passos

• Publicação: o que precisa estar no ar antes de divulgar o endereço.
• Uso e métricas: o bloco certificates do status da API.
• Erros e diagnóstico: domain_taken, domain_not_allowed e hostname_in_use_by_api.