Plataforma de APIs DotCompany — do zero, sem complicação

É a primeira tela que você vê ao entrar em /api-dev. Aqui você acompanha quanto de crédito ainda tem, quanto já gastou e a saúde das suas chamadas. Pense nela como o “painel do carro” da sua conta de API.

O que tem nesta tela

• O saldo disponível em destaque: quantos créditos restam e o valor em reais.
• Os indicadores (KPIs): quanto você gastou, o ritmo de gasto (burn-rate), o total de chamadas, a velocidade de resposta (latência p50/p95/p99) e a taxa de sucesso e de erro.
• Os filtros: escolha o período (Hoje, 7, 30 ou 90 dias) e refine por família, CNPJ, ambiente, chave e status — depois clique em Aplicar.
• O botão Exportar CSV, que baixa toda a tabela de consumo (chamadas, créditos e reais) numa planilha.

A chave é o que o seu sistema usa para entrar na plataforma. É como uma senha: você cria aqui, copia e guarda em lugar seguro. Toda chamada do seu sistema leva essa chave junto.

Passo a passo

1. Clique em “Nova chave” (botão no canto superior direito).
2. Escolha o ambiente: Sandbox (testes — gera uma chave dc_test_…) ou Produção (gera dc_live_…).
3. Confirme. A chave já nasce podendo fazer as consultas (os escopos de consulta vêm marcados). Copie o segredo na hora.
4. Pronto: a chave aparece na lista, com os botões Rotacionar (trocar o segredo) e Revogar (desligar) para quando precisar.

O Guia rápido (Quickstart) leva você da conta criada até a primeira chamada de verdade em 5 passos, já com o código pronto para copiar em curl, Python ou Node. É o jeito mais fácil de ver a API funcionando.

Como funciona

• Escolha a aba da sua linguagem (curl, Python ou Node) — o código do passo a passo troca junto.
• O Passo 1 cria a chave sandbox (dc_test_) e mostra onde colar o token (ele aparece só uma vez).
• Os passos seguintes mostram como montar a chamada e ler a resposta. Copie, cole no seu sistema e rode.

Toda a documentação viva num lugar só

A plataforma tem quatro “lugares” para aprender e testar. Use os atalhos abaixo — cada um abre a ferramenta certa no sistema:

Antes mesmo de pensar em nota fiscal, a plataforma já resolve um monte de coisa do dia a dia com consultas prontas. Você manda um dado e recebe a resposta na hora. Abaixo, as famílias mais usadas — todas cobradas por consulta que dá certo (veja “Quanto custa”).

Consultas de endereço e localização (família Geo)

• Endereço pelo CEP — informe o CEP e receba rua, bairro, cidade e UF. GET /api/v1/geo/cep/{cep}.
• Coordenadas de um endereço (geocoding) — transforma um endereço em latitude/longitude. GET /api/v1/geo/geocoding.
• Rota e tempo estimado (ETA) — distância e tempo entre dois pontos, ótimo para entrega. GET /api/v1/geo/rota.

Consultas de empresas e pessoas

• Dados de um CNPJ — razão social, situação, endereço e atividades de uma empresa.
• Validar CPF ou CNPJ — confere se o número é válido antes de cadastrar.
• Validar WhatsApp — confirma se um número tem WhatsApp ativo. GET /api/v1/whatsapp/validar.

Consultas de veículo e de produto

• Veículo por placa e tabela FIPE — marca, modelo, ano e o valor de referência FIPE.
• Catálogo de produto — consulta um produto por código de barras (GTIN/EAN) ou por NCM.

Ajudas para quem vai emitir nota

• Sugerir o perfil fiscal por CNPJ — a API olha o CNPJ e sugere regime, CFOP e afins, para você não errar o cadastro. GET /api/v1/fiscal/sugerir-perfil.
• Ler um XML de NF-e (parse) — você manda o XML de uma nota e recebe os dados organizados em JSON, fácil de usar. POST /api/v1/nfe/parse.

A conta é simples: cada chamada que dá certo desconta um punhado de créditos do seu saldo. Quanto mais “trabalho” a chamada dá, mais créditos custa. Abaixo, o preço por família — é a mesma tabela que vale na cobrança de verdade.

As três regras de ouro da cobrança

• Só o que dá certo é cobrado. Uma chamada que responde com sucesso (o famoso “2xx”) desconta créditos.
• Erro não custa nada. Se a chamada deu erro (dado inválido, falha nossa, recusa da SEFAZ) — os chamados “4xx” e “5xx” — nenhum crédito é descontado.
• Teste é de graça. Tudo o que você faz com a chave de teste (dc_test_) nunca desconta crédito. Experimente à vontade.

Dois limites protegem você (e a plataforma). Saber o que cada um significa evita susto quando o seu sistema recebe um “não” da API — e ensina o que fazer.

1) Ficou sem saldo → a API responde 402

Se acabaram os créditos, a plataforma não entrega o dado e responde com o código 402 (“pagamento necessário”). Isso é de propósito: em vez de te cobrar escondido ou entregar meia resposta, ela para e avisa. É só comprar créditos (seção “Comprar créditos”) que tudo volta a funcionar.

2) Chamou rápido demais → a API responde 429

Cada plano tem uma velocidade máxima de chamadas por minuto. Se o seu sistema disparar mais rápido que isso, a API responde 429 (“muitas chamadas”) e manda junto um aviso Retry-After dizendo quantos segundos esperar antes de tentar de novo.

O Swagger é o “catálogo” completo da API: todos os endpoints, com o que cada um recebe e o que devolve. Dá até para testar autenticado ali mesmo, sem instalar nada.

Como usar

• Clique em Authorize e cole a sua chave de teste — assim você testa autenticado direto na página.
• Use o Filter by tag para achar um endpoint por módulo (ex.: fiscal, vendas, geo).
• Clique num grupo (ex.: Autenticação) para expandir os endpoints dele e ver os detalhes.

O Playground é uma tela onde você dispara chamadas reais à API e vê a resposta ao lado, na hora. Perfeito para experimentar uma consulta antes de colocar no seu sistema.

Como usar

1. Escolha um dos exemplos prontos — o método e o endpoint já vêm preenchidos.
2. Confira o Método + Endpoint (ex.: GET /api/v1/geo/cep/…) e ajuste o valor se quiser.
3. Clique em Enviar. A resposta aparece ao lado.

Créditos são as “fichas” pré-pagas que você gasta ao usar a API de verdade. Aqui você escolhe um pacote pronto ou digita o valor que quiser (a partir de R$ 120) e paga por PIX, boleto ou cartão. Assim que o pagamento é confirmado, os créditos entram na sua conta automaticamente — e não vencem.

Como comprar

1. Escolha um pacote pronto, de 12.000 a 1.200.000 créditos. Ou use o cartão Outro valor e digite quanto quiser: de R$ 120 a R$ 50.000 por compra. O preço não muda: 1 crédito = R$ 0,01. R$ 120 viram 12.000 créditos.
2. Escolha como pagar: PIX (cai na hora), boleto (1 a 2 dias úteis) ou cartão de crédito (aprova em segundos). Boleto e cartão pedem o CNPJ ou CPF da empresa.
3. No PIX, aparece o código copia-e-cola (e o QR Code): pague pelo app do seu banco.
4. Pronto. Os créditos entram sozinhos quando o pagamento é confirmado. Veja o saldo no Painel (seção 1). O que sobrar fica para depois: crédito não vence.

A tela “Minha conta” reúne, num lugar só, o seu plano atual, quanto você já usou no mês, o saldo disponível, o ambiente e os dados da conta de API. É a visão de “como está a minha assinatura”.

O que você faz aqui

• Ver o plano atual e o ambiente em que está.
• Acompanhar os cartões de Uso do mês e Saldo disponível.
• Clicar em Ver planos (comparar e mudar de plano) ou Comprar créditos (recarregar).
• Usar Gerenciar minhas chaves como atalho para a tela de Chaves de API.

Antes de decidir, dá para simular tudo na página pública de preços — sem precisar estar logado. Ela mostra os planos, o preço por família e uma calculadora que estima o seu custo por mês.

O que tem nesta página

• Um resumo dos planos e do modelo de créditos.
• O botão Criar conta de teste grátis — começa sem cartão, com créditos sandbox.
• A calculadora de créditos: informe quantas chamadas de cada família você pretende fazer e veja o custo estimado por mês.

Se você só quer as APIs e não vai usar o ERP completo, dá para transformar a conta em “Somente API”. Esta tela explica exatamente o que muda e pede uma confirmação — porque é uma decisão importante.

O que acontece ao migrar

• A conta passa a ser Somente API: o foco vira o consumo das APIs.
• Você ganha uma chave sandbox para começar a testar.
• A cobrança passa a ser por crédito pré-pago (o modelo deste tutorial).

A emissão de notas é a família Fiscal da plataforma. Ela pede um passo a mais que as consultas: um certificado digital e um perfil fiscal. Se você não vai emitir nota, pode pular esta seção inteira. Se vai, siga a ordem abaixo — e comece sempre em homologação.

1) Cadastrar a empresa emissora (certificado A1)

Envie o certificado digital A1 (arquivo .pfx) + a senha da empresa que vai emitir. É o que prova para a SEFAZ que a nota é sua. O sistema lê sozinho o CNPJ, a razão social e a validade de dentro do certificado. Você faz isso uma vez por CNPJ, na tela de Emissores.

2) Completar o perfil fiscal

Cada empresa precisa de alguns dados antes de emitir: Inscrição Estadual (ou “Isento”), endereço completo, regime tributário (Simples, Presumido, Real ou MEI) e a série da nota (normalmente 1). Use o botão “Buscar dados por CNPJ” para preencher boa parte automaticamente.

3) Comece sempre por homologação

Cadastre a emissora em Homologação e use uma chave dc_test_. Emita algumas notas de teste (não têm valor fiscal) e confira se está tudo certo. Só então vire para Produção — pelo seletor Ambiente no card do emissor (ou PATCH /api/v1/emitters/{id}), sem reenviar o certificado — e use uma chave dc_live_ para emitir de verdade. A chave de teste nunca emite por emissor em produção.

4) Emitir e o que dá para fazer depois

O seu sistema faz a chamada de emissão levando a chave e os dados do documento. Na NF-e vão destinatário e itens; no cupom (NFC-e) vão itens e pagamentos (consumidor é opcional — CPF só se ele pedir) e a resposta já traz o QR Code. O XML autorizado e o DANFE (PDF) voltam na resposta — baixar a nota não custa nada a mais. Passo a passo do cupom: do zero ao primeiro cupom fiscal pela API.

Cofre fiscal: buscar, exportar em lote e auditar os documentos emitidos (novo em setembro/2026)

Tudo que foi emitido pela API fica guardado e consultável pela própria API — sem depender de tela. São quatro capacidades novas da família fiscal:

• documentos.buscar — localiza um documento (NF-e, NFC-e, NFS-e…) por chave, número, período ou CNPJ do destinatário.
• documentos.exportar_lote — gera um pacote com XML e PDF de vários documentos de uma vez (contabilidade, auditoria, migração).
• documentos.auditar — confere a retenção: o que está guardado, por quanto tempo, o que falta.
• nfe.listar — lista as NF-e da conta com filtros de status e período.

Webhooks com assinatura por destino e a fila dos eventos que morreram (novo em setembro/2026)

Em vez de ficar perguntando se a nota autorizou, o ERP avisa o seu sistema: quando o fato acontece, sai um POST para o endereço que você informou.

1. Em Plataforma de API → Webhooks, cole a URL que vai receber os eventos (HTTPS público; endereços internos são recusados) e marque quais eventos quer receber — nenhum marcado = todos os que já funcionam.
2. Clique em Salvar. O sistema mostra o segredo UMA vez — guarde-o. Sem segredo nenhum evento é enviado; cada destino tem o seu, e é com ele que o seu sistema confere que o POST veio mesmo de nós (Confira a assinatura, código pronto na página).
3. Clique em Enviar evento de teste. Apareceu 200 na lista de Entregas? Está pronto para os eventos de verdade.
4. Se o seu endereço ficar fora do ar, as tentativas automáticas se esgotam e o evento vai para Eventos que morreram — ele não se perde. Conserte o endereço e clique em Reabrir: o reenvio sai com o mesmo identificador da primeira tentativa (seu sistema não processa em dobro). O que não interessa mais, Descartar.

Sem decoreba. Sempre que bater uma dúvida com um termo, volte aqui.

• API — o jeito do seu sistema “falar” com o nosso automaticamente, sem ninguém digitar à mão.
• Família — um grupo de consultas parecidas (Geo/CEP, CNPJ, Veículo, Validação, Catálogo, Fiscal). Cada família tem o seu preço.
• Chave de API — a senha de acesso do seu sistema à plataforma (dc_test_ = teste, dc_live_ = produção).
• Escopo de consulta — a permissão que diz o que a chave PODE consultar (ex.: cep:read, cnpj:read). Já vêm ligados; emitir nota é um escopo extra opcional.
• Crédito — ficha pré-paga; cada chamada bem-sucedida gasta uma quantidade (consulta simples = 4, NF-e = 32). 1 crédito = R$ 0,01, e o crédito não vence.
• Sandbox / dc_test_ — ambiente de teste; nada é cobrado, ideal para experimentar.
• Produção / dc_live_ — ambiente real; cobra créditos e, no fiscal, as notas valem.
• Homologação — o “ensaio” do fiscal: notas de teste sem valor fiscal.
• HTTP 402 — “sem saldo”: a API não entrega o dado até você comprar créditos.
• HTTP 429 — “chamou rápido demais”: espere os segundos do Retry-After e tente de novo.
• Rollup — o resumo de uso do painel, fechado de hora em hora (por isso o gráfico aparece com até 1h de atraso).
• Idempotência — código seu por pedido; impede fazer/cobrar a mesma ação duas vezes.
• Geocoding / ETA — transformar endereço em coordenadas / estimar tempo e rota entre pontos.
• NF-e / NFC-e / NFS-e — nota de produto (55) / cupom (65) / nota de serviço.
• DANFE — o PDF da nota, aquele que você manda para o cliente.
• Certificado A1 (.pfx) — arquivo com senha que é a identidade digital da empresa; só é necessário para emitir notas.
• SEFAZ — a Secretaria da Fazenda, o órgão do governo que autoriza a nota.