Documentação

Como autenticar e consumir APIs e datasets liberados para a sua conta, com exemplos prontos e boas práticas.

Autenticação

Todas as rotas /api/client/* exigem o header X-Api-Key.

Observação: em caso de erro de autenticação ou limite de consumo, a API retorna um JSON com code e message para orientar o próximo passo.

Passo a passo para conectar

Escolha como você prefere ler a documentação: uma versão para leigo ou técnica.

Conectar (Para leigo)

Pegue sua chave de acesso: você recebe um token (a “chave”) para usar no consumo.
Entre no portal: cole o token no login e confirme que o acesso foi reconhecido.
Veja o que está liberado: abra APIs e Datasets para entender o catálogo disponível para sua conta.
Copie um exemplo pronto: na tela de cada API, use “Copiar curl” e envie para o seu time técnico.
Integre no seu sistema: seu sistema chama os endpoints liberados enviando a chave no header X-Api-Key.
Se aparecer limite excedido: aguarde e tente novamente. Se isso atrapalhar sua operação, peça ajuste de limites.
Opcional: Integrações: em Integrações, você pode cadastrar um webhook para receber eventos no seu sistema.

Checklist rápido

Token válido • Ao menos 1 item liberado (API/dataset) • Você sabe o objetivo da integração (o que quer consultar).

Conectar (Técnico)

Base URL: defina <sua_url>. As rotas do portal ficam em <sua_url>/api/client/*.
Autenticação: enviar X-Api-Key em todas as requisições.
Descoberta: liste APIs e datasets liberados no portal e identifique endpoints/versões.
Contrato: baixe o openapi.json da API e gere SDK/cliente HTTP (opcional).
Consumo: comece com GET simples. Adicione filtros/paginação conforme o contrato.
Tratamento de erro: 401 (token inválido/revogado), 429 (limite atingido), 404 (rota não disponível no seu acesso).
Boas práticas: backoff exponencial em 429, cache de resultados e retries com limite.
Webhook (opcional): em Integrações, cadastre URL e valide assinatura pelos headers X-BD-Timestamp e X-BD-Signature.

Exemplos

curl (GET)

										curl -H "X-Api-Key: <seu_token>" \
										"<sua_url>/api/client/apis"
									

JavaScript (fetch)

										fetch("<sua_url>/api/client/catalog", {
										headers: { "X-Api-Key": "<seu_token>" }
										}).then(r => r.json())
									

Python (requests)

										import requests
										resp = requests.get("<sua_url>/api/client/apis", headers={"X-Api-Key":"<seu_token>"})
										print(resp.status_code, resp.json())
									

Referência

Schemas, enums e contratos para acelerar a integração.

Ver APIs Ver Datasets

Faça login para ver a referência completa

Para listar schemas e baixar contratos OpenAPI do seu catálogo liberado, entre com seu token.

Entrar

Schemas (datasets)

Escolha um dataset para ver campos, tipos e descrições.

Carregue a lista e selecione um dataset.

OpenAPI (contrato da API)

Escolha uma API para baixar o contrato e ver rotas/params.

Carregue a lista e selecione uma API.

Enums e erros comuns

Referência rápida de estados e códigos usados no portal e nas integrações.

Domínios

Status	Significado
`active`	Disponível para uso e seleção.
`planned`	Planejado (ainda não disponível).
`archived`	Arquivado (não aparece em seletores “active-only”).

Solicitações de domínio

Status	Significado
`pending`	Em análise (pendente).
`approved`	Aprovado e habilitado.
`rejected`	Rejeitado (pode ter motivo).

Erros HTTP

Código	Quando acontece
`401`	Token inválido, revogado ou ausente.
`404`	Recurso não disponível para o seu acesso ou rota inexistente.
`429`	Limite de consumo atingido. Tente novamente em instantes.

Webhook (assinatura)

Se você usar webhooks, valide a assinatura do payload para garantir autenticidade.

											Headers esperados:
											X-BD-Timestamp: <epoch_ms>
											X-BD-Signature: v1=<hmac_sha256>
										