Documentação da API

O que é esta API

A API do Donara permite que sistemas externos (ERPs, apps de parceiros, integrações de recepção etc.) consultem o status de um voucher, marquem um voucher como usado, criem novos vouchers e cancelem vouchers — sem precisar de login nem de sessão de navegador. Toda a comunicação é feita via HTTPS, com corpo e resposta em JSON.

URL base e versionamento

Todos os endpoints ficam sob o prefixo de versão v1:

https://donara.com.br/api/v1/...

A URL não depende do subdomínio da sua clínica — o tenant é identificado automaticamente pela própria API key usada na requisição, então qualquer chamada usa sempre donara.com.br.

O que já existe / o que vem a seguir

A v1 cobre o fluxo essencial: consultar, usar, criar e cancelar vouchers comerciais/campanha. Vouchers do tipo provisório não são suportados pela API (não possuem código de validação e não são localizáveis pelos demais endpoints). Edição, exclusão, conversão de tipo, listagem/busca avançada e imagem/QR code do voucher não fazem parte desta versão.

A API é um addon avulso, independente do seu plano — contratável em Recursos Extras. Para começar:

1. Contrate o addon de API em Recursos Extras (menu, visível para usuários Master).
2. Acesse Configurações → Integrações (visível para usuários Administrador e Master), defina um label para identificar a integração e os escopos necessários (consultar, usar, criar e/ou cancelar), e clique em "Gerar chave".
3. A chave (formato dnr_live_...) é exibida uma única vez no momento da criação — copie e guarde em local seguro (variável de ambiente, cofre de segredos). Se perdê-la, revogue-a na mesma tela e gere uma nova.
4. Use a chave no header Authorization em todas as chamadas (veja a seção de Autenticação).

Toda requisição precisa do header Authorization no formato Bearer <chave>:

Authorization: Bearer dnr_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Não existe sessão, cookie ou CSRF token — a API é totalmente stateless. Cada requisição é autenticada de forma independente pela chave enviada.

O que pode fazer uma requisição ser rejeitada antes de chegar no endpoint

• Chave ausente ou mal formatada → 401 MISSING_TOKEN
• Chave inválida ou revogada → 401 INVALID_TOKEN
• Conta suspensa/cancelada → 403 TENANT_SUSPENDED
• Período de teste vencido sem assinatura → 403 TRIAL_EXPIRED
• Addon de API não contratado → 403 API_ADDON_REQUIRED
• Chave sem o escopo necessário para aquele endpoint → 403 SCOPE_NOT_ALLOWED
• Limite de requisições excedido → 429 RATE_LIMITED

Toda resposta é um JSON com o mesmo envelope, em sucesso ou erro:

// sucesso
{
  "ok": true,
  "data": { /* ... */ },
  "error": null
}

// erro
{
  "ok": false,
  "data": null,
  "error": {
    "code": "VOUCHER_NOT_FOUND",
    "message": "Voucher não encontrado.",
    "details": null
  }
}

Trate a resposta pelo campo ok e pelo error.code (estável, para tratamento programático) — não dependa apenas do HTTP status ou do texto de error.message (pode mudar de redação).

HTTP status usados

Cada chave de API tem uma ou mais permissões (escopos) definidas no momento da criação. Uma chamada a um endpoint que exige um escopo que a chave não possui retorna 403 SCOPE_NOT_ALLOWED.

GET /ping não exige nenhum escopo específico — qualquer chave válida pode chamá-lo.

Cada chave de API tem um limite de 60 requisições por minuto, avaliado em janelas fixas. Ao exceder o limite, a resposta é 429 RATE_LIMITED. Reduza a frequência de chamadas ou implemente backoff/retry no seu lado antes de tentar novamente.

Formato retornado em data pelos endpoints de consulta, busca, uso e cancelamento (dentro de vouchers, no caso da busca). Não inclui dados pessoais do comprador (nome, e-mail, CPF, celular) — apenas o necessário para validar e exibir o voucher.

Health-check de autenticação — confirma que a chave é válida e identifica a conta associada. Não exige escopo específico.

Exemplo

curl https://donara.com.br/api/v1/ping \
  -H "Authorization: Bearer dnr_live_..."

Resposta 200

{
  "ok": true,
  "data": {
    "pong": true,
    "tenant": "suaclinica",
    "scopes": ["read", "use"]
  },
  "error": null
}

Busca vouchers com filtros combináveis, passados como query string, com paginação real. Assim como os demais endpoints, nunca retorna vouchers provisórios.

Parâmetros de busca (todos opcionais e combináveis)

Todos os filtros são combinados com E (AND) entre si; valores separados por vírgula dentro de um mesmo parâmetro são combinados com OU (OR).

Exemplo

curl -G https://donara.com.br/api/v1/vouchers \
  -H "Authorization: Bearer dnr_live_..." \
  --data-urlencode "status=disponivel" \
  --data-urlencode "tipo=campanha" \
  --data-urlencode "data_validade_min=2026-01-01" \
  --data-urlencode "per_page=20" \
  --data-urlencode "page=1"

Resposta 200

{
  "ok": true,
  "data": {
    "vouchers": [
      { "oid": 491, "codigo": "i1gkayo4", "status": "disponivel", /* ...demais campos do Objeto Voucher */ }
    ],
    "meta": {
      "page": 1,
      "per_page": 20,
      "total": 37,
      "total_pages": 2
    }
  },
  "error": null
}

Erros específicos

Retorna status e informações de um voucher pelo código de validação. Vouchers do tipo provisório e códigos inexistentes retornam igualmente 404 — a API não distingue os dois casos, para não revelar a existência de vouchers provisórios.

Exemplo

curl https://donara.com.br/api/v1/vouchers/a1b2c3d4 \
  -H "Authorization: Bearer dnr_live_..."

Resposta 200

{
  "ok": true,
  "data": {
    "oid": 491,
    "codigo": "a1b2c3d4",
    "status": "disponivel",
    "tipo": "campanha",
    "valor": 100,
    "modalidade_desconto": "percentual",
    "data_validade": "2026-12-31",
    "descricao": "Vale uma consulta",
    "regras": "Válido apenas para...",
    "data_uso": null,
    "nome_paciente": null
  },
  "error": null
}

Repare que status pode vir como usado, cancelado ou expirado com HTTP 200 — isso não é um erro, é um estado válido do voucher.

Erros específicos

Marca um voucher disponível como usado, registrando quem o utilizou.

Corpo da requisição

Exemplo

curl -X POST https://donara.com.br/api/v1/vouchers/a1b2c3d4/usar \
  -H "Authorization: Bearer dnr_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "nome_paciente": "Maria Souza",
    "cpf_paciente": "123.456.789-00"
  }'

Resposta 200: o objeto do voucher atualizado (status: "usado", data_uso e nome_paciente preenchidos) — mesmo formato do endpoint de consulta.

Ordem de validação e erros específicos

As checagens abaixo são feitas nesta ordem — a primeira que falhar interrompe a requisição:

Cancela um voucher disponível. Não tem corpo de requisição.

Exemplo

curl -X POST https://donara.com.br/api/v1/vouchers/a1b2c3d4/cancelar \
  -H "Authorization: Bearer dnr_live_..."

Resposta 200: o objeto do voucher atualizado (status: "cancelado") — mesmo formato do endpoint de consulta.

Ordem de validação e erros específicos

Cria um ou mais vouchers do tipo comercial ou campanha. Vouchers provisórios não são suportados — não têm código de validação e não seriam localizáveis pelos demais endpoints.

Corpo da requisição

Exemplo

curl -X POST https://donara.com.br/api/v1/vouchers \
  -H "Authorization: Bearer dnr_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "tipo": "campanha",
    "modalidade_desconto": "percentual",
    "nome_comprador": "Parceiro XPTO",
    "valor": 15,
    "descricao": "Promoção de aniversário",
    "data_validade": "2026-12-31",
    "quantidade": 1
  }'

Resposta 201

{
  "ok": true,
  "data": {
    "vouchers": [
      { "codigo": "n7ta6w8v", "oid": 496 }
    ]
  },
  "error": null
}

Com quantidade > 1, o array vouchers traz um item por voucher criado, cada um com seu próprio código.

Erros específicos

Lista completa de error.code possíveis em qualquer endpoint da API:

Precisa de ajuda?

Dúvidas sobre a API ou problemas de integração: entre em contato em suporte@donara.com.br.