Documentação do Pharos
Gerencie sua empresa no Pharos ou integre o checkout hospedado ao seu aplicativo. Encontre guias de uso e a referência de API.
Operar Cobranças
Gerencie vendas e acompanhe cobranças pelo painel.
- Configure produtos, clientes, cupons e promoções automáticas.
- Gerencie assinaturas e faturas, confira tentativas de cobrança e ofereça acesso ao portal do cliente.
Autenticação
Todos os endpoints `/api/v1` exigem sua chave de API de negócio no header `x-api-key`.
- Crie e gerencie keys nas configurações de desenvolvedores do backoffice.
- Use keys somente leitura para fluxos de consulta e permissões mais amplas para fluxos de escrita.
Primeira requisição
Comece com uma requisição autenticada simples para validar sua key, o ambiente e o tratamento das respostas.
- Liste products ou payment links antes de tentar operações de escrita.
- Trate todas as respostas da API como escopadas ao negócio autenticado pela key.
Products
Products e prices definem o que um buyer pode comprar por meio de payment links e checkout hospedado.
- Use os endpoints de Products para buscar o catálogo exposto à sua integração.
- Mapeie IDs de produto e preço antes de criar ou atualizar payment links.
Payment Links
Payment links são URLs reutilizáveis de checkout hospedado. Ao iniciar o fluxo interativo, uma checkout session é criada ou retomada para esse link.
- Crie links para ofertas que você quer compartilhar no seu site, fluxos de CRM ou campanhas.
- Recupere e atualize links pela API quando precisar sincronizar status ou conteúdo.
Fluxo de checkout hospedado
O Pharos hospeda a experiência de checkout. Sua integração decide quando enviar o buyer ao checkout e como reconciliar o resultado.
- Use Payment Links para ofertas reutilizáveis ou Checkout Sessions para carrinhos controlados pelo backend.
- Trate conclusão e acompanhamento nos seus próprios sistemas usando webhook events.
Webhooks
Use entregas de webhook para reagir, no seu backend, a eventos de checkout, pagamento e assinatura.
- Valide `x-pharos-signature` com seu signing secret.
- Trate entregas como at-least-once e deixe seus handlers seguros contra duplicados.
Tratamento de erros
Projete sua integração para tratar explicitamente falhas de validação, autorização e recursos inexistentes.
- Espere `401` quando a chave de API estiver ausente, inválida ou sem permissão.
- Espere `404` quando o recurso escopado ao negócio não existir.
Próximos passos
Quando o fluxo principal estiver funcionando, avance da primeira requisição para uma integração pronta para produção.
- Conecte seu catálogo a products e prices.
- Publique payment links ou lance checkout hospedado a partir do seu site.
- Assine webhook events antes de entrar em produção.