Visão geral da API
- Endereço:
https://api.brasilsintetico.com, com todas as rotas sob/v1. - Autenticação:
Authorization: Bearer bs_…, uma chave de API do projeto. As únicas rotas abertas são as dos schemas: o do cenário e o do pedido de calibração. - Formato: JSON em UTF-8 na ida e na volta.
Convenções
Seção intitulada “Convenções”- Campos em português, códigos e mensagens em inglês. Os campos seguem o contrato do cenário (
pedido,estado,preco_micros). Os códigos de recusa e as mensagens são estáveis e em inglês (Erros). - Dinheiro em milionésimos de real, inteiros:
preco_micros: 14499640é R$ 14,499640. - Datas em ISO 8601, com o fuso.
- Ids de job são UUIDs.
- Envio idempotente:
POST /v1/jobsexigeIdempotency-Key(Jobs).
| Método e rota | Escopo | O que faz |
|---|---|---|
GET /v1/whoami |
results:read |
O projeto, a organização e os escopos da chave. |
GET /v1/schemas/cenario-campanha |
nenhum | O JSON Schema do cenário de campanha. |
GET /v1/schemas/pedido-calibracao |
nenhum | O JSON Schema do pedido de calibração, com o cenário de que ele parte. |
GET /v1/biblioteca |
qualquer | A biblioteca de campanhas: os modelos por setor e os casos públicos. |
GET /v1/biblioteca/{modelo} |
qualquer | Um modelo; com uf ou municipio, também o pedido pronto para esse lugar. |
POST /v1/jobs/estimate |
simulate |
Valida e cota um cenário, sem reservar nada. |
POST /v1/jobs |
simulate |
Reserva o preço e cria o job. |
GET /v1/jobs |
results:read |
Os 50 jobs mais recentes do projeto. |
GET /v1/jobs/{job_id} |
results:read |
Um job, com o estado e o registro. |
GET /v1/jobs/{job_id}/findings |
results:read |
Os achados de um job concluído, em linhas, tabela a tabela. |
GET /v1/jobs/{job_id}/respostas |
results:read |
As respostas ao contrato de resposta de um job concluído. |
GET /v1/jobs/{job_id}/setores |
results:read |
Os eventos por setor e semana de um município, para um job com saida_por_setor. |
GET /v1/jobs/compare?a={id}&b={id} |
results:read |
Duas simulações concluídas da mesma release lado a lado: o cenário de cada uma e os números principais dos achados, com a diferença (Comparar dois jobs). |
POST /v1/jobs/{job_id}/cancel |
simulate |
Cancela um job que ainda não tem máquina. |
Cada rota tem a página dela, com os esquemas e exemplos, na Referência da API. As descrições da referência vêm do código e estão em inglês.
OpenAPI
Seção intitulada “OpenAPI”O documento OpenAPI 3.1 das rotas /v1 está em https://docs.brasilsintetico.com/openapi.json. Ele é gerado do mesmo código que serve a API, a cada versão. Use-o para gerar um cliente ou para dar a um agente.