Primeiros passos
Fluxo de integração
Execute os endpoints na sequência abaixo. Todas as requisições exigem autenticação Bearer e retornam JSON.
1. Autenticar
Envie a chave no cabeçalho Authorization de cada requisição.
2. Consultar CNPJs
Use GET /legal-entities e guarde o id do CNPJ selecionado.
3. Consultar catálogo
Busque marcas, modelos e versões usando o legal_entity_id.
4. Montar o corpo
Informe os blocos applicant, vehicle e terms com todos os campos obrigatórios.
5. Criar simulação
Envie POST /simulations com o cabeçalho Idempotency-Key.
6. Consultar resultado
Use GET /simulations/{id} a cada 20 segundos por até 3 minutos.
URL-base oficial
https://saas.zinix.com.br/v1Os caminhos desta página já consideram o prefixo /v1. Não o repita.
Endpoints públicos
/legal-entitiesLista todos os CNPJs ativos permitidos para a chave./legal-entities/{id}/banksLista os bancos habilitados para o CNPJ./vehicles/brandsLista marcas por CNPJ e tipo de veículo./vehicles/modelsLista modelos da marca escolhida./vehicles/versionsLista versões reais para modelo e anos./simulationsValida, registra e enfileira uma simulação./simulations/{id}Retorna progresso e resultados por banco./billingRetorna modalidade, cota e saldo atual./usageRetorna uso e CPFs únicos por período e CNPJ.Open source · Licença MIT
SDK para TypeScript e Node.js
Use o @zinix/sdk para consumir a API sem montar cada requisição HTTP manualmente. O SDK oferece tipos para os dados, autenticação, tratamento de erros e acompanhamento das simulações. Funciona com TypeScript ou JavaScript ESM em Node.js 22 ou superior, sem dependências de runtime.
- Lojas/CNPJs, bancos e catálogo de marcas, modelos e versões.
- Criação, consulta e polling das simulações com tipos prontos.
- Saldo, consumo e erros com referência para suporte.
- Uso no backend do Next.js ou em um servidor Node para React/Vite.
SDK gratuito; contratação da API separada
1. Instale pelo repositório
A versão 0.1.0 está no GitHub e ainda não foi publicada no npm. Clone o código, gere o pacote e instale o arquivo no seu backend:
git clone https://github.com/pablorigueto/zinix-api-sdk.git
cd zinix-api-sdk
npm ci
npm test
npm pack
# No diretório do seu backend, ajuste o caminho do arquivo:
npm install ../zinix-api-sdk/zinix-sdk-0.1.0.tgz2. Configure a chave no servidor
Defina ZINIX_API_KEY nas variáveis de ambiente do backend. Os métodos retornam { data, meta }: dados da operação e metadados HTTP.
import { Zinix, ZinixApiError } from '@zinix/sdk';
// Configure ZINIX_API_KEY apenas no ambiente do servidor.
const zinix = new Zinix({ apiKey: process.env.ZINIX_API_KEY! });
try {
const { data: lojas } = await zinix.legalEntities.list();
const { data: saldo } = await zinix.billing.get();
// Use os dados no seu backend, conforme as permissões do usuário.
} catch (error) {
if (error instanceof ZinixApiError) {
// Referência para suporte; não registre chave ou dados pessoais.
console.error(error.status, error.code, error.requestId);
} else {
throw error;
}
}3. Envie e acompanhe a simulação
Monte SimulationRequest com os dados obrigatórios e os códigos do catálogo. Use uma chave persistida por operação; em falha de rede, repita somente com a mesma chave e o mesmo corpo.
import type { SimulationRequest } from '@zinix/sdk';
// Usa o cliente "zinix" do exemplo anterior.
async function criarSimulacao(
payload: SimulationRequest,
chaveDaOperacao: string, // Gere e persista ANTES do envio.
) {
const { data: simulacao } = await zinix.simulations.create(payload, {
idempotencyKey: chaveDaOperacao,
});
// Persista simulacao.id e vincule-o ao usuário autorizado.
return simulacao;
}
async function consultarSimulacao(uuidAutorizado: string) {
// Verifique a propriedade do UUID antes de chamar esta função.
const { data: resultado } = await zinix.simulations.get(uuidAutorizado);
return resultado; // Não cria outra simulação.
}No site, consulte pelo seu backend a cada 20 segundos, respeitando também Retry-After, até um estado final. Para jobs em segundo plano, zinix.simulations.wait(uuid) faz o polling por até três minutos por padrão. Não mantenha a requisição do visitante aberta durante essa espera.
O SDK não repete POSTs automaticamente. Um timeout de acompanhamento não significa recusa: guarde o UUID e retome com simulations.get(uuid). Leia as condições e os erros de cada banco; processamento concluído não é aprovação de todos os bancos.
A chave nunca vai para o navegador
NEXT_PUBLIC_ZINIX_API_KEY ou VITE_ZINIX_API_KEY. Valide os dados, o consentimento e a propriedade de cada simulação, com controle de acesso e proteção contra abuso.Acesso
Credencial e segurança
A chave é criada exclusivamente por uma pessoa autorizada da equipe Zinix no ambiente administrativo. Todas as chaves emitidas são de produção; não existe usuário ou senha adicional.
- Mantenha a chave somente no backend.
- Nunca exponha a chave em JavaScript do navegador.
- Use HTTPS fora do ambiente local.
- Armazene o segredo em variável de ambiente ou cofre.
- Não grave chave, CPF ou corpo completo em logs.
- Revogue imediatamente qualquer chave exposta.
curl 'https://saas.zinix.com.br/v1/legal-entities' \
-H 'Authorization: Bearer <SUA_CHAVE_API>' \
-H 'Accept: application/json'Integração server-to-server
Empresa
Escolha do CNPJ e dos bancos
Uma chave pertence ao cliente Zinix e acessa automaticamente todos os CNPJs ativos dele, inclusive os adicionados depois da emissão. O integrador deve listar os CNPJs e pedir ao usuário que escolha um antes da operação.
curl 'https://saas.zinix.com.br/v1/legal-entities' \
-H 'Authorization: Bearer <SUA_CHAVE_API>' \
-H 'Accept: application/json'{
"data": [
{
"id": "8b7c9d12-3456-4789-8abc-def012345678",
"legal_name": "Empresa Demonstração Ltda.",
"trade_name": "Empresa Demonstração",
"cnpj_masked": "12.***.***/****-90",
"is_primary": true,
"status": "active"
}
],
"request_id": "4f62ecbe-f769-4ea0-8e24-ea60f11d8e62"
}Guarde o campo id selecionado e envie-o como legal_entity_id nas consultas de catálogo e no POST da simulação.
curl 'https://saas.zinix.com.br/v1/legal-entities/<CNPJ_ID>/banks' \
-H 'Authorization: Bearer <SUA_CHAVE_API>' \
-H 'Accept: application/json'A API determina os bancos pelo CNPJ escolhido. O integrador não envia credenciais bancárias e não consegue acessar dados sigilosos configurados pela loja.
Veículo
Marca, modelo, anos e versão
Os códigos devem vir do catálogo. Exiba name ao usuário e guarde code para a consulta seguinte. Não invente códigos e não escolha automaticamente um veículo.
# 1. Marcas
GET /vehicles/brands?legal_entity_id=<CNPJ_ID>&type=car
# 2. Modelos da marca escolhida
GET /vehicles/models?legal_entity_id=<CNPJ_ID>&type=car&brand_code=<MARCA_CODE>
# 3. Versões do modelo e dos anos escolhidos
GET /vehicles/versions?legal_entity_id=<CNPJ_ID>&type=car&brand_code=<MARCA_CODE>&model_code=<MODELO_CODE>&manufacture_year=2024&model_year=2025| Etapa | O usuário escolhe | O sistema guarda |
|---|---|---|
| Marcas | Nome da marca | brand_code e brand_name |
| Modelos | Nome do modelo | model_code e model_name |
| Versões | Anos e versão | version_code e version_name |
Solicitação
Todos os dados obrigatórios
O corpo possui quatro partes: CNPJ, proponente, veículo e condições. Campos extras ou ausentes são rejeitados.
applicant — dados do proponente
document- CPF válido com 11 dígitos
gender- male ou female
name- Nome completo
birth_date- YYYY-MM-DD; idade entre 18 e 100 anos
email- E-mail válido
phone- 10 a 13 dígitos
state- UF com duas letras maiúsculas
city- Cidade
has_driver_license- Booleano: true ou false
vehicle — veículo escolhido
type- car ou motorcycle
brand_code / brand_name- Código e nome retornados em marcas
model_code / model_name- Código e nome retornados em modelos
version_code / version_name- Código e nome retornados em versões
manufacture_year- Ano de fabricação
model_year- Ano-modelo igual ou posterior à fabricação
zero_km- Booleano: true ou false
terms — condições desejadas
asset_value_cents- Valor do veículo em centavos
down_payment_cents- Entrada em centavos, menor que o valor do veículo
installments- Lista de 1 a 12 prazos, entre 1 e 84 parcelas
Valores sempre em centavos
6500000 representa R$ 65.000,00 e 1500000 representa R$ 15.000,00.{
"legal_entity_id": "8b7c9d12-3456-4789-8abc-def012345678",
"applicant": {
"document": "11144477735",
"gender": "female",
"name": "Maria Cliente de Teste",
"birth_date": "1990-05-20",
"email": "maria.teste@example.invalid",
"phone": "11999999999",
"state": "SP",
"city": "Campinas",
"has_driver_license": true
},
"vehicle": {
"type": "car",
"brand_code": "<CODIGO_DA_MARCA>",
"brand_name": "<NOME_DA_MARCA>",
"model_code": "<CODIGO_DO_MODELO>",
"model_name": "<NOME_DO_MODELO>",
"version_code": "<CODIGO_DA_VERSAO>",
"version_name": "<NOME_DA_VERSAO>",
"manufacture_year": 2024,
"model_year": 2025,
"zero_km": false
},
"terms": {
"asset_value_cents": 6500000,
"down_payment_cents": 1500000,
"installments": [24, 36, 48]
}
}Criação
Envio da simulação
Gere uma Idempotency-Key diferente para cada nova intenção. Se houver timeout de rede, repita o mesmo corpo com a mesma chave; isso evita cobranças e simulações duplicadas.
curl 'https://saas.zinix.com.br/v1/simulations' \
-X POST \
-H 'Authorization: Bearer <SUA_CHAVE_API>' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Idempotency-Key: sim-<IDENTIFICADOR_UNICO>' \
--data @simulacao.json{
"id": "7c582d48-e615-4cb9-bf0d-82037ac32520",
"status": "queued",
"status_url": "/v1/simulations/7c582d48-e615-4cb9-bf0d-82037ac32520",
"retry_after_ms": 20000,
"idempotent_replay": false,
"billing_charge": {
"debited": true,
"units": 1,
"reason": "new_cpf_this_month",
"balance_after": 99
},
"request_id": "d926d8f5-b68c-4e91-819f-e71c458fe8e7"
}O HTTP 202 confirma validação e enfileiramento, não a conclusão. Salve id, status_url e request_id.
Processamento assíncrono
Polling a cada 20 segundos
Espere 20 segundos antes da primeira consulta. Consulte no máximo 9 vezes — aos 20, 40, 60, 80, 100, 120, 140, 160 e 180 segundos — e pare antes se chegar a um estado final.
const API_URL = 'https://saas.zinix.com.br/v1';
const token = process.env.ZINIX_API_TOKEN;
async function aguardarResultado(simulationId) {
const estadosFinais = new Set(['completed', 'partial', 'failed', 'expired']);
for (let tentativa = 1; tentativa <= 9; tentativa++) {
await new Promise(resolve => setTimeout(resolve, 20_000));
const resposta = await fetch(`${API_URL}/simulations/${simulationId}`, {
headers: {
Authorization: `Bearer ${token}`,
Accept: 'application/json'
}
});
if (!resposta.ok) throw new Error(`HTTP ${resposta.status}`);
const resultado = await resposta.json();
if (estadosFinais.has(resultado.status)) return resultado;
}
return { id: simulationId, status: 'pending_after_timeout' };
}| Status | Significado |
|---|---|
queued | Solicitação aceita e aguardando processamento. |
processing | Um ou mais bancos ainda estão processando. |
completed | Todos os bancos chegaram a um estado final. |
partial | Parte dos bancos não concluiu dentro do prazo interno. |
failed | A solicitação não pôde ser processada. |
expired | O resultado ultrapassou o período de retenção. |
Enquanto estiver processando, acompanhe progress.expected_banks, finished_banks, pending_banks e results. O processamento da Zinix continua mesmo se o cliente parar o polling.
Controle de uso
Saldo, cota e CPFs únicos
Consulte GET /billing antes de apresentar a disponibilidade, mas trate sempre o HTTP 402 no POST porque o saldo pode mudar entre as chamadas.
prepaid: exige saldo para CPF novo.unlimited: não possui saldo ou cota.- O mesmo CPF consome apenas 1 crédito no mês.
- A regra vale entre chaves e CNPJs do mesmo cliente.
- Reconsultar CPF já contado continua permitido com saldo zero.
- Recargas adicionais já aparecem dentro da cota mensal total.
curl 'https://saas.zinix.com.br/v1/billing' \
-H 'Authorization: Bearer <SUA_CHAVE_API>' \
-H 'Accept: application/json'Para relatórios, use GET /usage. Sem datas, retorna o mês atual. Para um período específico, envie ?from=2026-09-01&to=2026-09-30. O intervalo máximo é de 366 dias e inclui detalhamento por dia, CNPJ e origem.
Operação
Erros e diagnóstico
| HTTP | Motivo | Ação |
|---|---|---|
| 400 | Dados, parâmetros ou datas inválidos.Corrija a requisição antes de repetir. | Corrija a requisição antes de repetir. |
| 401 | Chave ausente, inválida, expirada ou revogada.Confira a credencial ou peça uma substituição. | Confira a credencial ou peça uma substituição. |
| 402 | Sem saldo para consultar um CPF novo.Solicite uma recarga; CPF já contado no mês continua elegível. | Solicite uma recarga; CPF já contado no mês continua elegível. |
| 403 | Acesso suspenso, escopo ausente ou CNPJ não autorizado.Confira as permissões da chave. | Confira as permissões da chave. |
| 404 | Recurso inexistente ou de outro cliente.Confira o identificador. | Confira o identificador. |
| 409 | Idempotency-Key reutilizada com outro corpo.Use o corpo original ou uma nova chave para nova intenção. | Use o corpo original ou uma nova chave para nova intenção. |
| 422 | CNPJ sem bancos ativos ou operação não processável.Confira CNPJ, bancos, veículo e condições. | Confira CNPJ, bancos, veículo e condições. |
| 429 | Limite de requisições excedido.Aguarde o Retry-After. | Aguarde o Retry-After. |
| 503 | Indisponibilidade temporária.Repita com espera progressiva e a mesma Idempotency-Key. | Repita com espera progressiva e a mesma Idempotency-Key. |
Guarde o request_id
Simulações white label, com a sua marca
A API devolve as condições dos bancos em JSON e a interface é a sua: o comprador vê o seu produto, não a Zinix. Integração server-to-server, contratada separadamente do plano Essencial.
Cobrado por CPF, não por chamada
A consulta é amarrada ao CPF do comprador.
Repetiu o mesmo CPF? Não conta de novo
Simule quantas vezes precisar no mesmo mês: consome 1 consulta.
Sobrou? Acumula para o mês seguinte
As consultas não usadas continuam na sua conta enquanto a assinatura estiver ativa.
Vários bancos na mesma consulta
Uma consulta cobre as propostas dos bancos configurados.
200 consultas por mês
R$ 2,00 por CPF consultado
- Consultas não usadas acumulam para o mês seguinte
- Catálogo completo de veículos
- Operações com múltiplos CNPJs
- Processamento assíncrono e seguro
300 consultas por mês
R$ 1,50 por CPF consultado
- Consultas não usadas acumulam para o mês seguinte
- Catálogo completo de veículos
- Operações com múltiplos CNPJs
- Processamento assíncrono e seguro
Precisa de mais volume ou de um limite sob medida? Fale com a equipe Zinix
As consultas não utilizadas acumulam enquanto a assinatura estiver ativa. Não há estorno em caso de cancelamento: o valor da cota é repassado à instituição financeira para deixar as consultas disponíveis. O acúmulo é uma cortesia da Zinix. Ver termos. Não inclui o plano Essencial (Simulador + CRM), contratado à parte.
Referência técnica
Consulte o contrato completo
O Swagger apresenta todos os parâmetros, schemas e respostas da versão 1.0.1. A execução real deve permanecer no backend.