Principal Integração e API

Integração e API

Por Equipe Dotfy •
7 artigos

Onde encontro a documentação da API e a coleção Postman?

A documentação da API da Dotfy é pública. Você pode chegar a ela de dois jeitos: - Pelo painel: abra Documentação. A página reúne os guias, a referência e os arquivos para importar. - Direto no navegador: acesse app.dotfy.com.br/docs/pt/. O que há em cada seção - Documentação (guias): explica para que serve cada recurso, como as formas de pagamento se diferenciam e os fluxos de ponta a ponta. - Referência da API: uma página por requisição, com exemplos, respostas e observações. Um seletor no topo alterna entre as duas seções. - Coleção Postman: todas as requisições prontas para importar, com a chave numa variável. - OpenAPI 3.1: a especificação legível por máquina, para gerar um cliente ou importar em outra ferramenta. - PDF por categoria: em qualquer página de endpoint, o link "Baixar em PDF" fica na coluna da direita no computador e no fim da página no celular. Nos guias, o arquivo reúne todos os guias. Guias mais procurados - Início rápido: do zero à primeira cobrança paga, em cinco passos. - Autenticação: como usar a chave e quais escopos existem. - Convenções: unidades de valor, datas e paginação. - Erros e Limites de requisições. - Webhooks e Catálogo de eventos. - Formas de pagamento: o que muda entre PIX, boleto, cartão, carteira digital e pagamento internacional. É a sua primeira integração? Comece pelo Início rápido e leia Convenções antes de generalizar qualquer comportamento da API.

Última atualização em Nov 10, 2026

Como funciona a autenticação com chave de API?

A API usa uma chave estática, enviada no cabeçalho Authorization: Bearer <chave>. Não há OAuth, token de curta duração nem refresh. Todas as chamadas usam a base https://app.dotfy.com.br, no prefixo /api. Como gerar e testar 1. No painel, em Configurações, crie uma chave de API. A autenticação em duas etapas é exigida para emitir chaves. 2. Guarde a chave num cofre de segredos. Ela aparece uma única vez. 3. Chame GET /api/auth/me. Se responder 200, a chave é válida e você vê de qual conta ela é. Cuidados com a chave - A chave é credencial de saque. Autenticado por chave, o saque não pede a segunda prova que o painel exige. - Nunca coloque a chave no repositório ou no front-end. Troque-a ao menor sinal de exposição. - A API é só de servidor para servidor. Ela não envia cabeçalhos CORS, então chamadas pelo navegador são bloqueadas. - Chaves de API são pessoais e intransferíveis. Não existe ambiente de teste O prefixo vk_test_ é apenas um rótulo. Ele não aponta para um sandbox e não impede movimentação de dinheiro. Cobranças criadas com ele são reais, e saques saem de verdade. A simulação de pagamento funciona só em contas sandbox. Em conta comum, ela responde 403. Escopos Cada chave carrega escopos no formato recurso:ação, como charges:read e charges:write. Eles cobrem cobranças, clientes, saldo, saques, chaves PIX, webhooks, produtos, splits e subcontas. O escopo só é verificado em parte das rotas. Não use o escopo como sua única camada de controle de acesso. Quando a chave é recusada - 401 com type: authentication_error: chave ausente, inválida, inativa ou expirada, ou rota que não aceita chave de API. A lista de rotas que aceitam está no guia. - 403 com type: insufficient_scope: falta um escopo. O campo required_scope diz qual. Para a lista completa de escopos e rotas, veja o guia de Autenticação.

Última atualização em Nov 10, 2026

Como criar uma cobrança PIX pela API?

Antes de começar, a conta precisa ter a verificação de identidade aprovada e uma chave de API. O caminho básico leva poucos passos. Passo a passo 1. Envie a criação. Faça POST /api/charges com value em reais e description. Sem paymentMethod, a cobrança é PIX. 2. Guarde os identificadores. O correlationID que você enviar é descartado: a Dotfy gera o identificador e devolve em data.id e data.correlationID. Grave-os junto do seu pedido. 3. Mostre o PIX ao pagador. A resposta traz data.qrCode, o texto do copia e cola, e data.qrCodeImage. Em outros endpoints e nos webhooks, o mesmo texto aparece como brCode. Há também data.paymentLink, uma página pública da cobrança. 4. Espere o webhook. Cadastre um endpoint e assine EVENT:CHARGE_PAID. Esse é o sinal para liberar o produto ou serviço. Campos úteis - expiresIn: validade do QR em segundos, de 60 a 86400 (24 horas). - customer: dados do pagador. - webhook_url: URL que recebe também as entregas daquela cobrança. A lista completa está na referência da API. O que costuma pegar quem integra - Valor entra em reais e sai em centavos. Enviar 250.00 devolve "value": 25000. - Sucesso é 200, não 201. Trate toda a faixa 2xx como sucesso. - 200 nem sempre traz o QR. Se a resposta vier com queued: true e data.status igual a QUEUED, a cobrança existe, mas ainda não tem código. Teste queued antes de exibir o QR e espere o webhook EVENT:CHARGE_CREATED. - Não há ambiente de teste. Cobranças criadas com qualquer chave são reais. - Boleto usa o mesmo endereço, com corpo e regras próprios, e depende de liberação da conta. Para o fluxo completo, siga o Início rápido.

Última atualização em Nov 10, 2026

Como receber e validar webhooks da Dotfy?

O webhook é um POST assinado que a Dotfy envia à sua URL a cada acontecimento. O comprador pode fechar a página antes de voltar ao seu site, e o webhook chega mesmo assim. Cadastre um endpoint Faça POST /api/webhook-endpoints com name, url e events. A URL precisa ser HTTPS e alcançável pela internet. A conta aceita até 10 endpoints. A resposta traz o secret, que só aparece nesse momento. Se perder, rotacione. O segredo antigo para de valer no mesmo instante. Valide a assinatura O cabeçalho X-Webhook-Signature vem no formato t=<epoch_ms>,v1=<hmac_sha256_hex>. 1. Calcule HMAC-SHA256(secret, "<t>.<corpo bruto>"). 2. Compare o resultado com v1 em tempo constante. 3. Recuse o que estiver a mais de 5 minutos de t. Dois erros comuns: t está em milissegundos, não em segundos. E a assinatura usa o corpo cru, antes de qualquer parse. Responda rápido Responda qualquer 2xx em até 15 segundos. Fora disso, a entrega é reagendada. São cinco tentativas no total: na hora do evento, 60 segundos depois, 5 minutos depois, 15 minutos depois e 1 hora depois. Depois da quinta tentativa, a entrega fica FAILED e não é retomada sozinha. - Responda primeiro, processe depois. Grave o evento numa fila e devolva 200. - Seja idempotente por X-Webhook-ID. A mesma entrega pode chegar mais de uma vez. Principais eventos - EVENT:CHARGE_PAID: PIX ou boleto confirmado. É o sinal para entregar. - EVENT:CHARGE_CREATED e EVENT:CHARGE_EXPIRED. Estorno de PIX chega como EVENT:CHARGE_EXPIRED. - EVENT:INTERNATIONAL_PAID e EVENT:INTERNATIONAL_REVERSED: venda internacional, de cartão ou de carteira digital. - EVENT:DISPUTE_OPENED, _WON, _LOST e _CANCELED: MED e disputas. - EVENT:WITHDRAWAL_COMPLETED e EVENT:WITHDRAWAL_FAILED: saques. - EVENT:SPLIT_RECEIVED: chega no endpoint de quem recebe a parte. - EVENT:RECURRENCE_*: Pix Automático. Venda internacional expirada, recusada ou bloqueada não gera webhook. Consulte a API nesses casos. Não recebeu a notificação de uma cobrança? O histórico de entregas por cobrança mostra o evento, o endpoint e o status que o seu servidor respondeu. Os 25 eventos estão no Catálogo de eventos.

Última atualização em Nov 10, 2026

Como interpretar os erros da API?

O corpo de um erro depende de quem respondeu, e a API tem mais de um formato. Três regras cobrem a maior parte dos casos. Três regras práticas - Ramifique em code, nunca no texto de error. O code é estável, em MAIÚSCULAS_COM_UNDERSCORE. O texto de error serve para exibir e pode mudar. - Nem toda resposta traz code. Erros de autenticação e permissão trazem type. Erros de validação de schema e de limite de requisições não têm código: trate pelo status HTTP. - Um code desconhecido não pode quebrar o seu parser. A lista cresce. Caia no tratamento genérico do status. Em erro de validação, leia error para exibir e use details apenas se existir. O que cada status significa - 400: corpo ou parâmetro inválido. - 401: chave ausente, inválida, inativa ou expirada, ou rota que não aceita chave. - 403: escopo insuficiente ou recurso não habilitado para a conta. - 404: recurso inexistente ou de outra conta. A API não distingue os dois casos, de propósito. - 409: conflito, geralmente duplicidade em campo único. - 413: corpo grande demais. - 422: corpo válido, mas a operação não pode ser executada no estado atual. - 429: limite de requisições. - 500: erro interno ou serviço externo sem resposta. O code indica qual. - 503: indisponibilidade temporária. O Retry-After, quando vem, diz quando repetir. Sucesso também tem pegadinha A maioria das criações responde 200. A criação de cobrança internacional e a de cartão respondem 201. Trate a faixa 2xx inteira como sucesso. E se aparecer 502 ou 504? A Dotfy não responde esses códigos. Quando aparecem, vêm da rede no caminho, como uma página HTML sem JSON, e o desfecho é desconhecido. Numa operação que cria algo, consulte antes de repetir. Recebi 403 com a chave certa Alguns recursos, como cartão e boleto, são liberados por conta. Isso não se resolve por código: é uma configuração da conta. Fale com o seu contato na Dotfy. Os valores possíveis de code estão na página de cada endpoint, na referência da API.

Última atualização em Nov 10, 2026

Quais são os limites de requisições da API?

A API aplica limites em níveis independentes, e uma requisição precisa passar por todos. Teto global 1.200 requisições por minuto (20 por segundo), em janela deslizante, por conta. Todas as chaves da conta dividem o mesmo teto, então usar várias chaves não aumenta o limite. O painel tem um limite separado. Limites por rota Rotas específicas têm limites próprios, informados na página de cada endpoint. Alguns deles: - Criação de cobranças: 200 por minuto, por conta e por subconta. - Operações em conjunto de subcontas: 600 por minuto por conta principal, somando cobranças, KYC e saques feitos em nome delas. - Consulta de chave PIX: 20 por minuto, em recurso liberado por conta. Consulte a chave quando for pagar, não para validar cadastro em massa. - Cartão (POST /api/card-charges): 60 por minuto por IP e 60 por minuto por conta. - Cobrança internacional: 60 por minuto na rota e, hoje, 6 cobranças por minuto por conta. Esse número pode mudar, então não o trate como constante do seu sistema. Como saber qual limite estourou O corpo do 429 indica o nível: - Teto global: Limite de requisições excedido. Tente novamente em breve. - Limite de rota: Muitas requisições. Tente novamente em breve. Na criação de cobrança, os cabeçalhos Retry-After e X-RateLimit-Reset dizem quando voltar. Como reagir - Recue exponencialmente, com aleatoriedade. Reenviar na hora piora, porque a tentativa anterior continua contando na janela. - Uma cobrança que recebeu 429 não foi criada. Já uma que recebeu timeout de rede pode ter sido. - Na cobrança internacional, a fila responde 503 com code: PROVIDER_BUSY e retryAfter, em segundos. Nesse caso nada foi aberto, e repetir depois do prazo é seguro. Como consumir menos A maior parte do consumo vem de polling. Em vez de consultar GET /api/charges em laço, use o webhook EVENT:CHARGE_PAID. Consulte a API para reconciliar, não para descobrir. Detalhes no guia Limites de requisições.

Última atualização em Nov 10, 2026

Como evitar cobrança duplicada ao reenviar uma requisição?

A Dotfy não tem um cabeçalho Idempotency-Key. Onde há proteção contra duplicidade, ela vem de um campo do corpo. Sem essa proteção, um timeout é ambíguo: a operação pode ter acontecido. Por isso, consulte antes de reenviar. O que vale em cada fluxo - PIX (POST /api/charges): o correlationID enviado é descartado, então não conte com ele para evitar duplicidade. Guarde o identificador que a resposta devolve e consulte a cobrança antes de criar outra. Se a resposta não chegou, procure a cobrança na listagem antes de criar outra. - Cartão (POST /api/card-charges): idempotente por correlationID. Gere o valor antes da primeira chamada e guarde junto do pedido. Em 202 PROCESSING, 500 ou timeout, reenvie a mesma requisição com o mesmo correlationID. Uma recusa (402) não libera o identificador: se o comprador quiser tentar outro cartão, é um pedido novo, com correlationID novo. - Internacional: a criação não tem idempotência. Nunca crie uma segunda cobrança porque o comprador não voltou. Depois de um timeout, consulte pelo id que você guardou. Se o POST deu timeout e você não tem o id, não repita a criação às cegas: liste as cobranças recentes do produto e do país e procure a sua pelo customer.email antes de tentar de novo. - Pix Automático: repetir com o mesmo contractId e os mesmos dados devolve a assinatura existente. Com dados diferentes, a resposta é 409. Repetir ou consultar? - 429: nada foi criado. Aguarde, com recuo exponencial, e repita. - 503 PROVIDER_BUSY na cobrança internacional: nada foi aberto. Repita depois do prazo informado. - 500 com code: PROVIDER_INDETERMINATE na cobrança internacional: pode existir cobrança viva. Consulte antes de qualquer nova tentativa. - Fora do cartão, em 502, 504 ou timeout de rede o desfecho é desconhecido: consulte antes de repetir. Do lado do webhook A mesma entrega pode chegar mais de uma vez. Use o X-Webhook-ID como chave de idempotência, para não entregar um pedido duas vezes. Outras boas práticas - Trate a faixa 2xx inteira como sucesso. - Envie startDate e endDate sempre juntos. Com apenas um, o filtro é ignorado em silêncio. - Confira a unidade de cada campo. Entrada costuma ser em reais e saída, em centavos, com exceções. - Não compartilhe lógica de paginação entre áreas da API, porque o formato muda. Veja os detalhes em Convenções.

Última atualização em Nov 10, 2026